Swiftpack.co - Package - ikesyo/Himotoki

Himotoki

Join the chat at https://gitter.im/ikesyo/Himotoki

GitHub release CI Status Carthage compatible Swift Package Manager

Himotoki (紐解き) is a type-safe JSON decoding library written purely in Swift. This library is highly inspired by the popular Swift JSON parsing libraries: Argo and ObjectMapper.

Himotoki has the same meaning of 'decoding' in Japanese.

  • Just do JSON decoding (deserialization) well. JSON encoding (serialization) will not be supported going forward. :wink:
  • Much simpler API.
  • Fail-fast conditional model building. This is useful for some structs with non-optional let properties.
  • No external dependencies.

Let's take a look at a simple example:

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()
    }
}

:warning: Please note that you should need to add the module name Himotoki to Decodable (Himotoki.Decodable) to avoid type name collision with Foundation.Decodable in Xcode 9 or later. :warning:

Implementing the decode method for your models

To implement the decode method for you models conforming to the Decodable protocol, you can use the following Extractor's extraction methods:

  • 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]?

Extraction Operators

Himotoki also supports the following operators to decode JSON elements, where T is a generic type conforming to the Decodable protocol.

| Operator | Decode element as | Remarks | |:----------|:------------------|:---------------------------------| | <\| | T | A value | | <\|? | T? | An optional value | | <\|\| | [T] | An array of values | | <\|\|? | [T]? | An optional array of values | | <\|-\| | [String: T] | A dictionary of values | | <\|-\|? | [String: T]? | An optional dictionary of values |

Value Transformation

You can transform an extracted value to an instance of non-Decodable types by passing the value to a Transformer instance as follows:

// 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")

Requirements

Himotoki 4.x requires / supports the following environments:

  • Swift 4.1 / Xcode 9.3 or later
  • OS X 10.9 or later
  • iOS 8.0 or later
  • tvOS 9.0 or later
  • watchOS 2.0 or later
  • Linux is also supported

Installation

Currently Himotoki supports installation via the package managers Carthage and CocoaPods.

Carthage

Himotoki is Carthage compatible.

  • Add github "ikesyo/Himotoki" ~> 3.1 to your Cartfile.
  • Run carthage update.

CocoaPods

Himotoki also can be used by CocoaPods.

  • Add the followings to your Podfile:

    use_frameworks!
    pod "Himotoki", "~> 3.1"
    
  • Run pod install.

License

Himotoki is released under the MIT License.

Github

link
Stars: 704
Help us keep the lights on

Dependencies

Releases

3.1.0 - Jun 6, 2017

Fixed

  • Xcode 9 (Swift 3.2 / Swift 4.0) compatibility (#183)

Improved

  • Performance improvements (#166, #169, #177). Thanks @yudoufu!
  • README fixes (#172, #173, #180, #182). Thanks @andrewh42, @Nirma and @yuta-t!.

3.0.1 - Feb 22, 2017

Fixed

  • Fix an issue that Extractor.valueOptional(_:) and <|? operator are incorrectly throwing DecodeError.missingKeyPath(KeyPath) and that triggers Xcode's Swift Error Breakpoint unexpectedly (#162, #163).

Improved

  • Deprecate ExpressibleByNilLiteral conformance on KeyPath (#165).

3.0.0 - Sep 18, 2016

This release supports Swift 3.0 / Xcode 8.

Breaking

  • Support Swift 3 and Linux (#145).
    • If you want the version which support Swift 2.2 (Xcode 7.3) or Swift 2.3 (Xcode 8), you can use the latest compatible version of 2.1.1 instead.
  • Remove obsolete AnyJSON typealias (#147). That is no longer needed in Swift 3, so use Any directly instead.

2.1.1 - Jun 30, 2016

This release should support both Swift 2.2 / Xcode 7.3 and Swift 2.3 / Xcode 8.

Fixed

  • Fix code signing on Xcode 8 for device builds (#130).

2.1.0 - Jun 21, 2016

This release targets Swift 2.2 / Xcode 7.3.

Added

  • Xcode 8 and Swift 2.3 compatibility (#126).
  • Make castOrFail function public to support class cluster for now (#118, #127, ec25bff).