1- //! [`AttributeGroup`]s are groups of attributes (groups can be size 1) that are parsed together.
2- //! An [`AttributeGroup`] implementation defines its parser.
3- //!
4- //! You can find more docs on what groups are on [`AttributeGroup`] itself.
5- //! However, for many types of attributes, implementing [`AttributeGroup`] is not necessary.
1+ //! You can find more docs on what groups are on [`AttributeParser`] itself.
2+ //! However, for many types of attributes, implementing [`AttributeParser`] is not necessary.
63//! It allows for a lot of flexibility you might not want.
74//!
8- //! Specifically, you care about managing the state of your [AttributeGroup] state machine
9- //! yourself. In this case you can choose to implement:
5+ //! Specifically, you might not care about managing the state of your [`AttributeParser`]
6+ //! state machine yourself. In this case you can choose to implement:
107//!
11- //! - [`SingleAttributeGroup `]: makes it easy to implement an attribute which should error if it
8+ //! - [`SingleAttributeParser `]: makes it easy to implement an attribute which should error if it
129//! appears more than once in a list of attributes
13- //! - [`CombineAttributeGroup `]: makes it easy to implement an attribute which should combine the
10+ //! - [`CombineAttributeParser `]: makes it easy to implement an attribute which should combine the
1411//! contents of attributes, if an attribute appear multiple times in a list
1512//!
1613//! Attributes should be added to [`ATTRIBUTE_GROUP_MAPPING`](crate::context::ATTRIBUTE_GROUP_MAPPING) to be parsed.
@@ -21,7 +18,7 @@ use rustc_attr_data_structures::AttributeKind;
2118use rustc_span:: Span ;
2219use thin_vec:: ThinVec ;
2320
24- use crate :: context:: { AttributeAcceptContext , AttributeGroupContext } ;
21+ use crate :: context:: { AcceptContext , FinalizeContext } ;
2522use crate :: parser:: ArgParser ;
2623
2724pub ( crate ) mod allow_unstable;
@@ -33,60 +30,68 @@ pub(crate) mod stability;
3330pub ( crate ) mod transparency;
3431pub ( crate ) mod util;
3532
36- type AttributeHandler < T > = fn ( & mut T , & AttributeAcceptContext < ' _ > , & ArgParser < ' _ > ) ;
37- type AttributeMapping < T > = & ' static [ ( & ' static [ rustc_span:: Symbol ] , AttributeHandler < T > ) ] ;
33+ type AcceptFn < T > = fn ( & mut T , & AcceptContext < ' _ > , & ArgParser < ' _ > ) ;
34+ type AcceptMapping < T > = & ' static [ ( & ' static [ rustc_span:: Symbol ] , AcceptFn < T > ) ] ;
3835
39- /// An [`AttributeGroup `] is a type which searches for syntactic attributes.
36+ /// An [`AttributeParser `] is a type which searches for syntactic attributes.
4037///
41- /// Groups are often tiny state machines. [`Default::default`]
42- /// creates a new instance that sits in some kind of initial state, usually that the
38+ /// Parsers are often tiny state machines that gets to see all syntactical attributes on an item.
39+ /// [`Default::default`] creates a fresh instance that sits in some kind of initial state, usually that the
4340/// attribute it is looking for was not yet seen.
4441///
45- /// Then, it defines what paths this group will accept in [`AttributeGroup ::ATTRIBUTES`].
42+ /// Then, it defines what paths this group will accept in [`AttributeParser ::ATTRIBUTES`].
4643/// These are listed as pairs, of symbols and function pointers. The function pointer will
47- /// be called when that attribute is found on an item, which can influence the state.
44+ /// be called when that attribute is found on an item, which can influence the state of the little
45+ /// state machine.
46+ ///
47+ /// Finally, after all attributes on an item have been seen, and possibly been accepted,
48+ /// the [`finalize`](AttributeParser::finalize) functions for all attribute parsers are called. Each can then report
49+ /// whether it has seen the attribute it has been looking for.
4850///
49- /// Finally, all `finalize` functions are called, for each piece of state,
50- pub ( crate ) trait AttributeGroup : Default + ' static {
51- /// The symbols for the attributes that this extractor can extract .
51+ /// The state machine is automatically reset to parse attributes on the next item.
52+ pub ( crate ) trait AttributeParser : Default + ' static {
53+ /// The symbols for the attributes that this parser is interested in .
5254///
5355/// If an attribute has this symbol, the `accept` function will be called on it.
54- const ATTRIBUTES : AttributeMapping < Self > ;
56+ const ATTRIBUTES : AcceptMapping < Self > ;
5557
56- /// The extractor has gotten a chance to accept the attributes on an item,
57- /// now produce an attribute.
58- fn finalize ( self , cx : & AttributeGroupContext < ' _ > ) -> Option < AttributeKind > ;
58+ /// The parser has gotten a chance to accept the attributes on an item,
59+ /// here it can produce an attribute.
60+ fn finalize ( self , cx : & FinalizeContext < ' _ > ) -> Option < AttributeKind > ;
5961}
6062
61- /// A slightly simpler and more restricted way to convert attributes which you can implement for
62- /// unit types. Assumes that a single attribute can only appear a single time on an item
63- /// [`SingleGroup<T> where T: SingleAttributeGroup`](Single) creates an [`AttributeGroup`] from any [`SingleAttributeGroup`].
63+ /// Alternative to [`AttributeParser`] that automatically handles state management.
64+ /// A slightly simpler and more restricted way to convert attributes.
65+ /// Assumes that an attribute can only appear a single time on an item,
66+ /// and errors when it sees more.
67+ ///
68+ /// [`Single<T> where T: SingleAttributeParser`](Single) implements [`AttributeParser`].
6469///
65- /// [`SingleGroup `] can only convert attributes one-to-one, and cannot combine multiple
70+ /// [`SingleAttributeParser `] can only convert attributes one-to-one, and cannot combine multiple
6671/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
67- pub ( crate ) trait SingleAttributeGroup : ' static {
72+ pub ( crate ) trait SingleAttributeParser : ' static {
6873 const PATH : & ' static [ rustc_span:: Symbol ] ;
6974
7075 /// Caled when a duplicate attribute is found.
7176///
7277/// `first_span` is the span of the first occurrence of this attribute.
73- fn on_duplicate ( cx : & AttributeAcceptContext < ' _ > , first_span : Span ) ;
78+ // FIXME(jdonszelmann): default error
79+ fn on_duplicate ( cx : & AcceptContext < ' _ > , first_span : Span ) ;
7480
75- /// The extractor has gotten a chance to accept the attributes on an item,
76- /// now produce an attribute.
77- fn convert ( cx : & AttributeAcceptContext < ' _ > , args : & ArgParser < ' _ > ) -> Option < AttributeKind > ;
81+ /// Converts a single syntactical attribute to a single semantic attribute, or [`AttributeKind`]
82+ fn convert ( cx : & AcceptContext < ' _ > , args : & ArgParser < ' _ > ) -> Option < AttributeKind > ;
7883}
7984
80- pub ( crate ) struct Single < T : SingleAttributeGroup > ( PhantomData < T > , Option < ( AttributeKind , Span ) > ) ;
85+ pub ( crate ) struct Single < T : SingleAttributeParser > ( PhantomData < T > , Option < ( AttributeKind , Span ) > ) ;
8186
82- impl < T : SingleAttributeGroup > Default for Single < T > {
87+ impl < T : SingleAttributeParser > Default for Single < T > {
8388 fn default ( ) -> Self {
8489 Self ( Default :: default ( ) , Default :: default ( ) )
8590 }
8691}
8792
88- impl < T : SingleAttributeGroup > AttributeGroup for Single < T > {
89- const ATTRIBUTES : AttributeMapping < Self > = & [ ( T :: PATH , |group : & mut Single < T > , cx, args| {
93+ impl < T : SingleAttributeParser > AttributeParser for Single < T > {
94+ const ATTRIBUTES : AcceptMapping < Self > = & [ ( T :: PATH , |group : & mut Single < T > , cx, args| {
9095 if let Some ( ( _, s) ) = group. 1 {
9196 T :: on_duplicate ( cx, s) ;
9297 return ;
@@ -97,50 +102,49 @@ impl<T: SingleAttributeGroup> AttributeGroup for Single<T> {
97102 }
98103 } ) ] ;
99104
100- fn finalize ( self , _cx : & AttributeGroupContext < ' _ > ) -> Option < AttributeKind > {
105+ fn finalize ( self , _cx : & FinalizeContext < ' _ > ) -> Option < AttributeKind > {
101106 Some ( self . 1 ?. 0 )
102107 }
103108}
104109
105110type ConvertFn < E > = fn ( ThinVec < E > ) -> AttributeKind ;
106111
107- /// A slightly simpler and more restricted way to convert attributes which you can implement for
108- /// unit types. If multiple attributes appear on an element, combines the values of each into a
112+ /// Alternative to [`AttributeParser`] that automatically handles state management.
113+ /// If multiple attributes appear on an element, combines the values of each into a
109114/// [`ThinVec`].
110- /// [`CombineGroup <T> where T: CombineAttributeGroup `](Combine) creates an [`AttributeGroup`] from any [`CombineAttributeGroup `].
115+ /// [`Combine <T> where T: CombineAttributeParser `](Combine) implements [`AttributeParser `].
111116///
112- /// [`CombineAttributeGroup `] can only convert a single kind of attribute, and cannot combine multiple
117+ /// [`CombineAttributeParser `] can only convert a single kind of attribute, and cannot combine multiple
113118/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
114- pub ( crate ) trait CombineAttributeGroup : ' static {
119+ pub ( crate ) trait CombineAttributeParser : ' static {
115120 const PATH : & ' static [ rustc_span:: Symbol ] ;
116121
117122 type Item ;
118123 const CONVERT : ConvertFn < Self :: Item > ;
119124
120- /// The extractor has gotten a chance to accept the attributes on an item,
121- /// now produce an attribute.
125+ /// Converts a single syntactical attribute to a number of elements of the semantic attribute, or [`AttributeKind`]
122126fn extend < ' a > (
123- cx : & ' a AttributeAcceptContext < ' a > ,
127+ cx : & ' a AcceptContext < ' a > ,
124128 args : & ' a ArgParser < ' a > ,
125129 ) -> impl IntoIterator < Item = Self :: Item > + ' a ;
126130}
127131
128- pub ( crate ) struct Combine < T : CombineAttributeGroup > (
132+ pub ( crate ) struct Combine < T : CombineAttributeParser > (
129133 PhantomData < T > ,
130- ThinVec < <T as CombineAttributeGroup >:: Item > ,
134+ ThinVec < <T as CombineAttributeParser >:: Item > ,
131135) ;
132136
133- impl < T : CombineAttributeGroup > Default for Combine < T > {
137+ impl < T : CombineAttributeParser > Default for Combine < T > {
134138 fn default ( ) -> Self {
135139 Self ( Default :: default ( ) , Default :: default ( ) )
136140 }
137141}
138142
139- impl < T : CombineAttributeGroup > AttributeGroup for Combine < T > {
140- const ATTRIBUTES : AttributeMapping < Self > =
143+ impl < T : CombineAttributeParser > AttributeParser for Combine < T > {
144+ const ATTRIBUTES : AcceptMapping < Self > =
141145 & [ ( T :: PATH , |group : & mut Combine < T > , cx, args| group. 1 . extend ( T :: extend ( cx, args) ) ) ] ;
142146
143- fn finalize ( self , _cx : & AttributeGroupContext < ' _ > ) -> Option < AttributeKind > {
147+ fn finalize ( self , _cx : & FinalizeContext < ' _ > ) -> Option < AttributeKind > {
144148 if self . 1 . is_empty ( ) { None } else { Some ( T :: CONVERT ( self . 1 ) ) }
145149 }
146150}
0 commit comments