Generate human readable random names.
Petnames are useful when you need to name a large number of resources – like servers, services, perhaps bicycles for hire – and you want those names to be easy to recall and communicate unambiguously. For example, over a telephone compare saying "please restart remarkably-striking-cricket" with "please restart s01O97i4": the former is easier to say and less likely to be misunderstood. Avoiding sequential names adds confidence too: petnames have a greater lexical distance between them, so errors in transcription can be more readily detected.
This crate is both a command-line tool and a Rust library. Dustin Kirkland's petname project is the inspiration for this project. The word lists and the basic command-line UX here are taken from there. Check it out! Dustin maintains packages for Python, and Golang too.
Notable features:
no_std support (see later section).If you have installed Cargo, you can install rust-petname with
cargo install petname. This puts a petname binary in ~/.cargo/bin, which
the Cargo installation process will probably have added to your PATH.
The petname binary from rust-petname is drop-in compatible with the original
petname. It's more strict when validating arguments, but for most uses it
should behave the same.
```shellsession $ petname -h Generate human readable random names
Usage: petname [OPTIONS]
Options:
-w, --words Use the built-in word lists with small, medium, or large words [default: small] [possible values: small, medium, large]
-d, --dir
adjectives.txt, adverbs.txt, and nouns.txt
--count
Based on Dustin Kirkland's petname project https://github.com/dustinkirkland/petname.
$ petname unified-platypus
$ petname -s _ -w 3 lovelynotablerooster ```
This implementation is considerably faster than the upstream petname:
```shellsession $ 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 ```
These timings are irrelevant if you only need to name a single thing, but if you need to generate 100s or 1000s of names then rust-petname is handy:
```shellsession $ 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 ```
To be fair, /usr/bin/petname is a shell script. The Go command-line version
(available from the golang-petname package on Ubuntu) is comparable to the Rust
version for speed, but has very limited options compared to its shell-script
ancestor and to rust-petname.
Lastly, rust-petname has a --count option that speeds up generation of names
considerably:
```shellsession $ time target/release/petname --count=10000000 > /dev/null
real 0m1.327s user 0m1.322s sys 0m0.004s ```
That's ~240,000 (two hundred and forty thousand) times faster, for about 7.5 million petnames a second on this hardware. This is useful if you want to apply an external filter to the names being generated:
shellsession
$ petname --words=3 --stream | grep 'love.*\bsalmon$'
You can use of rust-petname in your own Rust projects with cargo add petname.
no_std supportThere are a few features that can be selected – or, more correctly, deselected, since all features are enabled by default:
default-rng enables std and std_rng in rand. A couple of convenience
functions depend on this for a default RNG.default-words enables the default word lists. Deselecting this will reduce
the size of compiled artifacts.clap enables the clap command-line argument parser, which is needed to
build the petname binary.
clap is not necessary for the library at all, and you
can deselect it, but it is presently a default feature since otherwise it's
inconvenient to build the binary. This will probably change in the future.All of these are required to build the command-line utility.
The library can be built without any default features, and it will work in a
no_std environment, like Wasm. You'll need to figure out a
source of randomness, but SmallRng::seedfromu64 may
be a good starting point.
Version 2.0 brought several breaking changes to both the API and the command-line too. Below are the most important:
--complexity <COMPLEXITY> option has been replaced by --lists <LISTS>.--dir <DIR>, nouns are now found in a file
named appropriately DIR/nouns.txt. Previously this was names.txt but this
was confusing; the term "names" is overloaded enough already.--count 0 is no longer a synonym for --stream. Use --stream
instead. It's not an error to pass --count 0, but it will result in zero
names being generated.std_rng is now default-rng,default_dictionary is now default-words.names field on the Petnames struct has been renamed to nouns.
Previously the complexity was given as a number – 0, 1, or 2 – but now the
word lists to use are given as a string: small, medium, or large.Petnames::new() is now Petnames::default().Petnames::new(…) now accepts word lists as strings.Names is no longer public. This served as the iterator struct returned by
Petnames::iter(…), but this now hides the implementation details by
returning impl Iterator<Item = String> instead. This also means that
Names::cardinality(&self) is no longer available; use
Petnames::cardinality(&self, words: u8) instead.To hack the source:
cargo build.git blame: git config blame.ignoreRevsFile .git-blame-ignore-revs.After installing the source (see above) run tests with: cargo test.
Cargo.toml.-h output into README.md (this file; see near
the top). On macOS the command cargo run -- -h | pbcopy is helpful.
Note that --help output is not the same as -h output: it's more
verbose and too much for an overview.cargo build && cargo test. The latter on its own does
do a build, but a test build can hide warnings about dead code, so do both.$VERSION."$VERSION", e.g. git tag v1.0.10.git push --follow-tags.cargo publish.This project is licensed under the Apache 2.0 License. See the LICENSE file for details.