From d0153f5872c484dff2a4b0ef6cad45c1f14fa1b7 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Mon, 14 Jul 2025 11:03:16 +0200 Subject: [PATCH] update `cfg_select!` documentation and make internal terminology consistent Co-authored-by: Travis Cross --- compiler/rustc_builtin_macros/messages.ftl | 6 +++--- compiler/rustc_builtin_macros/src/cfg_select.rs | 16 ++++++++-------- compiler/rustc_parse/src/parser/cfg_select.rs | 10 ++++++---- library/core/src/macros/mod.rs | 16 +++++++--------- tests/ui/macros/cfg_select.rs | 7 +++++-- tests/ui/macros/cfg_select.stderr | 14 ++++++++++---- 6 files changed, 39 insertions(+), 30 deletions(-) diff --git a/compiler/rustc_builtin_macros/messages.ftl b/compiler/rustc_builtin_macros/messages.ftl index 183927edb0220..ae186d744c40e 100644 --- a/compiler/rustc_builtin_macros/messages.ftl +++ b/compiler/rustc_builtin_macros/messages.ftl @@ -81,11 +81,11 @@ builtin_macros_cfg_accessible_literal_path = `cfg_accessible` path cannot be a l builtin_macros_cfg_accessible_multiple_paths = multiple `cfg_accessible` paths are specified builtin_macros_cfg_accessible_unspecified_path = `cfg_accessible` path is not specified -builtin_macros_cfg_select_no_matches = none of the rules in this `cfg_select` evaluated to true +builtin_macros_cfg_select_no_matches = none of the predicates in this `cfg_select` evaluated to true -builtin_macros_cfg_select_unreachable = unreachable rule +builtin_macros_cfg_select_unreachable = unreachable predicate .label = always matches - .label2 = this rules is never reached + .label2 = this predicate is never reached builtin_macros_coerce_pointee_requires_maybe_sized = `derive(CoercePointee)` requires `{$name}` to be marked `?Sized` diff --git a/compiler/rustc_builtin_macros/src/cfg_select.rs b/compiler/rustc_builtin_macros/src/cfg_select.rs index 2dc387d5866aa..f22d5f255c292 100644 --- a/compiler/rustc_builtin_macros/src/cfg_select.rs +++ b/compiler/rustc_builtin_macros/src/cfg_select.rs @@ -1,12 +1,12 @@ use rustc_ast::tokenstream::TokenStream; use rustc_attr_parsing as attr; use rustc_expand::base::{DummyResult, ExpandResult, ExtCtxt, MacroExpanderResult}; -use rustc_parse::parser::cfg_select::{CfgSelectBranches, CfgSelectRule, parse_cfg_select}; +use rustc_parse::parser::cfg_select::{CfgSelectBranches, CfgSelectPredicate, parse_cfg_select}; use rustc_span::{Ident, Span, sym}; use crate::errors::{CfgSelectNoMatches, CfgSelectUnreachable}; -/// Selects the first arm whose rule evaluates to true. +/// Selects the first arm whose predicate evaluates to true. fn select_arm(ecx: &ExtCtxt<'_>, branches: CfgSelectBranches) -> Option<(TokenStream, Span)> { for (cfg, tt, arm_span) in branches.reachable { if attr::cfg_matches( @@ -30,11 +30,11 @@ pub(super) fn expand_cfg_select<'cx>( ExpandResult::Ready(match parse_cfg_select(&mut ecx.new_parser_from_tts(tts)) { Ok(branches) => { if let Some((underscore, _, _)) = branches.wildcard { - // Warn for every unreachable rule. We store the fully parsed branch for rustfmt. - for (rule, _, _) in &branches.unreachable { - let span = match rule { - CfgSelectRule::Wildcard(underscore) => underscore.span, - CfgSelectRule::Cfg(cfg) => cfg.span(), + // Warn for every unreachable predicate. We store the fully parsed branch for rustfmt. + for (predicate, _, _) in &branches.unreachable { + let span = match predicate { + CfgSelectPredicate::Wildcard(underscore) => underscore.span, + CfgSelectPredicate::Cfg(cfg) => cfg.span(), }; let err = CfgSelectUnreachable { span, wildcard_span: underscore.span }; ecx.dcx().emit_warn(err); @@ -50,7 +50,7 @@ pub(super) fn expand_cfg_select<'cx>( Ident::with_dummy_span(sym::cfg_select), ); } else { - // Emit a compiler error when none of the rules matched. + // Emit a compiler error when none of the predicates matched. let guar = ecx.dcx().emit_err(CfgSelectNoMatches { span: sp }); DummyResult::any(sp, guar) } diff --git a/compiler/rustc_parse/src/parser/cfg_select.rs b/compiler/rustc_parse/src/parser/cfg_select.rs index 24a05afff4ac9..2c6fb224d70d6 100644 --- a/compiler/rustc_parse/src/parser/cfg_select.rs +++ b/compiler/rustc_parse/src/parser/cfg_select.rs @@ -7,7 +7,7 @@ use rustc_span::Span; use crate::exp; use crate::parser::Parser; -pub enum CfgSelectRule { +pub enum CfgSelectPredicate { Cfg(MetaItemInner), Wildcard(Token), } @@ -20,7 +20,7 @@ pub struct CfgSelectBranches { pub wildcard: Option<(Token, TokenStream, Span)>, /// All branches after the first wildcard, including further wildcards. /// These branches are kept for formatting. - pub unreachable: Vec<(CfgSelectRule, TokenStream, Span)>, + pub unreachable: Vec<(CfgSelectPredicate, TokenStream, Span)>, } /// Parses a `TokenTree` that must be of the form `{ /* ... */ }`, and returns a `TokenStream` where @@ -52,7 +52,7 @@ pub fn parse_cfg_select<'a>(p: &mut Parser<'a>) -> PResult<'a, CfgSelectBranches match branches.wildcard { None => branches.wildcard = Some((underscore, tts, span)), Some(_) => { - branches.unreachable.push((CfgSelectRule::Wildcard(underscore), tts, span)) + branches.unreachable.push((CfgSelectPredicate::Wildcard(underscore), tts, span)) } } } else { @@ -64,7 +64,9 @@ pub fn parse_cfg_select<'a>(p: &mut Parser<'a>) -> PResult<'a, CfgSelectBranches match branches.wildcard { None => branches.reachable.push((meta_item, tts, span)), - Some(_) => branches.unreachable.push((CfgSelectRule::Cfg(meta_item), tts, span)), + Some(_) => { + branches.unreachable.push((CfgSelectPredicate::Cfg(meta_item), tts, span)) + } } } } diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index 6b9cbb0643586..1b6dbc2f428f7 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -196,16 +196,14 @@ pub macro assert_matches { }, } -/// A macro for defining `#[cfg]` match-like statements. +/// Selects code at compile-time based on `cfg` predicates. /// -/// It is similar to the `if/elif` C preprocessor macro by allowing definition of a cascade of -/// `#[cfg]` cases, emitting the implementation which matches first. +/// This macro evaluates, at compile-time, a series of `cfg` predicates, +/// selects the first that is true, and emits the code guarded by that +/// predicate. The code guarded by other predicates is not emitted. /// -/// This allows you to conveniently provide a long list `#[cfg]`'d blocks of code -/// without having to rewrite each clause multiple times. -/// -/// Trailing `_` wildcard match arms are **optional** and they indicate a fallback branch when -/// all previous declarations do not evaluate to true. +/// An optional trailing `_` wildcard can be used to specify a fallback. If +/// none of the predicates are true, a [`compile_error`] is emitted. /// /// # Example /// @@ -225,7 +223,7 @@ pub macro assert_matches { /// } /// ``` /// -/// If desired, it is possible to return expressions through the use of surrounding braces: +/// The `cfg_select!` macro can also be used in expression position: /// /// ``` /// #![feature(cfg_select)] diff --git a/tests/ui/macros/cfg_select.rs b/tests/ui/macros/cfg_select.rs index a4d94836a09a1..461d2e0e8c1f5 100644 --- a/tests/ui/macros/cfg_select.rs +++ b/tests/ui/macros/cfg_select.rs @@ -18,10 +18,13 @@ fn arm_rhs_must_be_in_braces() -> i32 { cfg_select! { _ => {} true => {} - //~^ WARN unreachable rule + //~^ WARN unreachable predicate } cfg_select! { - //~^ ERROR none of the rules in this `cfg_select` evaluated to true + //~^ ERROR none of the predicates in this `cfg_select` evaluated to true false => {} } + +cfg_select! {} +//~^ ERROR none of the predicates in this `cfg_select` evaluated to true diff --git a/tests/ui/macros/cfg_select.stderr b/tests/ui/macros/cfg_select.stderr index fef5e95a6bce9..6c18a7c189dcc 100644 --- a/tests/ui/macros/cfg_select.stderr +++ b/tests/ui/macros/cfg_select.stderr @@ -4,15 +4,15 @@ error: expected `{`, found `1` LL | true => 1 | ^ expected `{` -warning: unreachable rule +warning: unreachable predicate --> $DIR/cfg_select.rs:20:5 | LL | _ => {} | - always matches LL | true => {} - | ^^^^ this rules is never reached + | ^^^^ this predicate is never reached -error: none of the rules in this `cfg_select` evaluated to true +error: none of the predicates in this `cfg_select` evaluated to true --> $DIR/cfg_select.rs:24:1 | LL | / cfg_select! { @@ -21,5 +21,11 @@ LL | | false => {} LL | | } | |_^ -error: aborting due to 2 previous errors; 1 warning emitted +error: none of the predicates in this `cfg_select` evaluated to true + --> $DIR/cfg_select.rs:29:1 + | +LL | cfg_select! {} + | ^^^^^^^^^^^^^^ + +error: aborting due to 3 previous errors; 1 warning emitted