# Phonet _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](#argument-syntax)). [Syntax Highlighting Extension for VSCode](https://github.com/darccyy/phonet-syntax) # Usage This project may be used as a rust library crate, or as a binary executable. ## Binary use [Download latest version here](https://github.com/darccyy/phonet/releases/latest) ### Argument Syntax Generated by [Clap](https://crates.io/crates/clap) ``` Usage: phonet.exe [OPTIONS] [TESTS]... Arguments: [TESTS]... Custom tests (optional) This overrides all tests in the file Options: -f, --file Name and path of file to run and test If name ends with a period, the 'phonet' extension is implied Eg. `phonet -f myfile.phonet` or `phonet -f myfile.` (same result) If name ends with a slash, the '/phonet' file name is implied Eg. `phonet -f folder/phonet` or `phonet -f folder/` (same result) [default: phonet] -q, --quiet Don't display passes and notes, only fails -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 Set minimum length (inclusive) for generated words Use with the `--generate` or `-g` flag Note: This increases generation time exponentially [default: 3] --gmax Set maximum length (inclusive) for generated words Use with the `--generate` or `-g` flag [default: 20] -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', 'tests' (overrides the tests in file) phonet some tests # Runs ./myfile.phonet phonet -f myfile.phonet phonet -f myfile.phonet some tests # 'phonet' extension implied phonet -f myfile. # 'phonet' filename implied phonet -f src/phonet phonet -f src/ # Runs ./phonet, only showing fails phonet -q # Runs ./phonet, and minifies to ./min.phonet without tests phonet -m # Runs ./myfile.phonet, only displaying fails, and minifies to ./myfile.min.phonet with tests phonet -f myfile. -q -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, only displaying fails, and generates 3 random words with length 6-8, writes output to ./phonet.txt (with no color) phonet -f myfile. -qn -g 3 --gmin 6 --gmax 8 > ./phonet.txt ``` ### Create Alias / Path Replace `` 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;\phonet.exe" ``` ## Library use Add `phonet = "1.0.2"` to your `Crates.toml` file - [Docs.rs](https://docs.rs/phonet/latest/phonet) - [Crates.io](https://crates.io/crates/phonet) ### Short Example ```rust use phonet::Draft; fn main() { let file = std::fs::read_to_string("phonet").unwrap(); // Parse draft Draft::from(&file).unwrap() // Run tests .run() // Display results .display(Default::default(), true) } ``` ### Long Example ```rust use std::fs; use phonet::{ draft::{Message::Test, TestDraft}, get_min_filename, 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"); // Run tests and display only failed tests draft.run().display(DisplayLevel::OnlyFails, true); // Create a generator for random words // Each with a length between 5 and 8 (inclusive) // Generation is done lazily, similar to an iterator println!("Randomly generated words:"); let mut words = draft .generator(5..=8) .expect("Failed to create word generator"); // Generate 10 random words for _ in 0..10 { println!(" - {}", words.next()); } } ``` # 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](https://github.com/darccyy/phonet-syntax) ## Statements The syntax is a statements, each separated by a semicolon `;` or a linebreak. Use a _Ampersand_ `&` to denote a multi-line statement. This may only be ended with a semicolon `;` Note that comments cannot be multiline. Comments will end with a linebreak or a semicolon `;` All whitespace is ignored, except to separate words in [_tests_](#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_](#classes) - `+` **_Plus_** or `!` **_Bang_**: Define a [_rule_](#rule) - `*` **Star**: Create a test [_note_](#notes), and define a _reason_ if a test fails - `?` **Question mark**: Create a [_test_](#tests) - `~` **Tilde**: Define the [_mode_](#mode) of the file ## Classes Classes are used as shorthand Regular Expressions, substituted into [_rules_](#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_](#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] # Every letter $_ = ⟨C⟩ | ``` ## 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_](#classes), 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_](#classes) in angle brackets `<>` or `⟨⟩` _Example (with predefined [*classes*](#classes)):_ ```phonet # Must be (C)V syllable structure + ^ (? ⟨V⟩)+ $ # 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_](#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*](#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** - `:` **Colon** (_Optional_) - Define a 'quiet' note - 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 # This is a 'quiet' note, it will not display, but it will be used as the reason for the following rule *: Must not have two vowels in a row ! {2} ?+ taso ``` ## Mode The mode of a _Phonet_ file may be one of these: - _Romanized_: Using `<>` (not `⟨⟩`) - _Broad transcription_: Using `//` - _Narrow transcription_: Using `[]` This may optionally be specified in a file, although it does not add any functionality. _Syntax:_ - `~` **Tilde** - `<.>`, `/./`, or `[.]` - Mode identifier, with `.` being any string for, or blank _Examples:_ ```phonet # Specify romanized mode (fish icon) ~<> ``` ```phonet # Specify broad transcription, with a given name ~ / My Language / ``` ## Examples See the [examples](./examples/) folder for _Phonet_ file examples. - [Good Syntax Example](./examples/example.phonet) - [Toki Pona](./examples/tokipona.phonet) ## 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 - Also define an [_'any'_ class](#classes) first, for word generation 3. Group related rules and tests, using a note - Define rules first, then positive tests, then negative tests 4. Indent rules and tests under note - Rules should use 1 intent, tests use 2 ### Example File _Example (this is from [example.phonet](./examples/example.phonet)):_ ```phonet ~<> ;# Mode (optional) - This file uses romanized letters # Class definitions $_ = ⟨C⟩ | ⟨V⟩ ;# 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 + ^ ⟨V⟩? ( ⟨C⟩ ⟨V⟩ )+ $ ;# Check that word is Consonant + Vowel, repeating at least once ?+ taso kili ano atoso ?! taaso an * Some more tests ?+ silo tila ?! akka axe # This is a 'quiet' note - It will not display, unless any following rules fail *: No repeated letters ! (.)\1 ;# This is an unnamed back-reference ! (? .) \k ;# (Alternative) 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 ; # Comments cannot be multiline, even using '&' * 2 tests *should* have failed! ``` ![Phonet Icon](./icon.png)