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 Custom test, separate with comma (Ignores tests in file)

-f, --file Name and path of file to run and test

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

  [default: phoner]

-d, --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 random words

  Default count 1, specify with number

-m, --minify [] Minify file and save

  Possible values:
    - tests: Include tests

-n, --no-color Display output in default color

  Use for piping standard output to a file

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

Example

```bash

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 -g myfile.phoner

Runs ./phoner, with no color, and writes output to ./phoner.txt

phoner -n > phoner.txt ```

Create Alias / Path

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

Bash

Add alias in .bashrc in user directory

```bash

~/.bashrc

alias phoner="/phoner.exe" ```

Powershell

Add to $env:PATH

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

Library use

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

Short example:

```rust use phoner::Phoner;

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

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

Long example:

```rust use phoner::{Phoner, DisplayLevel};

fn main() { let file = std::fs::readtostring("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, false);

// 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.

Note! This will replace spaces in Regex as well!

Each statement must begin with an operator:

Classes

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

Syntax:

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

Example:

```phoner

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.

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

Syntax:

Example (with predefined classes):

```phoner

Must be (C)V syllable structure

Must not have two vowels in a row

! {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.

Syntax:

Example (with predefined rules):

```phoner

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:

Example:

```phoner @ Syllable structure + ^ (? )+ $

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 ! {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:

Example (with predefined rules):

```phoner * Should match ?+ taso

Mode

The mode of a Phoner file can be one of these:

This can optionally be specified in a file, although it does not add any functionality.

Syntax:

Examples:

```phoner

Specify romanized mode (fish icon)

~<> ```

```phoner

Specify broad transcription

~ / this is the mode / ```

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. Specify the mode at the very top of the file
  2. Define all classes at the top of the file
  3. Group related rules and tests, using a noted reason
  4. Indent rules and tests under notes or reasons

Eg.

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

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

@* Syllable structure + ^ ( ) $ ?+ taso kili ?! ano taaso

Phoner Icon

TODO