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`]. 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>`|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>`|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>`|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`|`Option<darling::ast::Fields<__>>`|The fields associated with the variant|
65 //! |`attrs`|`Vec<syn::Attribute>`|The forwarded attributes from the passed in variant. These are controlled using the `forward_attrs` attribute.|
66 
67 extern crate core;
68 
69 #[allow(unused_imports)]
70 #[macro_use]
71 extern crate darling_macro;
72 
73 #[doc(hidden)]
74 pub use darling_macro::*;
75 
76 #[doc(inline)]
77 pub use darling_core::{
78     FromAttributes, FromDeriveInput, FromField, FromGenericParam, FromGenerics, FromMeta,
79     FromTypeParam, FromVariant,
80 };
81 
82 #[doc(inline)]
83 pub use darling_core::{Error, Result};
84 
85 #[doc(inline)]
86 pub use darling_core::{ast, error, usage, util};
87 
88 // XXX exported so that `ExtractAttribute::extractor` can convert a path into tokens.
89 // This is likely to change in the future, so only generated code should depend on this export.
90 #[doc(hidden)]
91 pub use darling_core::ToTokens;
92 
93 /// Core/std trait re-exports. This should help produce generated code which doesn't
94 /// depend on `std` unnecessarily, and avoids problems caused by aliasing `std` or any
95 /// of the referenced types.
96 #[doc(hidden)]
97 pub mod export {
98     pub use core::convert::From;
99     pub use core::default::Default;
100     pub use core::option::Option::{self, None, Some};
101     pub use core::result::Result::{self, Err, Ok};
102     pub use std::string::ToString;
103     pub use std::vec::Vec;
104 }
105 
106 #[macro_use]
107 mod macros_public;
108