rust-petname

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

$ petname unified-platypus

$ petname -s _ -w 3 lovelynotablerooster ```

Performance

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$'

Library

You can use rust-petname in your own Rust projects with cargo add petname.

Features & no_std support

There 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.
  • NOTE that 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.

Upgrading from 1.x

Version 2.0 brought several breaking changes to both the API and the command-line too. Below are the most important:

Command-line

• The --complexity <COMPLEXITY> option has been replaced by --lists <LISTS>.
  • For compatibility, --complexity [0,1,2] will still work, but its availability is not shown in the -h|--help text.
  • The default is now "medium" (equivalent to --complexity 1). Previously it was "small" (--complexity 0).
• When using custom word lists with --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.
  • For compatibility, if nouns.txt is not found, an attempt will be made to load nouns from names.txt.
• The option --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.
• The --non-repeating flag is no longer recognised ([#101]).

Library

• Feature flags have been renamed:
  • std_rng is now default-rng,
  • default_dictionary is now default-words.
• The names field on the Petnames struct has been renamed to nouns.
• 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.
• Petnames::iter_non_repeating has been removed ([#101]).
• Petnames::generate, Petnames::generate_one, and Petnames::iter have been extracted into a Generator trait. This must be in scope in order to call those methods ([#102]).
• The default word lists are now the "medium" lists.

Developing & Contributing

To hack the source:

• Install Cargo,
• Clone this repository,
• Build it: cargo build.
• Optionally, hide noise when using git blame: git config blame.ignoreRevsFile .git-blame-ignore-revs.

Running the tests

After installing the source (see above) run tests with: cargo test.

Making a release

1. Bump version in Cargo.toml.
2. Paste updated -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.
3. Build and test. The latter on its own does do a build, but a test build can hide warnings about dead code, so do both.
   • With default features: cargo build && cargo test
   • Without: cargo build --no-default-features && cargo test --no-default-features
4. Commit with message "Bump version to $VERSION."
5. Tag with "v$VERSION", e.g. git tag v1.0.10.
6. Push: git push && git push --tags.
7. Publish: cargo publish.

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.