🧰 CasePaths

案例路径将键路径层次结构扩展到枚举案例。

动机

Swift为每个结构体和类的属性都赋予了键路径。

struct User {
  let id: Int
  var name: String
}

\User.id    // KeyPath<User, Int>
\User.name  // WritableKeyPath<User, String>

这是编译器生成的代码，可以用来抽象地聚焦结构的一部分，检查甚至更改它，同时将这些更改传播到整个结构。它们是许多现代Swift API的无声伙伴，这些API由动态成员查找驱动，如SwiftUI 绑定，但也直接出现，如在SwiftUI 环境和不安全可变指针中。

不幸的是，枚举案例不存在这样的结构。

enum UserAction {
  case home(HomeAction)
  case settings(SettingsAction)
}

\UserAction.home  // 🛑

🛑 键路径不能引用静态成员'home'

因此，无法编写通用代码来放大和修改枚举中特定案例的数据。

在库中使用案例路径

迄今为止，案例路径最常见的用途是作为分发给其他开发者的库中的工具。案例路径在可组合架构、SwiftUI导航、解析和许多其他库中使用。

如果你维护一个库，期望用户使用枚举来模型化他们的领域，那么为他们提供案例路径工具可以帮助他们将领域分解成更小的单元。例如，考虑SwiftUI提供的Binding类型：

struct Binding<Value> {
  let get: () -> Value
  let set: (Value) -> Void
}

通过动态成员查找的力量，我们能够支持点链接语法来派生值成员的新绑定：

@dynamicMemberLookup
struct Binding<Value> {
  …
  subscript<Member>(dynamicMember keyPath: WritableKeyPath<Value, Member>) -> Binding<Member> {
    Binding<Member>(
      get: { self.get()[keyPath: keyPath] },
      set: { 
        var value = self.get()
        value[keyPath: keyPath] = $0
        self.set(value)
      }
    )
  }
}

如果你有一个用户的绑定，你可以简单地附加.name到该绑定上，立即派生出用户名称的绑定：

let user: Binding<User> = // ...
let name: Binding<String> = user.name

然而，对于枚举来说，没有这样的便利：

enum Destination {
  case home(HomeState)
  case settings(SettingsState)
}
let destination: Binding<Destination> = // ...
destination.home      // 🛑
destination.settings  // 🛑

无法通过使用简单的点链接语法从目标绑定中派生出只针对home案例的绑定。

然而，如果SwiftUI使用这个CasePaths库，他们就可以很容易地提供这个工具。他们可以提供一个额外的dynamicMember下标，使用CaseKeyPath，这是一个单独指出枚举案例的键路径，并用它来派生出枚举特定案例的绑定：

import CasePaths

extension Binding {
  public subscript<Case>(dynamicMember keyPath: CaseKeyPath<Value, Case>) -> Binding<Case>?
  where Value: CasePathable {
    Binding<Case>(
      unwrapping: Binding<Case?>(
        get: { self.wrappedValue[case: keyPath] },
        set: { newValue, transaction in
          guard let newValue else { return }
          self.transaction(transaction).wrappedValue[case: keyPath] = newValue
        }
      )
    )
  }
}

定义好之后，可以用@CasePathable宏注释枚举，然后立即使用点链接从枚举的绑定中派生出案例的绑定：

@CasePathable
enum Destination {
  case home(HomeState)
  case settings(SettingsState)
}
let destination: Binding<Destination> = // ...
destination.home      // Binding<HomeState>?
destination.settings  // Binding<SettingsState>?

这是一个例子，说明库如何为用户提供工具，以拥抱枚举而不失去结构体的人体工程学。

案例路径的基础

虽然库工具是使用这个库的最大用例，但在第一方代码中也有一些使用案例路径的方法。该库通过引入我们称之为"案例路径"的东西来弥合结构体和枚举之间的差距：枚举案例的键路径。

可以使用@CasePathable宏为枚举启用案例路径：

@CasePathable
enum UserAction {
  case home(HomeAction)
  case settings(SettingsAction)
}

它们可以通过"可案例路径"枚举的Cases命名空间生成：

\UserAction.Cases.home      // CaseKeyPath<UserAction, HomeAction>
\UserAction.Cases.settings  // CaseKeyPath<UserAction, SettingsAction>

像任何键路径一样，当可以推断枚举类型时，它们可以被缩写：

\.home as CaseKeyPath<UserAction, HomeAction>
\.settings as CaseKeyPath<UserAction, SettingsAction>

案例路径 vs. 键路径

提取、嵌入、修改和测试值

正如键路径打包了在根结构上获取和设置值的功能，案例路径打包了可选地提取和修改根枚举关联值的功能。

user[keyPath: \User.name] = "Blob"
user[keyPath: \.name]  // "Blob"

userAction[case: \UserAction.Cases.home] = .onAppear
userAction[case: \.home]  // Optional(HomeAction.onAppear)

如果案例不匹配，提取可能会失败并返回nil：

userAction[case: \.settings]  // nil

案例路径有一个额外的能力，就是将关联值嵌入到一个全新的根中：

let userActionToHome = \UserAction.Cases.home
userActionToHome(.onAppear)  // UserAction.home(.onAppear)

可以使用可案例路径枚举的is方法测试案例：

userAction.is(\.home)      // true
userAction.is(\.settings)  // false

let actions: [UserAction] = […]
let homeActionsCount = actions.count(where: { $0.is(\.home) })

可以使用modify方法就地修改它们的关联值：

var result = Result<String, Error>.success("Blob")
result.modify(\.success) {
  $0 += ", Jr."
}
result  // Result.success("Blob, Jr.")

组合路径

案例路径，像键路径一样，可以组合。你可以使用熟悉的点链接深入到枚举的枚举案例中：

\HighScore.user.name
// WritableKeyPath<HighScore, String>

\AppAction.Cases.user.home
// CaseKeyPath<AppAction, HomeAction>

或者你可以将它们附加在一起：

let highScoreToUser = \HighScore.user
let userToName = \User.name
let highScoreToUserName = highScoreToUser.append(path: userToName)
// WritableKeyPath<HighScore, String>

让 appActionToUser = \AppAction.Cases.user 让 userActionToHome = \UserAction.Cases.home 让 appActionToHome = appActionToUser.append(path: userActionToHome) // CaseKeyPath<AppAction, HomeAction>


#### 恒等路径

Case paths 和 key paths 一样，也提供了一个[恒等](https://github.com/apple/swift-evolution/blob/master/proposals/0227-identity-keypath.md)路径，这在与使用 key paths 和 case paths 的 API 交互时很有用，但你想处理整个结构。

``` swift
\User.self              // WritableKeyPath<User, User>
\UserAction.Cases.self  // CaseKeyPath<UserAction, UserAction>

属性访问

自 Swift 5.2 起，key path 表达式可以直接传递给像 map 这样的方法。带有动态成员查找注解的可 case-pathable 枚举为每个 case 启用了属性访问和 key path 表达式。

@CasePathable
@dynamicMemberLookup
enum UserAction {
  case home(HomeAction)
  case settings(SettingsAction)
}

let userAction: UserAction = .home(.onAppear)
userAction.home      // Optional(HomeAction.onAppear)
userAction.settings  // nil

let userActions: [UserAction] = [.home(.onAppear), .settings(.purchaseButtonTapped)]
userActions.compactMap(\.home)  // [HomeAction.onAppear]

动态 case 查找

因为 case key paths 本质上是 key paths，所以它们可以用于相同的应用场景，比如动态成员查找。例如，我们可以通过扩展带有下标的绑定类型来扩展 SwiftUI 的绑定类型到枚举 cases：

extension Binding {
  subscript<Member>(
    dynamicMember keyPath: CaseKeyPath<Value, Member>
  ) -> Binding<Member>? {
    guard let member = self.wrappedValue[case: keyPath]
    else { return nil }
    return Binding<Member>(
      get: { self.wrappedValue[case: keyPath] ?? member },
      set: { self.wrappedValue[case: keyPath] = $0 }
    )
  }
}

@CasePathable enum ItemStatus {
  case inStock(quantity: Int)
  case outOfStock(isOnBackOrder: Bool)
}

struct ItemStatusView: View {
  @Binding var status: ItemStatus

  var body: some View {
    switch self.status {
    case .inStock:
      self.$status.inStock.map { $quantity in
        Section {
          Stepper("数量: \(quantity)", value: $quantity)
          Button("标记为售罄") {
            self.item.status = .outOfStock(isOnBackOrder: false)
          }
        } header: {
          Text("有库存")
        }
      }
    case .outOfStock:
      self.$status.outOfStock.map { $isOnBackOrder in
        Section {
          Toggle("是否在补货中？", isOn: $isOnBackOrder)
          Button("已重新有库存！") {
            self.item.status = .inStock(quantity: 1)
          }
        } header: {
          Text("缺货")
        }
      }
    }
  }
}

注意上面是我们 SwiftUINavigation 库中提供的下标的简化版本。

计算路径

Key paths 为每个属性创建，甚至是计算属性，那么 case paths 的等价物是什么？嗯，可以通过扩展 case-pathable 枚举的 AllCasePaths 类型来创建"计算"case paths，属性实现自定义 case 的 embed 和 extract 功能：

@CasePathable
enum Authentication {
  case authenticated(accessToken: String)
  case unauthenticated
}

extension Authentication.AllCasePaths {
  var encrypted: AnyCasePath<Authentication, String> {
    AnyCasePath(
      embed: { decryptedToken in
        .authenticated(token: encrypt(decryptedToken))
      },
      extract: { authentication in
        guard
          case let .authenticated(encryptedToken) = authentication,
          let decryptedToken = decrypt(token)
        else { return nil }
        return decryptedToken
      }
    )
  }
}

\Authentication.Cases.encrypted
// CaseKeyPath<Authentication, String>

案例研究

SwiftUINavigation 使用 case paths 来为 SwiftUI 绑定提供动力，包括使用枚举的导航。
The Composable Architecture 允许你将大型功能分解成更小的功能，这些功能可以通过用户 key paths 和 case paths 粘合在一起。
Parsing 使用 case paths 将非结构化数据转换为枚举，反之亦然。

你有使用 case paths 的项目想要分享吗？请提交 PR 添加链接！