Himotoki

Himotoki（紐解き）是一个纯 Swift 编写的类型安全的 JSON 解码库。这个库深受流行的 Swift JSON 解析库的启发： Argo 和 ObjectMapper。

Himotoki 在日语中的意思是“解码”。

• 仅做好 JSON 解码（反序列化）。不会支持向前的 JSON 编码（序列化）。😉
• 更简单的 API。
• 快速失败 conditional 模型构建。这对于具有非可选 let 属性的某些 struct 非常有用。
• 无外部依赖。

让我们看看一个简单的例子

struct Group: Himotoki.Decodable {
    let name: String
    let floor: Int
    let locationName: String
    let optional: [String]?

    // MARK: Himotoki.Decodable

    static func decode(_ e: Extractor) throws -> Group {
        return try Group(
            name: e <| "name",
            floor: e <| "floor",
            locationName: e <| [ "location", "name" ], // Parse nested objects
            optional: e <|? "optional" // Parse optional arrays of values
        )
    }
}

func testGroup() {
    var JSON: [String: AnyObject] = [ "name": "Himotoki", "floor": 12 ]
    
    let g = try? Group.decodeValue(JSON)
    XCTAssert(g != nil)
    XCTAssert(g?.name == "Himotoki")
    XCTAssert(g?.floor == 12)
    XCTAssert(g?.optional == nil)

    JSON["name"] = nil
    do {
        try Group.decodeValue(JSON)
    } catch let DecodeError.MissingKeyPath(keyPath) {
        XCTAssert(keyPath == "name")
    } catch {
        XCTFail()
    }
}

⚠️ 请注意，您应该在 Xcode 9 或更高版本中将模块名称 Himotoki 添加到 Decodable (Himotoki.Decodable)，以避免与 Foundation.Decodable 发生类型名称冲突。 ⚠️

实现模型的 decode 方法

要为符合 Decodable 协议的模型实现 decode 方法，您可以使用以下 Extractor 的提取方法

• public func value<T: Decodable>(_ keyPath: KeyPath) throws -> T
• public func valueOptional<T: Decodable>(_ keyPath: KeyPath) throws -> T?
• public func array<T: Decodable>(_ keyPath: KeyPath) throws -> [T]
• public func arrayOptional<T: Decodable>(_ keyPath: KeyPath) throws -> [T]?
• public func dictionary<T: Decodable>(_ keyPath: KeyPath) throws -> [String: T]
• public func dictionaryOptional<T: Decodable>(_ keyPath: KeyPath) throws -> [String: T]?

提取操作符

Himotoki 还支持以下操作符来解码 JSON 元素，其中 T 是符合 Decodable 协议的泛型类型。

值转换

您可以通过将值传递给 Transformer 实例将其转换为非 Decodable 类型的一个实例，如下所示

// Creates a `Transformer` instance.
let URLTransformer = Transformer<String, URL> { urlString throws -> URL in
    if let url = URL(string: urlString) {
        return url
    }
    
    throw customError("Invalid URL string: \(urlString)")
}

let url: URL = try URLTransformer.apply(e <| "foo_url")
let otherURLs: [URL] = try URLTransformer.apply(e <| "bar_urls")

需求

Himotoki 4.x 版本需要/支持以下环境

• Swift 4.2 / Xcode 10.1 或更高版本
• OS X 10.9 或更高版本
• iOS 8.0 或更高版本
• tvOS 9.0 或更高版本
• watchOS 2.0 或更高版本
• Linux 同样支持

安装

目前 Himotoki 通过包管理器 Carthage 和 CocoaPods 支持。

Carthage

Himotoki 与 Carthage 兼容。

• 将 github "ikesyo/Himotoki" ~> 3.1 添加到您的 Cartfile。
• 运行 carthage update。

CocoaPods

Himotoki 也可以与 CocoaPods 一起使用。

• 将以下内容添加到您的 Podfile 文件中。

  use_frameworks!
  pod "Himotoki", "~> 3.1"

• 运行 pod install 命令。

许可证

Himotoki 采用 MIT 许可协议 发布。