Expand description
This crate is based around two traits, Buildable
and
Generatable
, and their associated derive macros, which provide
ways to construct objects succinctly.
Builder
A Builder
is a way to create a single object, specifying only the
fields you wish to give non-default values. The default values are
specified using attributes on your type for ease of reading. Each
field gains a method of the same type in the builder which can be
be used to customise it.
Example
use boulder::{Builder, Buildable};
#[derive(Buildable)]
struct Foo {
#[boulder(default=5)]
pub a: i32,
#[boulder(default="hello")]
pub b: String,
}
let f = Foo::builder()
.a(27)
.build();
assert_eq!(f.a, 27);
assert_eq!(f.b, "hello".to_string());
Generator
A Generator
is a way to create an infinite sequence of
objects, again specifying only the functions for generating the
fields you wish to have non-default sequences. The default
sequences are specified using attributes on your type for ease of
reading. Each field gains a method of the same name in the
generator, which can be be used to customise the sequence of
values produced for that field as objects are made.
Example
use boulder::{Generator, Generatable, Inc, Pattern};
#[derive(Generatable)]
struct Bar {
#[boulder(generator=Inc(1i32))]
pub a: i32,
#[boulder(generator=Pattern!("hello-{}-foo", Inc(5i32)))]
pub b: String,
}
let mut n = 2;
let mut gen = Bar::generator()
.a(move || {
n = n + 2;
n
});
let bar1 = gen.generate();
assert_eq!(bar1.a, 4);
assert_eq!(bar1.b, "hello-5-foo".to_string());
let bar2 = gen.generate();
assert_eq!(bar2.a, 6);
assert_eq!(bar2.b, "hello-6-foo".to_string());
persian-rug
When the "persian-rug"
feature is enabled, a parallel set of types,
traits and derive macros are enabled, i.e. BuildableWithPersianRug
and GeneratableWithPersianRug
. These provide similar facilities,
but for types based on the persian-rug crate.
Briefly, persian-rug moves ownership of all values
into a single container (the “rug” or
Context
). Client code then deals with handles
(in the form Proxy<T>
) to these values. The
builders and generators take a mutator for the type’s context in their
build
and
generate
methods, which means
at the point of construction, the set of other constructed instances
(of all types in that context) is available.
Since the derived generators pass through
Proxy<T>
, and since to get the most benefit from
this system you should work with proxies where possible, the most common
usage is to use these solely through the pass throughs.
Example:
use boulder::{BuilderWithPersianRug, BuildableWithPersianRug};
use persian_rug::{contextual, persian_rug, Context, Proxy};
#[persian_rug]
struct Rug(
#[table] Foo,
#[table] Bar,
);
#[contextual(Rug)]
#[derive(BuildableWithPersianRug)]
#[boulder(persian_rug(context=Rug))]
struct Foo {
#[boulder(default=5)]
pub a: i32,
#[boulder(buildable_with_persian_rug(a=5))]
pub b: Proxy<Bar>,
}
#[contextual(Rug)]
#[derive(BuildableWithPersianRug)]
#[boulder(persian_rug(context=Rug))]
struct Bar {
#[boulder(default=2)]
pub a: i32
}
let mut r = Rug(Default::default(), Default::default());
let (f, _) = Proxy::<Foo>::builder()
.a(27)
.build(&mut r);
assert_eq!(r.get(&f).a, 27);
assert_eq!(r.get(&r.get(&f).b).a, 5);
Macros
Make a Generator
for formatted Strings.
Make a Generator
that recycles a collection of values.
Structs
The same value every time.
Recycle values from an iterator.
An owning iterator for any generator.
A non-owning iterator for any generator.
persian-rug
Convert a Generator
into a GeneratorWithPersianRug
.
persian-rug
An owning iterator for any generator.
persian-rug
A non-owning iterator for any generator.
An increasing sequence.
Repeat a provided collection.
persian-rug
Cycle through the existing Proxy<T>
items
in the context.
Collections from an underlying sequence.
persian-rug
Produce collections of the existing
Proxy<T>
items in the context.
persian-rug
Collections drawn from an underlying generator.
Subsets of a base collection.
persian-rug
Produce subsets of the existing Proxy<T>
items in the context.
Increasing timestamps.
persian-rug
Cycle through the existing Proxy<T>
items
in the context.
Traits
persian-rug
A type that has an associated default BuilderWithPersianRug
Something which can create a default object of some type.
persian-rug
Something which can create a default object of some
persian_rug::Contextual
type.
A type that has an associated default Generator
persian-rug
A type that has an associated default GeneratorWithPersianRug
Something which can generate a sequence of objects of some type.
persian-rug
Something which can generate a sequence of objects of some
persian_rug::Contextual
type.
Derive Macros
Derive the Buildable
trait for a type, creating a suitable
Builder
.
persian-rug
Derive the BuildableWithPersianRug
trait for a type, creating a
suitable BuilderWithPersianRug
.
Derive the Generatable
trait for a type, creating a suitable
Generator
.
persian-rug
Derive the GeneratableWithPersianRug
trait for a type, creating
a suitable GeneratorWithPersianRug
.