Macro tor_config::list_builder::define_list_builder_helper

macro_rules! define_list_builder_helper {
    {
        $(#[ $docs_and_attrs:meta ])*
        $vis:vis
        struct $ListBuilder:ident $( [ $($generics:tt)* ] )?
        $( where [ $($where_clauses:tt)* ] )?
        {
            $field_vis:vis $things:ident : [$EntryBuilder:ty] $(,)?
        }
        built: $Built:ty = $built:expr;
        default = $default:expr;
        $( item_build: $item_build:expr; )?
        $(#[ serde $serde_attrs:tt ] )+
    } => { ... };
    {
        $(#[ $docs_and_attrs:meta ])*
        $vis:vis
        struct $ListBuilder:ident $( [ $($generics:tt)* ] )?
        $( where [ $($where_clauses:tt)* ] )?
        {
            $field_vis:vis $things:ident : [$EntryBuilder:ty] $(,)?
        }
        built: $Built:ty = $built:expr;
        default = $default:expr;
        $( item_build: $item_build:expr; )?
    } => { ... };
}

Define a list builder struct for use with define_list_builder_accessors

Generates an builder struct that can be used with derive_builder and define_list_builder_accessors to configure a list of some kind.

See the list_builder module documentation for an overview.

Generated struct

This macro-generated builder struct contains Option<Vec<ThingBuilder>>, to allow it to distinguish “never set” from “has been adjusted or set, possibly to the empty list”.

This struct is not exposed as part of the API for setting the configuration. Generally the visibility ($vis) should be private, but sometimes pub(crate) or pub is necessary, for example if the list is to be included in a struct in another module or crate. Usually $field_vis should be the same as $vis.

#[derive(Default, Clone, Debug, Serialize, Deserialize)] will be applied to the generated builder, but you can specify other attributes too. There is no need to supply any documentation; this is an internal struct and the macro will supply a suitable (bland) doc comment. (If you do supply documentation, the autogenerated docs will be appended, so start with a summary line.) Documentation for the semantics and default value should be applied to the field(s) in the containing struct(s).

#[serde(transparent)] will be applied to the generated ThingBuilder struct, so that it deserializes just like Option<Vec<Thing>>.

Input to the macro

For the input syntax, refer to the docs autogenerated from the macro’s matcher.

The built clause specifies the type of the built value, and how to construct it. In the expression part, things (the field name) will be the default-resolved Vec<Thing>; it should be consumed by the expression. If the built value is simply a Vec, you can just write built: ThingList = things;.

The default clause must provide an expression evaluating to a Vec<ThingBuilder>.

The item_build clause, if supplied, provides a closure with type FnMut(&ThingBuilder) -> Result<Thing, ConfigBuildError>; the default is to call thing_builder.build().

The #[ serde $serde_attrs:tt ], if supplied, replace the serde attribute #[serde(transparent)]. The transparent attribute is applied by default to arrange that the serde view of the list is precisely Option<Vec>. If serialisation is done another way, for example with #[serde(into)], that must be specified here.

[$generics] are generics for $ListBuilder. Inline bounds (T: Debug) are not supported; use a where clause instead. Due to limitations of macro_rules, the parameters must be within [ ] rather than < >, and an extraneous pair of [ ] must appear around any $where_clauses.