Crate darling

Darling

Darling is a tool for declarative attribute parsing in proc macro implementations.

Design

Darling takes considerable design inspiration from serde. A data structure that can be read from any attribute implements FromMeta (or has an implementation automatically generated using derive). Any crate can provide FromMeta implementations, even one not specifically geared towards proc-macro authors.

Proc-macro crates should provide their own structs which implement or derive FromDeriveInput, FromField, FromVariant, FromGenerics, et alia to gather settings relevant to their operation.

Attributes

There are a number of attributes that darling exposes to enable finer-grained control over the code it generates.

• Field renaming: You can use #[darling(rename="new_name")] on a field to change the name Darling looks for. You can also use #[darling(rename_all="...")] at the struct or enum level to apply a casing rule to all fields or variants.
• Map function: You can use #[darling(map="path::to::function")] to run code on a field before its stored in the struct.
• Default values: You can use #[darling(default)] at the type or field level to use that type’s default value to fill in values not specified by the caller.
• Skipped fields: You can skip a variant or field using #[darling(skip)]. Fields marked with this will fall back to Default::default() for their value, but you can override that with an explicit default or a value from the type-level default.

Forwarded Fields

All derivable traits except FromMeta support forwarding some fields from the input AST to the derived struct. These fields are matched up by identifier before rename attribute values are considered, allowing you to use their names for your own properties. The deriving struct is responsible for making sure the types of fields it chooses to declare are compatible with this table.

A deriving struct is free to include or exclude any of the fields below.

FromDeriveInput

Field name	Type	Meaning
ident	syn::Ident	The identifier of the passed-in type
vis	syn::Visibility	The visibility of the passed-in type
generics	T: darling::FromGenerics	The generics of the passed-in type. This can be syn::Generics, darling::ast::Generics, or any compatible type.
data	darling::ast::Data	The body of the passed-in type
attrs	Vec<syn::Attribute>	The forwarded attributes from the passed in type. These are controlled using the forward_attrs attribute.

FromField

Field name	Type	Meaning
ident	Option<syn::Ident>	The identifier of the passed-in field, or None for tuple fields
vis	syn::Visibility	The visibility of the passed-in field
ty	syn::Type	The type of the passed-in field
attrs	Vec<syn::Attribute>	The forwarded attributes from the passed in field. These are controlled using the forward_attrs attribute.

FromTypeParam

Field name	Type	Meaning
ident	syn::Ident	The identifier of the passed-in type param
bounds	Vec<syn::TypeParamBound>	The bounds applied to the type param
default	Option<syn::Type>	The default type of the parameter, if one exists
attrs	Vec<syn::Attribute>	The forwarded attributes from the passed in type param. These are controlled using the forward_attrs attribute.

FromVariant

Field name	Type	Meaning
ident	syn::Ident	The identifier of the passed-in variant
discriminant	Option<syn::Expr>	For a variant such as Example = 2, the 2
fields	darling::ast::Fields<T> where T: FromField	The fields associated with the variant
attrs	Vec<syn::Attribute>	The forwarded attributes from the passed in variant. These are controlled using the forward_attrs attribute.

Modules

• ast
  Utility types for working with the AST.
• error
  The darling::Error type, the multiple error Accumulator, and their internals.
• usage
  Traits and types used for tracking the usage of generic parameters through a proc-macro input.
• util
  Utility types for attribute parsing.

Macros

• uses_lifetimes
  Generator for UsesLifetimes impls that unions the used lifetimes of the selected fields.
• uses_type_params
  Generator for UsesTypeParam impls that unions the used type parameters of the selected fields.

Structs

• Error
  An error encountered during attribute parsing.

Traits

• FromAttributes
  Create an instance by parsing a list of attributes.
• FromDeriveInput
  Creates an instance by parsing an entire proc-macro derive input, including the, identity, generics, and visibility of the type.
• FromField
  Creates an instance by parsing an individual field and its attributes.
• FromGenericParam
  Creates an instance by parsing a specific syn::GenericParam. This can be a type param, a lifetime, or a const param.
• FromGenerics
  Creates an instance by parsing an entire generics declaration, including the where clause.
• FromMeta
  Create an instance from an item in an attribute declaration.
• FromTypeParam
  Creates an instance by parsing an individual type_param and its attributes.
• FromVariant
  Creates an instance from a specified syn::Variant.

Type Definitions

• Result
  An alias of Result specific to attribute parsing.