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`](crate::attributes::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`](crate::attributes::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_feature::{AttributeTemplate, template};
20use rustc_hir::attrs::AttributeKind;
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;
27use crate::target_checking::AllowedTargets;
28
29/// All the parsers require roughly the same imports, so this prelude has most of the often-needed ones.
30mod prelude;
31
32pub(crate) mod allow_unstable;
33pub(crate) mod autodiff;
34pub(crate) mod body;
35pub(crate) mod cfg;
36pub(crate) mod cfg_select;
37pub(crate) mod cfi_encoding;
38pub(crate) mod codegen_attrs;
39pub(crate) mod confusables;
40pub(crate) mod crate_level;
41pub(crate) mod debugger;
42pub(crate) mod deprecation;
43pub(crate) mod diagnostic;
44pub(crate) mod doc;
45pub(crate) mod dummy;
46pub(crate) mod inline;
47pub(crate) mod instruction_set;
48pub(crate) mod link_attrs;
49pub(crate) mod lint_helpers;
50pub(crate) mod loop_match;
51pub(crate) mod macro_attrs;
52pub(crate) mod must_not_suspend;
53pub(crate) mod must_use;
54pub(crate) mod no_implicit_prelude;
55pub(crate) mod no_link;
56pub(crate) mod non_exhaustive;
57pub(crate) mod path;
58pub(crate) mod pin_v2;
59pub(crate) mod proc_macro_attrs;
60pub(crate) mod prototype;
61pub(crate) mod repr;
62pub(crate) mod rustc_allocator;
63pub(crate) mod rustc_dump;
64pub(crate) mod rustc_internal;
65pub(crate) mod semantics;
66pub(crate) mod stability;
67pub(crate) mod test_attrs;
68pub(crate) mod traits;
69pub(crate) mod transparency;
70pub(crate) mod util;
71
72type AcceptFn<T, S> = for<'sess> fn(&mut T, &mut AcceptContext<'_, 'sess, S>, &ArgParser);
73type AcceptMapping<T, S> = &'static [(&'static [Symbol], AttributeTemplate, AcceptFn<T, S>)];
74
75/// An [`AttributeParser`] is a type which searches for syntactic attributes.
76///
77/// Parsers are often tiny state machines that gets to see all syntactical attributes on an item.
78/// [`Default::default`] creates a fresh instance that sits in some kind of initial state, usually that the
79/// attribute it is looking for was not yet seen.
80///
81/// Then, it defines what paths this group will accept in [`AttributeParser::ATTRIBUTES`].
82/// These are listed as pairs, of symbols and function pointers. The function pointer will
83/// be called when that attribute is found on an item, which can influence the state of the little
84/// state machine.
85///
86/// Finally, after all attributes on an item have been seen, and possibly been accepted,
87/// the [`finalize`](AttributeParser::finalize) functions for all attribute parsers are called. Each can then report
88/// whether it has seen the attribute it has been looking for.
89///
90/// The state machine is automatically reset to parse attributes on the next item.
91///
92/// For a simpler attribute parsing interface, consider using [`SingleAttributeParser`]
93/// or [`CombineAttributeParser`] instead.
94pub(crate) trait AttributeParser<S: Stage>: Default + 'static {
95 /// The symbols for the attributes that this parser is interested in.
96 ///
97 /// If an attribute has this symbol, the `accept` function will be called on it.
98 const ATTRIBUTES: AcceptMapping<Self, S>;
99 const ALLOWED_TARGETS: AllowedTargets;
100
101 /// The parser has gotten a chance to accept the attributes on an item,
102 /// here it can produce an attribute.
103 ///
104 /// All finalize methods of all parsers are unconditionally called.
105 /// This means you can't unconditionally return `Some` here,
106 /// that'd be equivalent to unconditionally applying an attribute to
107 /// every single syntax item that could have attributes applied to it.
108 /// Your accept mappings should determine whether this returns something.
109 fn finalize(self, cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind>;
110}
111
112/// Alternative to [`AttributeParser`] that automatically handles state management.
113/// A slightly simpler and more restricted way to convert attributes.
114/// Assumes that an attribute can only appear a single time on an item,
115/// and errors when it sees more.
116///
117/// [`Single<T> where T: SingleAttributeParser`](Single) implements [`AttributeParser`].
118///
119/// [`SingleAttributeParser`] can only convert attributes one-to-one, and cannot combine multiple
120/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
121pub(crate) trait SingleAttributeParser<S: Stage>: 'static {
122 /// The single path of the attribute this parser accepts.
123 ///
124 /// If you need the parser to accept more than one path, use [`AttributeParser`] instead
125 const PATH: &[Symbol];
126
127 /// Configures what to do when when the same attribute is
128 /// applied more than once on the same syntax node.
129 const ON_DUPLICATE: OnDuplicate<S>;
130
131 const ALLOWED_TARGETS: AllowedTargets;
132
133 /// The template this attribute parser should implement. Used for diagnostics.
134 const TEMPLATE: AttributeTemplate;
135
136 /// Converts a single syntactical attribute to a single semantic attribute, or [`AttributeKind`]
137 fn convert(cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser) -> Option<AttributeKind>;
138}
139
140/// Use in combination with [`SingleAttributeParser`].
141/// `Single<T: SingleAttributeParser>` implements [`AttributeParser`].
142pub(crate) struct Single<T: SingleAttributeParser<S>, S: Stage>(
143 PhantomData<(S, T)>,
144 Option<(AttributeKind, Span)>,
145);
146
147impl<T: SingleAttributeParser<S>, S: Stage> Default for Single<T, S> {
148 fn default() -> Self {
149 Self(Default::default(), Default::default())
150 }
151}
152
153impl<T: SingleAttributeParser<S>, S: Stage> AttributeParser<S> for Single<T, S> {
154 const ATTRIBUTES: AcceptMapping<Self, S> = &[(
155 T::PATH,
156 <T as SingleAttributeParser<S>>::TEMPLATE,
157 |group: &mut Single<T, S>, cx, args| {
158 if let Some(pa) = T::convert(cx, args) {
159 if let Some((_, used)) = group.1 {
160 T::ON_DUPLICATE.exec::<T>(cx, used, cx.attr_span);
161 }
162
163 group.1 = Some((pa, cx.attr_span));
164 }
165 },
166 )];
167 const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;
168
169 fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
170 Some(self.1?.0)
171 }
172}
173
174pub(crate) enum OnDuplicate<S: Stage> {
175 /// Give a default warning
176 Warn,
177
178 /// Duplicates will be a warning, with a note that this will be an error in the future.
179 WarnButFutureError,
180
181 /// Give a default error
182 Error,
183
184 /// Ignore duplicates
185 Ignore,
186
187 /// Custom function called when a duplicate attribute is found.
188 ///
189 /// - `unused` is the span of the attribute that was unused or bad because of some
190 /// duplicate reason
191 /// - `used` is the span of the attribute that was used in favor of the unused attribute
192 Custom(fn(cx: &AcceptContext<'_, '_, S>, used: Span, unused: Span)),
193}
194
195impl<S: Stage> OnDuplicate<S> {
196 fn exec<P: SingleAttributeParser<S>>(
197 &self,
198 cx: &mut AcceptContext<'_, '_, S>,
199 used: Span,
200 unused: Span,
201 ) {
202 match self {
203 OnDuplicate::Warn => cx.warn_unused_duplicate(used, unused),
204 OnDuplicate::WarnButFutureError => cx.warn_unused_duplicate_future_error(used, unused),
205 OnDuplicate::Error => {
206 cx.emit_err(UnusedMultiple {
207 this: unused,
208 other: used,
209 name: Symbol::intern(
210 &P::PATH.into_iter().map(|i| i.to_string()).collect::<Vec<_>>().join(".."),
211 ),
212 });
213 }
214 OnDuplicate::Ignore => {}
215 OnDuplicate::Custom(f) => f(cx, used, unused),
216 }
217 }
218}
219
220/// An even simpler version of [`SingleAttributeParser`]:
221/// now automatically check that there are no arguments provided to the attribute.
222///
223/// [`WithoutArgs<T> where T: NoArgsAttributeParser`](WithoutArgs) implements [`SingleAttributeParser`].
224//
225pub(crate) trait NoArgsAttributeParser<S: Stage>: 'static {
226 const PATH: &[Symbol];
227 const ON_DUPLICATE: OnDuplicate<S>;
228 const ALLOWED_TARGETS: AllowedTargets;
229
230 /// Create the [`AttributeKind`] given attribute's [`Span`].
231 const CREATE: fn(Span) -> AttributeKind;
232}
233
234pub(crate) struct WithoutArgs<T: NoArgsAttributeParser<S>, S: Stage>(PhantomData<(S, T)>);
235
236impl<T: NoArgsAttributeParser<S>, S: Stage> Default for WithoutArgs<T, S> {
237 fn default() -> Self {
238 Self(Default::default())
239 }
240}
241
242impl<T: NoArgsAttributeParser<S>, S: Stage> SingleAttributeParser<S> for WithoutArgs<T, S> {
243 const PATH: &[Symbol] = T::PATH;
244 const ON_DUPLICATE: OnDuplicate<S> = T::ON_DUPLICATE;
245 const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;
246 const TEMPLATE: AttributeTemplate = template!(Word);
247
248 fn convert(cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser) -> Option<AttributeKind> {
249 if let Err(span) = args.no_args() {
250 cx.adcx().expected_no_args(span);
251 }
252 Some(T::CREATE(cx.attr_span))
253 }
254}
255
256type ConvertFn<E> = fn(ThinVec<E>, Span) -> AttributeKind;
257
258/// Alternative to [`AttributeParser`] that automatically handles state management.
259/// If multiple attributes appear on an element, combines the values of each into a
260/// [`ThinVec`].
261/// [`Combine<T> where T: CombineAttributeParser`](Combine) implements [`AttributeParser`].
262///
263/// [`CombineAttributeParser`] can only convert a single kind of attribute, and cannot combine multiple
264/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
265pub(crate) trait CombineAttributeParser<S: Stage>: 'static {
266 const PATH: &[rustc_span::Symbol];
267
268 type Item;
269 /// A function that converts individual items (of type [`Item`](Self::Item)) into the final attribute.
270 ///
271 /// For example, individual representations from `#[repr(...)]` attributes into an `AttributeKind::Repr(x)`,
272 /// where `x` is a vec of these individual reprs.
273 const CONVERT: ConvertFn<Self::Item>;
274
275 const ALLOWED_TARGETS: AllowedTargets;
276
277 /// The template this attribute parser should implement. Used for diagnostics.
278 const TEMPLATE: AttributeTemplate;
279
280 /// Converts a single syntactical attribute to a number of elements of the semantic attribute, or [`AttributeKind`]
281 fn extend(
282 cx: &mut AcceptContext<'_, '_, S>,
283 args: &ArgParser,
284 ) -> impl IntoIterator<Item = Self::Item>;
285}
286
287/// Use in combination with [`CombineAttributeParser`].
288/// `Combine<T: CombineAttributeParser>` implements [`AttributeParser`].
289pub(crate) struct Combine<T: CombineAttributeParser<S>, S: Stage> {
290 phantom: PhantomData<(S, T)>,
291 /// A list of all items produced by parsing attributes so far. One attribute can produce any amount of items.
292 items: ThinVec<<T as CombineAttributeParser<S>>::Item>,
293 /// The full span of the first attribute that was encountered.
294 first_span: Option<Span>,
295}
296
297impl<T: CombineAttributeParser<S>, S: Stage> Default for Combine<T, S> {
298 fn default() -> Self {
299 Self {
300 phantom: Default::default(),
301 items: Default::default(),
302 first_span: Default::default(),
303 }
304 }
305}
306
307impl<T: CombineAttributeParser<S>, S: Stage> AttributeParser<S> for Combine<T, S> {
308 const ATTRIBUTES: AcceptMapping<Self, S> =
309 &[(T::PATH, T::TEMPLATE, |group: &mut Combine<T, S>, cx, args| {
310 // Keep track of the span of the first attribute, for diagnostics
311 group.first_span.get_or_insert(cx.attr_span);
312 group.items.extend(T::extend(cx, args))
313 })];
314 const ALLOWED_TARGETS: AllowedTargets = T::ALLOWED_TARGETS;
315
316 fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
317 if let Some(first_span) = self.first_span {
318 Some(T::CONVERT(self.items, first_span))
319 } else {
320 None
321 }
322 }
323}