rust-petname

生成易于阅读的随机名称。

🚨 从 1.x 升级？有多个重大更改；请参阅 说明。

Petnames 在需要命名大量资源时很有用，例如服务器、服务、甚至出租的自行车，并且希望这些名称易于记忆和明确传达。例如，在电话中比较说“请重启令人印象深刻的板球”和“请重启 s01O97i4”：前者更容易说出且更不容易被误解。避免连续的名称还可以增加信心：petnames 之间的词汇距离更大，因此转录错误更容易被发现。

此软件包既是命令行工具也是 Rust 库。Dustin Kirkland 的 petname 项目是这个项目的灵感来源。这里的单词列表和基本的命令行 UX 都取自那里。查看它！Dustin 还维护 Python 和 Golang 的软件包。

显著特性

• 从 3 个内置单词列表中选择，或提供自己的。
• 音韵名称，如 可行的秃鹰、恰当的小马、...
• 使用 1-255 个组件（形容词、副词、名词）构建名称。
• 名称组件可以不分开，或由任意字符或字符串连接。
• 生成 1..n 个名称，或连续流式传输名称。
• no_std 支持（见 后面的部分）。
• 不使用内置字典编译以减小库/二进制文件大小。

命令行工具

如果您已安装 Cargo，可以使用以下命令安装 rust-petname：cargo install petname。这将把一个名为 petname 的二进制文件放在 ~/.cargo/bin 目录下，Cargo 安装程序可能已经将其添加到您的 PATH 环境变量中。

rust-petname 中的 petname 二进制文件与原始的 petname 大多数情况下是直接兼容的。它提供了更多选项，并且在验证参数时更加严格，但对于大多数用途，它的行为应该是相同的[^differences]。

[^differences]：当使用 --dir 选项时，Dustin Kirkland 的 petname 会查找名为 names.txt 的文件，而本程序会首先查找 nouns.txt，然后再查找 names.txt。

$ petname -h
Generate human readable random names

Usage: petname [OPTIONS]

Options:
  -w, --words <WORDS>             Number of words in name [default: 2]
  -s, --separator <SEP>           Separator between words [default: -]
      --lists <LIST>              Use the built-in word lists with small, medium, or large words [default: medium] [possible values: small, medium, large]
  -c, --complexity <NUM>          Alias for compatibility with upstream; prefer --lists instead
  -d, --dir <DIR>                 Use custom word lists by specifying a directory containing `adjectives.txt`, `adverbs.txt`, and `nouns.txt`
      --count <COUNT>             Generate multiple names; or use --stream to generate continuously [default: 1]
      --stream                    Stream names continuously
  -l, --letters <LETTERS>         Maximum number of letters in each word; 0 for unlimited [default: 0]
  -a, --alliterate                Generate names where each word begins with the same letter
  -A, --alliterate-with <LETTER>  Generate names where each word begins with the given letter
  -u, --ubuntu                    Alias for compatibility with upstream; prefer --alliterate instead
      --seed <SEED>               Seed the RNG with this value (unsigned 64-bit integer in base-10)
  -h, --help                      Print help (see more with '--help')
  -V, --version                   Print version

Based on Dustin Kirkland's petname project <https://github.com/dustinkirkland/petname>.

$ petname
unified-platypus

$ petname -s _ -w 3
lovely_notable_rooster

性能

此实现比上游的 petname 快得多

$ time /usr/bin/petname
fit-lark

real    0m0.038s
user    0m0.032s
sys     0m0.008s

$ time target/release/petname
cool-guinea

real    0m0.002s
user    0m0.002s
sys     0m0.000s

如果您只需要命名一个对象，这些时间测量是不相关的，但如果您需要生成 100 个或 1000 个以上的名称，rust-petname 就非常方便

$ time { for i in $(seq 1000); do /usr/bin/petname; done; } > /dev/null

real    0m32.058s
user    0m29.360s
sys     0m5.163s

$ time { for i in $(seq 1000); do target/release/petname; done; } > /dev/null

real    0m2.199s
user    0m1.333s
sys     0m0.987s

公平地说，/usr/bin/petname 是一个 shell 脚本。从 Ubuntu 上的 golang-petname 包中可以获取的 Go 命令行版本在速度上与 Rust 版本相当，但与它的 shell 脚本前辈相比以及与 rust-petname 相比，它的选项非常有限。

最后，rust-petname 有一个 --count 选项，可以显著加快名称生成速度

$ time target/release/petname --count=10000000 > /dev/null

real    0m1.327s
user    0m1.322s
sys     0m0.004s

这大约是 240,000（二十四万）倍的速度，在此硬件上大约每秒可以生成 750 万个宠物名称。如果您想对生成的名称应用外部过滤器，这将非常有用

$ petname --words=3 --stream | grep 'love.*\bsalmon$'

库

您可以使用 cargo add petname 命令将 rust-petname 集成到您的 Rust 项目中。

功能与 no_std 支持

有一些功能可以选择启用或禁用（更准确地说，是禁用，因为默认情况下所有功能都是启用的）

• default-rng 启用了 std 和 std_rng，这是在 rand 中的。一些便利函数依赖于默认随机数生成器。
• default-words 启用了默认的单词列表。取消选中此选项将减小编译后的工件大小。
• clap 启用了 clap 命令行参数解析器，这是构建 petname 二进制文件所需的。
  • 注意，clap 对库本身来说并不是必需的，您可以取消选中它，但当前它是一个默认功能，因为如果不这样，构建二进制文件将非常不方便。这可能会在未来改变。

所有这些功能都是构建命令行工具所必需的。

库可以在不启用任何默认功能的情况下构建，并且可以在 no_std 环境中工作，如 Wasm。您需要确定随机数源，但 SmallRng::seed_from_u64 可能是一个良好的起点。

从 1.x 升级

2.0 版本在 API 和命令行中都带来了几个重大变更。以下是其中最重要的

命令行

• 将 --complexity <COMPLEXITY> 选项替换为 --lists <LISTS>。
  • 为了兼容性，--complexity [0,1,2] 仍然可以使用，但其在 -h|--help 文本中未显示其可用性。
  • 默认值现在是 "medium"（相当于 --complexity 1）。之前是 "small"（--complexity 0）。
• 当使用带有 --dir <DIR> 的自定义词表时，现在名词将在名为 DIR/nouns.txt 的文件中找到。之前这是 names.txt，但这很令人困惑；"names" 这个词已经足够多义了。
  • 为了兼容性，如果找不到 nouns.txt，将尝试从 names.txt 加载名词。
• --count 0 选项不再是 --stream 的同义词。请使用 --stream。传递 --count 0 不会出错，但它将导致生成的名称为零。
• --non-repeating 标志不再被识别（#101）。

库

• 功能标志已被重命名
  • std_rng 现在是 default-rng，
  • default_dictionary 现在是 default-words。
• 在 Petnames 结构体上的 names 字段已被重命名为 nouns。
• Petnames::new() 现在是 Petnames::default()。
• Petnames::new(…) 现在接受作为字符串的词表。
• Names 不再是公共的。这曾是 Petnames::iter(…) 返回的迭代器结构体，但现在通过返回 impl Iterator<Item = String> 来隐藏实现细节。这也意味着 Names::cardinality(&self) 不再可用；请使用 Petnames::cardinality(&self, words: u8) 代替。
• Petnames::iter_non_repeating 已被移除（#101）。
• Petnames::generate、Petnames::generate_one和Petnames::iter已经被提取到一个Generator特质中。调用这些方法必须在这个作用域内（参见#102）。
• 默认的单词列表现在是“中等”列表。