rust-petname

Generate human readable random names.

A petname library and command-line tool in Rust. Dustin Kirkland's petname project is the inspiration for this project. The word lists and command-line UX here are taken from there. Check it out! Dustin also maintains libraries for Python 2 & 3, and Golang.

Command-line utility

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 almost drop-in compatible with the original petname. It's missing a -d, --dir option, and is more strict when validating arguments, but for most uses it should behave the same.

``` $ petname --help rust-petname 1.0.6 Gavin Panella gavinpanella@gmail.com Generate human readable random names.

USAGE: petname [FLAGS] [OPTIONS]

FLAGS: -a, --alliterate Generate names where each word begins with the same letter -h, --help Prints help information -u, --ubuntu Alias; see --alliterate -V, --version Prints version information

OPTIONS: -c, --complexity Use small words (0), medium words (1), or large words (2) [default: 0] --count Generate multiple names; pass 0 to produce infinite names! [default: 1] -d, --dir

Directory containing adjectives.txt, adverbs.txt, names.txt -l, --letters Maxiumum number of letters in each word; 0 for unlimited [default: 0] -s, --separator Separator between words [default: -] -w, --words Number of words in name [default: 2]

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

$ petname untaunting-paxton

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

Performance

This implementation is considerably faster than the upstream petname:

``` $ time /usr/bin/petname steady-monitor

real 0m0.027s user 0m0.028s sys 0m0.002s

$ time /home/gavin/.cargo/bin/petname sharp-lobster

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:

``` $ 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 /home/gavin/.cargo/bin/petname; done; } > /dev/null

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

rust-petname also has a --count option that speeds this up further:

``` $ time /home/gavin/.cargo/bin/petname --count 1000 > /dev/null

real 0m0.005s user 0m0.004s sys 0m0.000s ```

That's nearly 400,000 (four hundred thousand) times faster!

However, this speed is truly useful if you want to apply an external filter to the names being generated:

$ petname --words=3 --count=0 | grep 'doubt.*salmon'

(This should generate some matches, but it might take a long time. With the original petname it will take ~400k times longer.)

Library

There's a petname::Petnames struct:

rust pub struct Petnames<'a> { pub adjectives: Vec<&'a str>, pub adverbs: Vec<&'a str>, pub names: Vec<&'a str>, }

You can populate this with your own word lists, but there's a convenient default which uses the word lists from upstream petname. The other thing you need is a random number generator from rand:

rust let mut rng = rand::thread_rng(); let pname = petname::Petnames::default().generate(&mut rng, 7, ":");

Or, to use the default random number generator:

rust let pname = petname::Petnames::default().generate_one(7, ":");

There's a convenience function that'll do this for you:

rust let pname = petname::petname(7, ":")

It's probably best to use the generate method if you're building more than a handful of names.

You can modify the word lists to, for example, only use words beginning with the letter "b":

rust let mut petnames = petname::Petnames::default(); petnames.retain(|s| s.starts_with("b")); petnames.generate_one(3, ".");

Getting Started

To install the command-line tool:

Alternatively, to hack the source:

Running the tests

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

License

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