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).
Importing this module will expose the following top-level symbol(s):
enum JSON
In addition, this module re-exports the following top-level symbol(s) from the Grammar
module of swift-grammar
:
enum Grammar
protocol TraceableError
protocol TraceableErrorRoot
struct ParsingError<Index>
struct ParsingInput<Diagnostics>
protocol ParsingDiagnostics
protocol ParsingRule
protocol TerminalRule
protocol LiteralRule
protocol DigitRule
protocol ASCIITerminal
protocol UTF8Terminal
protocol UTF16Terminal
protocol UnicodeTerminal
protocol CharacterTerminal
This module has library interfaces:
@_spi(experimental)
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 the JSON.Rule<Location>.Root
parsing rule:
import JSON
@main
enum Main
{
struct Decimal:Codable
{
let units:Int
let places:Int
}
struct Response:Codable
{
let success:Bool
let value:Decimal
}
static
func main() throws
{
let string:String =
"""
{"success":true,"value":0.1}
"""
let decoder:JSON = try Grammar.parse(string.utf8,
as: JSON.Rule<String.Index>.Root.self)
let response:Response = try .init(from: decoder)
print(response)
let invalid:String =
"""
{"success":true,value:0.1}
"""
do
{
let _:JSON = try Grammar.parse(diagnosing: invalid.utf8,
as: JSON.Rule<String.Index>.Root.self)
}
catch let error as ParsingError<String.Index>
{
let debug:String = error.annotate(source: invalid,
line: String.init(_:), newline: \.isNewline)
print(debug)
}
}
}
$ .build/release/examples
Response(success: true, value:
JSONExamples.Main.Decimal(units: 1, places: 1))
Grammar.Expected<Grammar.Encoding.ASCII.Quote>:
expected construction by rule 'Quote'
{"success":true,value:0.1}
^
note: expected pattern 'Grammar.Encoding.ASCII.Quote'
{"success":true,value:0.1}
^
note: while parsing value of type 'String' by rule
'JSON.Rule.StringLiteral'
{"success":true,value:0.1}
^
note: while parsing value of type '((), (key: String, value: JSON))'
by rule '(Grammar.Pad<Grammar.Encoding.ASCII.Comma,
JSON.Rule.Whitespace>, JSON.Rule.Object.Item)'
{"success":true,value:0.1}
^~
note: while parsing value of type '[String: JSON]' by rule
'JSON.Rule.Object'
{"success":true,value:0.1}
^~~~~~~~~~~~~~~~~
note: while parsing value of type 'JSON' by rule 'JSON.Rule.Root'
{"success":true,value:0.1}
^~~~~~~~~~~~~~~~~
The JSON
module supports parsing 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.
swift-json
as a dependencyTo 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
]
)
swift-json
is DocC-compatible. However, its documentation is a lot more useful when built with a documentation engine like swift-biome
.
swift-json
uses the swift-documentation-extract
plugin to gather its documentation.
Run the catalog
plugin command, and store its output in a JSON file.
swift package catalog JSON Grammar > catalog.json
The arguments JSON
and Grammar
tell swift package catalog
to gather documentation only from the JSON
module in this package, and the Grammar
module in swift-grammar
.
git submodule update --recursive
This checks out the .biome
submodule, which tracks swift-biome-index
and contains a copy of the Swift standard library’s symbolgraph.
This repository already contains an indexfile called swift.json
, which references the relevant modules in the ecosystem index. It’s just like the catalog.json
file you generated in the previous step.
swift-biome
swift-biome
is a normal SPM package. There’s lots of ways to build it.
git clone git@github.com:kelvin13/swift-biome.git
cd swift-biome
swift build -c release
cd ..
preview
serverswift-biome
includes an executable target called preview
. Pass it the two indexfiles, and it will start up a server on localhost:8080
.
swift-biome/.build/release/preview swift.json catalog.json
Note: The
swift.json
indexfile contains relative paths, so you should runpreview
from theswift-json
repository root.
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://
.
link |
Stars: 30 |
Last commit: 4 days ago |
this release contains backported fixes to get this package compiling again with the swift 5.6 toolchain in the wake of SE-0335 being dropped from swift 5.6. it also specifies the swift-grammar
dependency version more precisely.
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics