https://github.com/dxrcy/phonet
A CLI tool and library to validate phonotactic patterns for constructed languages
https://github.com/dxrcy/phonet
conlang language phonetics
Last synced: about 1 year ago
JSON representation
A CLI tool and library to validate phonotactic patterns for constructed languages
- Host: GitHub
- URL: https://github.com/dxrcy/phonet
- Owner: dxrcy
- License: gpl-3.0
- Created: 2023-02-19T00:36:44.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-02-02T03:53:57.000Z (over 2 years ago)
- Last Synced: 2025-03-15T08:37:17.220Z (about 1 year ago)
- Topics: conlang, language, phonetics
- Language: Rust
- Homepage:
- Size: 341 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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)).
# 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/dxrcy/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
- [TreeSitter Parser](https://github.com/dxrcy/tree-sitter-phonet)
- [VSCode Extension](https://github.com/dxrcy/phonet-syntax) (unmaintained)
## 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!
```
