generator_combinator/lib.rs
1//! Generates [`String`] combinations from combinable [`Generator`]s.
2//!
3//! `generator-combinator` aims to provide text _generation_ capabilities, similar to but in the opposite direction of [parser combinators](https://en.wikipedia.org/wiki/Parser_combinator) that transform text into structured data.
4//!
5//! # Iris example
6//! Consider the [regular expression](https://en.wikipedia.org/wiki/Regular_expression) `iris( (versicolor|virginica|setosa))?`. This regex matches exactly four input values:
7//! * `"iris"`
8//! * `"iris versicolor"`
9//! * `"iris virginica"`
10//! * `"iris setosa"`
11//!
12//! This regex does _not_ match other values such as `"iris fulva"` or `"iris "` (with trailing space). If we want to generate these four valid input values (something like a reverse regex), we can build a generator-combinator as:
13
14//! ```
15//! use generator_combinator::{oneof, Generator};
16//! let genus = Generator::from("iris");
17//!
18//! // Support three different species
19//! let species = Generator::from("versicolor")
20//! | Generator::from("virginica")
21//! | Generator::from("setosa");
22//! // Alternately:
23//! let species = oneof!("versicolor", "virginica", "setosa");
24//!
25//! // Delimit the genus and species with a space
26//! let species = Generator::from(' ') + species;
27//!
28//! // Allow generated values to be genus-only or with the species
29//! let iris = genus + species.optional();
30//!
31//! // Our generator should produce exactly four values
32//! assert_eq!(iris.len(), 4);
33//!
34//! let mut iris_values = iris.generate_all();
35//! assert_eq!(iris_values.next(), Some("iris".into()));
36//! assert_eq!(iris_values.next(), Some("iris versicolor".into()));
37//! assert_eq!(iris_values.next(), Some("iris virginica".into()));
38//! assert_eq!(iris_values.next(), Some("iris setosa".into()));
39//! assert_eq!(iris_values.next(), None);
40//!
41//! assert_eq!(iris.regex(), "iris( (versicolor|virginica|setosa))?");
42//! ```
43//!
44//! # Street address example
45//! Generators can be used to produce sample input data according to some pattern. For example, to generate street addresses (which aren't necessarily verifiable):
46//! ```
47//! use generator_combinator::{Generator, oneof, gen};
48//! let space = Generator::from(' ');
49//!
50//! let number = (Generator::Digit * (3, 5)).transform(|s| s.trim_start_matches('0').to_string());
51//!
52//! let directional = space.clone() + oneof!("N", "E", "S", "W", "NE", "SE", "SW", "NW");
53//! let street_names = space.clone() + oneof!("Boren", "Olive", "Spring", "Cherry", "Seneca", "Yesler", "Madison", "James", "Union", "Mercer");
54//! let street_suffixes = space.clone() + oneof!("Rd", "St", "Ave", "Blvd", "Ln", "Dr", "Way", "Ct", "Pl");
55//!
56//! let address = number
57//! + directional.clone().optional()
58//! + street_names
59//! + street_suffixes
60//! + directional.clone().optional();
61//!
62//! assert_eq!(address.len(), 809_190_000);
63//!
64//! #[cfg(feature = "with_rand")]
65//! {
66//! let addr_values = address.generate_all();
67//! println!("Example: {}", addr_values.random()); //Example: 344 W Yesler Way
68//! println!("Example: {}", addr_values.random()); //Example: 702 NE Spring Ct N
69//! println!("Example: {}", addr_values.random()); //Example: 803 SW Madison Way SE
70//! }
71
72#[cfg(test)]
73#[macro_use]
74extern crate quickcheck;
75
76mod macros;
77
78mod generator;
79pub use generator::Generator;
80
81mod iter;
82pub use iter::StringIter;
83
84mod transformfn;