model_mapper_macros/lib.rs
1mod input;
2mod model_mapper;
3mod type_path_ext;
4
5use proc_macro::TokenStream;
6use proc_macro_error2::proc_macro_error;
7
8/// Derive mapper functions to convert between types.
9///
10/// A `mapper` attribute is required at type-level and it's optional at field or variant level.
11///
12/// The following attributes are available:
13///
14/// #### Type level attributes
15///
16/// - `ty = PathType` _(**mandatory**)_: The other type to derive the conversion. Can be a string literal for complex
17/// types (e.g. `ty = "Type<T>"`)
18/// - `from` _(optional)_: Whether to derive `From` the other type for self
19/// - `custom` _(optional)_: Derive a custom function instead of the trait
20/// - `custom = from_other` _(optional)_: Derive a custom function instead of the trait, with the given name
21/// - `into` _(optional)_: Whether to derive `From` self for the other type
22/// - `custom` _(optional)_: Derive a custom function instead of the trait
23/// - `custom = from_other` _(optional)_: Derive a custom function instead of the trait, with the given name
24/// - `try_from` _(optional)_: Whether to derive `TryFrom` the other type for self
25/// - `custom` _(optional)_: Derive a custom function instead of the trait
26/// - `custom = from_other` _(optional)_: Derive a custom function instead of the trait, with the given name
27/// - `try_into` _(optional)_: Whether to derive `TryFrom` self for the other type
28/// - `custom` _(optional)_: Derive a custom function instead of the trait
29/// - `custom = from_other` _(optional)_: Derive a custom function instead of the trait, with the given name
30/// - `add` _(optional, multiple)_: Additional fields (for structs with named fields) or variants (for enums) the other
31/// type has and this one doesn't **¹**
32/// - `field = other_field` _(mandatory)_: The field or variant name
33/// - `ty = bool` _(optional)_: The field type, mandatory for `into` and `try_into` if no default value is provided
34/// - `default` _(optional)_: The field or variant will be populated using `Default::default()` (mandatory for enums,
35/// with or without value)
36/// - `value = true` _(optional)_: The field or variant will be populated with the given expression instead
37/// - `ignore_extra` _(optional)_: Whether to ignore all extra fields (for structs) or variants (for enums) of the other
38/// type **²**
39///
40/// #### Variant level attributes
41///
42/// - `rename = OtherVariant` _(optional)_: To rename this variant on the other enum
43/// - `add` _(optional, multiple)_: Additional fields of the variant that the other type variant has and this one
44/// doesn't **¹**
45/// - `field = other_field` _(mandatory)_: The field name
46/// - `ty = bool` _(optional)_: The field type, mandatory for `into` and `try_into` if no default value is provided
47/// - `default` _(optional)_: The field or variant will be populated using `Default::default()`
48/// - `value = true` _(optional)_: The field or variant will be populated with the given expression instead
49/// - `skip` _(optional)_: Whether to skip this variant because the other enum doesn't have it
50/// - `default` _(mandatory)_: The field or variant will be populated using `Default::default()`
51/// - `value = get_default_value()` _(optional)_: The field or variant will be populated with the given expression
52/// instead
53/// - `ignore_extra` _(optional)_: Whether to ignore all extra fields of the other variant (only valid for _from_ and
54/// _try_from_) **²**
55///
56/// #### Field level attributes
57///
58/// - `rename = other_name` _(optional)_: To rename this field on the other type
59/// - `other_ty = T` _(optional)_: If the field type corresponds to a generic parameter of the source type, this
60/// attribute allows specifying which generic parameter it maps to.
61/// - `skip` _(optional)_: Whether to skip this field because the other type doesn't have it
62/// - `default` _(optional)_: The field or variant will be populated using `Default::default()`
63/// - `value = get_default_value()` _(optional)_: The field or variant will be populated with the given expression
64/// instead
65///
66/// Additional hints on how to map fields:
67///
68/// - `opt` _(optional)_: The field is an `Option` and the inner value shall be mapped **³**
69/// - `iter` _(optional)_: The field is an iterator and the inner value shall be mapped **³**
70/// - `map` _(optional)_: The field is a hashmap-like iterator and the inner value shall be mapped **³**
71/// - `with = mod::my_function` _(optional)_: If the field type doesn't implement `Into` or `TryInto` the other, this
72/// property allows you to customize the behavior by providing a conversion function
73/// - `from_with = mod::my_function` _(optional)_: The same as above but only for the `from` or `try_from` derives
74/// - `from_with = mod::my_function` _(optional)_: The same as above but only for the `from` or `try_from` derives
75///
76/// **¹** When providing additional fields without defaults, the `From` and `TryFrom` traits can't be derived and
77/// a custom function will be required instead. When deriving `into` or `try_into`, the `ty` must be provided as well.
78///
79/// **²** When ignoring fields or variants it might be required that the enum or the struct implements `Default`
80/// in order to properly populate it.
81///
82/// **³** Hints can be nested, for example: `opt(vec)`, `vec(opt(with = "my_custom_fn"))`
83///
84/// ## Example
85///
86/// ```rs
87/// #[derive(Mapper)]
88/// #[mapper(from, ty = Entity)]
89/// pub struct Model {
90/// id: i64,
91/// name: String,
92/// #[mapper(skip(default))]
93/// surname: Option<String>,
94/// }
95/// ```
96///
97/// Other advanced use cases are available on the [examples folder](https://github.com/lasantosr/model-mapper/tree/main/model-mapper/examples/).
98#[proc_macro_error]
99#[proc_macro_derive(Mapper, attributes(mapper))]
100pub fn model_mapper(input: TokenStream) -> TokenStream {
101 let input = syn::parse_macro_input!(input as syn::DeriveInput);
102 model_mapper::r#impl(input).into()
103}