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;
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 repr;
39pub(crate) mod semantics;
40pub(crate) mod stability;
41pub(crate) mod traits;
42pub(crate) mod transparency;
43pub(crate) mod util;
44
45type AcceptFn<T, S> = for<'sess> fn(&mut T, &mut AcceptContext<'_, 'sess, S>, &ArgParser<'_>);
46type AcceptMapping<T, S> = &'static [(&'static [Symbol], AttributeTemplate, AcceptFn<T, S>)];
47
48/// An [`AttributeParser`] is a type which searches for syntactic attributes.
49///
50/// Parsers are often tiny state machines that gets to see all syntactical attributes on an item.
51/// [`Default::default`] creates a fresh instance that sits in some kind of initial state, usually that the
52/// attribute it is looking for was not yet seen.
53///
54/// Then, it defines what paths this group will accept in [`AttributeParser::ATTRIBUTES`].
55/// These are listed as pairs, of symbols and function pointers. The function pointer will
56/// be called when that attribute is found on an item, which can influence the state of the little
57/// state machine.
58///
59/// Finally, after all attributes on an item have been seen, and possibly been accepted,
60/// the [`finalize`](AttributeParser::finalize) functions for all attribute parsers are called. Each can then report
61/// whether it has seen the attribute it has been looking for.
62///
63/// The state machine is automatically reset to parse attributes on the next item.
64///
65/// For a simpler attribute parsing interface, consider using [`SingleAttributeParser`]
66/// or [`CombineAttributeParser`] instead.
67pub(crate) trait AttributeParser<S: Stage>: Default + 'static {
68 /// The symbols for the attributes that this parser is interested in.
69 ///
70 /// If an attribute has this symbol, the `accept` function will be called on it.
71 const ATTRIBUTES: AcceptMapping<Self, S>;
72
73 /// The parser has gotten a chance to accept the attributes on an item,
74 /// here it can produce an attribute.
75 ///
76 /// All finalize methods of all parsers are unconditionally called.
77 /// This means you can't unconditionally return `Some` here,
78 /// that'd be equivalent to unconditionally applying an attribute to
79 /// every single syntax item that could have attributes applied to it.
80 /// Your accept mappings should determine whether this returns something.
81 fn finalize(self, cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind>;
82}
83
84/// Alternative to [`AttributeParser`] that automatically handles state management.
85/// A slightly simpler and more restricted way to convert attributes.
86/// Assumes that an attribute can only appear a single time on an item,
87/// and errors when it sees more.
88///
89/// [`Single<T> where T: SingleAttributeParser`](Single) implements [`AttributeParser`].
90///
91/// [`SingleAttributeParser`] can only convert attributes one-to-one, and cannot combine multiple
92/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
93pub(crate) trait SingleAttributeParser<S: Stage>: 'static {
94 /// The single path of the attribute this parser accepts.
95 ///
96 /// If you need the parser to accept more than one path, use [`AttributeParser`] instead
97 const PATH: &[Symbol];
98
99 /// Configures the precedence of attributes with the same `PATH` on a syntax node.
100 const ATTRIBUTE_ORDER: AttributeOrder;
101
102 /// Configures what to do when when the same attribute is
103 /// applied more than once on the same syntax node.
104 ///
105 /// [`ATTRIBUTE_ORDER`](Self::ATTRIBUTE_ORDER) specified which one is assumed to be correct,
106 /// and this specified whether to, for example, warn or error on the other one.
107 const ON_DUPLICATE: OnDuplicate<S>;
108
109 /// The template this attribute parser should implement. Used for diagnostics.
110 const TEMPLATE: AttributeTemplate;
111
112 /// Converts a single syntactical attribute to a single semantic attribute, or [`AttributeKind`]
113 fn convert(cx: &mut AcceptContext<'_, '_, S>, args: &ArgParser<'_>) -> Option<AttributeKind>;
114}
115
116/// Use in combination with [`SingleAttributeParser`].
117/// `Single<T: SingleAttributeParser>` implements [`AttributeParser`].
118pub(crate) struct Single<T: SingleAttributeParser<S>, S: Stage>(
119 PhantomData<(S, T)>,
120 Option<(AttributeKind, Span)>,
121);
122
123impl<T: SingleAttributeParser<S>, S: Stage> Default for Single<T, S> {
124 fn default() -> Self {
125 Self(Default::default(), Default::default())
126 }
127}
128
129impl<T: SingleAttributeParser<S>, S: Stage> AttributeParser<S> for Single<T, S> {
130 const ATTRIBUTES: AcceptMapping<Self, S> = &[(
131 T::PATH,
132 <T as SingleAttributeParser<S>>::TEMPLATE,
133 |group: &mut Single<T, S>, cx, args| {
134 if let Some(pa) = T::convert(cx, args) {
135 match T::ATTRIBUTE_ORDER {
136 // keep the first and report immediately. ignore this attribute
137 AttributeOrder::KeepFirst => {
138 if let Some((_, unused)) = group.1 {
139 T::ON_DUPLICATE.exec::<T>(cx, cx.attr_span, unused);
140 return;
141 }
142 }
143 // keep the new one and warn about the previous,
144 // then replace
145 AttributeOrder::KeepLast => {
146 if let Some((_, used)) = group.1 {
147 T::ON_DUPLICATE.exec::<T>(cx, used, cx.attr_span);
148 }
149 }
150 }
151
152 group.1 = Some((pa, cx.attr_span));
153 }
154 },
155 )];
156
157 fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
158 Some(self.1?.0)
159 }
160}
161
162// FIXME(jdonszelmann): logic is implemented but the attribute parsers needing
163// them will be merged in another PR
164#[allow(unused)]
165pub(crate) enum OnDuplicate<S: Stage> {
166 /// Give a default warning
167 Warn,
168
169 /// Duplicates will be a warning, with a note that this will be an error in the future.
170 WarnButFutureError,
171
172 /// Give a default error
173 Error,
174
175 /// Ignore duplicates
176 Ignore,
177
178 /// Custom function called when a duplicate attribute is found.
179 ///
180 /// - `unused` is the span of the attribute that was unused or bad because of some
181 /// duplicate reason (see [`AttributeOrder`])
182 /// - `used` is the span of the attribute that was used in favor of the unused attribute
183 Custom(fn(cx: &AcceptContext<'_, '_, S>, used: Span, unused: Span)),
184}
185
186impl<S: Stage> OnDuplicate<S> {
187 fn exec<P: SingleAttributeParser<S>>(
188 &self,
189 cx: &mut AcceptContext<'_, '_, S>,
190 used: Span,
191 unused: Span,
192 ) {
193 match self {
194 OnDuplicate::Warn => cx.warn_unused_duplicate(used, unused),
195 OnDuplicate::WarnButFutureError => cx.warn_unused_duplicate_future_error(used, unused),
196 OnDuplicate::Error => {
197 cx.emit_err(UnusedMultiple {
198 this: used,
199 other: unused,
200 name: Symbol::intern(
201 &P::PATH.into_iter().map(|i| i.to_string()).collect::<Vec<_>>().join(".."),
202 ),
203 });
204 }
205 OnDuplicate::Ignore => {}
206 OnDuplicate::Custom(f) => f(cx, used, unused),
207 }
208 }
209}
210//
211// FIXME(jdonszelmann): logic is implemented but the attribute parsers needing
212// them will be merged in another PR
213#[allow(unused)]
214pub(crate) enum AttributeOrder {
215 /// Duplicates after the first attribute will be an error.
216 ///
217 /// This should be used where duplicates would be ignored, but carry extra
218 /// meaning that could cause confusion. For example, `#[stable(since="1.0")]
219 /// #[stable(since="2.0")]`, which version should be used for `stable`?
220 KeepFirst,
221
222 /// Duplicates preceding the last instance of the attribute will be a
223 /// warning, with a note that this will be an error in the future.
224 ///
225 /// This is the same as `FutureWarnFollowing`, except the last attribute is
226 /// the one that is "used". Ideally these can eventually migrate to
227 /// `ErrorPreceding`.
228 KeepLast,
229}
230
231type ConvertFn<E> = fn(ThinVec<E>) -> AttributeKind;
232
233/// Alternative to [`AttributeParser`] that automatically handles state management.
234/// If multiple attributes appear on an element, combines the values of each into a
235/// [`ThinVec`].
236/// [`Combine<T> where T: CombineAttributeParser`](Combine) implements [`AttributeParser`].
237///
238/// [`CombineAttributeParser`] can only convert a single kind of attribute, and cannot combine multiple
239/// attributes together like is necessary for `#[stable()]` and `#[unstable()]` for example.
240pub(crate) trait CombineAttributeParser<S: Stage>: 'static {
241 const PATH: &[rustc_span::Symbol];
242
243 type Item;
244 /// A function that converts individual items (of type [`Item`](Self::Item)) into the final attribute.
245 ///
246 /// For example, individual representations fomr `#[repr(...)]` attributes into an `AttributeKind::Repr(x)`,
247 /// where `x` is a vec of these individual reprs.
248 const CONVERT: ConvertFn<Self::Item>;
249
250 /// The template this attribute parser should implement. Used for diagnostics.
251 const TEMPLATE: AttributeTemplate;
252
253 /// Converts a single syntactical attribute to a number of elements of the semantic attribute, or [`AttributeKind`]
254 fn extend<'c>(
255 cx: &'c mut AcceptContext<'_, '_, S>,
256 args: &'c ArgParser<'_>,
257 ) -> impl IntoIterator<Item = Self::Item> + 'c;
258}
259
260/// Use in combination with [`CombineAttributeParser`].
261/// `Combine<T: CombineAttributeParser>` implements [`AttributeParser`].
262pub(crate) struct Combine<T: CombineAttributeParser<S>, S: Stage>(
263 PhantomData<(S, T)>,
264 ThinVec<<T as CombineAttributeParser<S>>::Item>,
265);
266
267impl<T: CombineAttributeParser<S>, S: Stage> Default for Combine<T, S> {
268 fn default() -> Self {
269 Self(Default::default(), Default::default())
270 }
271}
272
273impl<T: CombineAttributeParser<S>, S: Stage> AttributeParser<S> for Combine<T, S> {
274 const ATTRIBUTES: AcceptMapping<Self, S> = &[(
275 T::PATH,
276 <T as CombineAttributeParser<S>>::TEMPLATE,
277 |group: &mut Combine<T, S>, cx, args| group.1.extend(T::extend(cx, args)),
278 )];
279
280 fn finalize(self, _cx: &FinalizeContext<'_, '_, S>) -> Option<AttributeKind> {
281 if self.1.is_empty() { None } else { Some(T::CONVERT(self.1)) }
282 }
283}