Alembic

:alembic: Functional JSON Parser - Linux Ready :penguin:

Code Quality Rank: L4

Programming language: Swift

License: MIT License

Tags: JSON    

Latest version: v3.5.0

README

Functional JSON Parser

---

Feature

• Linux Ready
• Type-safe JSON parsing
• Functional value transformation
• Easy to parse nested value
• Dependency free
• No defined custom operators

---

Requirements

• Swift4.1 or later
• OS X 10.9 or later
• iOS 9.0 or later
• watchOS 2.0 or later
• tvOS 9.0 or later
• Linux

---

Installation

CocoaPods

Add the following to your Podfile:

use_frameworks!

target 'TargetName' do
  pod 'Alembic'
end

Carthage

Add the following to your Cartfile:

github "ra1028/Alembic"

Swift Package Manager

Add the following to your Package.swift:

// swift-tools-version:4.0

let package = Package(
    name: "ProjectName",
    dependencies : [
        .package(url: "https://github.com/ra1028/Alembic.git", .upToNextMajor(from: "3"))
    ]
)

---

Example

In example, parse the following JSON:

{
    "teams": [
        {
            "name": "Team ra1028",
            "url": "https://github.com/ra1028",
            "members": [
                {
                    "name": "Ryo Aoyama",
                    "age": 23
                },
                {
                    "name": "John Doe",
                    "age": 30
                }
            ]
        }
    ]
}

Make the JSON instance from Any, Data or String type JSON object.

// from `Any` type JSON object
let json = JSON(object)

// from JSON Data
let json = try JSON(data: data)

// from JSON String
let json = try JSON(string: string)

Parse value from JSON:

Parse the values type-safely

let memberName: String = try json.value(for: ["teams", 0, "members", 0, "name"])

Parse nullable value

let missingText: String? = try json.option(for: "missingKey")

Parse value from JSON with transforming:

Transform value using various monadic functions.

let teamUrl: URL = try json.parse(String.self, for: ["teams", 0, "url"])
        .filterMap(URL.init(string:))
        .value()

Transform nullable value if exist

let missingUrl: URL? = try json.parse(String.self, for: "missingKey")
        .filterMap(URL.init(string:))
        .option()

Mapping to model from JSON:

All types conforming to Parsable protocol and it's Array, Dictionary can be parsed.

struct Member: Parsable {
    let name: String
    let age: Int

    static func value(from json: JSON) throws -> Member {
        return try .init(
            name: json.value(for: "name"),
            age: json.value(for: "age")
        )
    }
}

extension URL: Parsable {
    public static func value(from json: JSON) throws -> URL {
        guard let url = try URL(string: json.value()) else {
            throw JSON.Error.dataCorrupted(value: json.rawValue, description: "The value was not valid url string.")
        }
        return url
    }
}

struct Team: Parsable {
    let name: String
    let url: URL
    let members: [Member]

    static func value(from json: JSON) throws -> Team {
        return try .init(
            name: json.value(for: "name"),
            url: json.value(for: "url"),
            members: json.value(for: "members")
        )
    }
}

let team: Team = try json.value(for: ["teams", 0])

---

Tips

The types conformed to Parsable as default.

JSON
String
Int
UInt
Double
Float
Bool
NSNumber
Int8
UInt8
Int16
UInt16
Int32
UInt32
Int64
UInt64
Decimal
Array where Element: Parsable
Dictionary where Key == String, Value: Parsable
Optional where Wrapped: Parsable

Conform to Parsable with initializer

struct Member: ParseInitializable {
    let name: String
    let age: Int

    init(with json: JSON) throws {
        name = try json.value(for: "name")
        age = try json.value(for: "age")
    }
}

Usage Reference Files

Functional operators for value transforming:

• [ParserProtocol.swift](./Sources/ParserProtocol.swift)
• [Parser.swift](./Sources/Parser.swift)
• [ThrowParser.swift](./Sources/ThrowParser.swift)

Errors

• [Error.swift](./Sources/Error.swift)

More Example

See the [Test files](./Tests/AlembicTests)

---

Playground

1. Open Alembic.xcworkspace.
2. Build the Alembic for Mac.
3. Open Alembic playground in project navigator.

---

Contribution

Welcome to fork and submit pull requests!

Before submitting pull request, please ensure you have passed the included tests. If your pull request including new function, please write test cases for it.

---

License

Alembic is released under the MIT License.

---