diff --git a/Sources/Jay/Conversions.swift b/Sources/Jay/Conversions.swift index 0c1b911..4dafca9 100644 --- a/Sources/Jay/Conversions.swift +++ b/Sources/Jay/Conversions.swift @@ -11,23 +11,27 @@ import Foundation //Useful methods for easier manipulation of type-safe JSON extension JSON { - + + /// Returns the `JSON` as `[String: JSON]` if valid, else `nil`. public var dictionary: [Swift.String: JSON]? { guard case .object(let dict) = self else { return nil } return dict } - + + /// Returns the `JSON` as `[JSON]` if valid, else `nil`. public var array: [JSON]? { guard case .array(let arr) = self else { return nil } return arr } - + + /// Returns the `JSON` as an `Int` if valid, else `nil`. public var int: Int? { guard case .number(let number) = self else { return nil } guard case .integer(let jsonInt) = number else { return nil } return jsonInt } - + + /// Returns the `JSON` as a `UInt` if valid, else `nil`. public var uint: UInt? { guard case .number(let number) = self else { return nil } switch number { @@ -36,7 +40,8 @@ extension JSON { default: return nil } } - + + /// Returns the `JSON` as a `Double` if valid, else `nil`. public var double: Double? { guard case .number(let number) = self else { return nil } switch number { @@ -45,17 +50,20 @@ extension JSON { case .unsignedInteger(let uint): return Double(uint) } } - + + /// Returns the `JSON` as a `String` if valid, else `nil`. public var string: Swift.String? { guard case .string(let str) = self else { return nil } return str } - + + /// Returns the `JSON` as a `Bool` if valid, else `nil`. public var boolean: Bool? { guard case .boolean(let bool) = self else { return nil } return bool } - + + /// Returns the `JSON` as `NSNull` if valid, else `nil`. public var null: NSNull? { guard case .null = self else { return nil } return NSNull() @@ -65,32 +73,43 @@ extension JSON { //Thanks for the inspiration for the following initializers, https://github.com/Zewo/JSON/blob/master/Source/JSON.swift extension JSON: BooleanLiteralConvertible { + + /// Create a `JSON` instance initialized to the provided `booleanLiteral`. public init(booleanLiteral value: BooleanLiteralType) { self = .boolean(value) } } extension JSON: IntegerLiteralConvertible { + + /// Create a `JSON` instance initialized to the provided `integerLiteral`. public init(integerLiteral value: IntegerLiteralType) { self = .number(.integer(value)) } } extension JSON: FloatLiteralConvertible { + + /// Create a `JSON` instance initialized to the provided `floatLiteral`. public init(floatLiteral value: FloatLiteralType) { self = .number(.double(value)) } } extension JSON: StringLiteralConvertible { + + /// Create a `JSON` instance initialized to the provided `unicodeScalarLiteral`. public init(unicodeScalarLiteral value: Swift.String) { self = .string(value) } - + + /// Create a `JSON` instance initialized to the provided `extendedGraphemeClusterLiteral`. public init(extendedGraphemeClusterLiteral value: Swift.String) { self = .string(value) } - + + + /// Create a `JSON` instance initialized to the provided `stringLiteral`. public init(stringLiteral value: StringLiteralType) { self = .string(value) } diff --git a/Sources/Jay/Extensions.swift b/Sources/Jay/Extensions.swift index 50f7401..db7258c 100644 --- a/Sources/Jay/Extensions.swift +++ b/Sources/Jay/Extensions.swift @@ -13,6 +13,9 @@ #endif extension JChar { + + /// Returns a `String` from an array of `JChar`s. + /// - Throws: `Error` when parsing the string fails. public func string() throws -> String { return try [self].string() } @@ -33,7 +36,9 @@ extension String { } extension Collection where Iterator.Element == UInt8 { - + + /// Returns a `String` from a collection with element `UInt8`. + /// - Throws: `Error` when parsing the string fails. public func string() throws -> String { var utf = UTF8() var gen = self.makeIterator() diff --git a/Sources/Jay/Jay.swift b/Sources/Jay/Jay.swift index cd0bc5f..5361d7e 100644 --- a/Sources/Jay/Jay.swift +++ b/Sources/Jay/Jay.swift @@ -9,59 +9,80 @@ //Implemented from scratch based on http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf and https://www.ietf.org/rfc/rfc4627.txt public struct Jay { - + + /// The formatting to apply to the `JSON`. public enum Formatting { case minified case prettified } - + + /// The formatting used. public let formatting: Formatting - + + /// Initializes and returns the `Jay` object. + /// - Parameter formatting: The `Formatting` to use. Defaults to `.minified`. public init(formatting: Formatting = .minified) { self.formatting = formatting } - //Parses data into a dictionary [String: Any] or array [Any]. - //Does not allow fragments. Test by conditional - //casting whether you received what you expected. - //Throws a descriptive error in case of any problem. + /// Parses data into a dictionary `[String: Any]` or array `[Any]`. + /// - Note: Does not allow fragments. Test by conditional + /// casting whether you received what you expected. + /// - Throws: A descriptive error in case of any problem. public func jsonFromData(_ data: [UInt8]) throws -> Any { return try NativeParser().parse(data) } - + + /// Parses the reader to `Any`. + /// - Throws: A descriptive error in case of any problem. public func jsonFromReader(_ reader: Reader) throws -> Any { return try NativeParser().parse(reader) } - //Formats your JSON-compatible object into data or throws an error. + /// Formats your JSON-compatible object into data. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(_ json: JaySON) throws -> [UInt8] { return try self.dataFromAnyJson(json.json) } - + + /// Outputs the data from json to the provided stream. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(_ json: JaySON, output: JsonOutputStream) throws { try self.dataFromAnyJson(json.json, output: output) } + /// Parses the json to data. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(_ json: [String: Any]) throws -> [UInt8] { return try self.dataFromAnyJson(json) } + /// Outputs the data from json to the provided stream. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(_ json: [String: Any], output: JsonOutputStream) throws { try self.dataFromAnyJson(json, output: output) } + /// Parses the json to data. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(_ json: [Any]) throws -> [UInt8] { return try self.dataFromAnyJson(json) } + /// Outputs the data from json to the provided stream. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(_ json: [Any], output: JsonOutputStream) throws { try self.dataFromAnyJson(json, output: output) } + /// Parses the json to data. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(_ json: Any) throws -> [UInt8] { return try self.dataFromAnyJson(json) } + /// Outputs the data from json to the provided stream. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(_ json: Any, output: JsonOutputStream) throws { try self.dataFromAnyJson(json, output: output) } @@ -121,25 +142,34 @@ extension Jay.Formatting { //Typesafe extension Jay { - //Allows users to get the JSON representation in a typesafe matter. - //However these types are wrapped, so the user is responsible for - //manually unwrapping each value recursively. If you just want - //Swift types with less type-information, use `jsonFromData()` above. + /// Allows users to get the `JSON` representation in a typesafe matter. + /// However, these types are wrapped, so the user is responsible for + /// manually unwrapping each value recursively. + /// - SeeAlso: If you just want Swift types with less + /// type-information, use `jsonFromData()` above. public func typesafeJsonFromData(_ data: [UInt8]) throws -> JSON { return try Parser().parseJsonFromData(data) } - + + /// Allows users to get the `JSON` representation in a typesafe matter. + /// However, these types are wrapped, so the user is responsible for + /// manually unwrapping each value recursively. + /// - SeeAlso: If you just want Swift types with less + /// type-information, use `jsonFromReader()` above. public func typesafeJsonFromReader(_ reader: Reader) throws -> JSON { return try Parser().parseJsonFromReader(reader) } - //Formats your JSON-compatible object into data or throws an error. + /// Formats your JSON-compatible object into data. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(json: JSON) throws -> [UInt8] { let output = ByteArrayOutputStream() try dataFromJson(json: json, output: output) return output.bytes } - + + /// Outputs your JSON-compatible object as data to the provided stream. + /// - Throws: A descriptive error in case of any problem. public func dataFromJson(json: JSON, output: JsonOutputStream) throws { try json.format(to: output, with: formatting.formatter()) } diff --git a/Sources/Jay/NativeTypeConversions.swift b/Sources/Jay/NativeTypeConversions.swift index 624b0f6..9050b84 100644 --- a/Sources/Jay/NativeTypeConversions.swift +++ b/Sources/Jay/NativeTypeConversions.swift @@ -13,9 +13,17 @@ public struct JaySON { } extension JaySON { + + /// Construct an instance representing the provided `NSDictionary`. public init(_ dict: NSDictionary) { self.json = dict } + + /// Construct an instance representing the provided `NSArray`. public init(_ array: NSArray) { self.json = array } + + /// Construct an instance representing the provided `[String: Any]`-dictionary. public init(_ dict: [String: Any]) { self.json = dict } + + /// Construct an instance representing the provided `[Any]`-array. public init(_ array: [Any]) { self.json = array } } diff --git a/Sources/Jay/OutputStream.swift b/Sources/Jay/OutputStream.swift index 1d2305e..b601f79 100644 --- a/Sources/Jay/OutputStream.swift +++ b/Sources/Jay/OutputStream.swift @@ -28,6 +28,7 @@ public class ConsoleOutputStream: JsonOutputStream { public init() { } + /// Writes the textual representation of the provided bytes into the standard output. public func print(_ bytes: [UInt8]) { let str = try? bytes.string() Swift.print(str ?? "UNFORMATTABLE DATA", terminator: "")