Swiftpack.co - kelvin13/swift-json as Swift Package

swift-json is a pure-Swift JSON parsing library designed for high-performance, high-throughput server-side applications. When compared using the test data captured.json, swift-json is nearly 7 times faster than Foundation.JSONDecoder (see benchmark source code). This library is powered by swift-grammar!

Importing this module will expose the following top-level symbol(s):

• enum JSON

example usage

The JSON module in swift-json enables you to express JSON parsing tasks as constructive parsers. This makes the JSON module very flexible without requiring much configuration from users who simply want to parse a JSON message from a remote peer.

To parse a complete JSON message, use its init(parsing:) initializer, or for more flexibility, the JSON.Rule<Location>.Root parsing rule:

BasicDecoding.swift

import JSON 

struct Decimal:Codable  
{
    let units:Int 
    let places:Int 
}
struct Response:Codable 
{
    let success:Bool 
    let value:Decimal
}

let string:String = 
"""
{"success":true,"value":0.1}
"""
let decoder:JSON = try .init(parsing: string.utf8)
let response:Response = try .init(from: decoder)

print(response)

$ swift run BasicDecoding
Response(success: true, value: Decimal(units: 1, places: 1))

The rule is called “Root” because it will match only complete JSON messages (objects or arrays). Like most swift-grammar-based parsers, JSON.Rule is generic over its input, which means you can parse directly from some Collection of UInt8.

swift-json’s constructive parsing engine also allows you to get diagnostics for invalid JSON messages:

Diagnostics.swift

import Grammar
import JSON

let invalid:String = 
"""
{"success":true,value:0.1}
"""
do 
{
    let _:JSON = try JSON.Rule<String.Index>.Root.parse(diagnosing: invalid.utf8)
}
catch let error as ParsingError<String.Index> 
{
    let debug:String = error.annotate(source: invalid, 
        line: String.init(_:), newline: \.isNewline)
    print(debug)
}

$ swift run Diagnostics
Grammar.Expected<Grammar.Encoding<String.Index, UInt8>.Quote>: expected construction by rule 'Quote'
{"success":true,value:0.1}
                ^
note: expected pattern 'Grammar.Encoding<String.Index, UInt8>.Quote'
{"success":true,value:0.1}
                ^
note: while parsing value of type 'String' by rule 'JSON.Rule<String.Index>.StringLiteral'
{"success":true,value:0.1}
                ^
note: while parsing value of type '((), (key: String, value: JSON))' 
by rule '(Grammar.Pad<Grammar.Encoding<String.Index, UInt8>.Comma, 
JSON.Rule<String.Index>.Whitespace>, JSON.Rule<String.Index>.Object.Item)'
{"success":true,value:0.1}
               ^~
note: while parsing value of type 'Array<(key: String, value: JSON)>' by rule 'JSON.Rule<String.Index>.Object'
{"success":true,value:0.1}
^~~~~~~~~~~~~~~~~
note: while parsing value of type 'JSON' by rule 'JSON.Rule<String.Index>.Root'
{"success":true,value:0.1}
^~~~~~~~~~~~~~~~~

You can be more selective about the form of the JSON you expect to receive by using one of the library’s subrules:

• Null
• True
• False
• NumberLiteral
• StringLiteral
• Object
• Array

The JSON module supports parsing arbitrary JSON fragments using the JSON.Rule<Location>.Value rule.

The nature of constructive parsing also means it is straightforward to parse multiple concatenated JSON messages, as is commonly encountered when interfacing with streaming JSON APIs.

adding swift-json as a dependency

To use swift-json in a project, add the following to your Package.swift file:

let package = Package(
    ...
    dependencies: 
    [
        // other dependencies
        .package(url: "https://github.com/kelvin13/swift-json", from: "0.2.2"),
    ],
    targets: 
    [
        .target(name: "example", 
            dependencies: 
            [
                .product(name: "JSON", package: "swift-json"),
                // other dependencies
            ]),
        // other targets
    ]
)

building and previewing documentation

swift-json is DocC-compatible. However, its documentation is a lot more useful when built with a documentation engine like swift-biome.

1. gather the documentation files

swift-json uses the swift-package-catalog plugin to gather its documentation.

Run the catalog plugin command, and store its output in a file named Package.catalog.

$ swift package catalog > Package.catalog

The catalog file must be named Package.catalog; Biome parses it (and the Package.resolved file generated by the Swift Package Manager) in order to find swift-json’s symbolgraphs and DocC archives.

2. build swift-biome

swift-biome is a normal SPM package. There’s lots of ways to build it.

$ git clone [email protected]:kelvin13/swift-biome.git
$ git submodule update --init --recursive

$ cd swift-biome 
$ swift build -c release 
$ cd ..

Don’t forget the git submodule update!

3. run the preview server

swift-biome includes an executable target called preview. Pass it the path to the swift-json repository (in this example, ..), and it will start up a server on localhost:8080.

$ cd swift-biome 
$ .build/release/preview --swift 5.6.2 ..

The --swift 5.6.2 option specifies the version of the standard library that the Biome compiler should link against.

Note: if you run the preview tool from outside the swift-biome repository, you will need to specify the path to the resources (sub)module. For example, if you did not cd into swift-biome, you would have to add the option --resources swift-biome/resources.

Navigate to http://127.0.0.1:8080/reference/swift-json in a browser to view the documentation. Make sure the scheme is http:// and not https://.