tracery

Rust实现的tracery生成语法语言。

这个库是Rust对tracery的移植/实现，tracery是一种由Kate Compton设计和创建的生成语法语言。给定一组用tracery语法编写的规则，它将使用这些规则来程序化生成文本字符串。有关tracery语言的信息，请参阅语言概念。

用法

库的用法可以分为两个领域：创建语法和生成输出字符串。

语法创建

可以使用grammar!宏来创建语法，从任何可迭代的Rust字符串对象及其关联的字符串列表，或者为了与原始tracery兼容，从表示JSON映射的字符串。

Grammar! 宏

接受以下形式的输入："key" => [ "list", "of", "rules" ] 或，如果一个键只有一个规则时，"key" => "rule"。相当于手动构建一个映射然后调用Grammar::from_map

use tracery::grammar;
let g = grammar! {
    "origin" => "#tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?;

从映射/迭代器

可以从任何实现了以下特性的对象创建语法：本质上，是 IntoIterator<Item = (Into<String>, Into<Vec<Into<String>>)>. 例如，HashMap<String, Vec<String>> 或 BTreeMap<&str, &[&str]>.

let map = hashmap! {
    "origin" => vec![ "#tool# is #description#!" ],
    "tool" => vec![ "tracery" ],
    "description" => vec![ "fun", "awesome" ]
};
let g = tracery::from_map(map)?;

从JSON字符串

为了与原始的tracery兼容，可以从表示JSON对象的字符串创建语法。此功能由 tracery_json 功能控制，默认情况下已启用。如果不需要此功能，可以将其关闭。

let json = r##"{
    "origin": [ "#tool# is #description#!" ],
    "tool": [ "tracery" ],
    "description": [ "fun", "awesome" ]
}"##;
let g = tracery::from_json(json)?;

生成输出字符串

从创建的语法中获取生成输出字符串有两种方法： execute 和 flatten。通常，如果可能的话，应优先使用 execute。

execute

execute 接受两个参数：要展开的规则和用于生成的RNG。RNG可以是任何实现了 rand::Rng 的类型。

use tracery::grammar;
let mut g = grammar! {
    "origin" => "#tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?;
// Generate an output (either "tracery is fun!" or "tracery is awesome!")
let key = String::from("origin");
let output = g.execute(&key, &mut rand::thread_rng())?;

execute 使用语法在原地生成其输出。由于语法允许修改自己的规则栈，execute 必须接受一个 &mut self 引用。这意味着在执行过程中所做的任何修改都将持久保留在语法中。

use tracery::grammar;
// This time, origin has a side-effect: it creates the rule 'aside'
let mut g = grammar! {
    "origin" => "#[aside:Rust is, too]tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?;
// Generate an output (either "tracery is fun!" or "tracery is awesome!")
let key = String::from("origin");
let output = g.execute(&key, &mut rand::thread_rng())?;
// The previous call to execute created the 'aside' rule
let key = String::from("aside");
// Generates the string "Rust is, too"
let output = g.execute(&key, &mut rand::thread_rng())?;

flatten

flatten 与 execute 不同，始终在语法的默认规则（默认为 "origin"）上操作，但与 execute 相同，在生成时使用 rand::Rng 的实例。此外，flatten 在生成期间使用语法的克隆，然后将其丢弃，这意味着生成的任何副作用都将被丢弃。

use tracery::grammar;
let g = grammar! {
    "origin" => "#tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?;
// Generate an output (either "tracery is fun!" or "tracery is awesome!")
let output = g.flatten(&mut rand::thread_rng())?;

许可：MIT/Apache-2.0