swift-json v0.3.0 is finally here!
obsoleting json dictionary representations
version 0.2 of swift-json modeled objects (things written in curly braces {}) as dictionaries of String keys and JSON values:
case array([Self])
case object([String: Self])
this is the most obvious representation for a JSON value, it’s convenient for many use cases, and it dovetails nicely with the JSON.array(_:) enumeration case. however, this representation also comes with some functional and performance issues, so we have replaced this representation with a array-based [(key:String, value:JSON)] representation. this matches APIs vended by Dictionary itself.
case object([(key:String, value:Self)])
to convert an object to a Dictionary, use one of the as(_:uniquingKeysWith:) methods on JSON.
ergonomics for high-performance decoding APIs
previously, users of swift-json had to choose between a slow but ergonomic Decodable-based API, and a fast but extremely verbose direct decoding API. swift-json v0.3 comes with a much more ergonomic API for high-performance decoding.
to decode objects, you can now use the LintingDictionary abstraction, and to decode arrays, you can now use swift-json’s Array extensions. in addition to being faster, using these decoding interfaces also gives better error diagnostics when decoding fails.
for an example of how to use LintingDictionary, see its associated snippet.
RawRepresentable convenience APIs
swift-json v0.3 comes with a handful of new convenience APIs for decoding RawRepresentable types directly from JSON messages:
func `as`<StringCoded>(cases: StringCoded.Type) throws -> StringCoded
func `as`<CharacterCoded>(cases: CharacterCoded.Type) throws -> CharacterCoded
func `as`<ScalarCoded>(cases: ScalarCoded.Type) throws -> ScalarCoded
func `as`<IntegerCoded>(cases: IntegerCoded.Type) throws -> IntegerCoded
func `as`<UnsignedIntegerCoded>(cases: UnsignedIntegerCoded.Type) throws -> UnsignedIntegerCoded
avoid working with swift-grammar directly
version 0.2 of swift-json re-exported Grammar’s entire API, and expected users to invoke swift-grammar parsing rules directly. this was done to reduce the amount of “magic” in the parser, and guide users towards the lowest-overhead parsing configurations needed for their use case, which was important back when swift-json was a closed-source library primarily used for fintech applications. however it also made for a very complex API that was hard to learn if you were not already familiar with how swift-grammar works.
version 0.3 of swift-json now comes with a simplified init(parsing:) initializer, which takes UTF-8-encoded input, and just “does the right thing” by default.
ExpressibleBy_Literal conformances
the JSON type now conforms to ExpressibleByArrayLiteral,ExpressibleByBooleanLiteral, ExpressibleByDictionaryLiteral, ExpressibleByExtendedGraphemeClusterLiteral, ExpressibleByStringLiteral, and ExpressibleByUnicodeScalarLiteral.
platform and toolchain support
swift-json supports swift 5.3 ... 5.8 nightly, and has official CI coverage for linux, macOS, iOS, watchOS, tvOS, and windows.
swift-json has a fully-green build matrix on the swift package index.
documentation
we have expanded swift-json’s documentation, and published it on swiftinit.
