Module rustc_builtin_macros::deriving::generic
source · Expand description
Some code that abstracts away much of the boilerplate of writing
derive
instances for traits. Among other things it manages getting
access to the fields of the 4 different sorts of structs and enum
variants, as well as creating the method and impl ast instances.
Supported features (fairly exhaustive):
- Methods taking any number of parameters of any type, and returning any type, other than vectors, bottom and closures.
- Generating
impl
s for types with type parameters and lifetimes (e.g.,Option<T>
), the parameters are automatically given the current trait as a bound. (This includes separate type parameters and lifetimes for methods.) - Additional bounds on the type parameters (
TraitDef.additional_bounds
)
The most important thing for implementors is the Substructure
and
SubstructureFields
objects. The latter groups 5 possibilities of the
arguments:
Struct
, whenSelf
is a struct (including tuple structs, e.gstruct T(i32, char)
).EnumMatching
, whenSelf
is an enum and all the arguments are the same variant of the enum (e.g.,Some(1)
,Some(3)
andSome(4)
)EnumTag
whenSelf
is an enum, for comparing the enum tags.StaticEnum
andStaticStruct
for static methods, where the type being derived upon is either an enum or struct respectively. (Any argument with type Self is just grouped among the non-self arguments.)
In the first two cases, the values from the corresponding fields in all the arguments are grouped together.
The non-static cases have Option<ident>
in several places associated
with field expr
s. This represents the name of the field it is
associated with. It is only not None
when the associated field has
an identifier in the source code. For example, the x
s in the
following snippet
struct A { x : i32 }
struct B(i32);
enum C {
C0(i32),
C1 { x: i32 }
}
The i32
s in B
and C0
don’t have an identifier, so the
Option<ident>
s would be None
for them.
In the static cases, the structure is summarized, either into the just spans of the fields or a list of spans and the field idents (for tuple structs and record structs, respectively), or a list of these, for enums (one for each variant). For empty struct and empty enum variants, it is represented as a count of 0.
“cs
” functions
The cs_...
functions (“combine substructure”) are designed to
make life easier by providing some pre-made recipes for common
threads; mostly calling the function being derived on all the
arguments and then combining them back together in some way (or
letting the user chose that). They are not meant to be the only
way to handle the structures that this code creates.
Examples
The following simplified PartialEq
is used for in-code examples:
trait PartialEq {
fn eq(&self, other: &Self) -> bool;
}
impl PartialEq for i32 {
fn eq(&self, other: &i32) -> bool {
*self == *other
}
}
Some examples of the values of SubstructureFields
follow, using the
above PartialEq
, A
, B
and C
.
Structs
When generating the expr
for the A
impl, the SubstructureFields
is
Struct(vec![FieldInfo {
span: <span of x>
name: Some(<ident of x>),
self_: <expr for &self.x>,
other: vec![<expr for &other.x]
}])
For the B
impl, called with B(a)
and B(b)
,
Struct(vec![FieldInfo {
span: <span of `i32`>,
name: None,
self_: <expr for &a>
other: vec![<expr for &b>]
}])
Enums
When generating the expr
for a call with self == C0(a)
and other == C0(b)
, the SubstructureFields is
EnumMatching(0, <ast::Variant for C0>,
vec![FieldInfo {
span: <span of i32>
name: None,
self_: <expr for &a>,
other: vec![<expr for &b>]
}])
For C1 {x}
and C1 {x}
,
EnumMatching(1, <ast::Variant for C1>,
vec![FieldInfo {
span: <span of x>
name: Some(<ident of x>),
self_: <expr for &self.x>,
other: vec![<expr for &other.x>]
}])
For the tags,
EnumTag(
&[<ident of self tag>, <ident of other tag>], <expr to combine with>)
Note that this setup doesn’t allow for the brute-force “match every variant against every other variant” approach, which is bad because it produces a quadratic amount of code (see #15375).
Static
A static method on the types above would result in,
StaticStruct(<ast::VariantData of A>, Named(vec![(<ident of x>, <span of x>)]))
StaticStruct(<ast::VariantData of B>, Unnamed(vec![<span of x>]))
StaticEnum(<ast::EnumDef of C>,
vec![(<ident of C0>, <span of C0>, Unnamed(vec![<span of i32>])),
(<ident of C1>, <span of C1>, Named(vec![(<ident of x>, <span of x>)]))])
Re-exports
pub use StaticFields::*;
pub use SubstructureFields::*;
Modules
- A mini version of ast::Ty, which is easier to use, and features an explicit
Self
type to use when specifying impls to be derived.
Structs
- The code snippets built up for derived code are sometimes used as blocks (e.g. in a function body) and sometimes used as expressions (e.g. in a match arm). This structure avoids committing to either form until necessary, avoiding the insertion of any unnecessary blocks.
- Summary of the relevant parts of a struct/enum field.
- All the data about the data structure/method being derived upon.
Enums
- The function passed to
cs_fold
is called repeatedly with a value of this type. It describes one part of the code generation. The result is always an expression. - How to handle fieldless enum variants.
- Fields for a static method
- A summary of the possible sets of fields.
Functions
- Folds over fields, combining the expressions for each field in a sequence. Statics may not be folded over.
- This method helps to extract all the type parameters referenced from a type. For a type parameter
<T>
, it looks for either aTyPath
that is not global and starts withT
, or aTyQPath
. Also include bound generic params from the input type.
Type Aliases
- Combine the values of all the fields together. The last argument is all the fields of all the structures.