phoner 0.6.0

A CLI tool and library to validate phonotactic patterns for constructed languages
Documentation

Phoner

Phoner is a CLI tool and library to validate phonotactic patterns for constructed languages. It is compatible with either romanization and phonetic transcription. Words can be randomly generated (see Argument Syntax).

Syntax Highlighting Extension for VSCode

Usage

This project can be used as a rust library, or as a binary.

Binary use

Download latest version here

Argument Syntax

$ phoner --help

Usage: phoner.exe [OPTIONS] [TESTS]

Options:
  -t, --tests <TESTS>
      Custom test, separate with comma (Ignores tests in file)

  -f, --file <FILE>
      Name and path of file to run and test

      Eg. `phoner -f ./myfile.phoner`

      [default: phoner]

  -d, --display-level <DISPLAY_LEVEL>
      What types of outputs to display

      Options can be single letter

      Eg. `phoner -d just-fails` or `phoner -df`

      [default: show-all]

      Possible values:
        - show-all:        Show everything (passes, notes, fails)
        - notes-and-fails: Show most (notes, fails), but not passes
        - just-fails:      Show only fails, not passes or notes
        - hide-all:        Show nothing: not passes, notes, or fails

  -g, --generate [<GENERATE>]
      Generate random words

      Default count 1, specify with number

  -m, --minify [<MINIFY>]
      Minify file and save

      Possible values:
        - tests: Include tests

  -h, --help
      Print help information (use `-h` for a summary)

Example

# Runs ./phoner
phoner

# Runs ./phoner, with tests: 'some', 'words' (instead of tests in file)
phoner -t some,words

# Runs ./myfile.phoner
phoner -f myfile.phoner

# Runs ./phoner, only showing fails
phoner -df
# Alternatives:
phoner -d just-fails
phoner -d fails

# Runs ./phoner, and minifies to ./min.phoner without tests
phoner -m

# Runs ./myfile.phoner, without outputting any results, and minifies to ./myfile.min.phoner with tests
phoner -f myfile.phoner -dh -mt

# Runs ./phoner, and generates 1 random word
phoner -g

# Runs ./myfile.phoner, and generates 10 random words
phoner -g10

Create Alias / Path

Replace <path_to_file> with the directory of the downloaded binary.

Bash

Add alias in .bashrc in user directory

# ~/.bashrc
alias phoner="<path_to_file>/phoner.exe"

Powershell

Add to $env:PATH

$env:Path = "$env:Path;<path_to_file>\phoner.exe"

Library use

Add phoner = "0.5.3" to your Crates.toml file

Short example:

use phoner::Phoner;

fn main() {
  let file = std::fs::read_to_string("phoner").unwrap();

  // Parse file
  Phoner::parse(&file).unwrap()
    // Run tests
    .run(scheme)
    // Display results
    .display(Default::default());
}

Long example:

use phoner::{Phoner, DisplayLevel};

fn main() {
  let file = std::fs::read_to_string("phoner").unwrap();

  // Parse file
  let scheme = Phoner::parse(&file).unwrap();

  // Run tests
  let results = scheme.run(scheme);

  // Display results - This could be manually implemented
  results.display(DisplayLevel::ShowAll);

  // Generate random words
  let words = scheme.generate(10, 3..14).unwrap();
  println!("{words:?}");
}

File syntax

A phoner file is used to define the rules, classes, and tests for the program.

Syntax Highlighting Extension for VSCode

Statements

The syntax is a statements, each separated by a semicolon ; or a linebreak.

All whitespace is ignored, except to separate words in tests.

Each statement must begin with an operator:

  • # Hashtag: A whole line comment. A semicolon ends the comment
  • $ Dollar: Define a class
  • + Plus or ! Bang: Define a rule
  • @ Commat: Define a reason if a test fails
  • ? Question: Create a test
  • * Star: Create a test note (also with @*)

Classes

Classes are used as shorthand Regular Expressions, substituted into rules at runtime.

Syntax:

  • $ Dollar
  • Name - Must be only characters from [a-zA-Z0-9_]
  • = Equals
  • Value - Regular Expression, may contain other classes in angle brackets <> (as with rules)

The any class, defined with $_ = ..., is used for random word generation.

Example:

# Some consonants
$C = [ptksmn]

# Some vowels
$V = [iueoa]

# Only sibilant consonants
$C_s = [sz]

Rules

Rules are Regular Expressions used to test if a word is valid.

Rules are defined with an intent, either + for positive, or ! for negative.

  • A positive rule must be followed for a word to be valid
  • A negative rule must not be followed for a word to be valid

To use a class, use the class name, surrounded by angle brackets <>.

Syntax:

  • + Plus or ! Bang - Plus for positive rule, Bang for negative rule
  • Pattern - Regular Expression, may contain classes in angle brackets <>

Example (with predefined classes):

# Must be (C)V syllable structure
+ ^ (<C>? <V>)+ $

# Must not have two vowels in a row
! <V>{2}

Tests

Tests are checked against all rules, and the result is displayed in the output.

Tests are ran in the order of definition.

Like rules, tests must have a defined intent, either + for positive, or ! for negative.

  • A positive test will pass if it is valid
  • A negative test will fail if it is valid

Syntax:

  • ? Question mark
  • + Plus or ! Bang - Plus for positive test, Bang for negative test
  • Tests - A word, or multiple words separated by a space

Example (with predefined rules):

# This should match, to pass
?+ taso
# This test should NOT match, to pass
?! tax
# Each word is a test, all should match to pass
?+ taso sato tasa

Reasons

Reasons are used before rules as an explanation if a test fails.

Syntax:

  • @ Commat
  • Optional * Star - Use as a note as well (a noted reason)
  • Text to define reason as (And print, if being used as note)

Example:

@ Syllable structure
+ ^ (<C>? <V>)+ $

# This test will NOT match, however it SHOULD (due to the Plus), so it will FAIL, with the above reason
?+ tasto

# This reason has a Star, so it will be used as a note as well
@* Must not have two vowels in a row
! <V>{2}

?+ taso

Notes

Notes are printed to the terminal output, alongside tests.

They can be used to separate tests into sections, however this is only cosmetic.

Syntax:

  • * Star
  • Text to print to terminal

Example (with predefined rules):

* Should match
?+ taso

* Should not match
?! tatso

Examples

See the examples folder for phoner file examples.

Recommended Syntax Patterns

These formatting tips are not required, but recommended to make the file easier to read.

  1. Define all rules at the top of the file
    • Also define an any class, for word generation
  2. Group related rules and tests, using a noted reason
    • Define rules first, then positive tests, then negative tests
  3. Indent rules and tests under notes or reasons
    • Rules should use 1 intent, tests use 2

Eg.

$_ = [ptkmnswjlaeiou]
$C = [ptkmnswjl]
$V = [aeiou]

@* Invalid letters
  + ^ <_>+ $
    ?+ taso
    ?! tyxo

@* Syllable structure
  + ^ ( <C> <V> ) $
    ?+ taso kili
    ?! ano taaso

* Some more tests
  ?+ silo tila
  ?! aka axe

TODO

  • Add line number traceback to initial class substitution error
  • Add more docs
  • Add tests !
  • Add more info to Error variants
  • Refactor modules (without breaking api?)
  • Remove unnecessary clones where possible