1//! # Darling
2//! Darling is a tool for declarative attribute parsing in proc macro implementations.
3//!
4//!
5//! ## Design
6//! Darling takes considerable design inspiration from [`serde`](https://serde.rs). A data structure that can be
7//! read from any attribute implements `FromMeta` (or has an implementation automatically
8//! generated using `derive`). Any crate can provide `FromMeta` implementations, even one not
9//! specifically geared towards proc-macro authors.
10//!
11//! Proc-macro crates should provide their own structs which implement or derive `FromDeriveInput`,
12//! `FromField`, `FromVariant`, `FromGenerics`, _et alia_ to gather settings relevant to their operation.
13//!
14//! ## Attributes
15//! There are a number of attributes that `darling` exposes to enable finer-grained control over the code
16//! it generates.
17//!
18//! * **Field renaming**: You can use `#[darling(rename="new_name")]` on a field to change the name Darling looks for.
19//! You can also use `#[darling(rename_all="...")]` at the struct or enum level to apply a casing rule to all fields or variants.
20//! * **Map function**: You can use `#[darling(map="path::to::function")]` to run code on a field before its stored in the struct.
21//! * **Default values**: You can use `#[darling(default)]` at the type or field level to use that type's default value to fill
22//! in values not specified by the caller.
23//! * **Skipped fields**: You can skip a variant or field using `#[darling(skip)]`. Fields marked with this will fall back to
24//! `Default::default()` for their value, but you can override that with an explicit default or a value from the type-level default.
25//!
26//! ## Forwarded Fields
27//! All derivable traits except `FromMeta` support forwarding some fields from the input AST to the derived struct.
28//! These fields are matched up by identifier **before** `rename` attribute values are considered,
29//! allowing you to use their names for your own properties.
30//! The deriving struct is responsible for making sure the types of fields it chooses to declare are compatible with this table.
31//!
32//! A deriving struct is free to include or exclude any of the fields below.
33//!
34//! ### `FromDeriveInput`
35//! |Field name|Type|Meaning|
36//! |---|---|---|
37//! |`ident`|`syn::Ident`|The identifier of the passed-in type|
38//! |`vis`|`syn::Visibility`|The visibility of the passed-in type|
39//! |`generics`|`T: darling::FromGenerics`|The generics of the passed-in type. This can be `syn::Generics`, `darling::ast::Generics`, or any compatible type.|
40//! |`data`|`darling::ast::Data`|The body of the passed-in type|
41//! |`attrs`|`Vec<syn::Attribute>` (or anything, using `#[darling(with = ...)]`)|The forwarded attributes from the passed in type. These are controlled using the `forward_attrs` attribute.|
42//!
43//! ### `FromField`
44//! |Field name|Type|Meaning|
45//! |---|---|---|
46//! |`ident`|`Option<syn::Ident>`|The identifier of the passed-in field, or `None` for tuple fields|
47//! |`vis`|`syn::Visibility`|The visibility of the passed-in field|
48//! |`ty`|`syn::Type`|The type of the passed-in field|
49//! |`attrs`|`Vec<syn::Attribute>` (or anything, using `#[darling(with = ...)]`)|The forwarded attributes from the passed in field. These are controlled using the `forward_attrs` attribute.|
50//!
51//! ### `FromTypeParam`
52//! |Field name|Type|Meaning|
53//! |---|---|---|
54//! |`ident`|`syn::Ident`|The identifier of the passed-in type param|
55//! |`bounds`|`Vec<syn::TypeParamBound>`|The bounds applied to the type param|
56//! |`default`|`Option<syn::Type>`|The default type of the parameter, if one exists|
57//! |`attrs`|`Vec<syn::Attribute>` (or anything, using `#[darling(with = ...)]`)|The forwarded attributes from the passed in type param. These are controlled using the `forward_attrs` attribute.|
58//!
59//! ### `FromVariant`
60//! |Field name|Type|Meaning|
61//! |---|---|---|
62//! |`ident`|`syn::Ident`|The identifier of the passed-in variant|
63//! |`discriminant`|`Option<syn::Expr>`|For a variant such as `Example = 2`, the `2`|
64//! |`fields`|`darling::ast::Fields<T> where T: FromField`|The fields associated with the variant|
65//! |`attrs`|`Vec<syn::Attribute>` (or anything, using `#[darling(with = ...)]`)|The forwarded attributes from the passed in variant. These are controlled using the `forward_attrs` attribute.|
66#![warn(rust_2018_idioms)]
67
68#[allow(unused_imports)]
69#[macro_use]
70extern crate darling_macro;
71
72#[doc(hidden)]
73pub use darling_macro::*;
74
75#[doc(inline)]
76pub use darling_core::{
77 FromAttributes, FromDeriveInput, FromField, FromGenericParam, FromGenerics, FromMeta,
78 FromTypeParam, FromVariant,
79};
80
81#[doc(inline)]
82pub use darling_core::{Error, Result};
83
84#[doc(inline)]
85pub use darling_core::{ast, error, usage, util};
86
87// XXX exported so that `ExtractAttribute::extractor` can convert a path into tokens.
88// This is likely to change in the future, so only generated code should depend on this export.
89#[doc(hidden)]
90pub use darling_core::ToTokens;
91
92/// Core/std trait re-exports. This should help produce generated code which doesn't
93/// depend on `std` unnecessarily, and avoids problems caused by aliasing `std` or any
94/// of the referenced types.
95#[doc(hidden)]
96pub mod export {
97 pub use core::convert::From;
98 pub use core::default::Default;
99 pub use core::option::Option::{self, None, Some};
100 pub use core::result::Result::{self, Err, Ok};
101 pub use darling_core::syn;
102 pub use std::string::ToString;
103 pub use std::vec::Vec;
104
105 pub use crate::ast::NestedMeta;
106}
107
108#[macro_use]
109mod macros_public;
110