Phoner

Phoner is a CLI tool and library to validate phonotactic patterns for constructed languages. It is compatible with either romanization and phonetic transcription.

Syntax Highlighting Extension for VSCode

This program is still in development, and is subject to change.

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

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

  Possible values:
    - tests: Include tests

-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 ```

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.5.3" to your Crates.toml file

• Docs.rs
• Crates.io

```rs use phoner::prelude::*; use std::fs;

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

// Parse file let scheme = Phoner::parse(&file).expect("Failed to parse");

// Run tests let results = PhonerResults::run(scheme);

// Display results results.display(DisplayLevel::ShowAll); } ```

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

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)

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.

• 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):

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

• 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):

```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:

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

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:

• * Star
• Text to print to terminal

Example (with predefined rules):

```phoner * Should match ?+ taso

• Should not match ?! tatso ```

Examples

See the examples folder for phoner file examples.

• Toki Pona
• Ivalingo

TODO

• Add more docs
• Change class substitution strategy
• • Find /<.*>/ in string
• • Replace w value or return error if invalid name
• Add tests !
• Remove unnecessary clones where possible