1 //! Parsing and validation of builtin attributes
3 use super::{find_by_name, mark_used};
5 use rustc_ast::ast::{self, Attribute, Lit, LitKind, MetaItem, MetaItemKind, NestedMetaItem};
6 use rustc_ast_pretty::pprust;
7 use rustc_errors::{struct_span_err, Applicability, Handler};
8 use rustc_feature::{find_gated_cfg, is_builtin_attr_name, Features, GatedCfg};
9 use rustc_macros::HashStable_Generic;
10 use rustc_session::parse::{feature_err, ParseSess};
11 use rustc_span::hygiene::Transparency;
12 use rustc_span::{symbol::sym, symbol::Symbol, Span};
13 use std::num::NonZeroU32;
14 use version_check::Version;
16 pub fn is_builtin_attr(attr: &Attribute) -> bool {
17 attr.is_doc_comment() || attr.ident().filter(|ident| is_builtin_attr_name(ident.name)).is_some()
22 UnknownMetaItem(String, &'static [&'static str]),
25 MultipleStabilityLevels,
26 UnsupportedLiteral(&'static str, /* is_bytestr */ bool),
29 fn handle_errors(sess: &ParseSess, span: Span, error: AttrError) {
30 let diag = &sess.span_diagnostic;
32 AttrError::MultipleItem(item) => {
33 struct_span_err!(diag, span, E0538, "multiple '{}' items", item).emit();
35 AttrError::UnknownMetaItem(item, expected) => {
36 let expected = expected.iter().map(|name| format!("`{}`", name)).collect::<Vec<_>>();
37 struct_span_err!(diag, span, E0541, "unknown meta item '{}'", item)
38 .span_label(span, format!("expected one of {}", expected.join(", ")))
41 AttrError::MissingSince => {
42 struct_span_err!(diag, span, E0542, "missing 'since'").emit();
44 AttrError::MissingFeature => {
45 struct_span_err!(diag, span, E0546, "missing 'feature'").emit();
47 AttrError::MultipleStabilityLevels => {
48 struct_span_err!(diag, span, E0544, "multiple stability levels").emit();
50 AttrError::UnsupportedLiteral(msg, is_bytestr) => {
51 let mut err = struct_span_err!(diag, span, E0565, "{}", msg);
53 if let Ok(lint_str) = sess.source_map().span_to_snippet(span) {
56 "consider removing the prefix",
57 lint_str[1..].to_string(),
58 Applicability::MaybeIncorrect,
67 #[derive(Clone, PartialEq, RustcEncodable, RustcDecodable)]
75 #[derive(Clone, RustcEncodable, RustcDecodable)]
76 pub enum OptimizeAttr {
82 #[derive(Copy, Clone, PartialEq)]
88 /// Determine what `#[unwind]` attribute is present in `attrs`, if any.
89 pub fn find_unwind_attr(diagnostic: Option<&Handler>, attrs: &[Attribute]) -> Option<UnwindAttr> {
90 attrs.iter().fold(None, |ia, attr| {
91 if attr.check_name(sym::unwind) {
92 if let Some(meta) = attr.meta() {
93 if let MetaItemKind::List(items) = meta.kind {
95 if items[0].check_name(sym::allowed) {
96 return Some(UnwindAttr::Allowed);
97 } else if items[0].check_name(sym::aborts) {
98 return Some(UnwindAttr::Aborts);
102 if let Some(d) = diagnostic {
103 struct_span_err!(d, attr.span, E0633, "malformed `unwind` attribute input")
104 .span_label(attr.span, "invalid argument")
107 "the allowed arguments are `allowed` and `aborts`",
108 (vec!["allowed", "aborts"])
110 .map(|s| format!("#[unwind({})]", s)),
111 Applicability::MachineApplicable,
123 /// Represents the following attributes:
127 #[derive(RustcEncodable, RustcDecodable, Copy, Clone, Debug, PartialEq, Eq, Hash)]
128 #[derive(HashStable_Generic)]
129 pub struct Stability {
130 pub level: StabilityLevel,
134 /// Represents the `#[rustc_const_unstable]` and `#[rustc_const_stable]` attributes.
135 #[derive(RustcEncodable, RustcDecodable, Copy, Clone, Debug, PartialEq, Eq, Hash)]
136 #[derive(HashStable_Generic)]
137 pub struct ConstStability {
138 pub level: StabilityLevel,
140 /// whether the function has a `#[rustc_promotable]` attribute
141 pub promotable: bool,
142 /// whether the function has a `#[rustc_allow_const_fn_ptr]` attribute
143 pub allow_const_fn_ptr: bool,
146 /// The available stability levels.
147 #[derive(RustcEncodable, RustcDecodable, PartialEq, PartialOrd, Copy, Clone, Debug, Eq, Hash)]
148 #[derive(HashStable_Generic)]
149 pub enum StabilityLevel {
150 // Reason for the current stability level and the relevant rust-lang issue
151 Unstable { reason: Option<Symbol>, issue: Option<NonZeroU32>, is_soft: bool },
152 Stable { since: Symbol },
155 impl StabilityLevel {
156 pub fn is_unstable(&self) -> bool {
157 if let StabilityLevel::Unstable { .. } = *self { true } else { false }
159 pub fn is_stable(&self) -> bool {
160 if let StabilityLevel::Stable { .. } = *self { true } else { false }
164 /// Checks if `attrs` contains an attribute like `#![feature(feature_name)]`.
165 /// This will not perform any "sanity checks" on the form of the attributes.
166 pub fn contains_feature_attr(attrs: &[Attribute], feature_name: Symbol) -> bool {
167 attrs.iter().any(|item| {
168 item.check_name(sym::feature)
171 .map(|list| list.iter().any(|mi| mi.is_word() && mi.check_name(feature_name)))
176 /// Collects stability info from all stability attributes in `attrs`.
177 /// Returns `None` if no stability attributes are found.
178 pub fn find_stability(
182 ) -> (Option<Stability>, Option<ConstStability>) {
183 find_stability_generic(sess, attrs.iter(), item_sp)
186 fn find_stability_generic<'a, I>(
190 ) -> (Option<Stability>, Option<ConstStability>)
192 I: Iterator<Item = &'a Attribute>,
194 use StabilityLevel::*;
196 let mut stab: Option<Stability> = None;
197 let mut const_stab: Option<ConstStability> = None;
198 let mut promotable = false;
199 let mut allow_const_fn_ptr = false;
200 let diagnostic = &sess.span_diagnostic;
202 'outer: for attr in attrs_iter {
204 sym::rustc_const_unstable,
205 sym::rustc_const_stable,
208 sym::rustc_promotable,
209 sym::rustc_allow_const_fn_ptr,
212 .any(|&s| attr.has_name(s))
214 continue; // not a stability level
219 let meta = attr.meta();
221 if attr.has_name(sym::rustc_promotable) {
224 if attr.has_name(sym::rustc_allow_const_fn_ptr) {
225 allow_const_fn_ptr = true;
227 // attributes with data
228 else if let Some(MetaItem { kind: MetaItemKind::List(ref metas), .. }) = meta {
229 let meta = meta.as_ref().unwrap();
230 let get = |meta: &MetaItem, item: &mut Option<Symbol>| {
235 AttrError::MultipleItem(pprust::path_to_string(&meta.path)),
239 if let Some(v) = meta.value_str() {
243 struct_span_err!(diagnostic, meta.span, E0539, "incorrect meta item").emit();
248 let meta_name = meta.name_or_empty();
250 sym::rustc_const_unstable | sym::unstable => {
251 if meta_name == sym::unstable && stab.is_some() {
252 handle_errors(sess, attr.span, AttrError::MultipleStabilityLevels);
254 } else if meta_name == sym::rustc_const_unstable && const_stab.is_some() {
255 handle_errors(sess, attr.span, AttrError::MultipleStabilityLevels);
259 let mut feature = None;
260 let mut reason = None;
261 let mut issue = None;
262 let mut issue_num = None;
263 let mut is_soft = false;
265 if let Some(mi) = meta.meta_item() {
266 match mi.name_or_empty() {
268 if !get(mi, &mut feature) {
273 if !get(mi, &mut reason) {
278 if !get(mi, &mut issue) {
282 // These unwraps are safe because `get` ensures the meta item
283 // is a name/value pair string literal.
284 issue_num = match &*issue.unwrap().as_str() {
287 let emit_diag = |msg: &str| {
292 "`issue` must be a non-zero numeric string \
296 mi.name_value_literal().unwrap().span,
301 match issue.parse() {
302 Ok(num) if num == 0 => {
304 "`issue` must not be \"0\", \
305 use \"none\" instead",
309 Ok(num) => NonZeroU32::new(num),
311 emit_diag(&err.to_string());
320 let msg = "`soft` should not have any arguments";
321 sess.span_diagnostic.span_err(mi.span, msg);
329 AttrError::UnknownMetaItem(
330 pprust::path_to_string(&mi.path),
331 &["feature", "reason", "issue", "soft"],
341 AttrError::UnsupportedLiteral("unsupported literal", false),
347 match (feature, reason, issue) {
348 (Some(feature), reason, Some(_)) => {
349 let level = Unstable { reason, issue: issue_num, is_soft };
350 if sym::unstable == meta_name {
351 stab = Some(Stability { level, feature });
353 const_stab = Some(ConstStability {
357 allow_const_fn_ptr: false,
362 handle_errors(sess, attr.span, AttrError::MissingFeature);
366 struct_span_err!(diagnostic, attr.span, E0547, "missing 'issue'")
372 sym::rustc_const_stable | sym::stable => {
373 if meta_name == sym::stable && stab.is_some() {
374 handle_errors(sess, attr.span, AttrError::MultipleStabilityLevels);
376 } else if meta_name == sym::rustc_const_stable && const_stab.is_some() {
377 handle_errors(sess, attr.span, AttrError::MultipleStabilityLevels);
381 let mut feature = None;
382 let mut since = None;
385 NestedMetaItem::MetaItem(mi) => match mi.name_or_empty() {
387 if !get(mi, &mut feature) {
392 if !get(mi, &mut since) {
400 AttrError::UnknownMetaItem(
401 pprust::path_to_string(&mi.path),
408 NestedMetaItem::Literal(lit) => {
412 AttrError::UnsupportedLiteral("unsupported literal", false),
419 match (feature, since) {
420 (Some(feature), Some(since)) => {
421 let level = Stable { since };
422 if sym::stable == meta_name {
423 stab = Some(Stability { level, feature });
425 const_stab = Some(ConstStability {
429 allow_const_fn_ptr: false,
434 handle_errors(sess, attr.span, AttrError::MissingFeature);
438 handle_errors(sess, attr.span, AttrError::MissingSince);
448 // Merge the const-unstable info into the stability info
449 if promotable || allow_const_fn_ptr {
450 if let Some(ref mut stab) = const_stab {
451 stab.promotable = promotable;
452 stab.allow_const_fn_ptr = allow_const_fn_ptr;
458 "rustc_promotable and rustc_allow_const_fn_ptr attributes \
459 must be paired with either a rustc_const_unstable or a rustc_const_stable \
469 pub fn find_crate_name(attrs: &[Attribute]) -> Option<Symbol> {
470 super::first_attr_value_str_by_name(attrs, sym::crate_name)
473 /// Tests if a cfg-pattern matches the cfg set
474 pub fn cfg_matches(cfg: &ast::MetaItem, sess: &ParseSess, features: Option<&Features>) -> bool {
475 eval_condition(cfg, sess, features, &mut |cfg| {
476 try_gate_cfg(cfg, sess, features);
477 let error = |span, msg| {
478 sess.span_diagnostic.span_err(span, msg);
481 if cfg.path.segments.len() != 1 {
482 return error(cfg.path.span, "`cfg` predicate key must be an identifier");
485 MetaItemKind::List(..) => {
486 error(cfg.span, "unexpected parentheses after `cfg` predicate key")
488 MetaItemKind::NameValue(lit) if !lit.kind.is_str() => {
492 AttrError::UnsupportedLiteral(
493 "literal in `cfg` predicate value must be a string",
494 lit.kind.is_bytestr(),
499 MetaItemKind::NameValue(..) | MetaItemKind::Word => {
500 let ident = cfg.ident().expect("multi-segment cfg predicate");
501 sess.config.contains(&(ident.name, cfg.value_str()))
507 fn try_gate_cfg(cfg: &ast::MetaItem, sess: &ParseSess, features: Option<&Features>) {
508 let gate = find_gated_cfg(|sym| cfg.check_name(sym));
509 if let (Some(feats), Some(gated_cfg)) = (features, gate) {
510 gate_cfg(&gated_cfg, cfg.span, sess, feats);
514 fn gate_cfg(gated_cfg: &GatedCfg, cfg_span: Span, sess: &ParseSess, features: &Features) {
515 let (cfg, feature, has_feature) = gated_cfg;
516 if !has_feature(features) && !cfg_span.allows_unstable(*feature) {
517 let explain = format!("`cfg({})` is experimental and subject to change", cfg);
518 feature_err(sess, *feature, cfg_span, &explain).emit();
522 /// Evaluate a cfg-like condition (with `any` and `all`), using `eval` to
523 /// evaluate individual items.
524 pub fn eval_condition(
527 features: Option<&Features>,
528 eval: &mut impl FnMut(&ast::MetaItem) -> bool,
531 ast::MetaItemKind::List(ref mis) if cfg.name_or_empty() == sym::version => {
532 try_gate_cfg(cfg, sess, features);
533 let (min_version, span) = match &mis[..] {
534 [NestedMetaItem::Literal(Lit { kind: LitKind::Str(sym, ..), span, .. })] => {
537 [NestedMetaItem::Literal(Lit { span, .. })
538 | NestedMetaItem::MetaItem(MetaItem { span, .. })] => {
540 .struct_span_err(*span, "expected a version literal")
546 .struct_span_err(cfg.span, "expected single version literal")
551 let min_version = match Version::parse(&min_version.as_str()) {
554 sess.span_diagnostic.struct_span_err(*span, "invalid version literal").emit();
558 let channel = env!("CFG_RELEASE_CHANNEL");
559 let nightly = channel == "nightly" || channel == "dev";
560 let rustc_version = Version::parse(env!("CFG_RELEASE")).unwrap();
562 // See https://github.com/rust-lang/rust/issues/64796#issuecomment-625474439 for details
563 if nightly { rustc_version > min_version } else { rustc_version >= min_version }
565 ast::MetaItemKind::List(ref mis) => {
566 for mi in mis.iter() {
567 if !mi.is_meta_item() {
571 AttrError::UnsupportedLiteral("unsupported literal", false),
577 // The unwraps below may look dangerous, but we've already asserted
578 // that they won't fail with the loop above.
579 match cfg.name_or_empty() {
582 .any(|mi| eval_condition(mi.meta_item().unwrap(), sess, features, eval)),
585 .all(|mi| eval_condition(mi.meta_item().unwrap(), sess, features, eval)),
589 sess.span_diagnostic,
592 "expected 1 cfg-pattern"
598 !eval_condition(mis[0].meta_item().unwrap(), sess, features, eval)
602 sess.span_diagnostic,
605 "invalid predicate `{}`",
606 pprust::path_to_string(&cfg.path)
613 ast::MetaItemKind::Word | ast::MetaItemKind::NameValue(..) => eval(cfg),
617 #[derive(RustcEncodable, RustcDecodable, Clone, HashStable_Generic)]
618 pub struct Deprecation {
619 pub since: Option<Symbol>,
620 /// The note to issue a reason.
621 pub note: Option<Symbol>,
622 /// A text snippet used to completely replace any use of the deprecated item in an expression.
624 /// This is currently unstable.
625 pub suggestion: Option<Symbol>,
627 /// Whether to treat the since attribute as being a Rust version identifier
628 /// (rather than an opaque string).
629 pub is_since_rustc_version: bool,
632 /// Finds the deprecation attribute. `None` if none exists.
633 pub fn find_deprecation(
637 ) -> Option<Deprecation> {
638 find_deprecation_generic(sess, attrs.iter(), item_sp)
641 fn find_deprecation_generic<'a, I>(
645 ) -> Option<Deprecation>
647 I: Iterator<Item = &'a Attribute>,
649 let mut depr: Option<Deprecation> = None;
650 let diagnostic = &sess.span_diagnostic;
652 'outer: for attr in attrs_iter {
653 if !(attr.check_name(sym::deprecated) || attr.check_name(sym::rustc_deprecated)) {
658 struct_span_err!(diagnostic, item_sp, E0550, "multiple deprecated attributes").emit();
662 let meta = match attr.meta() {
666 let mut since = None;
668 let mut suggestion = None;
670 MetaItemKind::Word => {}
671 MetaItemKind::NameValue(..) => note = meta.value_str(),
672 MetaItemKind::List(list) => {
673 let get = |meta: &MetaItem, item: &mut Option<Symbol>| {
678 AttrError::MultipleItem(pprust::path_to_string(&meta.path)),
682 if let Some(v) = meta.value_str() {
686 if let Some(lit) = meta.name_value_literal() {
690 AttrError::UnsupportedLiteral(
691 "literal in `deprecated` \
692 value must be a string",
693 lit.kind.is_bytestr(),
697 struct_span_err!(diagnostic, meta.span, E0551, "incorrect meta item")
707 NestedMetaItem::MetaItem(mi) => match mi.name_or_empty() {
709 if !get(mi, &mut since) {
713 sym::note if attr.check_name(sym::deprecated) => {
714 if !get(mi, &mut note) {
718 sym::reason if attr.check_name(sym::rustc_deprecated) => {
719 if !get(mi, &mut note) {
723 sym::suggestion if attr.check_name(sym::rustc_deprecated) => {
724 if !get(mi, &mut suggestion) {
732 AttrError::UnknownMetaItem(
733 pprust::path_to_string(&mi.path),
734 if attr.check_name(sym::deprecated) {
737 &["since", "reason", "suggestion"]
744 NestedMetaItem::Literal(lit) => {
748 AttrError::UnsupportedLiteral(
749 "item in `deprecated` must be a key/value pair",
760 if suggestion.is_some() && attr.check_name(sym::deprecated) {
761 unreachable!("only allowed on rustc_deprecated")
764 if attr.check_name(sym::rustc_deprecated) {
766 handle_errors(sess, attr.span, AttrError::MissingSince);
771 struct_span_err!(diagnostic, attr.span, E0543, "missing 'reason'").emit();
778 let is_since_rustc_version = attr.check_name(sym::rustc_deprecated);
779 depr = Some(Deprecation { since, note, suggestion, is_since_rustc_version });
785 #[derive(PartialEq, Debug, RustcEncodable, RustcDecodable, Copy, Clone)]
796 #[derive(Eq, PartialEq, Debug, RustcEncodable, RustcDecodable, Copy, Clone, HashStable_Generic)]
798 SignedInt(ast::IntTy),
799 UnsignedInt(ast::UintTy),
804 pub fn is_signed(self) -> bool {
808 SignedInt(..) => true,
809 UnsignedInt(..) => false,
814 /// Parse #[repr(...)] forms.
816 /// Valid repr contents: any of the primitive integral type names (see
817 /// `int_type_of_word`, below) to specify enum discriminant type; `C`, to use
818 /// the same discriminant size that the corresponding C enum would or C
819 /// structure layout, `packed` to remove padding, and `transparent` to elegate representation
820 /// concerns to the only non-ZST field.
821 pub fn find_repr_attrs(sess: &ParseSess, attr: &Attribute) -> Vec<ReprAttr> {
824 let mut acc = Vec::new();
825 let diagnostic = &sess.span_diagnostic;
826 if attr.has_name(sym::repr) {
827 if let Some(items) = attr.meta_item_list() {
830 if !item.is_meta_item() {
834 AttrError::UnsupportedLiteral(
835 "meta item in `repr` must be an identifier",
842 let mut recognised = false;
844 let hint = match item.name_or_empty() {
845 sym::C => Some(ReprC),
846 sym::packed => Some(ReprPacked(1)),
847 sym::simd => Some(ReprSimd),
848 sym::transparent => Some(ReprTransparent),
849 sym::no_niche => Some(ReprNoNiche),
850 name => int_type_of_word(name).map(ReprInt),
853 if let Some(h) = hint {
857 } else if let Some((name, value)) = item.name_value_literal() {
858 let parse_alignment = |node: &ast::LitKind| -> Result<u32, &'static str> {
859 if let ast::LitKind::Int(literal, ast::LitIntType::Unsuffixed) = node {
860 if literal.is_power_of_two() {
861 // rustc_middle::ty::layout::Align restricts align to <= 2^29
862 if *literal <= 1 << 29 {
865 Err("larger than 2^29")
868 Err("not a power of two")
871 Err("not an unsuffixed integer")
875 let mut literal_error = None;
876 if name == sym::align {
878 match parse_alignment(&value.kind) {
879 Ok(literal) => acc.push(ReprAlign(literal)),
880 Err(message) => literal_error = Some(message),
882 } else if name == sym::packed {
884 match parse_alignment(&value.kind) {
885 Ok(literal) => acc.push(ReprPacked(literal)),
886 Err(message) => literal_error = Some(message),
889 if let Some(literal_error) = literal_error {
894 "invalid `repr(align)` attribute: {}",
900 if let Some(meta_item) = item.meta_item() {
901 if meta_item.check_name(sym::align) {
902 if let MetaItemKind::NameValue(ref value) = meta_item.kind {
904 let mut err = struct_span_err!(
908 "incorrect `repr(align)` attribute format"
911 ast::LitKind::Int(int, ast::LitIntType::Unsuffixed) => {
914 "use parentheses instead",
915 format!("align({})", int),
916 Applicability::MachineApplicable,
919 ast::LitKind::Str(s, _) => {
922 "use parentheses instead",
923 format!("align({})", s),
924 Applicability::MachineApplicable,
935 // Not a word we recognize
940 "unrecognized representation hint"
950 fn int_type_of_word(s: Symbol) -> Option<IntType> {
954 sym::i8 => Some(SignedInt(ast::IntTy::I8)),
955 sym::u8 => Some(UnsignedInt(ast::UintTy::U8)),
956 sym::i16 => Some(SignedInt(ast::IntTy::I16)),
957 sym::u16 => Some(UnsignedInt(ast::UintTy::U16)),
958 sym::i32 => Some(SignedInt(ast::IntTy::I32)),
959 sym::u32 => Some(UnsignedInt(ast::UintTy::U32)),
960 sym::i64 => Some(SignedInt(ast::IntTy::I64)),
961 sym::u64 => Some(UnsignedInt(ast::UintTy::U64)),
962 sym::i128 => Some(SignedInt(ast::IntTy::I128)),
963 sym::u128 => Some(UnsignedInt(ast::UintTy::U128)),
964 sym::isize => Some(SignedInt(ast::IntTy::Isize)),
965 sym::usize => Some(UnsignedInt(ast::UintTy::Usize)),
970 pub enum TransparencyError {
971 UnknownTransparency(Symbol, Span),
972 MultipleTransparencyAttrs(Span, Span),
975 pub fn find_transparency(
978 ) -> (Transparency, Option<TransparencyError>) {
979 let mut transparency = None;
980 let mut error = None;
982 if attr.check_name(sym::rustc_macro_transparency) {
983 if let Some((_, old_span)) = transparency {
984 error = Some(TransparencyError::MultipleTransparencyAttrs(old_span, attr.span));
986 } else if let Some(value) = attr.value_str() {
987 transparency = Some((
989 sym::transparent => Transparency::Transparent,
990 sym::semitransparent => Transparency::SemiTransparent,
991 sym::opaque => Transparency::Opaque,
993 error = Some(TransparencyError::UnknownTransparency(value, attr.span));
1002 let fallback = if macro_rules { Transparency::SemiTransparent } else { Transparency::Opaque };
1003 (transparency.map_or(fallback, |t| t.0), error)
1006 pub fn allow_internal_unstable<'a>(
1007 attrs: &[Attribute],
1008 diag: &'a rustc_errors::Handler,
1009 ) -> Option<impl Iterator<Item = Symbol> + 'a> {
1010 let attr = find_by_name(attrs, sym::allow_internal_unstable)?;
1011 let list = attr.meta_item_list().or_else(|| {
1012 diag.span_err(attr.span, "allow_internal_unstable expects list of feature names");
1015 Some(list.into_iter().filter_map(move |it| {
1016 let name = it.ident().map(|ident| ident.name);
1018 diag.span_err(it.span(), "`allow_internal_unstable` expects feature names");