1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

//! Traits and types used for tracking the usage of generic parameters through a proc-macro input.
//!
//! When generating trait impls, libraries often want to automatically figure out which type parameters
//! are used in which fields, and then emit bounds that will produce the most permissive compilable
//! code.
//!
//! # Usage
//!
//! ## Example 1: Filtering
//! This example accepts a proc-macro input, then finds all lifetimes and type parameters used
//! by private fields.
//!
//! ```rust
//! # extern crate darling_core;
//! # extern crate syn;
//! #
//! # // in real-world usage, import from `darling`
//! # use darling_core::usage::{self, CollectLifetimes, CollectTypeParams, GenericsExt, Purpose};
//! # use syn::{Data, DeriveInput, GenericParam, Generics, Visibility};
//! #
//! # #[allow(dead_code)]
//! fn process(input: &DeriveInput) -> Generics {
//!     let type_params = input.generics.declared_type_params();
//!     let lifetimes = input.generics.declared_lifetimes();
//!
//!     let mut ret_generics = input.generics.clone();
//!
//!     if let Data::Struct(ref body) = input.data {
//!         let internal_fields = body
//!             .fields
//!             .iter()
//!             .filter(|field| field.vis == Visibility::Inherited)
//!             .collect::<Vec<_>>();
//!
//!         let int_type_params = internal_fields
//!             .collect_type_params(&Purpose::BoundImpl.into(), &type_params);
//!
//!         // We could reuse the vec from above, but here we'll instead
//!         // directly consume the chained iterator.
//!         let int_lifetimes = body
//!             .fields
//!             .iter()
//!             .filter(|field| field.vis == Visibility::Inherited)
//!             .collect_lifetimes(&Purpose::BoundImpl.into(), &lifetimes);
//!
//!
//!         ret_generics.params = ret_generics
//!             .params
//!             .into_iter()
//!             .filter(|gp| {
//!                 match *gp {
//!                     GenericParam::Type(ref ty) => int_type_params.contains(&ty.ident),
//!                     GenericParam::Lifetime(ref lt) => int_lifetimes.contains(&lt.lifetime),
//!                     _ => true,
//!                 }
//!             })
//!             .collect();
//!     }
//!
//!     ret_generics
//! }
//!
//! # fn main() {}
//! ```
//!
//! ## Example 2: Integrating with `FromDeriveInput`
//! It is possible to use `darling`'s magic fields feature in tandem with the `usage` feature set.
//! While there is no custom derive for `UsesTypeParams` or `UsesLifetimes`, there are macros to
//! generate impls.
//!
//! ```rust,ignore
//! #![allow(dead_code)]
//!
//! #[derive(FromField)]
//! #[darling(attributes(speak))]
//! struct SpeakerField {
//!     ident: Option<syn::Ident>,
//!     ty: syn::Type,
//!     #[darling(default)]
//!     volume: Option<u32>,
//! }
//!
//! uses_type_params!(SpeakerField, ty);
//! uses_lifetimes!(SpeakerField, ty);
//!
//! #[derive(FromDeriveInput)]
//! struct SpeakerOptions {
//!     generics: syn::Generics,
//!     data: darling::ast::Data<darling::util::Ignored, SpeakerField>,
//! }
//! ```
//!
//! At this point, you are able to call `uses_type_params` on `SpeakerOptions.data`, or any filtered
//! view of it. `darling` internally uses this in conjunction with the `skip` meta-item to determine
//! which type parameters don't require the `FromMeta` bound in generated impls.
//!
//! **Note:** If you are performing operations referencing generic params in meta-items parsed by `darling`,
//! you should determine if those impact the emitted code and wire up `UsesTypeParams` accordingly for
//! your field/variant.

mod generics_ext;
mod ident_set;
mod lifetimes;
mod options;
mod type_params;

pub use self::generics_ext::GenericsExt;
pub use self::ident_set::{IdentRefSet, IdentSet};
pub use self::lifetimes::{CollectLifetimes, LifetimeRefSet, LifetimeSet, UsesLifetimes};
pub use self::options::{Options, Purpose};
pub use self::type_params::{CollectTypeParams, UsesTypeParams};