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.3")
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 YAMLString
from an instance of type conforming toEncodable
. - Decoding:
YAMLDecoder.decode(_:from:)
Decodes an instance of type conforming toDecodable
from YAMLString
orData
.
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 YAMLString
from an instance of Swift Standard Library types. - Decoding:
Yams.load(yaml:)
Produces an instance of Swift Standard Library types asAny
from 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 YAMLString
from an instance ofNode
. - Decoding
Yams.compose(yaml:)
Produces an instance ofNode
from 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) -> AnyPublisher<Book, Error> {
URLSession.shared.dataTaskPublisher(for: url)
.map(\.data)
.decode(type: Book.self, decoder: YAMLDecoder())
.eraseToAnyPublisher()
}
License
Both Yams and libYAML are MIT licensed.
Github
link |
Stars: 666 |
You may find interesting
Used By
- MakeAWishFoundation/SwiftyMockyCLI
- muukii/L10n.swift
- diegofesanto/movies-swift
- mattpolzin/OrderedDictionary
- flintprocessor/Flint
- Arrnas/ios-unit-test-workshop
- MadsBogeskov/Swagger_2_0_to_Swift
- nhamada/UFlow
- MaxAdamyan/maxadamyan.github.io
- josefdolezal/redmine-toggl-importer
- bscothern/SecretKeeper
- broadwaylamb/GottaGoFast
- hoemoon/bearc
- mattt/swift-package-registry-oas
- artemnovichkov/spasibo
- spprichard/picker
- genuflecto/fisherman
- dmiotti/jargon
- MadsBogeskov/SwaggerSwiftML
- MobiTech1191/Vapor-WebSiteProject
Total: 189
Releases
4.0.3 - 2020-12-11T18:41:18
Breaking
- None.
Enhancements
-
Update Xcode project from Swift 4.2 to 5.0.
Brennan Stehling -
Enable
CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER
.
Brennan Stehling
Bug Fixes
- None.
4.0.2 - 2020-12-09T14:31:16
Breaking
- None.
Enhancements
- Add support for Apple Silicon in
SwiftSupport.cmake
.
Max Desiatov
Bug Fixes
- None.
4.0.1 - 2020-11-11T16:51:59
Breaking
- None.
Enhancements
- None.
Bug Fixes
-
String scalars containing numbers are no longer decoded as numbers.
Matt Polzin #263 -
Fix compilation errors when compiling using Swift For TensorFlow or Windows.
Saleem Abdulrasool
4.0.0 - 2020-08-21T16:45:52
Breaking
- Swift 5.1 or later is now required to build Yams.
JP Simard
Enhancements
-
YAMLDecoder
now conforms to theTopLevelDecoder
protocol when Apple's Combine framework is available.
JP Simard #261 -
Add
YAMLDecoder.decode(...)
overload tha takes a YAML string encoded asData
using UTF8 or UTF16.
JP Simard
Bug Fixes
- Fix CMake installation issues.
Saleem Abdulrasool
3.0.1 - 2020-05-10T08:04:53
3.0.0 - 2020-04-18T04:05:43
Breaking
- Swift 4.1 or later is now required to build Yams.
Norio Nomura
Enhancements
-
Accurately represent
Date
s with nanosecond components in Swift 4.x.
Norio Nomura -
Change to apply single quoted style to YAML representation of
String
, if that contents will be resolved to other than.str
by defaultResolver
.
Norio Nomura #197 -
Support
UUID
scalars.
Ondrej Rafaj -
Get Yams building for Windows.
Saleem Abdulrasool -
Add support for CMake based builds.
Saleem Abdulrasool -
Merge anchors in
YAMLDecoder
by default.
Brentley Jones #238
Bug Fixes
-
Fix
Yams.dump
when object contains a keyed null value.
JP Simard #232 -
Fix a bug where
YAMLEncoder
would delayDate
s by 1 second when encoding values with ananosecond
component greater than 999499997.
Norio Nomura #192 -
Fix dangling pointer warning with Swift 5.2.
JP Simard
2.0.0 - 2019-04-06T23:48:52
Breaking
- Change
byteOffset
tooffset
inYamlError.reader
.
Norio Nomura
Enhancements
- Add
encoding
option toParser
asParser.Encoding
type to specify which encoding to pass to libYAML. Along with that change, addencoding
options toload()
,load_all()
,compose()
,compose_all()
andYAMLDecoder
. The default encoding will be determined at run time based on the String type's native encoding.
Norio Nomura
Bug Fixes
- None.
1.0.2 - 2019-04-01T17:53:55
Breaking
- None.
Enhancements
- Update LibYAML sources to latest versions as of January 6 2018.
JP Simard
Bug Fixes
-
Fix some test failures with the latest Swift 5 snapshot on Apple platforms.
Norio Nomura #143 -
Preserve nanoseconds in dates when using swift-corelibs-foundation with Swift 5.
Norio Nomura #146 -
Fix null/~/NULL/Null were parsed as strings, not nil by
YAMLDecoder
.
Norio Nomura #157
1.0.1 - 2018-08-30T20:29:33
Breaking
- None.
Enhancements
- Improve support for compiling with Swift 4.2 or later.
Norio Nomura
Bug Fixes
- Fix issues with unset
DYLIB_COMPATIBILITY_VERSION
andDYLIB_CURRENT_VERSION
. Now both values are set to1
.
Norio Nomura #131
1.0.0 - 2018-05-19T01:42:55
Breaking
- Rename
ScalarRepresentableCustomizedForCodable
toYAMLEncodable
.
Norio Nomura
Enhancements
- API documentation now available at jpsim.com/Yams.
JP Simard
Bug Fixes
- None.