Go to file
Norio Nomura 4556cfb81b
Add `test_null_yml()` to `EncoderTests` from #157
2019-01-29 12:03:53 +09:00
Sources Update LibYAML (#150) 2019-01-06 13:19:48 -08:00
Tests Add `test_null_yml()` to `EncoderTests` from #157 2019-01-29 12:03:53 +09:00
Yams.xcodeproj Change `SWIFT_VERSION` to 4.2 2018-12-25 11:07:37 +09:00
.gitignore Basic API doc generation 2018-04-29 14:33:24 -07:00
.jazzy.yaml Change jazzy github_file_prefix to master 2018-05-09 20:57:34 -07:00
.swift-version Update LibYAML (#150) 2019-01-06 13:19:48 -08:00
.swiftlint.yml Lint for unused private declarations (#149) 2019-01-06 10:18:32 -08:00
CHANGELOG.md Update LibYAML (#150) 2019-01-06 13:19:48 -08:00
CONTRIBUTING.md Add CONTRIBUTING.md 2017-11-02 22:25:37 -07:00
Docs.md Point to API docs link from Docs.md 2018-05-12 16:26:23 -07:00
Gemfile Add jazzy to Gemfile 2018-05-06 11:26:49 -07:00
Gemfile.lock Update gems 2018-12-05 12:35:25 -08:00
LICENSE first commit 2016-11-19 13:59:58 -08:00
Package.swift Revert Package.swift changes 2018-09-10 07:25:50 -07:00
Package@swift-4.2.swift Fix indentation 2018-09-11 10:51:28 -07:00
Package@swift-5.swift Add Package@swift-5.swift 2018-12-25 09:17:16 +09:00
README.md Update badge in README to point to Azure Pipelines 2018-12-24 14:19:05 -08:00
Yams.podspec Release 1.0.1 2018-08-30 13:27:59 -07:00
azure-pipelines.yml Revert "Use SwiftLint HEAD to avoid false positives in unused_private_declaration" 2019-01-18 15:08:55 +09:00
yams.jpg add image to readme 2016-11-20 11:26:22 -08:00

README.md

Yams

Yams

A sweet and swifty YAML parser built on LibYAML.

Azure Pipelines

Installation

Building Yams on macOS requires Xcode 9.x or a Swift 3.2/4.x toolchain with the Swift Package Manager.

Building Yams on Linux requires a Swift 4.x compiler and Swift Package Manager to be installed.

Swift Package Manager

Add .package(url: "https://github.com/jpsim/Yams.git", from: "1.0.1") to your Package.swift file's dependencies.

CocoaPods

Add pod 'Yams' to your Podfile.

Carthage

Add github "jpsim/Yams" to your Cartfile.

Usage

Yams has three groups of conversion APIs: one for use with Codable types, another for Swift Standard Library types, and a third one for a Yams-native representation.

Codable types

  • Codable is an encoding & decoding strategy introduced in Swift 4 enabling easy conversion between YAML and other Encoders like JSONEncoder and PropertyListEncoder.
  • Lowest computational overhead, equivalent to Yams.Node.
  • Encoding: YAMLEncoder.encode(_:) Produces a YAML String from an instance of type conforming to Encodable.
  • Decoding: YAMLDecoder.decode(_:from:) Decodes an instance of type conforming to Decodable from YAML String.
import Foundation
import Yams

struct S: Codable {
    var p: String
}

let s = S(p: "test")
let encoder = YAMLEncoder()
let encodedYAML = try encoder.encode(s)
encodedYAML == """
p: test

"""
let decoder = YAMLDecoder()
let decoded = try decoder.decode(S.self, from: encodedYAML)
s.p == decoded.p

Swift Standard Library types

  • The type of Swift Standard Library is inferred from the contents of the internal Yams.Node representation by matching regular expressions.
  • This method has the largest computational overhead When decoding YAML, because the type inference of all objects is done up-front.
  • It may be easier to use in such a way as to handle objects created from JSONSerialization or if the input is already standard library types (Any, Dictionary, Array, etc.).
  • Encoding: Yams.dump(object:) Produces a YAML String from an instance of Swift Standard Library types.
  • Decoding: Yams.load(yaml:) Produces an instance of Swift Standard Library types as Any from YAML String.
// [String: Any]
let dictionary: [String: Any] = ["key": "value"]
let mapYAML: String = try Yams.dump(object: dictionary)
mapYAML == """
key: value

"""
let loadedDictionary = try Yams.load(yaml: mapYAML) as? [String: Any]

// [Any]
let array: [Int] = [1, 2, 3]
let sequenceYAML: String = try Yams.dump(object: array)
sequenceYAML == """
- 1
- 2
- 3

"""
let loadedArray: [Int]? = try Yams.load(yaml: sequenceYAML) as? [Int]

// Any
let string = "string"
let scalarYAML: String = try Yams.dump(object: string)
scalarYAML == """
string

"""
let loadedString: String? = try Yams.load(yaml: scalarYAML) as? String

Yams.Node

  • Yams' native model representing Nodes of YAML which provides all functions such as detection and customization of the YAML format.
  • Depending on how it is used, computational overhead can be minimized.
  • Encoding: Yams.serialize(node:) Produces a YAML String from an instance of Node.
  • Decoding Yams.compose(yaml:) Produces an instance of Node from YAML String.
var map: Yams.Node = [
    "array": [
        1, 2, 3
    ]
]
map.mapping?.style = .flow
map["array"]?.sequence?.style = .flow
let yaml = try Yams.serialize(node: map)
yaml == """
{array: [1, 2, 3]}

"""
let node = try Yams.compose(yaml: yaml)
map == node

License

Both Yams and libYAML are MIT licensed.