⭐Result Builders

Swift ⟩ Attributes ⟩

Swift 5.4 Result builders were first introduced as a semi-official language feature called “function builders” as part of the Swift 5.1 release. Xcode 12.5

🔴 主題

• result-building methods

• result builder transform

• custom result-builder attributes

⭐️ 重點

The declaration of a result builder type doesn’t have to include any protocol conformance. 👉 Swift Reference

Result builders allow us to create a new value step by step by passing in a sequence of our choosing. 👉 Paul (💈例一)

A function builder is a type that implements an embedded DSL for collecting partial results from the expression-statements of a function and combining them into a return value [1]. 👉 Vadim

The function builders feature of Swift is described in Swift Evolution Proposal. The main goal of function builders is providing DSL like syntax. 👉 Swift with Majid

📗 參考

• obj.io ⟩ Advanced Swift, Ch. 4: Functions, Result Builders

• Paul ⟩ Result Builders (💈例一) ⭐️

• SwiftLee ⟩ Result builders in Swift explained - Constraints Builder

• Swift.Dev ⟩ Result builders in Swift - HTML Builder

• Swift Senpai ⟩ Swift Result Builders: The Basics You Need to Know! ⭐️

• GitHub ⟩ Awesom Result Builders

• Vadim ⟩ Function Builders in Swift and SwiftUI

• Sundell ⟩

  • Swift 5.1 Features that Powers SwiftUI's API ⟩ Function builders

  • A deep dive into Swift’s result builders (💈例二) ⭐️

• Function Builder - zonble

📘 手冊

• Swift ⟩ Advanced Operators ⟩ Result Builders ⭐️ (💈例三)

• Swift Reference ⟩ Attributes ⟩ Declaration Attributes ⟩ resultBuilder ⭐️ (💈例四)

• SE0289 Result Builders ⟩ Result-building methods ⭐️

• SwiftUI ⟩

  • App ⟩ SceneBuilder

  • Scene ⟩ Commands ⟩ CommandsBuilder

  • Table ⟩ TableRowBuilder, TableColumnBuilder

👥 相關

• ViewBuilder

• Attributes

• Swift 5.4 features.

❓

問：Why not make result builder a protocol❓

💈例一

those buildEither() methods also enable switch statements to be used within result builder contexts, without requiring any additional build methods. 👉 Sundell

👉paiza.io

@resultBuilder
struct StringBuilder {

    // ⭐️ (mandantory)
    static func buildBlock(_ parts: String...) -> String {
        parts.joined(separator: "\n")
    }
    
    // ⭐️ support `if...else...` statement
    static func buildEither(first part: String) -> String {
        return part
    }

    static func buildEither(second part: String) -> String {
        return part
    }
    
    // ⭐️ support `for...in` loop
    static func buildArray(_ parts: [String]) -> String {
        parts.joined(separator: ", ")
    }
}

// ⭐️ applied on `func`
@StringBuilder func s1() -> String {
    "Why settle for a Duke"
    "when you can have"
    "a Prince?"
}

// ⭐️ applied on `var`
@StringBuilder var s2: String {
    "Why settle for a Duke"
    "when you can have"
    "a Prince?"
}

// ⭐️ translated by complier to:
// ------------------------------
// StringBuilder.buildBlock(
//     "Why settle for a Duke",
//     "when you can have",
//     "a Prince?"
// )
// ------------------------------

print(s1())
print(s2)
// Why settle for a Duke
// when you can have
// a Prince?

@StringBuilder var s3: String {

    "Why settle for a Duke"
    "when you can have"

    // ⭐️ supported by `buildEither(first:)` / `buildEither(second:)`
    if .random() { "a Frog?" } 
    else { "a King?" }
}

print(s3)

@StringBuilder var countDown: String {

    // ⭐️ supported by `buildArray(_:)`
    for i in (0...10).reversed() { "\(i)…" }

    "Lift off!"
}

print(countDown)
// 10…, 9…, 8…, 7…, 6…, 5…, 4…, 3…, 2…, 1…, 0…
// Lift off!

💈例二

👉 paiza.io

// before using @SettingsBuilder
[
    Setting("Offline mode", .bool(false)),
    Setting("Search page size", .int(25)),
    Setting("Experimental", .group([
        Setting("Default name", .string("Untitled")),
        Setting("Fluid animations", .bool(true))
    ]))
]

// ⭐️ after using @SettingsBuilder
Settings {                                 // ⭐️ 1
    ("Offline mode", false)
    ("Search page size", 25)
    Settings.Group("Experimental") {       // ⭐️ 2
        ("Default name", "Untitled")
        ("Fluid animations", true)
    }
}

評論：這個例子用 Result Builder 似乎沒討到什麼好處。

// ---------------
//     Setting
// ---------------

struct Setting {
    var name: String
    var value: Value
}

extension Setting {

    enum Value {
        case bool(Bool)
        case int(Int)
        case string(String)
        case group([Setting])
    }
    
    init(_ name: String, _ value: Value){
        self.init(name: name, value: value)
    }
    
    init(_ tuple: Tuple){
        self.init(name: tuple.name, value: tuple.value)
    }
    
    typealias Tuple = (name: String, value: Value)
}

// -----------------------
//     SettingsBuilder
// -----------------------

@resultBuilder
struct SettingsBuilder {

    typealias Component = Settings
    
    static func buildBlock(_ components: Component...) -> Component {
        Array(components.joined())
    }
    
    // -------------------------
    //     ⭐️ buildExpression
    // -------------------------
    
    // for tuple
    static func buildExpression(_ tuple: Setting.Tuple) -> Component {
        [Setting(tuple)]
    }
    
    // ⭐️ case .bool
    static func buildExpression(_ tuple: (name: String, bool: Bool)) -> Component {
        [Setting(tuple.name, .bool(tuple.bool))]
    }
    
    // ⭐️ case .int
    static func buildExpression(_ tuple: (name: String, int: Int)) -> Component {
        [Setting(tuple.name, .int(tuple.int))]
    }
    
    // ⭐️ case .string
    static func buildExpression(_ tuple: (name: String, string: String)) -> Component {
        [Setting(tuple.name, .string(tuple.string))]
    }
    
    // for a normal Setting
    static func buildExpression(_ setting: Setting) -> Component {
        [setting]
    }
}

// -----------------
//     Settings
// -----------------

typealias Settings = [Setting]

// typealias can be extended ⭐️
extension Settings {

    // Settings { ... }
    init(
        @SettingsBuilder settings: () -> [Setting]      // ⭐️ 1
    ) {
        self = settings()
    }
    
    // Settings.Group { ... }
    static func Group(
        _ name: String, 
        @SettingsBuilder settings: () -> [Setting]      // ⭐️ 2
    ) -> Setting {
        Setting(name: name, value: .group(settings()))
    }
}

💈例三

👉 paiza.io

• 此範例建立一個 Drawable 協定來規範所有「用於組合的型別」。

• Line 是 Drawable 這類型別的「最終組合目標」。

• DrawingBuilder 用來實現「如何組合」這些型別。

// ---------------
//    Drawable
// ---------------
//
// • Types for drawing on a single line 
//   using stars ("*") and text (String)

// 🔸 Drawable
// defines the requirement for something that can be drawn (as a String)
protocol Drawable: CustomStringConvertible {
    func draw() -> String
}

extension Drawable {
    var description: String { draw() }      // CustomStringConvertible
}

// 🔸 Line
// represents a single-line drawing.
// serves the top-level container for most drawings.
struct Line: Drawable {

    var drawables: [Drawable]
    init(_ drawables: [Drawable]) { self.drawables = drawables }
    
    // ⭐ 5. closure parameter (@DrawingBuilder)
    init(@DrawingBuilder content: () -> Drawable) {
        self.drawables = [content()]
    }
    
    func draw() -> String {
        drawables
            .map { $0.draw() }
            .joined(separator: "")
    }
}

// 🔸 Text
// wraps a string to make it part of a drawing
struct Text: Drawable {
    var content: String
    init(_ content: String) { self.content = content }
    func draw() -> String { content }
}

// 🔸 Space
struct Space: Drawable {
    func draw() -> String { " " }
}

// 🔸 Stars
struct Stars: Drawable {
    var length: Int
    init(_ length: Int) { self.length = length }
    func draw() -> String { String(repeating: "🌟", count: length) }
}

// 🔸 AllCaps
// converts text in the drawing to uppercase
struct AllCaps: Drawable {
    var content: Drawable
    
    // ⭐ 3. closure parameter (@DrawingBuilder)
    init(@DrawingBuilder content: () -> Drawable) {
        self.content = content()
    }
    
    func draw() -> String { content.draw().uppercased() }
}

// -----------------------
//    ⭐ DrawingBuilder
// -----------------------

// 🔸 DrawingBuilder
@resultBuilder
struct DrawingBuilder {

    /// ⭐ 1. asupport a block of code 
    ///   每個 @DrawingBuilder closure 的最外層都是由此方法處理。
    static func buildBlock(_ drawables: Drawable...) -> Drawable {
        Line(drawables)
    }
    
    /// ⭐ 2. support `if-else`, `if-let-else` , `switch`
    static func buildEither(first: Drawable) -> Drawable {
        return first
    }
    static func buildEither(second: Drawable) -> Drawable {
        return second
    }
}

// -----------------------
//    ⭐ Use Cases
// -----------------------

// 🔸 greeting(for:)
@DrawingBuilder
func greeting(for name: String? = nil) -> Drawable {// ⭐ @DrawingBuilder

    Stars(3)
    Space()
    Text("Hello")
    Space()
    
    AllCaps {                                       // ⭐ 3. init (@DrawingBuilder)
        if let name = name { Text(name + "!") }     // ╮ 
        else { Text("World!") }                     // ╯ ⭐ 2. buildEither
    }
    
    Space()
    Stars(2)
}


print(greeting())
print(greeting(for: "swift taylor"))
// 🌟🌟🌟 Hello WORLD! 🌟🌟
// 🌟🌟🌟 Hello SWIFT TAYLOR! 🌟🌟

// ---------------------------------
//    ⭐ DrawingBuilder extension
// ---------------------------------

extension DrawingBuilder {
    /// ⭐ 4. support `for-in` , `.map()`
    static func buildArray(_ components: [Drawable]) -> Drawable {
        Line(components)
    }
}

// -----------------------
//    ⭐ Use Cases
// -----------------------

let stars = Line {      // ⭐ 5. @DrawingBuilder

    Text("Stars:")
    
    // ⭐ 4. buildArray
    for i in 1...3 {        // ╮
        Space()             // ⭐️ 1. buildBlock
        Stars(i)            // │
    }                       // ╯
}

print(stars)
// Stars: 🌟 🌟🌟 🌟🌟🌟

💈例四 ⭐️

此例說明 result building methods 到底是如何執行組合的任務。 👉 Result-Building Methods

👉 paiza.io

// --------------------
//     ArrayBuilder
// --------------------

@resultBuilder
struct ArrayBuilder {

    // log message index ⭐️
    static var index = 0

    typealias Component = [Int]
    typealias Expression = Int
    
    // helper function ⭐️
    static func reportAndReturn<Input, Result>(
        _ input:Input, _ result: Result, _ token: String
    ) -> Result 
    {
        index += 1
        print("\(index)] build \(token): \(input) -> \(result)")
        return result
    }
    
    // translate Expression into Component ⭐️
    static func buildExpression(_ element: Expression) -> Component {
        reportAndReturn(element, [element], "expression")
    }
    
    // support `if` ⭐️
    static func buildOptional(_ component: Component?) -> Component {
        reportAndReturn(component, component ?? [], "optional  ")
    }
    
    // support `if-else`, `if-let-else` ⭐️
    static func buildEither(first component: Component) -> Component {
        reportAndReturn(component, component, "1st       ")
    }
    static func buildEither(second component: Component) -> Component {
        reportAndReturn(component, component, "2nd       ")
    }
    
    // support `for-in` loop ⭐️
    static func buildArray(_ components: [Component]) -> Component {
        reportAndReturn(components, Array(components.joined()), "array     ")
    }
    
    // translate block statement into Component (required) ⭐️
    static func buildBlock(_ components: Component...) -> Component {
        reportAndReturn(components, Array(components.joined()), "block     ")
    }
}

// --------------------
//     test run
// --------------------

@ArrayBuilder var c1: [Int] {               // 3
    let _ = print("hi")                     // `print` in builder ⭐️
    10                                      // 2
}

var c2 = ArrayBuilder.buildExpression(5)    // 1
// 1] build expression: 5 -> [5]            // 這個竟然先執行 ⭐️
// hi
// 2] build expression: 10 -> [10]
// 3] build block     : [[10]] -> [10]

print(c1)   //  [10]
print(c2)   //  [5]

var n = 19
@ArrayBuilder var c3: [Int] {               // 7
    if n < 12 {
        21
    } else {                                // 5, 6
        22                                  // 4
    } 
}
// 4] build expression: 22 -> [22]
// 5] build block     : [[22]] -> [22]
// 6] build 2nd       : [22] -> [22]
// 7] build block     : [[22]] -> [22]

print(c3)   // [22]

n = 51
@ArrayBuilder var c4: [Int] {                   // 15 ({)      
    if n < 12 { 
        let _ = print("level: 1, 1st")
        31
    } else {                                    // 13 ({), 14 (else)
        let _ = print("level: 1, 2nd")
        if n == 19 {                        
            let _ = print("level: 2, 1st")
            32                              
        } else {                                // 11 ({), 12 (else)
            let _ = print("level: 2, 2nd")
            if n > 50 {                         // 9 ({), 10 (if)
                let _ = print("level: 3, 1st")
                33                              // 8
            } else {                        
                let _ = print("level: 3, 2nd")
                34                          
            }
        }
    }
}

print(c4)
// level: 1, 2nd
// level: 2, 2nd
// level: 3, 1st
//  8] build expression: 33 -> [33]
//  9] build block     : [[33]] -> [33]
// 10] build 1st       : [33] -> [33]
// 11] build block     : [[33]] -> [33]
// 12] build 2nd       : [33] -> [33]
// 13] build block     : [[33]] -> [33]
// 14] build 2nd       : [33] -> [33]
// 15] build block     : [[33]] -> [33]

/*
    規則：由最內層往外回溯 ⭐️
    ------------------------------
    • 最內層   ：build Expression
    • 遇到 {   ：build Block
    • 遇到 if  ：build 1st / Optional
    • 遇到 else：build 2nd
    • 遇到 for ：build Array
*/

n = 51
@ArrayBuilder var c5: [Int] {           // 20 ({)
    if n < 12 { 
        let _ = print("level: 1, 1st")
        41
    } else if n == 19 {
        let _ = print("level: 2, 1st")
        42                              
    } else if n > 50 {                  // 17 ({), 18 (if), 19 (else)
        let _ = print("level: 3, 1st")
        43                              // 16
    } else {                        
        let _ = print("level: 3, 2nd")
        44                          
    }
}

// level: 3, 1st
// 16] build expression: 43 -> [43]
// 17] build block     : [[43]] -> [43]
// 18] build 1st       : [43] -> [43]
// 19] build 2nd       : [43] -> [43]
// 20] build block     : [[43]] -> [43]

print(c5)   // [43]

@ArrayBuilder var c6: [Int] {       // 24 ({)
    if (n % 2) == 1 {               // 22 ({), 23 (if)
        51                          // 21
    }
}
// 21] build expression: 51 -> [51]
// 22] build block     : [[51]] -> [51]
// 23] build optional  : Optional([51]) -> [51]
// 24] build block     : [[51]] -> [51]

print(c6)   // [51]

@ArrayBuilder var c7: [Int] {   // ({) 32
    for i in 1...3 {            // ({) 26, 28, 30 | 31 (for)
        100 + i                 // (E) 25, 27, 29
    }
}
// 25] build expression: 101 -> [101]
// 26] build block     : [[101]] -> [101]
// 27] build expression: 102 -> [102]
// 28] build block     : [[102]] -> [102]
// 29] build expression: 103 -> [103]
// 30] build block     : [[103]] -> [103]
// 31] build array     : [[101], [102], [103]] -> [101, 102, 103]
// 32] build block     : [[101, 102, 103]] -> [101, 102, 103]

print(c7)   // [101, 102, 103]