Phoner

Phonet 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

Formerly named 'Phoner'

Usage

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

Binary use

Download latest version here

Argument Syntax

``` Usage: phonet.exe [OPTIONS]

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

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

      Eg. `phonet -f ./myfile.phonet`

      [default: phonet]

-d, --display-level What types of outputs to display

      Options can be single letter

      Eg. `phonet -d only-fails` or `phonet -do`

      [default: show-all]

      Possible values:
      - show-all:      Show everything: passed or failed tests, and notes
      - ignore-passes: Show failed tests and notes, but not passes
      - only-fails:    Show only failed tests, not passed tests or notes
      - hide-all:      Show nothing: not passed or failed tests, or notes

-m, --minify Minify file and save

-w, --with-tests Include tests in minified file

-g, --generate [] Generate random words

      Default count 1, specify with number

  --gmin <GENERATE_MIN_LEN>
      Set minimum length for generated words

      Use with the `--generate` or `-g` flag

      Note: This increases generation time exponentially

  --gmax <GENERATE_MAX_LEN>
      Set maximum length for generated words

      Use with the `--generate` or `-g` flag

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

      Use for piping standard output to a file

-h, --help Print help (see a summary with '-h')

-V, --version Print version ```

Example

```bash

Runs ./phonet

phonet

Runs ./phonet, with tests: 'some', 'words' (overrides the tests in file)

phonet -t some,words

Runs ./myfile.phonet

phonet -f myfile.phonet

Runs ./phonet, only showing fails

phonet -df

Alternatives:

phonet -d only-fails phonet -d fails

Runs ./phonet, and minifies to ./min.phonet without tests

phonet -m

Runs ./myfile.phonet, without outputting any results, and minifies to ./myfile.min.phonet with tests

phonet -f myfile.phonet -dh -mw

Runs ./phonet, and generates 1 random word

phonet -g

Runs ./myfile.phonet, and generates 10 random words

phonet -g10 -f myfile.phonet

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

phonet -n > phonet.txt

Runs ./myfile.phonet, with all test output hidden, and generates 3 random words with length 6-8, writes output to ./phonet.txt (with no color)

phonet -f myfile.phonet -ndh -g 3 --gmin 6 --gmax 8 > ./phonet.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 phonet="/phonet.exe" ```

Powershell

Add to $env:PATH

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

Library use

Add phonet = "0.9.0" to your Crates.toml file

Short Example

```rs use phonet::Draft;

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

// Parse draft
Draft::from(&file).unwrap()
    // Run tests
    .run()
    // Display results
    .display(Default::default())

} ```

Long Example

```rs use std::fs;

use phonet::{ draft::{Message::Test, TestDraft}, getminfilename, DisplayLevel, Draft, };

fn main() { let filename = "myfile.phonet";

// Read file
let file = fs::read_to_string(filename).expect("Could not read phonet file");

// Parse file
let mut draft = Draft::from(&file).expect("Failed to parse file");

// Add a custom test
draft.messages.push(Test(TestDraft {
    intent: true,
    word: "taso".to_string(),
}));

// Minify file
fs::write(
    get_min_filename(filename),
    draft.minify(false).expect("Failed to minify"),
)
.expect("Could not write minified file");

// Generate 10 words, each between 5 and 8 in length
let generated = draft.generate(10, 5..8).expect("Failed to generate words");

// Run tests and display only failed tests
draft.run().display(DisplayLevel::OnlyFails, true);

// Display generated words
println!("Randomly generated words:");
for word in generated {
    println!(" - {}", word);
}

} ```

File syntax

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

The file should either be called phonet, or end in .phonet

Syntax Highlighting Extension for VSCode

Statements

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

Use a Ampersand & to denote a multi-line statement. This can only be ended with a semicolon ;.

Comments will end with a linebreak or a semicolon ;.

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

Note! This will replace spaces in Regex as well! Use \s if you need a space

Each statement must begin with an operator:

# Hashtag: A whole line comment. A linebreak (not a semicolon) ends the comment
$ Dollar: Define a class
+ Plus or ! Bang: Define a rule
* Star: Create a test note, and define a reason if a test fails
? Question: Create a test
~ Tilde: Define the mode of the file

Classes

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

Note: Angle brackets will not parse as class names directly after:

An opening round bracket and a question mark: (?

An opening round bracket, question mark, and letter 'P': (?P

A backslash and letter 'k': \k

This is the syntax used for look-behinds and named groups

Syntax:

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

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

Example:

```phonet

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 <> or ⟨⟩.

Syntax:

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

Example (with predefined *classes*):

```phonet

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

```phonet

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

Notes

Notes are printed to the terminal output, alongside tests.

They are used as a reason for any proceeding rules, as an explanation if a test fails.

Syntax:

* Star
Text to print, and define reason as

Example:

```phonet * Syllable structure + ^ (? )+ $

This test will NOT match, however it SHOULD (due to the Plus), so it will FAIL, with the above note as the reason

?+ tasto

Must not have two vowels in a row ! {2}

?+ taso ```

Mode

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

Romanized: Using <> (not ⟨⟩)
Broad transcription: Using //
Narrow transcription: Using []

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

Syntax:

~ Tilde
<.>, /./, or [.] - Mode identifier, with . being any string, or blank

Examples:

```phonet

Specify romanized mode (fish icon)

~<> ```

```phonet

Specify broad transcription

~ / this is the mode / ```

Examples

See the examples folder for Phonet file examples.

Recommended Syntax Patterns

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

Specify the mode at the very top of the file
Define all classes at the top of the file
- Also define an 'any' class first, for word generation
Group related rules and tests, using a note
- Define rules first, then positive tests, then negative tests
Indent rules and tests under note
- Rules should use 1 intent, tests use 2

Example (this is from example.phonet):

```phonet ~<> ;# Mode (optional) - This file uses romanized letters

Class definitions

$_ = [ptkmnswjlaeiou] ;# Any / all letters (required for generating words) $C = [ptkmnswjl] ;# Consonants $V = [aeiou] ;# Vowels

Invalid letters ;# Note - Prints to standard output, and used as reason if test fails
- ^ ⟨_⟩+ $ ;# Check that every letter is in the 'any' class ?+ taso ?! tyxo
Examples of failing tests ?+ tyxo ;# This test will fail - with the reason 'Invalid Letters' (above) ?! taso ;# This test will fail, as a false positive
Syllable structure
- ^ ( ⟨C⟩ ⟨V⟩ )+ $ ;# Check that word is Consonant + Vowel, repeating at least once ?+ taso kili ?! ano taaso
Some more tests ?+ silo tila ?! aka axe
No repeated letters ! (.)\1 ;# This is an unnamed back-reference ! (? .) \k ;# This is a named back-reference (NOT a class) ?+ taso ;# An example of multi-line statements on next line (comments cannot be on same line) ?! & taaso ttaso ;
2 tests should have failed! ```