Himotoki (紐解き) is a type-safe JSON decoding library purely written in Swift. This library is highly inspired by popular JSON parsing libraries in Swift: Argo and ObjectMapper.
Himotoki has the same meaning of 'decoding' in Japanese.
- Just do JSON decoding (deserialization) well. JSON encoding (serialization) would not be supported going forward. 😉
- Much simpler API.
- Fail-fast conditional model building. This is useful for some
struct
s with non-optionallet
properties. - No external dependencies.
See a simple example from a test code:
struct Group: Decodable {
let name: String
let floor: Int
let locationName: String
let optional: [String]?
// MARK: 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()
}
}
Himotoki supports the following operators to decode JSON elements, where T
is a generic type conforming to 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 |
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, NSURL> { URLString throws -> NSURL in
if let URL = NSURL(string: URLString) {
return URL
}
throw customError("Invalid URL string: \(URLString)")
}
let URL = try URLTransformer.apply(e <| "foo_url")
let otherURLs = try URLTransformer.apply(e <|| "bar_urls")
- Swift 2.2 / Xcode 7.3
- OS X 10.9 or later
- iOS 8.0 or later (by Carthage or CocoaPods) / iOS 7 (by copying the source files directly)
- tvOS 9.0 or later
- watchOS 2.0 or later
There are 3 options. If your app support iOS 7, you can only use the last way.
Himotoki is Carthage compatible.
- Add
github "ikesyo/Himotoki" ~> 2.0
to your Cartfile. - Run
carthage update
.
Himotoki also can be used by CocoaPods.
-
Add the followings to your Podfile:
use_frameworks! pod "Himotoki", "~> 2.0"
-
Run
pod install
.
-
Add this repository as a git submodule:
$ git submodule add https://github.com/ikesyo/Himotoki.git PATH_TO_SUBMODULE // or $ carthage update --use-submodules
-
Then just add references of
Sources/*.swift
to your Xcode project.
Himotoki is released under the MIT License.