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