The tadpole Sound Change Engine

Integrating tadpole

Tadpole is designed to be integrated into other projects, with and without its default specification language. The engine is written in Rust. Integrating with other language ecosystems will require additional effort.

For more details on the API, refer to the rustdoc documentation.

Adding the Crate

Currently, tadpole is not published to the crates repository. It needs to be included via its git repository. Add the following to Cargo.toml:

tadpole = { git = "https://codeberg.org/zhuriel/tadpole.git", tag = "v1.2.0" }

To add the default specification frontend, also add the following:

tadpole_frontend = { git = "https://codeberg.org/zhuriel/tadpole.git", tag = "v1.2.0" }

Always use a tag to pin a specific version.

Creating a Sound Changer

The main entry point to the tadpole API is the SoundChanger struct. It encapsulates all the rules and definitions of a sound changer specification. The tadpole API includes a Frontend trait to simplify creating SoundChangers. For the default language, tadpole_frontend::TadpoleParser implements this trait and can be used to create a SoundChanger as follows:

let engine = SoundChanger::parse(input, &TadpoleParser)?;

The disadvantage of this shared interface is that it uses a generic error type. This may lose some error information with frontends which offer rich error type information like the default specification language. An improved error type may be implemented in a future update.

Using the Sound Changer

There are three main methods for running the sound changer, depending on the desired startpoint.

Starting from the Main Input

To start from the main (first) input, or from the beginning of the file if there no inputs or rules before the first input, use the run method:

let res = engine.run("word")?;

Starting from a Specific Input

The from_input method allows starting from a specific input:

let res = engine.from_input("word", Some("input_name"))?;

Where the second parameter is the input name. If it is set to None, this method behaves as engine.run.

Starting from a Generator

Finally, to start with a randomly generated word, use the from_generator method:

let res = engine.from_gen("gen_name", None)?;

Where the first parameter is the generator name and the second parameter is a seed. If the seed is None, a hash of the current timestamp is used as the seed. Specifying a specific seed (u64) such as Some(1) will use the given seed and always result in the same word.

Starting from a Start Point Name

There is also a from_startpoint_name method, which will automatically be forwarded to either from_input or from_gen depending on which the given name represents.

let res = engine.from_startpoint_name("word", "name")?;

This method will always call generators with a seed of None.

Extracting Results

The methods described above all return Result<SoundChangerResult, SoundChangerError>. The SoundChangerResult type contains the following:

pub struct SoundChangerResult {
    /// The input the sound changer was applied to
    pub input: String,
    /// The final state of the internal string
    pub result: String,
    /// The intermediate outputs
    pub outputs: Vec<(String, String)>,
}

Currently, data on which input or generator was used is not stored. Outputs are stored in a vector to preserve ordering information.

For convenience, there is also a final_output method which returns the value of the final named output, if any.