# faker_rand ![Crates.io](https://img.shields.io/crates/v/faker_rand) ![Docs.rs](https://docs.rs/faker_rand/badge.svg)
`faker_rand` is a Rust crate that lets you easily generate fake data using the
[`rand`](https://docs.rs/rand) crate. It also provides macros so you can easily
build your own data generators on top of those provided out of the box.
## Installation
You can use `faker_rand` in your Rust project by adding the following to your
`Cargo.toml`:
```toml
faker_rand = "0.1"
```
## Usage
See [the docs on docs.rs for more details](https://docs.rs/faker_rand), but at a
high level here's how you can use this crate:
```rust
use rand::Rng;
use faker_rand::en_us::names::FirstName;
// you can display generators using "{}"
println!("random first name: {}", rand::random::<FirstName>());
println!("random first name: {}", rand::thread_rng().gen::<FirstName>());
// or, you can use to_string as well
let name = rand::random::<FirstName>().to_string();
println!("random first name: {}", name);
```
You can also build your own generators on top of those provided by this crate,
for example if you already have a file of fake data you'd like to generate:
```rust
use faker_rand::faker_impl_from_file;
// First, declare your newtype wrapper around String.
struct Demo(String);
// Then, use the macro. data/lorem_words is a path to a file containing
// example words; you will need to change this path to suit your needs.
faker_impl_from_file!(Demo, "data/lorem_words");
use rand::{Rng, SeedableRng};
let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(0);
assert_eq!("impedit", rng.gen::<Demo>().to_string());
```
Or, if you want to compose upon sub-generators:
```rust
use faker_rand::faker_impl_from_templates;
// First, declare your newtype wrapper around String.
struct Demo(String);
// Then, invoke the macro.
//
// Note well: all commas and semicolons in this example, even trailing
// semicolons, are strictly required.
faker_impl_from_templates! {
// The type we're creating a generator implementation for.
Demo;
// The template patterns.
"{}.{}", faker_rand::util::AsciiDigit, faker_rand::lorem::Word;
"{} ~~~ {}", faker_rand::lorem::Word, faker_rand::util::AsciiDigit;
}
use rand::{Rng, SeedableRng};
let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(0);
assert_eq!("qui ~~~ 5", rng.gen::<Demo>().to_string());
assert_eq!("debitis ~~~ 5", rng.gen::<Demo>().to_string());
assert_eq!("5.aliquid", rng.gen::<Demo>().to_string());
assert_eq!("0.doloribus", rng.gen::<Demo>().to_string());
```
Most of the documentation for this crate lives in the Rust docs, not this
README. Check out https://docs.rs/faker_rand for copy-pastable examples you can
use.