Benefits

Great validation and errors, no work required. When users of your proc-macro make a mistake, darling makes sure they get error markers at the right place in their source, and provides "did you mean" suggestions for misspelled fields.

Usage

darling provides a set of traits which can be derived or manually implemented.

FromMeta is used to extract values from a meta-item in an attribute. Implementations are likely reusable for many libraries, much like FromStr or serde::Deserialize. Trait implementations are provided for primitives, some std types, and some syn types.

FromDeriveInput is implemented or derived by each proc-macro crate which depends on darling. This is the root for input parsing; it gets access to the identity, generics, and visibility of the target type, and can specify which attribute names should be parsed or forwarded from the input AST.

FromField is implemented or derived by each proc-macro crate which depends on darling. Structs deriving this trait will get access to the identity (if it exists), type, and visibility of the field.

FromVariant is implemented or derived by each proc-macro crate which depends on darling. Structs deriving this trait will get access to the identity and contents of the variant, which can be transformed the same as any other darling input.

Additional Modules

darling::ast provides generic types for representing the AST.

darling::usage provides traits and functions for determining where type parameters and lifetimes are used in a struct or enum.

darling::util provides helper types with special FromMeta implementations, such as IdentList.

/// A doc comment which will be available in `MyTraitOpts::attrs`.#[derive(MyTrait)]#[my_crate(lorem(dolor ="Hello", ipsum))]pubstructConsumingType;

Attribute Macros

Non-derive attribute macros are supported.
To parse arguments for attribute macros, derive FromMeta on the argument receiver type, then pass &syn::AttributeArgs to the from_list method.
This will produce a normal darling::Result<T> that can be used the same as a result from parsing a DeriveInput.

Consuming Code

Features

Defaults: Supports struct- and field-level defaults, using the same path syntax as serde.

Field Renaming: Fields can have different names in usage vs. the backing code.

Auto-populated fields: Structs deriving FromDeriveInput and FromField can declare properties named ident, vis, ty, attrs, and generics to automatically get copies of the matching values from the input AST. FromDeriveInput additionally exposes data to get access to the body of the deriving type, and FromVariant exposes fields.

Mapping function: Use #[darling(map="path")] to specify a function that runs on the result of parsing a meta-item field. This can change the return type, which enables you to parse to an intermediate form and convert that to the type you need in your struct.

Skip fields: Use #[darling(skip)] to mark a field that shouldn't be read from attribute meta-items.

Multiple-occurrence fields: Use #[darling(multiple)] on a Vec field to allow that field to appear multiple times in the meta-item. Each occurrence will be pushed into the Vec.

Span access: Use darling::util::SpannedValue in a struct to get access to that meta item's source code span. This can be used to emit warnings that point at a specific field from your proc macro. In addition, you can use darling::Error::write_errors to automatically get precise error location details in most cases.