tor-netdoc 0.43.0

//! Common macro elements for deriving parsers and encoders

use derive_deftly::{define_derive_deftly, define_derive_deftly_module};

define_derive_deftly! {
    /// Defines a constructor struct and method
    //
    // TODO maybe move this out of tor-netdoc, to a lower-level dependency
    ///
    /// "Constructor" is a more lightweight alternative to the builder pattern.
    ///
    /// # Comparison to builders
    ///
    ///  * Suitable for transparent, rather than opaque, structs.
    ///  * Missing fields during construction are detected at compile-time.
    ///  * Construction is infallible at runtime.
    ///  * Making a previously-required field optional is an API break.
    ///
    /// # Input
    ///
    ///  * `struct Thing`.  (enums and unions are not supported.)
    ///
    ///  * Each field must impl `Default` or be annotated `#[deftly(constructor)]`
    ///
    ///  * `Thing` must contain `#[doc(hidden)] pub __non_exhaustive: ()`
    ///    rather than being `#[non_exhaustive]`.
    ///    (Because struct literal syntax is not available otherwise.)
    ///
    /// # Generated items
    ///
    ///  * **`pub struct ThingConstructor`**:
    ///    contains all the required (non-optional) fields from `Thing`.
    ///    `ThingConstructor` is `exhaustive`.
    ///
    ///  * **`fn ThingConstructor::construct(self) -> Thing`**:
    ///    fills in all the default values.
    ///
    ///  * `impl From<ThingConstructor> for Thing`
    ///
    /// # Attributes
    ///
    /// ## Field attributes
    ///
    ///  * **`#[deftly(constructor)]`**:
    ///    Include this field in `ThingConstructor`.
    ///    The caller must provide a value.
    ///
    ///  * **`#[deftly(constructor(default = EXPR))]`**:
    ///    Instead of `Default::default()`, the default value is EXPR.
    ///    EXPR cannot refer to anything in `ThingConstructor`.
    //     If we want that we would need to invent a feature for it.
    ///
    /// # Example
    ///
    /// ```
    /// use derive_deftly::Deftly;
    /// use tor_netdoc::derive_deftly_template_Constructor;
    ///
    /// #[derive(Deftly, PartialEq, Debug)]
    /// #[derive_deftly(Constructor)]
    /// #[allow(clippy::exhaustive_structs)]
    /// pub struct Thing {
    ///     /// Required field
    ///     #[deftly(constructor)]
    ///     pub required: i32,
    ///
    ///     /// Optional field
    ///     pub optional: Option<i32>,
    ///
    ///     /// Optional field with fixed default
    ///     #[deftly(constructor(default = 7))]
    ///     pub defaulted: i32,
    ///
    ///     #[doc(hidden)]
    ///     pub __non_exhaustive: (),
    /// }
    ///
    /// let thing = Thing {
    ///     optional: Some(23),
    ///     ..ThingConstructor {
    ///         required: 12,
    ///     }.construct()
    /// };
    ///
    /// assert_eq!(
    ///     thing,
    ///     Thing {
    ///         required: 12,
    ///         optional: Some(23),
    ///         defaulted: 7,
    ///         __non_exhaustive: (),
    ///     }
    /// );
    /// ```
    ///
    /// # Note
    export Constructor for struct, meta_quoted rigorous, beta_deftly:

    ${define CONSTRUCTOR_NAME $<$tname Constructor>}
    ${define CONSTRUCTOR $<$ttype Constructor>}

    ${defcond F_DEFAULT_EXPR fmeta(constructor(default))}
    ${defcond F_DEFAULT_TRAIT not(fmeta(constructor))}
    ${defcond F_REQUIRED not(any(F_DEFAULT_EXPR, F_DEFAULT_TRAIT))}

    ${for fields {
        ${loop_exactly_1 "need a `__non_exhaustive` field (instead of `#[non_exhaustive]`"}
        ${when all(
            approx_equal($fname, __non_exhaustive),
            approx_equal({}, ${tattrs non_exhaustive}),
        )}
    }}

    $/// Constructor (required fields) for `$tname`
    $///
    $/// See [`$tname`].
    $///
    $/// This constructor struct contains precisely the required fields.
    $/// You can make a `$tname` out of it with [`.construct()`]($CONSTRUCTOR_NAME::construct),
    $/// or the `From` impl,
    $/// and use the result as a basis for further modifications.
    $///
    $/// # Example
    $///
    $/// ```rust,ignore
    $/// let ${snake_case $tname} = $tname {
  ${for fields { ${when any(fmeta(constructor(default)), not(fmeta(constructor)))}
    $///     $fname: /* optional field value */,
  }}
    $///     ..$CONSTRUCTOR_NAME {
  ${for fields { ${when not(any(fmeta(constructor(default)), not(fmeta(constructor))))}
    $///         $fname: /* required field value */,
  }}
    $///     }.construct()
    $/// };
    $/// ```
    #[allow(clippy::exhaustive_structs)]
    $tvis struct $CONSTRUCTOR_NAME<$tdefgens> where $twheres { $(
        ${when F_REQUIRED}

        ${fattrs doc}
        $fdefvis $fname: $ftype,
    ) }

    impl<$tgens> $CONSTRUCTOR where $twheres {
        $/// Construct a minimal `$tname`
        $///
        $/// In the returned [`$tname`],
        $/// optional fields all get the default values.
        $tvis fn construct(self) -> $ttype {
            $tname { $(
                $fname: ${select1
                    F_REQUIRED {
                        self.$fname
                    }
                    F_DEFAULT_TRAIT {
                        <$ftype as ::std::default::Default>::default()
                    }
                    F_DEFAULT_EXPR {
                        ${fmeta(constructor(default)) as expr}
                    }
                },
            ) }
        }
    }

    impl<$tgens> From<$CONSTRUCTOR> for $ttype where $twheres {
        fn from(constructor: $CONSTRUCTOR) -> $ttype {
            constructor.construct()
        }
    }
}

define_derive_deftly! {
    /// Derive all parsing and encoding for a fixed, constant, string
    ///
    /// Usually, use the more-cooked [`define_constant_string!`] macro instead.
    ///
    /// # Input
    ///
    /// Typically, a unit struct.
    /// (Can be applied to any ZST struct that implements `Default`.)
    ///
    /// # Required attribute
    ///
    ///  * `#[deftly(constant_string = EXPR))]` where `EXPR` is a `&str` expression.
    ///
    /// # Generated items
    ///
    /// Implementations of [`FromStr`, `Display`, and `NormalItemArgument`].
    /// Therefore also [`ItemArgument`](crate::encode::ItemArgument)
    /// and [`ItemArgumentParseable`](crate::parse2::ItemArgumentParseable).
    ///
    /// # Example
    ///
    /// ```
    /// use derive_deftly::Deftly;
    /// use tor_netdoc::derive_deftly_template_ConstantString;
    ///
    /// #[derive(Default, Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deftly)]
    /// #[derive_deftly(ConstantString)]
    /// #[deftly(constant_string = "sha3-256")]
    /// #[allow(clippy::exhaustive_structs)]
    /// pub struct SharedRandV1AlgName;
    /// ```
    // TODO DIRMIRROR / TODO DIRAUTH use ConstantString for routerdesc::OverloadGeneralVersion?
    // TODO DIRMIRROR / TODO DIRAUTH use ConstantString for routerdesc::AuthCertVersion?
    export ConstantString for struct, beta_deftly, meta_quoted retain:

    // Bind `constant`.  Ensures the type is as expected.
    ${define LET_CONSTANT {
        let constant: &str = ${tmeta(constant_string) as expr};
    }}

    ${define FMT { ::std::fmt} }
    ${define ERR { $crate::ExpectedConstantString } }

    impl<$tgens> $FMT::Display for $ttype where $twheres {
        fn fmt(&self, f: &mut $FMT::Formatter) -> $FMT::Result {
            $LET_CONSTANT
            $FMT::Display::fmt(constant, f)
        }
    }

    impl<$tgens> ::std::str::FromStr for $ttype where $twheres {
        type Err = $ERR;

        fn from_str(s: &str) -> ::std::result::Result<Self, $ERR> {
            $LET_CONSTANT
            if s == constant {
                Ok(::std::default::Default::default())
            } else {
                Err($ERR {
                    got: s.to_string(),
                    expected: constant,
                })
            }
        }
    }

    impl<$tgens> $crate::NormalItemArgument for $ttype where $twheres {}
}

/// Define a ZST struct for a fixed, constant, argument string in a netdoc item
///
/// Convenience macro to define a unit struct, derive many traits,
/// and derive
/// [`ConstantString`](derive_deftly_template_ConstantString).
///
/// # Example
///
/// ```
/// use tor_netdoc::define_constant_string;
/// use tor_netdoc::derive_deftly_template_ConstantString; // sadly, needed for Reasons
///
/// define_constant_string! {
///     /// The shared random algorithm name for the V1 shared random protocol
///     ///
///     /// This is a constant string, since the version defines the hash algorithm.
///     SharedRandV1AlgName = "sha3-256";
/// }
///
/// assert_eq!("sha3-256".parse::<SharedRandV1AlgName>(), Ok(SharedRandV1AlgName));
/// assert_eq!(SharedRandV1AlgName.to_string(), "sha3-256");
/// ```
///
/// # Input
///
/// ```rust,ignore
/// define_constant_string! {
///     #[ATTRIBUTES...]
///     TYPE_NAME = STRING_LITERAL;
/// }
/// ```
///
/// # Generated items
///
/// ```rust,ignore
/// #[ATTRIBUTES...]
/// pub struct TYPE_NAME;
/// ```
///
/// Implementations of `Default`, `Debug`, `Clone`, `Copy`,
/// `Eq`, `PartialEq`, `Ord`, `PartialOrd`, `Hash`.
///
/// Implementations of [`FromStr`, `Display`, and `NormalItemArgument`].
/// Therefore also [`ItemArgument`](crate::encode::ItemArgument)
/// and [`ItemArgumentParseable`](crate::parse2::ItemArgumentParseable).
//
// This macro exists mostly to encapsulate this astonishing list of traits to derive!
#[macro_export]
macro_rules! define_constant_string {
    {
        $( #[ $($attr:tt)* ] )*
        $name:ident = $string:expr;
    } => {
        $( #[ $($attr)* ] )*
        #[derive(Default, Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)]
        #[derive($crate::derive_deftly::Deftly)]
        #[derive_deftly(ConstantString)]
        #[deftly(constant_string = ($string))]
        #[allow(clippy::exhaustive_structs)]
        pub struct $name;
    };
}

/// Macro to help check that netdoc items in a derive input are in the right order
///
/// Used only by the `NetdocParseable` derive-deftly macro.
#[doc(hidden)]
#[macro_export]
macro_rules! netdoc_ordering_check {
    { } => { compile_error!("netdoc must have an intro item so cannot be empty"); };

    // When we have   K0 P0 K1 P1 ...
    //   * Check that P0 and P1 have a consistent ordr
    //   * Continue with   K1 P1 ...
    // So we check each consecutive pair of fields.
    { $k0:ident $f0:ident $k1:ident $f1:ident $($rest:tt)* } => {
        $crate::netdoc_ordering_check! { <=? $k0 $k1 $f1 }
        $crate::netdoc_ordering_check! { $k1 $f1 $($rest)* }
    };
    { $k0:ident $f0:ident } => {}; // finished

    // Individual ordering checks for K0 <=? K1
    //
    // We write out each of the allowed this-kind next-kind combinations:
    { <=? intro     $any:ident $f1:ident } => {};
    { <=? normal    normal     $f1:ident } => {};
    { <=? normal    subdoc     $f1:ident } => {};
    { <=? subdoc    subdoc     $f1:ident } => {};
    // Not in the allowed list, must be an error:
    { <=? $k0:ident $k1:ident  $f1:ident } => {
        compile_error!(concat!(
            "in netdoc, ", stringify!($k1)," field ", stringify!($f1),
            " may not come after ", stringify!($k0),
        ));
    };
}

define_derive_deftly_module! {
    /// Common definitions for any netdoc derives
    NetdocDeriveAnyCommon beta_deftly:

    // Emit an eprintln with deftly(netdoc(debug)), just so that we don't get surprises
    // where someone leaves a (debug) in where it's not implemented, and we later implement it.
    ${define EMIT_DEBUG_PLACEHOLDER {
        ${if tmeta(netdoc(debug)) {
            use std::io::Write as _;

            // This messing about with std::io::stderr() mirrors netdoc_parseable_derive_debug.
            // (We could use eprintln! #[test] captures eprintln! but not io::stderr.)
            writeln!(
                std::io::stderr().lock(),
                ${concat "#[deftly(netdoc(debug))] applied to " $tname},
            ).expect("write to stderr failed");
        }}
    }}
    ${define DOC_DEBUG_PLACEHOLDER {
        /// * **`#[deftly(netdoc(debug))]`**:
        ///
        ///   Currently implemented only as a placeholder
        ///
        ///   The generated implementation may in future generate copious debug output
        ///   to the program's stderr when it is run.
        ///   Do not enable in production!
    }}
}

define_derive_deftly_module! {
    /// Common definitions for derives of structs containing items
    ///
    /// Used by `NetdocParseable`, `NetdocParseableFields`,
    /// `NetdocEncodable` and `NetdocEncodableFields`.
    ///
    /// Importing template must define these:
    ///
    ///  * **`F_INTRO`**, **`F_SUBDOC`**, **`F_SIGNATURE`**
    ///    conditions for the fundamental field kinds which aren't supported everywhere.
    ///
    ///    The `F_FLATTEN`, `F_SKIP`, `F_NORMAL` field type conditions are defined here.
    ///
    /// Importer must also import `NetdocDeriveAnyCommon`.
    //
    // We have the call sites import the other modules, rather than using them here, because:
    //  - This avoids the human reader having to chase breadcrumbs
    //    to find out what a particular template is using.
    //  - The dependency graph is not a tree, so some things would be included twice
    //    and derive-deftly cannot deduplicate them.
    NetdocSomeItemsDeriveCommon beta_deftly:

    // Is this field `flatten`?
    ${defcond F_FLATTEN fmeta(netdoc(flatten))}
    // Is this field `skip`?
    ${defcond F_SKIP fmeta(netdoc(skip))}
    // Is this field normal (non-structural)?
    ${defcond F_NORMAL not(any(F_SIGNATURE, F_INTRO, F_FLATTEN, F_SUBDOC, F_SKIP))}

    // Field keyword as `&str`
    ${define F_KEYWORD_STR { ${concat
        ${if any(F_FLATTEN, F_SUBDOC, F_SKIP) {
          ${if F_INTRO {
            ${error "#[deftly(netdoc(subdoc))] (flatten) and (skip) not supported for intro items"}
          } else {
            // Sub-documents and flattened fields have their keywords inside;
            // if we ask for the field-based keyword name for one of those then that's a bug.
            ${error "internal error, subdoc or skip KeywordRef"}
          }}
        }}
        ${fmeta(netdoc(keyword)) as str,
          default ${concat ${kebab_case $fname}}}
    }}}
    // Field keyword as `&str` for debugging and error reporting
    ${define F_KEYWORD_REPORT ${concat
        ${if any(F_FLATTEN, F_SUBDOC, F_SKIP) { $fname }
             else { $F_KEYWORD_STR }}
    }}
    // Field keyword as `KeywordRef`
    ${define F_KEYWORD { (KeywordRef::new_const($F_KEYWORD_STR)) }}
}

define_derive_deftly_module! {
    /// Common definitions for derives of whole network documents
    ///
    /// Used by `NetdocParseable` and `NetdocEncodable`.
    ///
    /// Importer must also import `NetdocSomeItemsDeriveCommon` and `NetdocDeriveAnyCommon`.
    NetdocEntireDeriveCommon beta_deftly:

    // Predicate for the toplevel
    ${defcond T_SIGNATURES false}

    // Predicates for the field kinds
    ${defcond F_INTRO approx_equal($findex, 0)}
    ${defcond F_SUBDOC fmeta(netdoc(subdoc))}
    ${defcond F_SIGNATURE T_SIGNATURES} // signatures section documents have only signature fields

    // compile-time check that fields are in the right order in the struct
    ${define FIELD_ORDERING_CHECK {
        ${if not(T_SIGNATURES) { // signatures structs have only signature fields
          netdoc_ordering_check! {
            $(
                ${when not(F_SKIP)}

                ${select1
                  F_INTRO     { intro     }
                  F_NORMAL    { normal    }
                  F_FLATTEN   { normal    }
                  F_SUBDOC    { subdoc    }
                }
                $fname
            )
          }
        }}
    }}
}

define_derive_deftly_module! {
    /// Common definitions for derives of flattenable network document fields structs
    ///
    /// Used by `NetdocParseableFields` and `NetdocEncodableFields`.
    ///
    /// Importer must also import `NetdocSomeItemsDeriveCommon` and `NetdocDeriveAnyCommon`.
    NetdocFieldsDeriveCommon beta_deftly:

    // Predicates for the field kinds, used by NetdocSomeItemsDeriveCommon etc.
    ${defcond F_INTRO false}
    ${defcond F_SUBDOC false}
    ${defcond F_SIGNATURE false}

    ${define DOC_NETDOC_FIELDS_DERIVE_SUPPORTED {
        ///  * The input struct can contain only normal non-structural items
        ///    (so it's not a sub-document with an intro item).
        ///  * The only attributes supported are the field attributes
        ///    `#[deftly(netdoc(keyword = STR))]`
        ///    `#[deftly(netdoc(default))]`
        ///    `#[deftly(netdoc(single_arg))]`
        ///    `#[deftly(netdoc(with = MODULE))]`
        ///    `#[deftly(netdoc(flatten))]`
        ///    `#[deftly(netdoc(skip))]`
    }}
}

define_derive_deftly_module! {
    /// Common definitions for derives of network document item value structs
    ///
    /// Used by `ItemValueParseable` and `ItemValueEncodable`.
    ///
    /// Importer must also import `NetdocDeriveAnyCommon`.
    NetdocItemDeriveCommon beta_deftly:

    ${defcond F_REST fmeta(netdoc(rest))}
    ${defcond F_OBJECT fmeta(netdoc(object))}
    ${defcond F_SKIP fmeta(netdoc(skip))}
    ${defcond F_NORMAL not(any(F_REST, F_OBJECT, F_SKIP))}

    ${defcond T_IS_SIGNATURE tmeta(netdoc(signature))}
}