[SE-0415] Narrow scope down to just "body" macros. (#2433)

DougGregor · PsychoH13 · web-flow · commit 49f5b777d6c5 · 2024-05-03T09:13:43.000-07:00
* [SE-0415] Narrow scope down to just "body" macros.

* Update proposals/0415-function-body-macros.md

Co-authored-by: Remy Demarest &lt;remy.demarest@gmail.com&gt;

---------

Co-authored-by: Remy Demarest &lt;remy.demarest@gmail.com&gt;
diff --git a/proposals/0415-function-body-macros.md b/proposals/0415-function-body-macros.md
@@ -4,7 +4,7 @@
 * Authors: [Doug Gregor](https://github.com/DougGregor)
 * Review Manager: [Tony Allevato](https://github.com/allevato)
 * Status: **Returned for revision**
-* Implementation: [Pull request](https://github.com/apple/swift/pull/70034)
+* Implementation: Available on `main` behind the flag `-enable-experimental-feature BodyMacros`
 * Feature Flag: `BodyMacros`
 * Review: [pitch](https://forums.swift.org/t/function-body-macros/66471), [review](https://forums.swift.org/t/se-0415-function-body-macros/68847), [returned for revision](https://forums.swift.org/t/returned-for-revision-se-0415-function-body-macros/69114)
 
@@ -17,13 +17,11 @@
    * [Implementing function body macros](#implementing-function-body-macros)
    * [Composing function body macros](#composing-function-body-macros)
    * [Type checking of functions involving function body macros](#type-checking-of-functions-involving-function-body-macros)
-   * [Function body macros and implicit returns](#function-body-macros-and-implicit-returns)
 * [Source compatibility](#source-compatibility)
 * [Effect on ABI stability](#effect-on-abi-stability)
 * [Effect on API resilience](#effect-on-api-resilience)
 * [Future directions](#future-directions)
    * [Function body macros on closures](#function-body-macros-on-closures)
-
 * [Alternatives considered](#alternatives-considered)
    * [Eliminating preamble macros](#eliminating-preamble-macros)
    * [Capturing the withSpan pattern in another macro role](#capturing-the-withspan-pattern-in-another-macro-role)
@@ -123,12 +121,12 @@ When using the shorthand syntax for get-only properties, a function body macro c
 
 ### Declaring function body macros
 
-Function body macros are declared with the `body` or `preamble` role, which indicate that they can be attached to any kind of function, and can produce the contents of a function body. For example, here are declarations for the macros used above:
+Function body macros are declared with the `body` role, which indicate that they can be attached to any kind of function, and can produce the contents of a function body. For example, here are declarations for the macros used above:
 
 ```swift
 @attached(body) macro Remote() = #externalMacro(...)
 
-@attached(preamble) macro Logged() = #externalMacro(...)
+@attached(body) macro Logged() = #externalMacro(...)
 
 @attached(body) macro AssumeMainActor() = #externalMacro(...)
 ```
@@ -158,99 +156,10 @@ public protocol BodyMacro: AttachedMacro {
 
 That function may have a function body, which will be replaced by the code items produced from the macro implementation.
 
-Preamble macros are implemented with a type that conforms to the `PreambleMacro` protocol:
-
-```swift
-/// Describes a macro that can introduce "preamble" code into an existing
-/// function body.
-public protocol PreambleMacro: AttachedMacro {
-  /// Expand a macro described by the given custom attribute and
-  /// attached to the given declaration and evaluated within a
-  /// particular expansion context.
-  ///
-  /// The macro expansion can introduce code items that form a preamble to
-  /// the body of the given function. The code items produced by this macro
-  /// expansion will be inserted at the beginning of the function body.
-  static func expansion(
-    of node: AttributeSyntax,
-    providingPreambleFor declaration: some DeclSyntaxProtocol & WithOptionalCodeBlockSyntax,
-    in context: some MacroExpansionContext
-  ) throws -> [CodeBlockItemSyntax]
-}
-```
-
-Preamble macros don't provide a complete function body. Rather, they provide code items that will be introduced at the beginning of the existing function body. Preamble macros are useful for injecting code without changing anything else about the function body, for example to introduce logging or simple tracing facilities. The `defer` statement can be used to trigger code that will run once the function returns.
-
 ### Composing function body macros
 
 At most one `body` macro can be applied to a given function. It receives the function declaration to which it is attached as it was written in the source code and produces a new function body.
 
-Any number of `preamble` macros can be applied to a given function. Each sees the function declaration to which it is attached as it was written in the source code, and produces code items that will be introduced at the beginning of the function body. The code items produced by the `preamble` macros will be applied in the order that the preamble macro attributes are applied in the source.
-
-For example, given:
-
-```swift
-@A @B @C func f() { print("hello") }
-```
-
-Where `A` and `B` are preamble macros and `C` is a function body macro, each macro will see the same declaration of `f`. The resulting function body for `f` will involve the code items produced by all three macros as follows:
-
-```swift
-{
-  // code items produced by preamble macro A
-  // code items produced by preamble macro B
-  // code items produced by function body macro C
-}
-```
-
-Preamble macros may introduce new local declarations, which will be visible to later preamble macros (e.g., names introduced by `@A` will be visible in `@B` and `@C` as well) and the remainder of the function body. As with all macros that introduce new names into existing code, those names must be documented with a [`names` clause](https://github.com/apple/swift-evolution/blob/main/proposals/0389-attached-macros.md#specifying-newly-introduced-names). For example, a tracing macro for [swift-distributed-tracing](https://swiftpackageindex.com/apple/swift-distributed-tracing) might want to introduce a local variable `span` that can be used by the rest of the function body to add more information to the trace. Such a macro could be declared as a preamble macro as follows:
-
-```swift
-@attached(preamble, names: named(span))
-macro Traced(_ name: String? = nil) = #externalMacro(...)
-```
-
-The `Traced` macro could introduce a `span` local variable that can be used by the function body. For example:
-
-```swift
-@Traced("Prepare dinner")
-func prepareDinner(guests: Int) async throws -> Meal {
-  span.attributes["operation"] = "Making dinner"
-  // ...
-}
-```
-
-The `@Traced` preamble macro could expand this into:
-
-```swift
-func prepareDinner(guests: Int) async throws -> Meal {
-  // from "Traced" macro
-  let span = DistributedTracing._getCurrentSpan()
-  DistributedTracing._pushSpan()
-  defer {
-    DistributedTracing._popSpan()
-  }
-  
-  // Existing code
-  span.attributes["operation"] = "Making dinner"
-  // ...
-}
-```
-
-It is possible that the newly-introduced `span` variable could shadow a variable from an outer scope, for example if `prepareDinner` was inside an actor with `span` property:
-
-```swift
-actor Chef {
-  var span: Int
-  
-  @Traced("Prepare dinner")
-  func prepareDinner(guests: Int) async throws -> Meal {
-    print("Arm span is \(span) meters")  // refers to 'span' from the Traced macro expansion
-    // ...
-  }
-}
-```
-
 ### Type checking of functions involving function body macros
 
 When a function body macro is applied, the macro-expanded function body will need to be type checked when it is incorporated into the program. However, the function might already have a body that was written by the developer, which can be inspected by the macro implementation. The function body as written must be syntactically well-formed (i.e., it must conform to the [Swift grammar](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/summaryofthegrammar/)) but will *not* be type-checked, so it need not be semantically well-formed.
@@ -281,42 +190,9 @@ func employees(hiredIn year: Int) -> [String] {
 
 The requirement for syntactic wellformedness should help rein in the more outlandish uses of function body macros, as well as making sure that existing tools that operate on source code will continue to work well even in the presence of body macros.
 
-### Function body macros and implicit returns
-
-Swift functions that contain only a single expression will implicitly return that expression, e.g.,
-
-```swift
-func g(a: Int, b: Int) -> Int {
-  a + b      // return is implicit
-}
-```
-
-The application of preamble macros to the function body does not affect the implicit return, so the following is well-formed
-
-```swift
-@Logged
-func g(a: Int, b: Int) -> Int {
-  a + b      // return is implicit
-}
-```
-
-and the expansion of the macro is treated like the following code:
-
-```swift
-func g(a: Int, b: Int) -> Int {
-  log("Entering g(a: \(a), b: \(b))")
-  defer {
-    log("Exiting g")
-  }
-  return a + b
-}
-```
-
-Body macros are different: because they replace the entire function body, whether the original function body as written would have had an implicit return is not considered.
-
 ## Source compatibility
 
-Function body macros introduce new macro roles into the existing attached macro syntax, and therefore do not have an impact on source compatibility.
+Function body macros introduce a new macro role into the existing attached macro syntax, and therefore does not have an impact on source compatibility.
 
 ## Effect on ABI stability
 
@@ -338,7 +214,7 @@ Function body macros as presented in this proposal are limited to declared funct
 }
 ```
 
-This extension would involve extending the `PreambleMacro` and `BodyMacro` protocols with another `expansion` method that accepts closure syntax. The primary challenge with applying function body macros to closures is the interaction with type inference, because closures generally occur within an expression and some of the macro arguments themselves might be part of the expression. In the example above, the `z` value could come from an outer scope and be the subject of type inference:
+This extension would involve extending the `BodyMacro` protocol with another `expansion` method that accepts closure syntax. The primary challenge with applying function body macros to closures is the interaction with type inference, because closures generally occur within an expression and some of the macro arguments themselves might be part of the expression. In the example above, the `z` value could come from an outer scope and be the subject of type inference:
 
 ```swift
 f(0) { z in
@@ -350,21 +226,23 @@ f(0) { z in
 
 Macros are designed to avoid [multiply instantiating the same macro](https://github.com/apple/swift-evolution/blob/main/proposals/0382-expression-macros.md#macro-expansion), and have existing limitations in place to prevent the type checker from getting into a position where it is not obvious which macro to expand or the same macro needs to be expanded multiple times. To extend function body macros to closures will require a solution to this type-checking issue, and might be paired with lifting other restrictions on (e.g.) freestanding declaration macros.
 
-## Alternatives considered
+### Preamble macros
 
-### Eliminating preamble macros
-
-Preamble macros aren't technically necessary, because one could always write a function body macro that injects the preamble code into an existing body. However, preamble macros provide several end-user benefits over function body macros for the cases where they apply:
+The first reviewed revision of this proposal contained *preamble* macros, which let a macro introduce code at the beginning of a function without changing the rest of the function body. Preamble macros aren't technically necessary, because one could always write a function body macro that injects the preamble code into an existing body. However, preamble macros provide several end-user benefits over function body macros for the cases where they apply:
 
 * Preamble macros can be composed, whereas function body macros cannot.
 * Preamble macros don't change the code as written by the user, so they provide a better user experience (e.g., for diagnostics, code completion, and so on).
 
-### Capturing the `withSpan` pattern in another macro role
+Preamble macros would be expressed as its own attached macro role (`preamble`), implemented with a type that conforms to the `PreambleMacro` protocol. Details are available in [the prior revision](https://github.com/apple/swift-evolution/blob/f1b9da80315578666352a7d6d40a9f6cc936f69a/proposals/0415-function-body-macros.md). 
+
+Preamble macros have been moved out to Future Directions because they represent a possible future, but not an obviously right one: preamble macros might not add sufficient expressivity to cover the cost of the complexity they introduce, and another kind of macro (like the "wrapper" macro below) might provide a more reasonable tradeoff between expressivity and complexity.
 
-An alternative formulation of the `Traced` macro (call it `@TracedBody`) makes use of its existing [`withSpan` API](https://swiftpackageindex.com/apple/swift-distributed-tracing/1.0.1/documentation/tracing) in a `body` macro, such that a function such as:
+### Wrapper macros
+
+A number of use cases for body macros involve "wrapping" the existing body in additional logic. For example, consider an alternative formulation of the `Traced` macro (let's call it `@TracedWithSpan`) could make use of the [`withSpan` API](https://swiftpackageindex.com/apple/swift-distributed-tracing/1.0.1/documentation/tracing) such that a function such as:
 
 ```swift
-@TracedBody("Doing complicated math")
+@TracedWithSpan("Doing complicated math")
 func h(a: Int, b: Int) -> Int {
   return a + b
 }
@@ -380,7 +258,7 @@ func h(a: Int, b: Int) -> Int {
 }
 ```
 
-The `withSpan` function used here is one instance of a fairly general pattern in Swift, where a `with<something>` function accepts a closure argument and runs it with some extra contextual parameters. As we did with the `preamble` macro role, we could introduce a special macro role that describes this pattern: the macro would not see the function body that was written by the developer at all, but would instead have a function value representing the body that it could call opaquely. For example, the `TracedBody` example function `h` would expand to:
+This `withSpan` function used here is one instance of a fairly general pattern in Swift, where a function accepts a closure argument and runs it with some extra contextual parameters. As we with the `preamble` macro role mentioned above, we could introduce a special macro role that describes this pattern: the macro would not see the function body that was written by the developer at all, but would instead have a function value representing the body that it could call opaquely. For example, the `TracedWithSpan` example function `h` would expand to:
 
 ```swift
 func h(a: Int, b: Int) -> Int {
@@ -391,7 +269,7 @@ func h(a: Int, b: Int) -> Int {
 With this approach, the original function body for `h` would be type-checked prior to macro expansion, and then would be handed off to the macro as an opaque value `h-impl` to be called by `withSpan`. The macro could introduce its own closure wrapping that body as needed, e.g.,
 
 ```swift
-@TracedBody("Doing complicated math", { span in
+@TracedWithSpan("Doing complicated math", { span in
   span.attributes["operation"] = "addition"
 })
 func myMath(a: Int, b: Int) -> Int {
@@ -410,9 +288,9 @@ func myMath(a: Int, b: Int) -> Int {
 }
 ```
 
-The advantage of this approach over allowing a `body` macro to replace a body is that we can type-check the  function body as it was written, and only need to do so once---then it becomes a value of function type that's passed along to the underying macro. Also like preamble macros, this approach can compose, because the result of one macro could produce another value of function type that can be passed along to another macro.
+The advantage of this approach over allowing a `body` macro to replace a body is that we can type-check the  function body as it was written, and only need to do so once---then it becomes a value of function type that's passed along to the underying macro. Also like preamble macros, this approach can compose, because the result of one macro could produce another value of function type that can be passed along to another macro. [Python decorators](https://www.datacamp.com/tutorial/decorators-python) have been successful in that language for customizing the behavior of functions in a similar manner.
 
-On the other hand, having a third kind of macro role for function body macros adds yet more language complexity, and introducing this role in lieu of allowing function body macros to replace an existing function body might be overfitting to today's use cases. Moreover, this only works for very specific examples. The `@AssumeMainActor` macro would not be able to use this feature, because the intent is that the code as written (in a `nonisolated` function) is processed in a different actor isolation context (the `@MainActor` closure).
+## Alternatives considered
 
 ### Type-checking bodies as they were written
 
@@ -422,6 +300,9 @@ On the other hand, type-checking the function bodies before macro expansion has
 
 ## Revision history
 
+* Revision 3:
+  * Narrowed the focus down to `body` macros.
+  * Moved preamble macros into Future Directions, added discussion of wrapper macros.
 * Revision 2:
   * Clarify that preamble macro-introduced local names can shadow names from outer scopes
   * Clarify the effect of function body macros on single-expression functions and implicit returns
