//! Derive-deftly macro for deriving configuration objects.

//!

//! The macro defined here makes a configuration object

//! able to participate in the arti configuration system by giving

//! it a Builder type implementing the appropriate serde traits.

//!

//! It is more ergonomic and less error-prone for our purposes than

//! `derive_builder`.

//!

//! ## Basic usage:

//!

//! ```

//! use derive_deftly::Deftly;

//! use tor_config::derive::prelude::*;

//!

//! #[derive(Deftly, Clone, Debug, PartialEq)]

//! #[derive_deftly(TorConfig)]

//! pub struct ExampleConfig {

//!     #[deftly(tor_config(default))]

//!     owner_uid: Option<u32>,

//!

//!     #[deftly(tor_config(default = r#" "~".to_string() "#))]

//!     path: String,

//! }

//! ```

//! For topic-specific information, see one of the following:

//!

//! * [How to declare a configuration type](doc_howto)

//! * [Code generated by the tor_config macro](doc_generated_code)

//! * [Reference: Attributes supported by the tor_config macro](doc_ref_attrs)

//! * [Differences from derive_builder](doc_differences)

//! * [Types with magic handling](doc_magic_types)

/// How to declare a configuration type

///

/// ## Getting started

///

/// Every configuration type should implement at least `Clone` and `Debug`;

/// it should almost[^partialeq-notest] always implement `PartialEq` too.

/// In addition to these, you should use `derive(Deftly)` and `derive_deftly(TorConfig)`

/// to use this macro.

///

/// You can start out by copying this template:

///

/// ```

/// use derive_deftly::Deftly;

/// use tor_config::derive::prelude::*;

///

/// #[derive(Deftly, Clone, Debug, PartialEq)]

/// #[derive_deftly(TorConfig)]

/// pub struct XyzzyConfig {

///     // ...

/// }

/// ```

///

/// ## Declaring fields

///

/// At this point, you start declaring the fields that should appear in the configuration.

/// You declare them as struct fields (as usual);

/// but to avoid mistakes, you need to specify the default behavior for each field.

/// You typically do this in one of the following ways:

///

/// ```

/// # use derive_deftly::Deftly;

/// # use tor_config::derive::prelude::*;

/// # fn some_function() -> u32 { 7 }

/// # #[derive(Deftly, Clone, Debug, PartialEq)]

/// # #[derive_deftly(TorConfig)]

/// # pub struct Foo {

///

/// // If the user doesn't set this field, we set it by calling some_function().

/// #[deftly(tor_config(default="some_function()"))]

/// value1: u32,

///

/// // If the user doesn't set this field, we set it by calling Default::default().

/// #[deftly(tor_config(default))]

/// value2: String,

///

/// // This field has no default!  It's an error if the user doesn't set this.

/// // (See warnings on no_default below.)

/// #[deftly(tor_config(no_default))]

/// value3: u16,

/// # }

/// ```

///

/// Notes:

/// - There is no "default" behavior for the unset fields: you need to say which one you want.

///   This requirement is meant to avoid programming errors.

/// - Try to avoid using `no_default` on any configuration element unless you truly want the user

///   to specify it in their configuration file every time this section exists.

///   It's okay to use `no_default`

///   on something like the address of a fallback directory

///   (where each one needs to be fully specified)

///   or the nickname of an onion service

///   (which needs to be specified for every onion service that exists).

/// - If you use `no_default`, you will need to use [`no_default_trait`] on the structure

///   as a whole.

///

/// ## Other things you can do

///

/// There are many other attributes you can set on struct and fields

/// to control their behavior.

/// See [the reference](doc_ref_attrs) for more information.

///

/// <!-- TODO: Write a cookbook for common patterns. -->

///

/// [^partialeq-notest]: If you decide not to implement `PartialEq` for some reason,

///    you will need to use the [`no_test_default`] attribute to suppress a test that requires it.

///    (I do not really know why you would do this.  Just implement `PartialEq`, or

///    edit this documentation to explain why people would sometimes not want to implement it.)

///

/// [`no_default_trait`]: crate::derive::doc_ref_attrs#tmeta:no_default_trait

/// [`no_test_default`]: crate::derive::doc_ref_attrs#tmeta:no_test_default

pub mod doc_howto {}

/// Code generated by the tor_config macro

///

/// > Here we describe the code generated by the `derive_deftly(TorConfig)` macro.

/// > Note that this is the _default_ behavior;

/// > particular [attributes](doc_ref_attrs) not described here will override it.

///

/// <!-- TODO: Add "See: X" notes links to the options that override each thing? -->

///

/// The `tor_config` macro generates a Builder struct, with a name formed by appending

/// `Builder` to the name of the configuration struct.

/// That is, if the configuration struct is `MyConfig`,

/// the macro generates `MyConfigBuilder`.

///

/// The builder struct has the same visibility as the configuration struct.

/// The builder struct has,

/// for every ordinary field[^ordinary] of type T in the configuration struct,

/// a field with the same name and type `Option<T>`.

/// For every [sub-builder] field in the configuration struct of type `T`,

/// it has a field with the same name and the type `TBuilder`.

/// These fields are private.

///

/// The builder struct implements [`serde::Serialize`] and [`serde::Deserialize`].

/// Every field is marked with `#[serde(default)]` to allow it to be absent

/// in the toml configuration.

///

/// The builder struct implements [`derive_deftly::Deftly`].

///

/// The builder struct derives `Default`, `Clone`, and `Debug`.

/// It also has a `new()` method that calls `Default::default()`.

///

/// The builder struct implements

/// [`Builder`](crate::load::Builder),

/// [`ConfigBuilder`](crate::load::ConfigBuilder),

/// [`ExtendBuilder`](crate::extend_builder::ExtendBuilder)

/// and [`Flattenable`](crate::Flattenable).

///

/// The _configuration struct_ receives a generated "builder" method,

/// of type `fn () -> MyConfigBuilder`.

/// This function calls the builder's `Default::default()` method.

///

/// For every ordinary[^ordinary] field of type T in the configuration struct,

/// the builder has a **setter method** with the same name,

/// of type `fn (&mut self, value: T) -> &mut Self`.

/// The setter method sets the corresponding field in `self` to `Some(value)`,

/// and returns `self``.

///

/// For every [sub-builder] field of type SubCfg in the configuration struct,

/// the builder has an accessor method with the same name,

/// returning `&mut SubCfgBuilder`.

///

/// The builder has a **build method**, with the name `build`,

/// of type `fn (&self) -> Result<MyConfig, ConfigBuildError>`.

/// It has the same visibility as the builder struct.

/// For every field in the builder of value `Some(x)`,

/// it sets the corresponding field in the configuration object to `x`.

/// For every field in the builder of value `None`,

/// it sets the corresponding field in the configuration object to its default,

/// or returns an error,

/// depending on the attributes set on the field.

/// For every field in the builder with a [sub-builder],

/// it invokes the build method on that sub-builder,

/// and sets the corresponding field in the configuration object to its result.

///

/// A new `#[cfg(test)]` module is generated, with tests for the builder behavior.

/// This module is called `test_my_config_builder`, with `my_config` replaced with the

/// snake-case name of your actual configuration type.

///

/// [^ordinary]: For the purpose of this documentation,

///     a field is "ordinary" if it does not have a [sub-builder].

///

///

/// [sub-builder]: crate::derive::doc_ref_attrs#fmeta:sub_builder

pub mod doc_generated_code {}

/// Reference: Attributes supported by the tor_config macro

///

/// * [Top-level attributes](crate::derive::doc_ref_attrs#tmeta)

/// * [Field-level attributes](crate::derive::doc_ref_attrs#fmeta)

///

/// <div id="tmeta">

///

/// ## Top-level attributes

///

/// </div>

///

/// These attributes can be provided at the top-level, right after

/// `derive_deftly(TorConfig)` and before `pub struct FooConfig`.

///

/// <div id="tmeta:no_serialize_trait">

///

/// ### `deftly(tor_config(no_serialize_trait))`  — Don't derive Serialize for the builder struct

///

/// </div>

///

/// By default, the generated Builder will derive [`serde::Serialize`].

/// This attribute suppresses that behavior.

///

///

/// <div id="tmeta:no_deserialize_trait">

///

/// ### `deftly(tor_config(no_deserialize_trait))` — Don't derive Deserialize for the builder struct

///

/// </div>

///

/// By default, the generated Builder will implement [`serde::Deserialize`].

/// This attribute suppresses that behavior.

///

/// Using this option will prevent your type from participating directly

/// in the Arti configuration system.

///

///

/// <div id="tmeta:no_flattenable_trait">

///

/// ### `deftly(tor_config(no_flattenable_trait))`  — Don't derive Flattenable for the builder struct

///

/// </div>

///

/// By default, the generated Builder will derive [`Flattenable`](crate::Flattenable).

/// This attribute suppresses that behavior.

///

/// <div id="tmeta:no_extendbuilder_trait">

///

/// ### `deftly(tor_config(no_extendbuilder_trait))`  — Don't derive ExtendBuilder for the builder struct

///

/// </div>

///

/// By default, the generated Builder will derive [`ExtendBuilder`].

/// This attribute suppresses that behavior.

///

/// <div id="tmeta:no_default_trait">

///

/// ### `deftly(tor_config(no_default_trait))` — Don't derive Default for the config struct

///

/// </div>

///

/// By default, the macro will derive [`Default`] on the configuration type

/// by creating a default builder, and constructing the configuration type with it.

///

/// <div id="tmeta:no_test_default">

///

/// ### `deftly(tor_config(no_test_default))` — Don't test Default for the config struct

///

/// </div>

///

/// By default, the macro will implement a test to make sure that its generated `Default`

/// implementation produces the same result as deserializing an empty configuration builder,

/// and building it.

/// This attribute prevents that test from being generated.

///

/// The test is also omitted when [`no_default_trait`] or [`no_deserialize_trait`] is given.

///

/// > Note: You must specify this option if the configuration type has any generic parameters.

/// > Otherwise, it's best to avoid this attribute.

/// >

/// > TODO: We should remove this limitation if we can.

///

/// <div id="tmeta:no_builder_trait">

///

/// ### `deftly(tor_config(no_builder_trait))` — Don't derive Builder for the builder struct

///

/// </div>

///

/// By default, the builder will implement [`tor_config::load::Builder`](crate::load::Builder).

/// This attribute suppresses that behavior.

///

/// > This attribute's name ends with `_trait` to remind the caller that the Builder struct itself

/// > will still be implemented.

///

/// <div id="tmeta:no_buildable_trait">

///

/// ### `deftly(tor_config(no_buildable_trait))` — Don't derive Buildable for the config struct

///

/// </div>

///

/// By default, the configuration struct will implement

/// [`tor_config::load::Buildable`](crate::load::Buildable).

/// This attribute suppresses that behavior.

///

/// <div id="tmeta:attr">

///

/// ### `deftly(tor_config(attr = ".."))` — Apply an attribute to the builder struct

///

/// </div>

///

/// This attribute passes its contents through to a new attribute on the derived builder struct.

/// For example, you can make the builder derive `PartialOrd` by saying

///

/// ```no_compile

/// #[deftly(tor_config(attr= "derive(PartialOrd)"))]

/// ```

///

/// (See also [`attr`](crate::derive::doc_ref_attrs#fmeta:attr) for fields.)

///

/// <div id="tmeta:pre_build">

///

/// ### `deftly(tor_config(pre_build = ".."))` — Call a function before building

///

/// </div>

///

/// This attribute makes the generated `build()` method call a validation function on itself

/// **before** it builds the configuration.  The function must take `&FooBuilder`

/// as an argument, and return `Result<(),ConfigBuildError>`.  If the function

/// returns an error, then the build method fails with that error.

///

/// Example:

/// ```

/// # use derive_deftly::Deftly;

/// # use tor_config::{derive::prelude::*, ConfigBuildError};

/// #[derive(Clone,Debug,PartialEq,Deftly)]

/// #[derive_deftly(TorConfig)]

/// #[deftly(tor_config(pre_build="Self::must_be_odd"))]

/// pub struct FavoriteOddNumber {

///     #[deftly(tor_config(default="23"))]

///     my_favorite: u32,

/// }

///

/// impl FavoriteOddNumberBuilder {

///     fn must_be_odd(&self) -> Result<(), ConfigBuildError> {

///         let Some(fav) = self.my_favorite else { return Ok(()); };

///         if fav % 2 != 1 {

///             return Err(ConfigBuildError::Invalid {

///                 field: "my_favorite".to_string(),

///                 problem: format!("{fav} was not an odd number")

///             })

///         }

///         Ok(())

///     }

/// }

/// ```

///

/// See also [`post_build`].

///

/// <div id="tmeta:post_build">

///

/// ### `deftly(tor_config(post_build = ".."))` — Call a function after building

///

/// </div>

///

/// This attribute makes the generated `build()` method call a validation function

/// on the configuration **after** it is built.

/// The function must take the configuration

/// _by value_ as an argument,

/// and `Result<`(the configuration)`,ConfigBuildError>`.  If the function

/// returns an error, then the build method fails with that error.

///

/// Example:

/// ```

/// # use derive_deftly::Deftly;

/// # use tor_config::{derive::prelude::*, ConfigBuildError};

/// #[derive(Clone,Debug,PartialEq,Deftly)]

/// #[derive_deftly(TorConfig)]

/// #[deftly(tor_config(post_build="FavoriteEvenNumber::must_be_even"))]

/// pub struct FavoriteEvenNumber {

///     #[deftly(tor_config(default="86"))]

///     my_favorite: u32,

/// }

///

/// impl FavoriteEvenNumber {

///     fn must_be_even(self) -> Result<Self, ConfigBuildError> {

///         if self.my_favorite % 2 != 0 {

///             return Err(ConfigBuildError::Invalid {

///                 field: "my_favorite".to_string(),

///                 problem: format!("{} was not an even number", self.my_favorite)

///             })

///         }

///         Ok(self)

///     }

/// }

/// ```

///

/// > Note:

/// > You can also use this attribute to clean up or normalize the configuration object.

///

/// <div id="tmeta:vis">

///

/// ### `deftly(tor_config(vis = ".."))` — Change visibility of the builder

///

/// </div>

///

/// By default, the builder struct is generated with the same visibility as the

/// configuration struct.

/// You can use this attribute to change its visibility.

///

///

/// <div id="tmeta:build_fn_name">

///

/// ### `deftly(tor_config(build_fn(name = "..")))` — Change name of the build method

///

/// </div>

///

/// By default, the generated build method is called `build`.

/// You can use this attribute to change its name.

///

/// <div id="tmeta:build_fn_vis">

///

/// ### `deftly(tor_config(build_fn(vis = "..")))` — Change visibility of the build method

///

/// </div>

///

/// By default, the `build()` method has the same visibility as the builder struct.

/// You can use this attribute to change its visibility.

///

/// See also:

/// * [`deftly(tor_config(vis = ".."))`](crate::derive::doc_ref_attrs#tmeta:vis)

///

/// <div id="tmeta:build_fn_error">

///

/// ### `deftly(tor_config(build_fn(error = "..")))` — Change return error type of the build method.

///

/// </div>

///

/// By default, the `build()` method returns [`ConfigBuildError`

/// on failure.  You can change the error type with this attribute.

///

/// You will probably need to use this attribute along with [`build_fn(missing_field)`],

/// if any of your fields are mandatory.

///

/// <div id="tmeta:build_fn_missing_field">

///

/// ### `deftly(tor_config(build_fn(missing_field = "..")))` — Code to generate a missing field error.

///

/// </div>

///

/// By default, when a required field is not set, the `build()` method returns

/// `Err(E::MissingField { field: "field_name".to_string() })`,

/// where `E` is [`ConfigBuildError`] or the type configured with [`build_fn(error)`].

/// You can use this attribute to override this behavior.

/// Its value should be an expression evaluating to a closure of type

/// `FnOnce(&str) -> E`.

///

/// > For compatibility with `derive_builder`'s version of `build_fn(error)``, you can say:

/// > ```no_compile

/// > #[build_fn(error="SomeError",

/// >            missing_field=

/// >     r#"|fname| derive_builder::UninitializedFieldError(

/// >                                  fname.to_string()

/// >                ).into()"

/// > )]

/// > ```

///

/// <div id="fmeta">

///

/// ## Field-level attributes

///

/// </div>

///

/// <div id="fmeta:default_default">

///

/// ### `deftly(tor_config(default)))` — Use Default::default() when no value is provided

///

/// </div>

///

/// When this attribute is provided, if the given field is absent in the builder,

/// the `build()` method will set its value to `Default::default()`.

///

/// For each field, you must specify exactly one of

/// [`default`], [`default =`], [`no_default`], [`build`], [`try_build`], or [`sub_builder`].

///

/// <div id="fmeta:default_equals">

///

/// ### `deftly(tor_config(default = "..")))` — Use a given value when no value is provided

///

/// </div>

///

/// When this attribute is provided, if the given field is absent in the builder,

/// the `build()` method will set its value to the value of the provided expression.

/// The expression may invoke a function, but cannot use `self`.

///

/// The type of the default must match the type of the field _in the builder_.

/// Usually this is the same type as in the built configuration, but for some

/// ["magic" types](crate::derive::doc_magic_types), the two can differ.

/// (If this is the case, we note the fact with the "magic" type's documentation.)

///

/// For each field, you must specify exactly one of

/// [`default`], [`default =`], [`no_default`], [`build`], [`try_build`], or [`sub_builder`].

///

///

/// <div id="fmeta:no_default">

///

/// ### `deftly(tor_config(no_default))` — Do not provide a default for this field.

///

/// </div>

///

/// When this attribute is provided, if the given field is absent in the builder,

/// the `build()` method will fail with an error.

///

/// For each field, you must specify exactly one of

/// [`default`], [`default =`], [`no_default`], [`build`], [`try_build`], or [`sub_builder`].

///

/// > When you set this attribute on a field, you must also set the top-level

/// > [`no_default_trait`] attribute,

/// > since there will not be a meaningful value for the configuration struct.

/// >

/// > Don't use this option on any config struct that's always present with a multiplicity of one,

/// > or else the empty configuration will become invalid.

///

/// <div id="fmeta:build">

///

/// ### `deftly(tor_config(build = ".."))` — Call a function to build this field.

///

/// </div>

///

/// When this attribute is provided, you can completely override the way that this field is constructed.

/// The expression must evaluate to a function taking `&Builder` as an argument,

/// and returning the type of the field.

///

/// For each field, you must specify exactly one of

/// [`default`], [`default =`], [`no_default`], [`build`], [`try_build`], or [`sub_builder`].

///

/// > Be careful with this attribute: it can lead to counterintuitive behavior for the end user.

///

/// Example:

///

/// ```

/// # use derive_deftly::Deftly;

/// # use tor_config::{derive::prelude::*, ConfigBuildError};

/// #[derive(Clone,Debug,PartialEq,Deftly)]

/// #[derive_deftly(TorConfig)]

/// pub struct LowercaseExample {

///     #[deftly(tor_config(build="Self::build_lc"))]

///     lc: String,

/// }

/// impl LowercaseExampleBuilder {

///     fn build_lc(&self) -> String {

///         let s = self.lc.as_ref().map(String::as_str).unwrap_or("");

///         s.to_lowercase()

///     }

/// }

/// ```

///

/// <div id="fmeta:try_build">

///

/// ### `deftly(tor_config(try_build = ".."))` — Call a fallible function to build this field.

///

/// </div>

///

/// When this attribute is provided, you can completely override the way that this field is constructed.

/// The expression must evaluate to a function taking `&Builder` as an argument,

/// and returning `Result<T, ConfigBuildError>`, where `T` is the type of the field.

///

/// For each field, you must specify exactly one of

/// [`default`], [`default =`], [`no_default`], [`build`], [`try_build`], or [`sub_builder`].

///

/// > Be careful with this attribute: it can lead to counterintuitive behavior for the end user.

///

/// Example:

///

/// ```

/// # use derive_deftly::Deftly;

/// # use tor_config::{derive::prelude::*, ConfigBuildError};

/// #[derive(Clone,Debug,PartialEq,Deftly)]

/// #[derive_deftly(TorConfig)]

/// pub struct SqrtExample {

///     #[deftly(tor_config(try_build="Self::build_sqrt"))]

///     val: f64,

/// }

/// impl SqrtExampleBuilder {

///     fn build_sqrt(&self) -> Result<f64, ConfigBuildError> {

///         let v = self.val.unwrap_or(0.0).sqrt();

///         if v.is_nan() {

///             return Err(ConfigBuildError::Invalid {

///                 field: "val".to_string(),

///                 problem: format!("{v} was negative")

///             })

///         }

///         Ok(v)

///     }

/// }

/// ```

///

/// <div id="fmeta:sub_builder">

///

/// ### `deftly(tor_config(sub_builder))` — Declare a field to contain a nested configuration

///

/// </div>

///

/// This attribute is what allows configuration structures to nest.

/// When you set this attribute on a field of type `InnerCfg`,

/// the builder structure will contain a field of type `InnerCfgBuilder`.

/// In order to construct the field, the `build()` method will call

/// `InnerCfgBuilder::build()`.

///

/// For each field, you must specify exactly one of

/// [`default`], [`default =`], [`no_default`], [`build`], [`try_build`], or [`sub_builder`].

///

/// <div id="fmeta:sub_builder_build_fn">

///

/// ### `deftly(tor_config(sub_builder(build_fn = "...")))` — Call a different function on this sub-builder

///

/// </div>

///

/// By default, when [`sub_builder`] is in use,

/// the `build()` method is used to generate the inner configuration object.

/// This attribute changes the name of the function that is called on the inner builder.

///

/// <div id="fmeta:no_sub_builder">

///

/// ### `deftly(tor_config(no_sub_builder))` — Allow a Buildable field _without_ a sub_builder.

///

/// </div>

///

/// By default, the `TorConfig` macro inserts code to checks whether each field

/// implements [`Buildable`], and causes a compile-time error if any such field

/// does not have an explicit [`sub_builder`], [`build`], [`try_build`],

/// or [`no_magic`] declaration.

/// This attribute overrides this check, and allows you to have a field

/// implementing [`Buildable`] without using the `sub_builder` pattern.

///

///

/// <div id="fmeta:list">

///

/// ### `deftly(tor_config(list))` — Declare a field to contain a nested list of items.

///

/// </div>

///

/// This attribute should be used on every field containing a `Vec`,

/// `BTreeSet`, `HashSet`, or similar.

/// It causes the an appropriate [list-builder](crate::list_builder)

/// and set of accessors to be generated.

///

/// When using this attribute, you must also provide a [`default =`] producing a `Vec`

/// of the builder type, and either [`list(element(build))`] or [`list(element(clone))`].

///

/// Examples:

///

/// ```no_compile

/// // The builder and the constructed list will both contain u32.

/// #[deftly(tor_config(list(element(clone)), default = "vec![7]"))]

/// integers: Vec<u32>,

///

/// // The builder will contain a Vec<MyTypeBuilder>;.

/// #[deftly(tor_config(list(), (element(build)), default = "vec![]"))]

/// objects: Vec<MyType>

/// ```

///

/// <div id="fmeta:list_listtype">

///

/// ### `deftly(tor_config(list(listtype = ...)))`

///

/// </div>

///

/// Usually, the name of the list type alias and builder object  based on the struct and the field name.

/// You can provide a different name for the list type alias using this attribute, as in

/// `listtype = "TypeName"`.

/// The list builder will then be constructed with the list type name, suffixed with `Builder`.

///

///  <!-- TODO:

///    We could support a third option, where we give an explicit closure to build elements.

///    We could support an option where the types in the builder vec are listed explicitly.

/// -->

///

/// <div id="fmeta:list_element_build">

///

/// ### `deftly(tor_config(list(element(build)))` — Declare that the list builder contains sub-builders.

///

/// </div>

///

/// Used along with [`list`],

/// and indicates the elements of the built list should be constructed via

/// builders themselves.  When this attribute is used, the builder structure

/// will contain a Vec of builders for the list's elements.

///

/// If this attribute is given a value, it will be used as the name of the

/// "build" method for the list elements.

///

/// <div id="fmeta:list_element_clone">

///

/// ### `deftly(tor_config(list(element(clone)))` — Declare that the list builder objects should be cloned directly.

///

/// </div>

///

/// Used along with [`list`],

/// and indicates the elements of the built list should be cloned directly

/// from those in the builder.  When this attribute is used, the builder structure

/// will contain a Vec whose elements are the same type as those of the genated list.

///

/// <div id="fmeta:map">

///

/// ### `deftly(tor_config(map))` — Use a map-builder pattern.

///

/// </div>

///

/// This attribute should be used on every field containing a `HashMap` or `BTreeMap`

/// whose key is a `String`, and whose value type is a [`Buildable`].

/// It causes the template to generate a map builder type and corresponding accessor functions.

/// The map builder behaves like a map from String to the builder type.

///

/// If a value is provided for this attribute, it is used as the name of the

/// map type alias, and suffixed with `Builder` to get the name for the builder type.

/// Otherwise, the map type alias is derived from the name of the struct and the field.

///

/// The [`default =`] attribute is mandatory with this attribute.

///

/// For more information on the generated code, see

/// [`define_map_builder`](crate::define_map_builder).

///

/// <div id="fmeta:map_maptype">

///

/// ### `deftly(tor_config(list(maptype = ...)))`

///

/// </div>

///

/// Usually, the name of the map type alias and builder object  based on the struct and the field name.

/// You can provide a different name for the map type alias using this attribute, as in

/// `maptype = "TypeName"`.

/// The map builder will then be constructed with the map type name, suffixed with `Builder`.

///

/// <div id = "fmeta:setter_name">

///

/// ### `deftly(tor_config(setter(name = "..")))` — Change the name of the setter function

///

/// </div>

///

/// By default, the setter function for a field has the same name as its field.

/// You can provide a different name in this attribute.

///

/// <div id="fmeta:setter_vis">

///

/// ### `deftly(tor_config(setter(vis = "..")))` — Change the visibility of the setter function

///

/// </div>

///

/// By default, the setter function for a field has the same visibility as the builder type.

/// You can provide a different visibility in this attribute.

///

/// <div id="fmeta:setter_skip">

///

/// ### `deftly(tor_config(setter(skip)))` — Do not generate a setter function

///

/// </div>

///

/// By default, the builder generates a setter function for every field.

/// You can tell it not to do so for a single field by providing this attribute.

///

/// <div id="fmeta:setter_into">

///

/// ### `deftly(tor_config(setter(into)))` — Have the setter function accept `impl Into<T>`

///

/// </div>

///

/// By default, the setter function expects an argument of type `T`,

/// where `T` is the same type of the field.

/// When this option is provided, the setter instead expects an argument of type `impl Into<T>`,

/// and calls [`Into::into`] on it to set the field.

///

/// <div id="fmeta:setter_try_into">

///

/// ### `deftly(tor_config(setter(try_into)))` — Have the setter function accept `impl TryInto<T>`

///

/// </div>

///

/// By default, the setter function expects an argument of type `T`,

/// where `T` is the same type of the field.

/// When this option is provided, the setter instead expects an argument of type `impl TryInto<T>`,

/// and calls [`TryInto::try_into`] on it to set the field.

/// If `try_into` returns an error, the setter function returns that error.

///

/// <div id="fmeta:setter_strip_option">

///

/// ### `deftly(tor_config(setter(strip_option)))` — Have the setter for `Option<T>` accept `T`

///

/// </div>

///

/// This attribute requires that the field itself have type `Option<T>` for some `T`.

/// Instead of taking `Option<T>` as an argument, the setter now accepts `T`.

///

/// <!-- TODO -- Do we still want this, given that option magic should take care of it for us,

/// and will do a better job? -->

///

/// <div id="fmeta:field_ty">

///

/// ### `deftly(tor_config(field(ty = "..")))` — Change the type of a field in the builder

///

/// </div>

///

/// By default, for every field of type `T` in the configuration,

/// the builder has a field of type `Option<T>`.

/// This attribute changes the type of the field in the builder to the provided type.

///

/// > This attribute has no effect on the generated setter or builder code.

/// > Therefore, you will typically need to use it along with

/// > the [`setter(skip)`], [`build`], and [`extend_with`] field attributes.

///

/// Example:

///

/// ```

/// # #![allow(unexpected_cfgs)]

/// # use derive_deftly::Deftly;

/// # use tor_config::{derive::prelude::*, ConfigBuildError};

/// #[derive(Clone,Debug,PartialEq)]

/// pub struct ParsedValue {

///    // ...

/// }

/// impl std::str::FromStr for ParsedValue {

///     type Err = String;

///     fn from_str(s: &str) -> Result<Self, Self::Err> {

///         // ...

/// #       unimplemented!()

///     }

/// }

///

/// #[derive(Clone,Debug,PartialEq,Deftly)]

/// #[derive_deftly(TorConfig)]

/// pub struct MyConfig {

///     #[deftly(tor_config(

///         try_build = r#"Self::try_build_behavior"#,

///         field(ty = "Option<String>"),

///         setter(skip)

///     ))]

///     behavior: ParsedValue,

/// }

///

/// impl MyConfigBuilder {

///     pub fn behavior(&mut self, s: impl AsRef<str>) -> &mut Self {

///         self.behavior = Some(s.as_ref().to_string());

///         self

///     }

///     fn try_build_behavior(&self) -> Result<ParsedValue, ConfigBuildError> {

///         self.behavior

///             .as_ref()

///             .map(String::as_str)

///             .unwrap_or("Leave the macro processor. Take the cannoli.")

///             .parse()

///             .map_err(|problem| ConfigBuildError::Invalid {

///                 field: "behavior".to_string(),

///                 problem,

///             })

///     }

/// }

/// ```

///

/// <div id="fmeta:apply_field_default">

///

/// ### `deftly(tor_config(apply_field_default = { FIELD_DEFAULT }))` — Apply a default for a specialized builder.

///

/// </div>

///

/// By default, the builder's generated [`apply_defaults()`] method

/// does nothing for fields with [`build`] or [`try_build`] attributes,

/// and recursively calls [`apply_defaults()`]

/// for [`sub_builder`] fields.

///

/// This attribute replaces that behavior for a single field.

/// FIELD_DEFAULT must be an expression that expands to a closure taking `&mut Self` as an argument.

/// It checks whether the field is set,

/// and sets it to a reasonable default otherwise.

/// It must return Result<(), E>, where E is some type implementing `Into<ConfigBuildError>`.

/// Within `FIELD_DEFAUlT`, `self` refers to the `Builder`.

/// The [`build`] or [`try_build`] functions for that field may assume

/// that the FIELD_DEFAULT has already been executed.

///

/// The code in this attribute is invoked after earlier fields are set to their defaults,

/// and before later fields are set to theirs.

///

/// It is an error to use this attribute along with [`default`] or [`no_default`].

///

/// <div id="fmeta:field_vis">

///

/// ### `deftly(tor_config(field(vis = "..")))` — Change the visibility of a field in the builder

///

/// </div>

///

/// By default, fields in the builder are private.

/// This attribute changes their visibility to the one provided.

///

///

/// <div id="fmeta:skip">

///

/// ### `deftly(tor_config(skip))` — Do not generate the field in the builder

///

/// </div>

///

/// If this attribute is present, no field is generated in the builder for this field.

/// Implies [`setter(skip)`].  Requires [`build`].

///

/// <div id="fmeta:attr">

///

/// ### `deftly(tor_config(attr = "..")))` — Apply an attribute to the field in the builder

///

/// </div>

///

/// Any attribute provided here is applied to the declared field in the builder.

///

/// Example:

/// ```no_compile

/// #[deftly(tor_config(attr = "allow(deprecated)"))]

/// x: SomeDeprecatedType,

/// ```

///

/// See also the [`cfg`](crate::derive::doc_ref_attrs#fmeta:cfg) and [`serde`] attributes.

///

/// <div id="fmeta:serde">

///

/// ### `deftly(tor_config(serde = "..")))` — Apply a serde attribute to the field in the builder

///

/// </div>

///

/// Any serde attribute provided here is applied to the declared field in the builder.

///

/// Example:

/// ```no_compile

/// #[deftly(tor_config(serde = r#"alias = "old_name_of_field" "#))]

/// current_name_of_field: String,

/// ```

///

/// Attributes applied with `serde` apply after any specified with

/// [`attr`](crate::derive::doc_ref_attrs#fmeta:attr) instead.

///

/// > This is a convenience attribute; you could just use

/// > [`attr`](crate::derive::doc_ref_attrs#fmeta:attr) instead.

///

/// <!-- TODO: write up a list of recommended serde attributes -->

///

/// <div id="fmeta:extend_with">

///

/// ### `deftly(tor_config(extend_with = ""))` — Change the ExtendBuilder behavior for a field.

///

/// </div>

///

/// Unless you specify [`no_extendbuilder_trait`], the builder type will

/// implement [`ExtendBuilder`],

/// and will need a way to replace or extend every field in the builder with

/// the value from another builder.

/// This attribute lets you override the default behavior for a single field.

/// It expects an expression that evaluates to type

/// `FnOnce(&mut T, T, `[`ExtendStrategy`]`)`,

/// where `T` is the type of the field in the builder.

///

/// <div id="fmeta:cfg">

///

/// ### `deftly(tor_config(cfg = "..")))` — Mark a field as conditionally present

///

/// </div>

///

/// This option causes a field in the builder to be conditionally present or absent at compile time,

/// similar to the ordinary [`cfg`] attribute.

/// However, unlike with the ordinary `cfg` attribute,

/// if the user provides any configuration values for this field when it is disabled,

/// the generated `build()` code will emit a warning via [`tracing`] at runtime telling them

/// what feature they would need to turn on.

///

/// If an error is more appropriate than a warning, additionally use

/// [`cfg_reject`].

///

/// > Note that you _cannot_ use this along with a regular [`cfg`] attribute,

/// > since a regular [`cfg`] attribute would suppress the field altogether.

/// > Therefore, the field will still be present in the configuration struct

/// > even when the `cfg` condition is false.

/// > To work around this limitation, it's conventional to arrange for the type of the field

/// > to be `()` when the `cfg` condition is false.

///

/// The `tor_config(cfg_desc)` attribute is mandatory to use along with `cfg`.

/// It should contain a short prepositional phrase

/// describing how the program needs to be built with

/// in order to make this feature present.

/// Examples might be "with RPC support" or "for Windows".

///

///

/// Example:

/// ```

/// # #![allow(unexpected_cfgs)]

/// # use derive_deftly::Deftly;

/// # use tor_config::{derive::prelude::*, ConfigBuildError};

/// #[cfg(feature = "rpc")]

/// pub type RpcOptionType = String;

///

/// #[cfg(not(feature = "rpc"))]

/// type RpcOptionType = ();

///

/// #[derive(Clone,Debug,PartialEq,Deftly)]

/// #[derive_deftly(TorConfig)]

/// pub struct OnionSoupConfig {

///     #[deftly(tor_config(cfg = r#" feature="rpc" "#, cfg_desc = "with RPC support"))]

///     #[deftly(tor_config(default))]

///     rpc_option: RpcOptionType,

/// }

/// ```

///

/// <!-- TODO: This is a warning now, since it is in general only a warning

///      to use an option that is not recognized.

///      We may want to provide a variant that produces an error instead. -->

///

/// <div id="fmeta:cfg_reject">

///

/// ### `deftly(tor_config(cfg_reject))` — Reject the configuration when a feature is missing.

///

/// </div>

///

/// Used alongside [`tor_config(cfg)`](#fmeta:cfg); see also that attribute's documentation.

///

/// Usually, `tor_config(cfg)` causes a warning if values are provided

/// for a compiled-out configuration option.

/// When this attribute is present, then `tor_config(cfg)` causes an error instead.

///

/// <div id="fmeta:cfg_desc">

///

/// ### `deftly(tor_config(cfg_desc = "..")))` — Description of when a field is present.

///

/// </div>

///

/// Used along with [`tor_config(cfg)`](#fmeta:cfg); see that attribute's documentation.

///

/// <div id="fmeta:no_magic">

///

/// ### `deftly(tor_config(no_magic)))` — Disable magic handling based on a field's type

///

/// </div>

///

/// This attribute disables [type-based magic behavior](crate::derive::doc_magic_types)

/// for the current field.

///

/// [`apply_defaults()`]: crate::load::ConfigBuilder::apply_defaults

/// [`build_fn(error)`]:  crate::derive::doc_ref_attrs#tmeta:build_fn_error

/// [`build_fn(missing_field)`]:  crate::derive::doc_ref_attrs#tmeta:build_fn_missing_field

/// [`build`]: crate::derive::doc_ref_attrs#fmeta:build

/// [`Buildable`]: crate::load::Buildable

/// [`ConfigBuildError`]: crate::ConfigBuildError

/// [`cfg_reject`]: crate::derive::doc_ref_attrs#fmeta:cfg_reject

/// [`default =`]: crate::derive::doc_ref_attrs#fmeta:default_equals

/// [`default`]: crate::derive::doc_ref_attrs#fmeta:default_default

/// [`extend_with`]: crate::derive::doc_ref_attrs#fmeta:extend_with

/// [`ExtendBuilder`]: crate::extend_builder::ExtendBuilder

/// [`ExtendStrategy`]: crate::extend_builder::ExtendStrategy

/// [`list`]: crate::derive::doc_ref_attrs#fmeta:list

/// [`list(listtype)`]: crate::derive::doc_ref_attrs#fmeta:list_listtype

/// [`list(element(build))`]:  crate::derive::doc_ref_attrs#fmeta:list_element_build

/// [`list(element(clone))`]:  crate::derive::doc_ref_attrs#fmeta:list_element_clone

/// [`no_default`]: crate::derive::doc_ref_attrs#fmeta:no_default

/// [`no_default_trait`]: crate::derive::doc_ref_attrs#tmeta:no_default_trait

/// [`no_deserialize_trait`]: crate::derive::doc_ref_attrs#tmeta:no_deserialize_trait

/// [`no_extendbuilder_trait`]: crate::derive::doc_ref_attrs#tmeta:no_extendbuilder_trait

/// [`no_flattenable_trait`]: crate::derive::doc_ref_attrs#tmeta:no_flattenable_trait

/// [`no_magic`]: crate::derive::doc_ref_attrs#fmeta:no_default

/// [`post_build`]: crate::derive::doc_ref_attrs#tmeta:post_build

/// [`serde`]:  crate::derive::doc_ref_attrs#fmeta:serde

/// [`setter(skip)`]: crate::derive::doc_ref_attrs#fmeta:setter_skip

/// [`sub_builder`]: crate::derive::doc_ref_attrs#fmeta:sub_builder

/// [`try_build`]: crate::derive::doc_ref_attrs#fmeta:try_build

pub mod doc_ref_attrs {}

/// Differences from `derive_builder`

///

/// * Not all derive_builder attributes have been cloned: only the ones that we used.

/// * Attributes have been adjusted where possible to be easier to use.

/// * It is not necessary to use `impl_standard_builder!`

/// * The appropriate `serde` attributes are automatically provided on the builder.

/// * Every field must have some default behavior specified, or must have the `no_default` option given.

///   (With `derive_builder`, `no_default` is the default, which can result in confusing test failures.)

/// * Sub-builders are supported.

/// * The `cfg` attribute can be used to warn when the user

///   tries to provide a value for an compiled-out field.

/// * There is (limited) support for generics.

/// * The generated documentation is a little better.

/// * `validate` has been renamed to `pre_build`.

/// * There is `post_build` attribute to replace the pattern where we would rename the build function,

///   make it private, and wrap it.

/// * A top-level `build_fn` does not override the build function on sub-builders.

/// * The list builder and map builder patterns are supported via attributes; you don't need separate

///   macros for them.

/// * Builders automatically derive `ExtendBuilder`, `Flattenable`, and `Builder`.

/// * The configuration type automatically derives `Buildable`.

/// * Visibility is set more reasonably.

/// * For many types, we automatically generate setters or serde code that conforms

///   to our standards.

pub mod doc_differences {}

/// # Types with "magic" handling

///

/// The `derive_deftly(TorConfig)` macro currently has automatic "magic"

/// handling for a few types, and a few other types where it can "magically"

/// detect that you forgot to use a certain option that you probably wanted.

///

/// To override the magic handling for a field, use the [`tor_config(no_magic)`]

/// attribute on that field.

///

/// These types are handled on a best-effort basis by matching their names.

/// If you define a field to have another type that is an alias one of these,

/// the macro won't be able to handle it.

/// To prevent this case, we use [`assert_not_impl`]

/// to insure that you will get a compile-time error if you use one of these

/// types under a different name without specifying [`tor_config(no_magic)`].

///

/// The types with magic handling are:

///

/// ## `String`

///

/// The setter for each [`String`] field takes `impl `[`StringOrStr`] as its argument.

/// This trait is implemented by `String` and `&str`.

///

/// > Earlier we had considered having it take `AsRef<str>`, but this is too general

/// > and can lead to unwanted surprises.

///

/// ## `NonZero<T>`

///

/// The setter for a [`NonZero`]`<T>` field takes

/// `impl `[`PossiblyBoundsChecked`]`<T>` as its argument.

/// This trait is implemented by `T` and by [`NonZero`]`<T>`.

///

/// The default for a `NonZero<T>` should be of type `T`.

/// (Passing the value `0` will cause a test failure.)

///

/// When the build() function is called, it returns an error if the provided

/// value was zero.

///

/// ## `Duration`

///

/// The serde implementations for a [`Duration`](std::time::Duration) field

/// use [`humantime_serde`] to accept and generate human-readable strings.

///

/// ## `Option`

///

/// For an `Option<T>` field, the setter accepts both `T` and `Option<T>`.

/// It does so by requiring that the argument implement traits as follows:

///

/// | Field type           | Setter arg trait                     | Implemented by |

/// | -------------------- | ------------------------------------ | -------------- |

/// | `Option<String>`     | [`OptionStringOrStr`]                | `String, &str, Option<String>, Option<&str>` |

/// | `Option<NonZero<T>>` | [`OptionPossiblyBoundsChecked`]`<T>` | `T, NonZero<T>, Option<T>, Option<NonZero<T>> `|

/// | `Option<T>`          | [`PossiblyOption`]`<T>`              | `T, Option<T>` |

///

/// ## `impl Buildable`

///

/// Any type that implements buildable must either use a the [`sub_builder`] attribute,

/// or opt out of it with [`no_sub_builder`] or [`no_magic`].

///

/// ## `Vec`, `HashSet`, `BTreeSet`

///

/// These types require you to either use the [`list`] attribute,

/// or to opt out of it with [`no_sub_builder`] or [`no_magic`].

///

/// ## `HashMap<String, impl Buildable>`, `BTreeMap<String, impl Buildable>`

///

/// These types require you to either use the [`map`] attribute,

/// or to opt out of it with [`no_sub_builder`] or [`no_magic`].

///

/// ## `Option<Duration>`

///

/// This type will cause a compile-time error unless you set [`no_magic`],

/// since there is not actually a way to

/// set a None in toml (other than omitting the value).

///

/// > (TODO: Doesn't) that logic apply to _all_ Option types?

///

/// ## Container of `Duration`.

///

/// These are currently disallowed unless you provide [`no_magic`],

/// and will cause a compile-time error,

/// since we cannot apply our regular serde magic.

///

/// [`StringOrStr`]: crate::setter_traits::StringOrStr

/// [`OptionStringOrStr`]: crate::setter_traits::OptionStringOrStr

/// [`PossiblyBoundsChecked`]: crate::setter_traits::PossiblyBoundsChecked

/// [`OptionPossiblyBoundsChecked`]: crate::setter_traits::OptionPossiblyBoundsChecked

/// [`PossiblyOption`]: crate::setter_traits::PossiblyOption

/// [`NonZero`]: std::num::NonZero

/// [`tor_config(no_magic)`]: crate::derive::doc_ref_attrs#fmeta:no_magic

/// [`list`]: crate::derive::doc_ref_attrs#fmeta:list

/// [`map`]: crate::derive::doc_ref_attrs#fmeta:map

/// [`sub_builder`]: crate::derive::doc_ref_attrs#fmeta:sub_builder

/// [`no_sub_builder`]: crate::derive::doc_ref_attrs#fmeta:no_sub_builder

/// [`no_magic`]: crate::derive::doc_ref_attrs#fmeta:no_magic

pub mod doc_magic_types {}

// TODO:

// - Can I replace cfg() with a single FeatureNotSupported type, or a family of such types?

//   (See #2298.)

// - derive-deftly#109 would let us have better syntax for tmeta:attr, fmeta:attr, and fmeta:serde.

// - We must decide before merging whether we actually _want_ to always accept T

//   for setters on `NonZero<T>`.  There are some places in our code where we do this now:

//   so if we were to stop doing so, we'd be breaking backward compat in the `arti` crate.

//   But that doesn't  mean we need to continue to do so everywhere.

//   (See #2296)

use derive_deftly::define_derive_deftly;

/// Values used by the tor_config derive_deftly template.

#[doc(hidden)]

pub mod exports {

    pub use super::{

        ShouldBeCaughtAsSerdeSpecialCase, ShouldBeCaughtAsSpecialCase, ShouldNotBeUsed,

        ShouldUseListBuilder, ShouldUseMapBuilder, assert_not_impl, bld_magic_check_type,

        bld_magic_cvt, bld_magic_setter_arg_type, bld_magic_setter_cvt, bld_magic_setter_docs,

        bld_magic_type, list_element, normalize_and_invoke, strip_option,

    };

    pub use crate::flatten::derive_deftly_template_Flattenable;

    pub use crate::{

        ConfigBuildError, define_list_builder_accessors, define_list_builder_helper,

        define_map_builder,

        extend_builder::{ExtendBuilder, ExtendStrategy},

        impl_standard_builder,

        load::Buildable as BuildableTrait,

        load::Builder as BuilderTrait,

        load::ConfigBuilder,

    };

    pub use derive_deftly::Deftly;

    pub use figment;

    pub use humantime_serde;

    pub use serde::{Deserialize, Deserializer, Serialize, Serializer};

    pub use serde_value;

    pub use std::{

        clone::Clone,

        convert::{AsRef, Into, TryInto},

        default::Default,

        fmt::Debug,

        option::Option,

        result::Result,

    };

    pub use tracing;

    pub use void;

}

/// Module to import in order to use the tor_config template.

pub mod prelude {

    pub use super::derive_deftly_template_TorConfig;

}

/// Helper to implement `strip_option`: Takes a single argument whose type is an Option<T>,

/// and yields T.

#[doc(hidden)]

#[macro_export]

macro_rules! strip_option {

    { $($($(::)? std::)? option::)? Option $(::)? < $t:ty >  } => { $t };

    { $t:ty } => { compile_error!{"'strip_option' only works on a type that is an Option<X>"} }

}

pub use strip_option;

/// Helper: Takes a @command name, a {type}, and a list of arguments.

/// Determines which macro corresponds to the type,

/// and invokes that macro with arguments: @command {type} args.

///

/// The macros corresponding to types are [`string_typemagic`] for `String`,

/// [`nonzero_typemagic`] for `NonZero*`,

/// and [`no_typemagic`] for everything else.

///

/// Recognized @commands are:

///  - `@build_type {ty}` - The type that should be used as `T` for the builder field's `Option<T>`.

///  - `@setter_arg_type {ty}` - The type that the setter should take as an argument.

///  - `@setter_cvt {ty} {e}`- Code to run inside the setter to convert {e} into a `@build_type {ty}`

///  - `@build_field {ty} {e} {name}` - Code to convert `@build_type {ty}` into {ty}.  Uses the

///    field name `{fname}` to generate errors.

///  - `@check_type {ty}` - Make sure that it is not a bug for this type to have reached this position.

///    Give a compile-time error if it is.

///  - `@setter_docs {ty}` - A string to add to the setter documentation.

#[doc(hidden)]

#[macro_export]

macro_rules! normalize_and_invoke {

    // HEY YOU! DON'T ADD OR REMOVE ANY TYPES WITHOUT READING THE COMMENT BELOW!

    { @$cmd:ident {$( $($(::)? std::)? option:: )? Option $(::)?

        < $( $($(::)? std::)? num:: )? NonZero $(::)? < $t:ty > >

    } $($args:tt)*}                                                                   => { $crate::derive::opt_nz_typemagic!    { @$cmd {$t} $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? option:: )? Option $(::)?

        < $( $($(::)? std::)? num:: )? NonZeroU8 >

    } $($args:tt)*}                                                                    => { $crate::derive::opt_nz_typemagic!   { @$cmd {u8} $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? option:: )? Option $(::)?

        < $( $($(::)? std::)? num:: )? NonZeroU16 >

    } $($args:tt)*}                                                                    => { $crate::derive::opt_nz_typemagic!   { @$cmd {u16} $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? option:: )? Option $(::)?

        < $( $($(::)? std::)? num:: )? NonZeroU32 >

    } $($args:tt)*}                                                                    => { $crate::derive::opt_nz_typemagic!   { @$cmd {u32} $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? option:: )? Option $(::)?

        < $( $($(::)? std::)? num:: )? NonZeroU64 >

    } $($args:tt)*}                                                                    => { $crate::derive::opt_nz_typemagic!   { @$cmd {u64} $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? option:: )? Option $(::)?

        < $( $($(::)? std::)? num:: )? NonZeroU128 >

    } $($args:tt)*}                                                                    => { $crate::derive::opt_nz_typemagic!   { @$cmd {u128} $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? option:: )? Option $(::)?

        < $( $($(::)? std::)? string:: )? String >

    } $($args:tt)*}                                                                    => { $crate::derive::opt_str_typemagic!  { @$cmd $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? option:: )? Option $(::)?

        < $t:ty >

    } $($args:tt)*}                                                                    =>   {$crate::derive::opt_other_typemagic!{@$cmd {$t}  $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? num:: )? NonZero $(::)? < $t:ty >}  $($args:tt)*} => { $crate::derive::nonzero_typemagic!{ @$cmd {$t}   $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? num:: )? NonZeroU8}                 $($args:tt)*} => { $crate::derive::nonzero_typemagic!{ @$cmd {u8}   $($args)* } };

    { @$cmd:ident {$( $($(::)? std::)? num:: )? NonZeroU16}                $($args:tt)*} => { $crate::derive::nonzero_typemagic!{ @$cmd {u16}  $($args)*  } };

    { @$cmd:ident {$( $($(::)? std::)? num:: )? NonZeroU32}                $($args:tt)*} => { $crate::derive::nonzero_typemagic!{ @$cmd {u32}  $($args)*  } };

    { @$cmd:ident {$( $($(::)? std::)? num:: )? NonZeroU64}                $($args:tt)*} => { $crate::derive::nonzero_typemagic!{ @$cmd {u64}  $($args)*  } };

    { @$cmd:ident {$( $($(::)? std::)? num:: )? NonZeroU128}               $($args:tt)*} => { $crate::derive::nonzero_typemagic!{ @$cmd {u128} $($args)*  } };

    { @$cmd:ident {$( $($(::)? std::)? string:: )? String}                 $($args:tt)*} => { $crate::derive::string_typemagic! { @$cmd $($args)* } };

    { @$cmd:ident {$($t:tt)+}                                              $($args:tt)*} => { $crate::derive::no_typemagic!     { @$cmd {$($t)+} $($args)* } };

    // HEY YOU! DON'T ADD OR REMOVE TYPES WITHOUT READING THIS COMMENT!

    //

    // 1. You need to make sure that every type handled by this macro implements

    //    `ShouldBeCaughtAsASpecialCase`.

    // 2. Make sure to document the behavior in `doc_magic_types` above.

}

pub use normalize_and_invoke;

/// Implement type magic for types that aren't at all special.

///

/// See [`normalize_and_invoke`] for details.

#[doc(hidden)]

#[macro_export]

macro_rules! no_typemagic {

    { @build_type {$t:ty} } => { $t };

    { @setter_arg_type {$t:ty}} => { $t };

    { @setter_cvt {$t:ty} {$e:expr} } => { $e };

    { @build_field {$t:ty} {$e:expr} {$fname:expr}} => { $e.clone() };

    { @check_type {$t:ty} } => {

        $crate::derive::exports::assert_not_impl!(

            [type_was_not_correctly_identified_as_a_TorConfig_special_case]

            $t: $crate::derive::ShouldBeCaughtAsSpecialCase

        );

    };

    { @setter_docs {$t:ty} } => { "" };

}

pub use no_typemagic;

/// Implement type magic for `String`.

///

/// See [`normalize_and_invoke`] for details.

#[doc(hidden)]

#[macro_export]

macro_rules! string_typemagic {

    { @build_type } => { String };

    { @setter_arg_type } => { impl $crate::setter_traits::StringOrStr };

    { @setter_cvt {$e:expr} } => { $e.to_string() };

    { @build_field {$e:expr} {$fname:expr}} => { $e.clone() };