Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ikesyo/himotoki
A type-safe JSON decoding library purely written in Swift
https://github.com/ikesyo/himotoki
decoding json swift
Last synced: 12 days ago
JSON representation
A type-safe JSON decoding library purely written in Swift
- Host: GitHub
- URL: https://github.com/ikesyo/himotoki
- Owner: ikesyo
- License: mit
- Created: 2015-05-16T02:25:18.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2019-09-01T07:54:17.000Z (about 5 years ago)
- Last Synced: 2024-05-29T01:17:56.405Z (6 months ago)
- Topics: decoding, json, swift
- Language: Swift
- Homepage:
- Size: 368 KB
- Stars: 796
- Watchers: 26
- Forks: 50
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Himotoki
[](https://gitter.im/ikesyo/Himotoki?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://github.com/ikesyo/Himotoki/releases)
[](https://travis-ci.org/ikesyo/Himotoki)
[](https://github.com/Carthage/Carthage)
[](https://github.com/apple/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](https://github.com/thoughtbot/Argo) and [ObjectMapper](https://github.com/Hearst-DD/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 `struct`s with non-optional `let` properties.
- No external dependencies.
Let's take a look at a simple example:
```swift
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(_ keyPath: KeyPath) throws -> T`
- `public func valueOptional(_ keyPath: KeyPath) throws -> T?`
- `public func array(_ keyPath: KeyPath) throws -> [T]`
- `public func arrayOptional(_ keyPath: KeyPath) throws -> [T]?`
- `public func dictionary(_ keyPath: KeyPath) throws -> [String: T]`
- `public func dictionaryOptional(_ 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:
```swift
// Creates a `Transformer` instance.
let URLTransformer = Transformer { 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.2 / Xcode 10.1 or later
- OS X 10.9 or later
- iOS 8.0 or later
- tvOS 9.0 or later
- watchOS 2.0 or later
- [Linux](https://swift.org/download/#linux) is also supported
## Installation
Currently Himotoki supports installation via the package managers [Carthage](https://github.com/Carthage/Carthage) and [CocoaPods](https://cocoapods.org/).
### Carthage
Himotoki is [Carthage](https://github.com/Carthage/Carthage) compatible.
- Add `github "ikesyo/Himotoki" ~> 3.1` to your Cartfile.
- Run `carthage update`.
### CocoaPods
Himotoki also can be used by [CocoaPods](https://cocoapods.org/).
- Add the followings to your Podfile:
```ruby
use_frameworks!
pod "Himotoki", "~> 3.1"
```
- Run `pod install`.
## License
Himotoki is released under the [MIT License](LICENSE.md).