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.5
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 <COM> Use small words (0), medium words (1), or large words (2) [default: 0]
--count <COUNT> Generate multiple names; pass 0 to produce infinite names! [default: 1]
-l, --letters <LETTERS> Maxiumum number of letters in each word; 0 for unlimited [default: 0]
-s, --separator <SEP> Separator between words [default: -]
-w, --words <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
suitably_overdelicate_jamee
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:
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:
let mut rng = thread_rng;
let pname = default.generate;
Or, to use the default random number generator:
let pname = default.generate_one;
There's a convenience function that'll do this for you:
let pname = petname
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":
let mut petnames = default;
petnames.retain;
petnames.generate_one;
Getting Started
To install the command-line tool:
- Install Cargo,
- Install this crate:
cargo install petname
.
Alternatively, to hack the source:
- Install Cargo,
- Clone this repository,
- Build it:
cargo build
.
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.