Derive Macro deluxe::ParseMetaItem

#[derive(ParseMetaItem)]
{
    // Attributes available to this derive:
    #[deluxe]
}

Generates ParseMetaItem for a struct or enum.

Container Attributes

The following attributes are supported on structs and enums:

• #[deluxe(default)]

  Initializes the container with [Default::default] before parsing.

• #[deluxe(default = expr)]

  Initializes the container with the value of expr before parsing. The expression will be evaluated every time it is needed to construct the field, and must evaluate to a value of the same type as the field.

• #[deluxe(transparent)]

  Parses a struct with one field as if it were the field. Can only be used on a struct with a single parseable field. Analogous to #[repr(transparent)]. The struct can still contain fields that are skip, as those will be ignored by transparent.

• #[deluxe(transparent(flatten_named)]

  #[deluxe(transparent(flatten_unnamed)]

  #[deluxe(transparent(flatten_unnamed, append)]

  #[deluxe(transparent(rest)]

  Parses a struct with one field as if it were the field, additionally implementing the traits required to use flatten, rest, or append. Can only be used on a struct with a single parseable field.

  Currently, it is required to provide these additional attributes to generate the trait definitions to use flatten, append or rest on this type.

• #[deluxe(and_then = expr)]

  Executes an additional function ater parsing to perform additional transformations or validation on the input.

  This attribute is a simple wrapper around Result::and_then. The function returned by expr must conform to the signature fn(T) -> deluxe::Result<T> where T is the type of the struct/enum being parsed. Returning Err will cause the entire parse to fail.

  This attribute can be specified multiple times. When multiple and_then attributes are present, Deluxe will chain each function in the order the attributes were specified.

  Example

  #[derive(deluxe::ParseMetaItem)]
  #[deluxe(and_then = Self::validate)]
  struct Data(i32);
  impl Data {
      fn validate(self) -> deluxe::Result<Self> {
          // ... perform some checks here ...
          Ok(self)
      }
  }

• #[deluxe(allow_unknown_fields)]

  Ignore any tokens and do not generate an error when an unknown field is encountered.

• #[deluxe(crate = path)]

  Specifies path as a custom path to the deluxe crate. Useful if proc_macro_crate is unable to find the deluxe crate, for instance if the crate is only re-exported inside another dependency.

Variant Attributes

The following attributes are supported on variants:

• #[deluxe(rename = ident)]

  Parse the variant with the given ident instead of its Rust name.

• #[deluxe(alias = ident)]

  Parse the variant with the given ident, or its Rust name. Can be repeated multiple times to provide additional aliases.

• #[deluxe(transparent)]

  Parses a variant with one field as if it were the field. Can only be used on a variant with a single parseable field. Analogous to #[repr(transparent)]. The variant can still contain fields that are skip, as those will be ignored by transparent.

• #[deluxe(flatten)]

  Flattens the variant so that its unique fields are used as the key for this variant instead of its name. Can be used on multiple variants as long as they each have a unique set of parseable fields that can be used to identify the variant. Fields with flatten, append or rest are not counted as unique fields as their field names are ignored.

  A single variant with no parseable fields can also be flattened. In that case, that variant will always be parsed as the default variant. Setting a default variant in this way is mutually exclusive with using #[deluxe(default)] on the enum.

• #[deluxe(skip)]

  Skips this variant from parsing entirely.

• #[deluxe(allow_unknown_fields)]

  Ignore any tokens and do not generate an error when an unknown field is encountered in this variant.

Field Attributes

The following attributes are supported on struct fields and enum fields:

• #[deluxe(rename = ident)]

  Parse the field with the given ident instead of its Rust name.

• #[deluxe(alias = ident)]

  Parse the field with the given ident, or its Rust name. Can be repeated multiple times to provide additional aliases.

• #[deluxe(default)]

  Initializes the field with the value of [Default::default] if the field is omitted.

  It is not necessary to use this on fields of type [Option] or Flag, or any other type that has a top-level #[deluxe(default)] on the type itself.

• #[deluxe(default = expr)]

  Initializes the field with the value of expr if the field is omitted. The expression will be evaluated every time it is needed to construct the field, and must evaluate to a value of the same type as the field.

• #[deluxe(flatten)]

  Flattens the field so that its fields are parsed inline as part of the current struct or enum variant.

  When the container uses named fields, only enums or other structs with named fields can be flattened. The fields from the flattened field can be freely interspersed with the fields from the containing struct or variant. This has the effect of making it so the order of flattened fields does not matter when using named fields.

  When the container uses unnamed fields, only unnamed structs, tuples, and collections/arrays can be flattened. The order of flattened unnamed fields is important. The fields of the flattened structure will be consumed starting from the position of the field in the containing tuple. Flattening a collection into a tuple struct/variant without a finite size will consume all fields from that position until the end.

  This attribute is implemented by either calling ParseMetaFlatUnnamed::parse_meta_flat_unnamed or ParseMetaFlatNamed::parse_meta_flat_named depending on the type of the containing structure. The appropriate trait will be automatically implemented when deriving ParseMetaItem, but some implementations are provided for common collection types. Custom container types can support flattening by providing implementations of those traits.

• #[deluxe(flatten(prefix = path)])

  Flattens the field so that its fields are parsed inline as part of the current struct or enum variant, only accepting fields that are prefixed with path. This can be used if the flattened structure contains field names that conflict with the fields in the containing structure.

  For all other details on this attribute, refer to flatten.

• #[deluxe(append)]

  Allows duplicates of this field. Additional fields parsed with the same name will be appended on to the previous value. This attribute is only allowed on named fields.

  This attribute is implemented by calling ParseMetaAppend::parse_meta_append. Some implementations are provided for common collection types. Custom container types can support appending by providing an implementation of that trait.

• #[deluxe(rest)]

  Inserts all unknown fields into this field. Typically, this field will be a map type with [syn::Path] as the key. This attribute is only allowed on named fields.

  This attribute is implemented by calling ParseMetaRest::parse_meta_rest. Some implementations are provided for common collection types. Custom map types can be allowed as a rest field by providing an implementation of that trait.

• #[deluxe(map = expr)]

  #[deluxe(and_then = expr)]

  Executes additional functions ater parsing to perform additional transformations or validation on the input.

  These attributes are simple wrappers around Result::map and Result::and_then. These attributes can be specified multiple times. When multiple are present, Deluxe will chain each function in the order the attributes were specified.

  For map, the function returned by expr must conform to the signature fn(T) -> U. For and_then, the function returned by expr must conform to the signature fn(T) -> deluxe::Result<U>. Returning Err will cause the entire parse to fail. Arbitrary types can be used for T and U as long as the following constraints hold:

  • The first function must have a fully specified type for T, which will have its ParseMetaItem implementation used.
  • The U from any function in the chain matches the T` for the following function.
  • The last function must have a type for U that matches the type of the field.

  Example

  #[derive(deluxe::ParseMetaItem)]
  struct Data {
      // parses as an Ident but stored as a string
      #[deluxe(map = |i: syn::Ident| i.to_string())]
      ident_string: String,
      // converts an Ident to a string and does a validation
      #[deluxe(and_then = Self::check_ident)]
      valid_ident_string: String,
  }
  
  impl Data {
      fn check_ident(i: syn::Ident) -> deluxe::Result<String> {
          let s = i.to_string();
          if s == "invalid" {
              Err(syn::Error::new(i.span(), "`invalid` not allowed"))
          } else {
              Ok(s)
          }
      }
  }

• #[deluxe(with = module)]

  When parsing, call functions from the path module instead of attempting to call ParseMetaItem functions. The path can be a module path or a path to a type containing associated functions.

  The functions will be called as module::parse_meta_item, module::parse_meta_item_inline, module::parse_meta_item_flag, module::parse_meta_item_named, and module::missing_meta_item. All five functions must be implemented, even if just to return an error. The signatures of these functions should match the equivalent functions in ParseMetaItem, although they can be generic over the return type. Fields using this attribute are not required to implement ParseMetaItem.

  parse_meta_item_inline implementations can call parse_first to simply delegate the impementation to parse_meta_item. parse_meta_item_flag implementations can call flag_disallowed_error for a standard error if flags are not supported by the target type. parse_meta_item_named implementations can call parse_named_meta_item_with! using self as the last parameter for the standard behavior.

  Some common parsers are available in the with module.

• #[deluxe(skip)]

  Skips this field from parsing entirely. The field still must receive a default value through a default attribute either on the struct or the field, so the parse function can still construct the object. If not used in a struct with default, then this implies default on the field if it is omitted.