rustc_attr_parsing/attributes/mod.rs
1//! This module defines traits for attribute parsers, little state machines that recognize and parse
2//! attributes out of a longer list of attributes. The main trait is called [`AttributeParser`].
3//! You can find more docs about [`AttributeParser`]s on the trait itself.
4//! However, for many types of attributes, implementing [`AttributeParser`] is not necessary.
5//! It allows for a lot of flexibility you might not want.
6//!
7//! Specifically, you might not care about managing the state of your [`AttributeParser`]
8//! state machine yourself. In this case you can choose to implement:
9//!
10//! - [`SingleAttributeParser`]: makes it easy to implement an attribute which should error if it
11//! appears more than once in a list of attributes
12//! - [`CombineAttributeParser`]: makes it easy to implement an attribute which should combine the
13//! contents of attributes, if an attribute appear multiple times in a list
14//!
15//! Attributes should be added to `crate::context::ATTRIBUTE_PARSERS` to be parsed.
16
17use std::marker::PhantomData;
18
19use rustc_attr_data_structures::AttributeKind;
20use rustc_feature::{AttributeTemplate, template};
21use rustc_span::{Span, Symbol};
22use thin_vec::ThinVec;
23
24use crate::context::{AcceptContext, FinalizeContext, Stage};
25use crate::parser::ArgParser;
26use crate::session_diagnostics::UnusedMultiple;
27
28pub(crate) mod allow_unstable;
29pub(crate) mod cfg;
30pub(crate) mod codegen_attrs;
31pub(crate) mod confusables;
32pub(crate) mod deprecation;
33pub(crate) mod inline;
34pub(crate) mod link_attrs;
35pub(crate) mod lint_helpers;
36pub(crate) mod loop_match;
37pub(crate) mod must_use;
38pub(crate) mod no_implicit_prelude;
39pub(crate) mod non_exhaustive;
40pub(crate) mod path;
41pub(crate) mod repr;
42pub(crate) mod rustc_internal;
43pub(crate) mod semantics;
44pub(crate) mod stability;
45pub(crate) mod test_attrs;
46pub(crate) mod traits;
47pub(crate) mod transparency;
48pub(crate) mod util;
49
50type AcceptFn<T, S> = for<'sess> fn(&mut T, &mut AcceptContext<'_, 'sess, S>, &ArgParser<'_>);
51type AcceptMapping<T, S> = &'static [(&'static [Symbol], AttributeTemplate, AcceptFn<T, S>)];
52
53/// An [`AttributeParser`] is a type which searches for syntactic attributes.
54///
55/// Parsers are often tiny state machines that gets to see all syntactical attributes on an item.
56/// [`Default::default`] creates a fresh instance that sits in some kind of initial state, usually that the
57/// attribute it is looking for was not yet seen.
58///
59/// Then, it defines what paths this group will accept in [`AttributeParser::ATTRIBUTES`].
60/// These are listed as pairs, of symbols and function pointers. The function pointer will
61/// be called when that attribute is found on an item, which can influence the state of the little
62/// state machine.
63///
64/// Finally, after all attributes on an item have been seen, and possibly been accepted,
65/// the [`finalize`](AttributeParser::finalize) functions for all attribute parsers are called. Each can then report
66/// whether it has seen the attribute it has been looking for.
67///
68/// The state machine is automatically reset to parse attributes on the next item.
69///
70/// For a simpler attribute parsing interface, consider using [`SingleAttributeParser`]
71/// or [`CombineAttributeParser`] instead.
72pub(crate) trait AttributeParser<S: Stage>: Default + 'static {
73 /// The symbols for the attributes that this parser is interested in.
74 ///
75 /// If an attribute has this symbol, the `accept` function will be called on it.
76 const ATTRIBUTES: AcceptMapping<Self, S>;
77
78 /// The parser has gotten a chance to accept the attributes on an item,
79 /// here it can produce an attribute.
80 ///
81 /// All finalize methods of all parsers are unconditionally called.
82 /// This means you can't unconditionally return `Some` here,
83 /// that'd be equivalent to unconditionally applying an attribute to
84 /// every single syntax item that could have attributes applied to it.
85 /// Your accept mappings should determine whether this returns something.
86 fn finalize(self, cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind>;
87}
88
89/// Alternative to [`AttributeParser`] that automatically handles state management.
90/// A slightly simpler and more restricted way to convert attributes.
91/// Assumes that an attribute can only appear a single time on an item,
92/// and errors when it sees more.
93///
94/// [`Single<T> where T: SingleAttributeParser`](Single) implements [`AttributeParser`].
95///
96/// [`SingleAttributeParser`] can only convert attributes one-to-one, and cannot combine multiple
97/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
98pub(crate) trait SingleAttributeParser<S: Stage>: 'static {
99 /// The single path of the attribute this parser accepts.
100 ///
101 /// If you need the parser to accept more than one path, use [`AttributeParser`] instead
102 const PATH: &[Symbol];
103
104 /// Configures the precedence of attributes with the same `PATH` on a syntax node.
105 const ATTRIBUTE_ORDER: AttributeOrder;
106
107 /// Configures what to do when when the same attribute is
108 /// applied more than once on the same syntax node.
109 ///
110 /// [`ATTRIBUTE_ORDER`](Self::ATTRIBUTE_ORDER) specified which one is assumed to be correct,
111 /// and this specified whether to, for example, warn or error on the other one.
112 const ON_DUPLICATE: OnDuplicate<S>;
113
114 /// The template this attribute parser should implement. Used for diagnostics.
115 const TEMPLATE: AttributeTemplate;
116
117 /// Converts a single syntactical attribute to a single semantic attribute, or [`AttributeKind`]
118 fn convert(cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser<'_>) -> Option<AttributeKind>;
119}
120
121/// Use in combination with [`SingleAttributeParser`].
122/// `Single<T: SingleAttributeParser>` implements [`AttributeParser`].
123pub(crate) struct Single<T: SingleAttributeParser<S>, S: Stage>(
124 PhantomData<(S, T)>,
125 Option<(AttributeKind, Span)>,
126);
127
128impl<T: SingleAttributeParser<S>, S: Stage> Default for Single<T, S> {
129 fn default() -> Self {
130 Self(Default::default(), Default::default())
131 }
132}
133
134impl<T: SingleAttributeParser<S>, S: Stage> AttributeParser<S> for Single<T, S> {
135 const ATTRIBUTES: AcceptMapping<Self, S> = &[(
136 T::PATH,
137 <T as SingleAttributeParser<S>>::TEMPLATE,
138 |group: &mut Single<T, S>, cx, args| {
139 if let Some(pa) = T::convert(cx, args) {
140 match T::ATTRIBUTE_ORDER {
141 // keep the first and report immediately. ignore this attribute
142 AttributeOrder::KeepFirst => {
143 if let Some((_, unused)) = group.1 {
144 T::ON_DUPLICATE.exec::<T>(cx, cx.attr_span, unused);
145 return;
146 }
147 }
148 // keep the new one and warn about the previous,
149 // then replace
150 AttributeOrder::KeepLast => {
151 if let Some((_, used)) = group.1 {
152 T::ON_DUPLICATE.exec::<T>(cx, used, cx.attr_span);
153 }
154 }
155 }
156
157 group.1 = Some((pa, cx.attr_span));
158 }
159 },
160 )];
161
162 fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
163 Some(self.1?.0)
164 }
165}
166
167// FIXME(jdonszelmann): logic is implemented but the attribute parsers needing
168// them will be merged in another PR
169#[allow(unused)]
170pub(crate) enum OnDuplicate<S: Stage> {
171 /// Give a default warning
172 Warn,
173
174 /// Duplicates will be a warning, with a note that this will be an error in the future.
175 WarnButFutureError,
176
177 /// Give a default error
178 Error,
179
180 /// Ignore duplicates
181 Ignore,
182
183 /// Custom function called when a duplicate attribute is found.
184 ///
185 /// - `unused` is the span of the attribute that was unused or bad because of some
186 /// duplicate reason (see [`AttributeOrder`])
187 /// - `used` is the span of the attribute that was used in favor of the unused attribute
188 Custom(fn(cx: &AcceptContext<'_, '_, S>, used: Span, unused: Span)),
189}
190
191impl<S: Stage> OnDuplicate<S> {
192 fn exec<P: SingleAttributeParser<S>>(
193 &self,
194 cx: &mut AcceptContext<'_, '_, S>,
195 used: Span,
196 unused: Span,
197 ) {
198 match self {
199 OnDuplicate::Warn => cx.warn_unused_duplicate(used, unused),
200 OnDuplicate::WarnButFutureError => cx.warn_unused_duplicate_future_error(used, unused),
201 OnDuplicate::Error => {
202 cx.emit_err(UnusedMultiple {
203 this: used,
204 other: unused,
205 name: Symbol::intern(
206 &P::PATH.into_iter().map(|i| i.to_string()).collect::<Vec<_>>().join(".."),
207 ),
208 });
209 }
210 OnDuplicate::Ignore => {}
211 OnDuplicate::Custom(f) => f(cx, used, unused),
212 }
213 }
214}
215//
216// FIXME(jdonszelmann): logic is implemented but the attribute parsers needing
217// them will be merged in another PR
218#[allow(unused)]
219pub(crate) enum AttributeOrder {
220 /// Duplicates after the first attribute will be an error.
221 ///
222 /// This should be used where duplicates would be ignored, but carry extra
223 /// meaning that could cause confusion. For example, `#[stable(since="1.0")]
224 /// #[stable(since="2.0")]`, which version should be used for `stable`?
225 KeepFirst,
226
227 /// Duplicates preceding the last instance of the attribute will be a
228 /// warning, with a note that this will be an error in the future.
229 ///
230 /// This is the same as `FutureWarnFollowing`, except the last attribute is
231 /// the one that is "used". Ideally these can eventually migrate to
232 /// `ErrorPreceding`.
233 KeepLast,
234}
235
236/// An even simpler version of [`SingleAttributeParser`]:
237/// now automatically check that there are no arguments provided to the attribute.
238///
239/// [`WithoutArgs<T> where T: NoArgsAttributeParser`](WithoutArgs) implements [`SingleAttributeParser`].
240//
241pub(crate) trait NoArgsAttributeParser<S: Stage>: 'static {
242 const PATH: &[Symbol];
243 const ON_DUPLICATE: OnDuplicate<S>;
244
245 /// Create the [`AttributeKind`] given attribute's [`Span`].
246 const CREATE: fn(Span) -> AttributeKind;
247}
248
249pub(crate) struct WithoutArgs<T: NoArgsAttributeParser<S>, S: Stage>(PhantomData<(S, T)>);
250
251impl<T: NoArgsAttributeParser<S>, S: Stage> Default for WithoutArgs<T, S> {
252 fn default() -> Self {
253 Self(Default::default())
254 }
255}
256
257impl<T: NoArgsAttributeParser<S>, S: Stage> SingleAttributeParser<S> for WithoutArgs<T, S> {
258 const PATH: &[Symbol] = T::PATH;
259 const ATTRIBUTE_ORDER: AttributeOrder = AttributeOrder::KeepLast;
260 const ON_DUPLICATE: OnDuplicate<S> = T::ON_DUPLICATE;
261 const TEMPLATE: AttributeTemplate = template!(Word);
262
263 fn convert(cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser<'_>) -> Option<AttributeKind> {
264 if let Err(span) = args.no_args() {
265 cx.expected_no_args(span);
266 }
267 Some(T::CREATE(cx.attr_span))
268 }
269}
270
271type ConvertFn<E> = fn(ThinVec<E>, Span) -> AttributeKind;
272
273/// Alternative to [`AttributeParser`] that automatically handles state management.
274/// If multiple attributes appear on an element, combines the values of each into a
275/// [`ThinVec`].
276/// [`Combine<T> where T: CombineAttributeParser`](Combine) implements [`AttributeParser`].
277///
278/// [`CombineAttributeParser`] can only convert a single kind of attribute, and cannot combine multiple
279/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
280pub(crate) trait CombineAttributeParser<S: Stage>: 'static {
281 const PATH: &[rustc_span::Symbol];
282
283 type Item;
284 /// A function that converts individual items (of type [`Item`](Self::Item)) into the final attribute.
285 ///
286 /// For example, individual representations fomr `#[repr(...)]` attributes into an `AttributeKind::Repr(x)`,
287 /// where `x` is a vec of these individual reprs.
288 const CONVERT: ConvertFn<Self::Item>;
289
290 /// The template this attribute parser should implement. Used for diagnostics.
291 const TEMPLATE: AttributeTemplate;
292
293 /// Converts a single syntactical attribute to a number of elements of the semantic attribute, or [`AttributeKind`]
294 fn extend<'c>(
295 cx: &'c mut AcceptContext<'_, '_, S>,
296 args: &'c ArgParser<'_>,
297 ) -> impl IntoIterator<Item = Self::Item> + 'c;
298}
299
300/// Use in combination with [`CombineAttributeParser`].
301/// `Combine<T: CombineAttributeParser>` implements [`AttributeParser`].
302pub(crate) struct Combine<T: CombineAttributeParser<S>, S: Stage> {
303 phantom: PhantomData<(S, T)>,
304 /// A list of all items produced by parsing attributes so far. One attribute can produce any amount of items.
305 items: ThinVec<<T as CombineAttributeParser<S>>::Item>,
306 /// The full span of the first attribute that was encountered.
307 first_span: Option<Span>,
308}
309
310impl<T: CombineAttributeParser<S>, S: Stage> Default for Combine<T, S> {
311 fn default() -> Self {
312 Self {
313 phantom: Default::default(),
314 items: Default::default(),
315 first_span: Default::default(),
316 }
317 }
318}
319
320impl<T: CombineAttributeParser<S>, S: Stage> AttributeParser<S> for Combine<T, S> {
321 const ATTRIBUTES: AcceptMapping<Self, S> = &[(
322 T::PATH,
323 <T as CombineAttributeParser<S>>::TEMPLATE,
324 |group: &mut Combine<T, S>, cx, args| {
325 // Keep track of the span of the first attribute, for diagnostics
326 group.first_span.get_or_insert(cx.attr_span);
327 group.items.extend(T::extend(cx, args))
328 },
329 )];
330
331 fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
332 if let Some(first_span) = self.first_span {
333 Some(T::CONVERT(self.items, first_span))
334 } else {
335 None
336 }
337 }
338}