Yams
A sweet and swifty YAML parser built on LibYAML.
Installation
Building Yams requires Xcode 11.x or a Swift 5.1+ toolchain with the Swift Package Manager or CMake and Ninja.
CMake
CMake 3.17.2 or newer is required, along with Ninja 1.9.0 or newer.
When building for non-Apple platforms:
cmake -B /path/to/build -G Ninja -S /path/to/yams -DCMAKE_BUILD_TYPE=Release -DFoundation_DIR=/path/to/foundation/build/cmake/modules
cmake --build /path/to/build
To build for Apple platforms (macOS, iOS, tvOS, watchOS), there is no need to spearately build Foundation because it is included as part of the SDK:
cmake -B /path/to/build -G Ninja -S /path/to/yams -DCMAKE_BUILD_TYPE=Release
cmake --build /path/to/build
Swift Package Manager
Add .package(url: "https://github.com/jpsim/Yams.git", from: "4.0.6") to your Package.swift file's dependencies.
CocoaPods
Add pod 'Yams' to your Podfile.
Carthage
Add github "jpsim/Yams" to your Cartfile.
Bazel
In your WORKSPACE file
YAMS_GIT_SHA = "SOME_SHA"
http_archive(
name = "com_github_jpsim_yams",
urls = [
"https://github.com/jpsim/Yams/archive/%s.zip" % YAMS_GIT_SHA,
],
strip_prefix = "yams-%s" % YAMS_GIT_SHA,
)
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 YAMLStringfrom an instance of type conforming toEncodable. - Decoding:
YAMLDecoder.decode(_:from:)Decodes an instance of type conforming toDecodablefrom YAMLStringorData.
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.Noderepresentation 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
JSONSerializationor if the input is already standard library types (Any,Dictionary,Array, etc.). - Encoding:
Yams.dump(object:)Produces a YAMLStringfrom an instance of Swift Standard Library types. - Decoding:
Yams.load(yaml:)Produces an instance of Swift Standard Library types asAnyfrom YAMLString.
// [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 YAMLStringfrom an instance ofNode. - Decoding
Yams.compose(yaml:)Produces an instance ofNodefrom YAMLString.
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
Integrating with Combine
When Apple's Combine framework is available, YAMLDecoder conforms to the TopLevelDecoder protocol, which allows it to be used with the decode(type:decoder:) operator:
import Combine
import Foundation
import Yams
func fetchBook(from url: URL) -> AnyPublisherError> {
URLSession.shared.dataTaskPublisher(for: url)
.map(\.data)
.decode(type: Book.self, decoder: YAMLDecoder())
.eraseToAnyPublisher()
}
License
Both Yams and libYAML are MIT licensed.
![[Experimental] Replace FloatingPoint Formatter and add support Float80](https://avatars.githubusercontent.com/u/33430?v=4)
3.8k Jan 5, 2023
31 Nov 22, 2021
9 Jul 20, 2022
132 Dec 5, 2021
117 Sep 9, 2022
27 Aug 19, 2020
14 Aug 13, 2018
0 Dec 3, 2021
0 Dec 14, 2021
452 Dec 26, 2022
964 Dec 14, 2022
8.5k Jan 3, 2023
287 Nov 11, 2022
3.5k Dec 20, 2022
1k Jul 15, 2022
611 Oct 23, 2022
4.1k Dec 29, 2022
788 Jul 19, 2022
9k Jan 2, 2023