cfg_select! macro

src/conditional-compilation.md

@@ -31,7 +31,7 @@ r[cfg.general]
 *Conditionally compiled source code* is source code that is compiled only under certain conditions.
 
 r[cfg.attributes-macro]
-Source code can be made conditionally compiled using the [`cfg`] and [`cfg_attr`] [attributes] and the built-in [`cfg` macro].
+Source code can be made conditionally compiled using the [`cfg`] and [`cfg_attr`] [attributes] and the built-in [`cfg!`] and [`cfg_select!`] [macros].
 
 r[cfg.conditional]
 Whether to compile can depend on the target architecture of the compiled crate, arbitrary values passed to the compiler, and other things further described below.
@@ -466,11 +466,78 @@ let machine_kind = if cfg!(unix) {
 println!("I'm running on a {} machine!", machine_kind);
 ```
 
+r[cfg.cfg_select]
+### The `cfg_select` macro
+
+r[cfg.cfg_select.syntax]
+```grammar,configuration
+@root CfgSelect -> CfgSelectArms?
+
+CfgSelectArms ->
+    CfgSelectConfigurationPredicate `=>`
+    (
+        `{` ^ TokenTree `}` CfgSelectArms?
+      | ExpressionWithBlockNoAttrs `,`? CfgSelectArms?
+      | ExpressionWithoutBlockNoAttrs ( `,` CfgSelectArms? )?
+    )
+
+CfgSelectConfigurationPredicate ->
+    ConfigurationPredicate | `_`
+```
+
+r[cfg.cfg_select.general]
+The built-in `cfg_select` macro expands to the arm payload of the first configuration predicate that evaluates to `true`. If the payload is wrapped in curly braces, those are removed during expansion.
+
+For example:
+
+```rust
+cfg_select! {
+    unix => {
+        fn foo() { /* unix specific functionality */ }
+    }
+    target_pointer_width = "32" => {
+        fn foo() { /* non-unix, 32-bit functionality */ }
+    }
+    _ => {
+        fn foo() { /* fallback implementation */ }
+    }
+}
+```
+The `cfg_select` macro can also be used in expression position:
+
+```rust
+let is_unix_str = cfg_select! {
+    unix => "unix",
+    _ => "not unix",
+};
+```
+
+r[cfg.cfg_select.wildcard]
+A `_` can be used to write a configuration predicate that always evaluates to `true`.
+
+r[cfg.cfg_select.fallthrough]
+If none of the predicates evaluates to `true`, a compiler error is emitted.
+
+r[cfg.cfg_select.positions]
+The `cfg_select!` macro is accepted in the following macro expansion positions
+
+- items
+- statements
+- expression
+- impl items
+- trait impl items
+- trait items
+- foreign items
+
+r[cfg.cfg_select.well-formed]
+Each right-hand side must syntactically be valid expansion for the position that the macro is invoked in.
+
 [Testing]: attributes/testing.md
 [`--cfg`]: ../rustc/command-line-arguments.html#--cfg-configure-the-compilation-environment
 [`--test`]: ../rustc/command-line-arguments.html#--test-build-a-test-harness
 [`cfg`]: #the-cfg-attribute
-[`cfg` macro]: #the-cfg-macro
+[`cfg!`]: #the-cfg-macro
+[`cfg_select!`]: #the-cfg_select-macro
 [`cfg_attr`]: #the-cfg_attr-attribute
 [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
 [`crate_type`]: linkage.md
@@ -479,4 +546,5 @@ println!("I'm running on a {} machine!", machine_kind);
 [attributes]: attributes.md
 [cargo-feature]: ../cargo/reference/features.html
 [crate type]: linkage.md
+[macros]: macros.md
 [static C runtime]: linkage.md#static-and-dynamic-c-runtimes

src/expressions.md

@@ -8,41 +8,41 @@ Expression ->
     | ExpressionWithBlock
 
 ExpressionWithoutBlock ->
-    OuterAttribute*
-    (
-        LiteralExpression
-      | PathExpression
-      | OperatorExpression
-      | GroupedExpression
-      | ArrayExpression
-      | AwaitExpression
-      | IndexExpression
-      | TupleExpression
-      | TupleIndexingExpression
-      | StructExpression
-      | CallExpression
-      | MethodCallExpression
-      | FieldExpression
-      | ClosureExpression
-      | AsyncBlockExpression
-      | ContinueExpression
-      | BreakExpression
-      | RangeExpression
-      | ReturnExpression
-      | UnderscoreExpression
-      | MacroInvocation
-    )
+    OuterAttribute* ExpressionWithoutBlockNoAttrs
+
+ExpressionWithoutBlockNoAttrs ->
+      LiteralExpression
+    | PathExpression
+    | OperatorExpression
+    | GroupedExpression
+    | ArrayExpression
+    | AwaitExpression
+    | IndexExpression
+    | TupleExpression
+    | TupleIndexingExpression
+    | StructExpression
+    | CallExpression
+    | MethodCallExpression
+    | FieldExpression
+    | ClosureExpression
+    | AsyncBlockExpression
+    | ContinueExpression
+    | BreakExpression
+    | RangeExpression
+    | ReturnExpression
+    | UnderscoreExpression
+    | MacroInvocation
 
 ExpressionWithBlock ->
-    OuterAttribute*
-    (
-        BlockExpression
-      | ConstBlockExpression
-      | UnsafeBlockExpression
-      | LoopExpression
-      | IfExpression
-      | MatchExpression
-    )
+    OuterAttribute* ExpressionWithBlockNoAttrs
+
+ExpressionWithBlockNoAttrs ->
+      BlockExpression
+    | ConstBlockExpression
+    | UnsafeBlockExpression
+    | LoopExpression
+    | IfExpression
+    | MatchExpression
 ```
 
 r[expr.intro]