Darling

Build Status Latest Version

darling is a crate for proc macro authors, which enables parsing attributes into structs. It is heavily inspired by serde both in its internals and in its API.

Usage

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Example

```rust,ignore

[macro_use]

extern crate darling; extern crate syn;

[derive(Default, FromMeta)]

[darling(default)]

pub struct Lorem { #[darling(rename = "sit")] ipsum: bool, dolor: Option, }

[derive(FromDeriveInput)]

[darling(fromident, attributes(mycrate), forward_attrs(allow, doc, cfg))]

pub struct MyTraitOpts { ident: syn::Ident, attrs: Vec, lorem: Lorem, } ```

The above code will then be able to parse this input:

``rust,ignore /// A doc comment which will be available inMyTraitOpts::attrs`.

[derive(MyTrait)]

[my_crate(lorem(dolor = "Hello", ipsum))]

pub struct ConsumingType; ```

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.

Macro Code

```rust,ignore use darling::FromMeta; use syn::{AttributeArgs, ItemFn}; use proc_macro::TokenStream;

[derive(Debug, FromMeta)]

pub struct MacroArgs { #[darling(default)] timeout_ms: Option, path: String, }

[procmacroattribute]

fn yourattr(args: TokenStream, input: TokenStream) -> TokenStream { let attrargs = parsemacroinput!(args as AttributeArgs); let input = parsemacro_input!(input as ItemFn);

let _args = match MacroArgs::from_list(&attr_args) {
    Ok(v) => v,
    Err(e) => { return e.write_errors(); }
};

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

} ```

Consuming Code

```rust,ignore use yourcrate::yourattr;

[yourattr(path = "hello", timeoutms = 15)]

fn do_stuff() { println!("Hello"); } ```

Features

Darling's features are built to work well for real-world projects.