From d81bddcc6c3f10dd0ab469d73c3c7768c88b13eb Mon Sep 17 00:00:00 2001 From: Alex Martini Date: Tue, 29 Nov 2022 15:29:55 -0800 Subject: [PATCH 1/5] Add initial reference for "build partial block". --- Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md b/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md index 1c7d2cd67..eff523287 100644 --- a/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md +++ b/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md @@ -1368,6 +1368,17 @@ The result-building methods are as follows: Combines an array of partial results into a single partial result. A result builder must implement this method. +- term `static func buildPartialBlock(first: Component) -> Component`: + Builds a partial result component from the first component. + Implement both this method and `buildPartialBlock(accumulated:next:)` + to support building blocks one component at a time. + +- term `static func buildPartialBlock(accumulated: Component, next: Component) -> Component`: + Builds a partial result component + by combining an accumulated component with a new component. + Implement both this method and `buildPartialBlock(first:)` + to support building blocks one component at a time. + - term `static func buildOptional(_ component: Component?) -> Component`: Builds a partial result from a partial result that can be `nil`. Implement this method to support `if` statements From 2a4e87f76bbd5b81b149c58f12978c89ff7c4330 Mon Sep 17 00:00:00 2001 From: Alex Martini Date: Tue, 29 Nov 2022 19:53:02 -0800 Subject: [PATCH 2/5] Update required methods for builders. --- .../TSPL.docc/ReferenceManual/Attributes.md | 25 ++++++++++++++++--- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md b/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md index eff523287..dcf18f75c 100644 --- a/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md +++ b/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md @@ -1344,8 +1344,10 @@ A result builder implements static methods described below. Because all of the result builder's functionality is exposed through static methods, you don't ever initialize an instance of that type. -The `buildBlock(_:)` method is required; -the other methods --- +A result builder must implement either the `buildBlock(_:)` method +or both the `buildPartialBlock(first:)` +and `buildPartialBlock(accumulated:next:)` methods. +The other methods --- which enable additional functionality in the DSL --- are optional. The declaration of a result builder type @@ -1362,22 +1364,37 @@ If your result-building methods don't specify a type for `Expression` or `FinalResult`, they default to being the same as `Component`. -The result-building methods are as follows: +The block-building methods are as follows: - term `static func buildBlock(_ components: Component...) -> Component`: Combines an array of partial results into a single partial result. - A result builder must implement this method. - term `static func buildPartialBlock(first: Component) -> Component`: Builds a partial result component from the first component. Implement both this method and `buildPartialBlock(accumulated:next:)` to support building blocks one component at a time. + Compared to `buildBlock(_:)`, + this approach reduces the need for generic overloads + that handle different numbers of arguments. - term `static func buildPartialBlock(accumulated: Component, next: Component) -> Component`: Builds a partial result component by combining an accumulated component with a new component. Implement both this method and `buildPartialBlock(first:)` to support building blocks one component at a time. + Compared to `buildBlock(_:)`, + this approach reduces the need for generic overloads + that handle different numbers of arguments. + +If a result builder implements all three of the block-building methods listed above, +and the availability of the enclosing declaration +is greater than or equal to the availability of `buildPartialBlock(first:)` +and `buildPartialBlock(accumulated:next:)`, +those methods are used. + +Otherwise, `buildBlock(_:)` is used. + +The additional result-building methods are as follows: - term `static func buildOptional(_ component: Component?) -> Component`: Builds a partial result from a partial result that can be `nil`. From 9cbf8484b50ef64b7f023495fbc0bd2feaf1d837 Mon Sep 17 00:00:00 2001 From: Alex Martini Date: Fri, 17 Mar 2023 14:17:00 -0700 Subject: [PATCH 3/5] Explain the availability comparison. --- Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md b/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md index dcf18f75c..551f27e20 100644 --- a/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md +++ b/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md @@ -1387,11 +1387,13 @@ The block-building methods are as follows: that handle different numbers of arguments. If a result builder implements all three of the block-building methods listed above, -and the availability of the enclosing declaration -is greater than or equal to the availability of `buildPartialBlock(first:)` +availability determines which method gets used. +If the availability of the enclosing declaration is the same as +the availability of `buildPartialBlock(first:)` and `buildPartialBlock(accumulated:next:)`, -those methods are used. - +the build-partial-block methods are used. +If the enclosing declaration is also available in older versions of the library, +the build-partial-block methods are used. Otherwise, `buildBlock(_:)` is used. The additional result-building methods are as follows: From 10af2104c9ff37901617f9cf2aef0ec419d2a450 Mon Sep 17 00:00:00 2001 From: Alex Martini Date: Tue, 21 Mar 2023 16:53:02 -0700 Subject: [PATCH 4/5] Correct the availability info. Incorporates tech review from Richard Wei . --- .../TSPL.docc/ReferenceManual/Attributes.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md b/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md index 551f27e20..fc45e6018 100644 --- a/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md +++ b/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md @@ -1386,15 +1386,14 @@ The block-building methods are as follows: this approach reduces the need for generic overloads that handle different numbers of arguments. -If a result builder implements all three of the block-building methods listed above, -availability determines which method gets used. -If the availability of the enclosing declaration is the same as -the availability of `buildPartialBlock(first:)` -and `buildPartialBlock(accumulated:next:)`, -the build-partial-block methods are used. -If the enclosing declaration is also available in older versions of the library, -the build-partial-block methods are used. -Otherwise, `buildBlock(_:)` is used. +A result builder can implement +all three of the block-building methods listed above --- +in that case, +availability determines which method is used. +If the enclosing declaration is available +before the build-partial-block methods, +the `buildBlock(_:)` method is used. +Otherwise, the build-partial-block methods are used. The additional result-building methods are as follows: From 781bc701c198e07d3595800ded2a32a111271964 Mon Sep 17 00:00:00 2001 From: Alex Martini Date: Wed, 24 May 2023 14:21:04 -0700 Subject: [PATCH 5/5] Reword the availability discussion to be clearer. Per discussion with Chuck. --- TSPL.docc/ReferenceManual/Attributes.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/TSPL.docc/ReferenceManual/Attributes.md b/TSPL.docc/ReferenceManual/Attributes.md index e8f002927..e6fba7a52 100644 --- a/TSPL.docc/ReferenceManual/Attributes.md +++ b/TSPL.docc/ReferenceManual/Attributes.md @@ -1388,14 +1388,12 @@ The block-building methods are as follows: this approach reduces the need for generic overloads that handle different numbers of arguments. -A result builder can implement -all three of the block-building methods listed above --- -in that case, -availability determines which method is used. -If the enclosing declaration is available -before the build-partial-block methods, -the `buildBlock(_:)` method is used. -Otherwise, the build-partial-block methods are used. +A result builder can implement all three of the block-building methods listed above; +in that case, availability determines which method is called. +By default, Swift calls the `buildPartialBlock(first:)` and `buildPartialBlock(second:)` methods. +To make Swift call `buildBlock(_:)` instead, +mark the enclosing declaration as being available +before the availability you write on `buildPartialBlock(first:)` and `buildPartialBlock(second:)`. The additional result-building methods are as follows: