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