darling

Darling uses a set of traits to map attribute meta-items and AST elements into structured Rust types. The primary traits are:

1. FromMeta: Extracts values from a meta-item (e.g., key = "value" or flag) within an attribute. Similar to serde::Deserialize, it is used for individual field parsing.
2. FromDeriveInput: The root for parsing Derive macro inputs. It provides access to the target type's identity, generics, and visibility, and allows specifying which attributes to parse or forward.
3. FromField: Used for parsing struct fields. It provides access to the field's identity, type, and visibility.
4. FromVariant: Used for parsing enum variants. It provides access to the variant's identity and contents.
5. FromAttributes: A lower-level trait for non-derive proc-macros. It allows parsing any syntax element (traits, functions, etc.) by providing a meta-item extractor and error collection.

To parse arguments for a non-derive attribute macro, follow these steps:

1. Define an argument receiver type and derive FromMeta on it.
2. In your #[proc_macro_attribute] function, use syn::parse to parse the args TokenStream into a syn::parse::Parse compatible type, or use darling::ast::NestedMeta::parse_meta_list to convert the TokenStream to a Vec<NestedMeta>.
3. Call the derived from_list method on your argument receiver type to get a darling::Result<T>.

Example implementation:

use darling::{Error, FromMeta};
use darling::ast::NestedMeta;
use syn::ItemFn;
use proc_macro::TokenStream;

#[derive(Debug, FromMeta)]
#[darling(derive_syn_parse)]
struct MacroArgs {
    #[darling(default)]
    timeout_ms: Option<u16>,
    path: String,
}

#[proc_macro_attribute]
pub fn your_attr(args: TokenStream, input: TokenStream) -> TokenStream {
    let _args: MacroArgs = match syn::parse(args) {
        Ok(v) => v,
        Err(e) => { return e.to_compile_error().into(); }
    };
    let _input = syn::parse_macro_input!(input as ItemFn);

    // do things with `args`
    unimplemented!()
}

Sometimes you need to parse content that is not a valid Rust expression (e.g., a where clause in a trait bound). In these cases, darling will call from_invalid_expr.

To support truly arbitrary inputs like #[example(bound = where T: Deserialize<'de>, D: 'static)], you should implement both from_expr and from_invalid_expr. from_expr handles valid Rust expressions, while from_invalid_expr handles the tokens that failed expression parsing.

Recommended Pattern for syn::parse::Parse types: If your type implements syn::parse::Parse, you can use syn::parse2 to handle both valid and invalid expressions by converting the tokens into a TokenStream.

fn from_expr(expr: &syn::Expr) -> darling::Result<Self> {
    match *expr {
        // Invisible delimiter when the input to the macro is passed
        // by a `macro_rules!`, but we can safely ignore it
        Expr::Group(ref group) => Self::from_expr(&group.expr),
        _ => Ok(syn::parse2(expr.into_token_stream().clone())?)
    }
    .map_err(|e| e.with_span(expr))
}

fn from_invalid_expr(value: &MetaNameValueInvalidExpr) -> darling::Result<Self> {
    syn::parse2(value.value.clone()).map_err(Into::into)
}

When building proc-macros with darling, follow these three best practices to ensure high-quality compiler diagnostics:

1. Do not simplify darling::Error: Avoid converting darling::Error into other error types like syn::Error. To surface errors to the user, use darling::Error::write_errors. This preserves all span information and suggestions.
2. Avoid early returns for validation: Do not use the ? operator for custom validations. Instead, use an error::Accumulator to collect all errors encountered during parsing. Use Accumulator::finish to return the final result; it returns Ok only if no errors were collected.
3. Use with_span for custom errors: When creating additional errors via darling::Error::custom, call .with_span(node) to ensure the error points to the correct location in the source code. Use darling::util::SpannedValue to keep span information available on parsed fields.

The Override<T> type is used when an attribute can either inherit a default value from an external source or be explicitly set by the user.

In darling, this is commonly used for attributes like default. An attribute can take two forms:

1. Inherit: A bare word (e.g., #[darling(default)]). This maps to Override::Inherit.
2. Explicit: A value or list (e.g., #[darling(default="path::to::fn")]). This maps to Override::Explicit(T).

When defining a struct to collect these attributes using FromField or FromVariant, use Option<Override<T>> to represent the presence of the attribute itself.

use darling::{util::Override, FromField};

#[derive(FromField)]
#[darling(attributes(darling))]
pub struct Options {
   default: Option<Override<syn::Path>>,
}

impl Options {
    fn hydrate(self) -> Option<syn::Path> {
        // If the attribute was present, use the explicit value or fall back to a default path
        self.default.map(|ov| ov.unwrap_or(syn::parse_path("::Default::default").unwrap()))
    }
}