Gitiles
Code Review Sign In
android-review.linaro.org / platform / external / rust / crates / darling / refs/heads/upstream
commit8ddb0abb828ad2993c3a3cd23e0f24aa6f9f736f[log] [tgz]
authorMartin Geisler <mgeisler@google.com>Thu Mar 21 15:42:53 2024 +0100
committerMartin Geisler <mgeisler@google.com>Tue Mar 26 17:46:47 2024 +0100
treedef60f9ddc8691c7d7e8d772082afa058d6272bf
parentf9a69249116bbd1ab777f11e807c812e294ce83d [diff]
Import 'darling' crate

Request Document: go/android-rust-importing-crates
For CL Reviewers: go/android3p#cl-review
For Build Team: go/ab-third-party-imports
Bug: http://b/328420253
Test: m libdarling

Change-Id: I759dddf9d1306135cef49357590d7853589418ba
69 files changed
tree: def60f9ddc8691c7d7e8d772082afa058d6272bf
  1. examples/
  2. src/
  3. tests/
  4. .cargo_vcs_info.json
  5. .gitignore
  6. Android.bp
  7. Cargo.toml
  8. cargo_embargo.json
  9. CHANGELOG.md
  10. clippy.toml
  11. compiletests.sh
  12. LICENSE
  13. METADATA
  14. MODULE_LICENSE_MIT
  15. OWNERS
  16. README.md
README.md

Darling

Build Status Latest Version [Rustc Version 1.56+]

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.

Benefits

  • Easy and declarative parsing of macro input - make your proc-macros highly controllable with minimal time investment.
  • 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.

  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.
  5. FromAttributes is a lower-level version of the more-specific FromDeriveInput, FromField, and FromVariant traits. Structs deriving this trait get a meta-item extractor and error collection which works for any syntax element, including traits, trait items, and functions. This is useful for non-derive proc macros.

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.

Example

#[macro_use]
extern crate darling;
extern crate syn;

#[derive(Default, FromMeta)]
#[darling(default)]
pub struct Lorem {
    #[darling(rename = "sit")]
    ipsum: bool,
    dolor: Option<String>,
}

#[derive(FromDeriveInput)]
#[darling(attributes(my_crate), forward_attrs(allow, doc, cfg))]
pub struct MyTraitOpts {
    ident: syn::Ident,
    attrs: Vec<syn::Attribute>,
    lorem: Lorem,
}

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

/// A doc comment which will be available in `MyTraitOpts::attrs`.
#[derive(MyTrait)]
#[my_crate(lorem(dolor = "Hello", sit))]
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

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

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

#[proc_macro_attribute]
pub fn your_attr(args: TokenStream, input: TokenStream) -> TokenStream {
    let attr_args = match NestedMeta::parse_meta_list(args.into()) {
        Ok(v) => v,
        Err(e) => { return TokenStream::from(Error::from(e).write_errors()); }
    };
    let _input = syn::parse_macro_input!(input as ItemFn);

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

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

Consuming Code

use your_crate::your_attr;

#[your_attr(path = "hello", timeout_ms = 15)]
fn do_stuff() {
    println!("Hello");
}

Features

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

  • Defaults: Supports struct- and field-level defaults, using the same path syntax as serde. Additionally, Option<T> and darling::util::Flag fields are innately optional; you don't need to declare #[darling(default)] for those.
  • 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.
    • Transformation of forwarded attributes: You can add #[darling(with=path)] to the attrs field to use a custom function to transform the forwarded attributes before they're provided to your struct. The function signature is fn(Vec<Attribute>) -> darling::Result<T>, where T is the type you declared for the attrs field. Returning an error from this function will propagate with all other parsing errors.
  • Mapping function: Use #[darling(map="path")] or #[darling(and_then="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.
  • "Did you mean" suggestions: Compile errors from derived darling trait impls include suggestions for misspelled fields.
  • Struct flattening: Use #[darling(flatten)] to remove one level of structure when presenting your meta item to users. Fields that are not known to the parent struct will be forwarded to the flatten field.

Shape Validation

Some proc-macros only work on structs, while others need enums whose variants are either unit or newtype variants. Darling makes this sort of validation extremely simple. On the receiver that derives FromDeriveInput, add #[darling(supports(...))] and then list the shapes that your macro should accept.

NameDescription
anyAccept anything
struct_anyAccept any struct
struct_namedAccept structs with named fields, e.g. struct Example { field: String }
struct_newtypeAccept newtype structs, e.g. struct Example(String)
struct_tupleAccept tuple structs, e.g. struct Example(String, String)
struct_unitAccept unit structs, e.g. struct Example;
enum_anyAccept any enum
enum_namedAccept enum variants with named fields
enum_newtypeAccept newtype enum variants
enum_tupleAccept tuple enum variants
enum_unitAccept unit enum variants

Each one is additive, so listing #[darling(supports(struct_any, enum_newtype))] would accept all structs and any enum where every variant is a newtype variant.

This can also be used when deriving FromVariant, without the enum_ prefix.