Skip to content

Latest commit

 

History

History
198 lines (155 loc) · 5.13 KB

Docs.md

File metadata and controls

198 lines (155 loc) · 5.13 KB

Yams Documentation

For installation instructions, see README.md.

API documentation available at jpsim.com/Yams.

Usage

Consume YAML

Here's a simple example parsing a YAML array of strings:

import Yams

let yamlString = """
  - a
  - b
  - c
  """
do {
  let yamlNode = try Yams.load(yaml: yamlString)
  if let yamlArray = yamlNode as? [String] {
    print(yamlArray)
  }
} catch {
  print("handle error: \(error)")
}

// Prints:
// ["a", "b", "c"]

Emit YAML

Here's a simple example emitting YAML string from a Swift Array<String>:

import Yams

do {
  let yamlString = try Yams.serialize(node: ["a", "b", "c"])
  print(yamlString)
} catch {
  print("handle error: \(error)")
}

// Prints:
// - a
// - b
// - c

You can even customize the style:

import Yams

var node: Node = ["a", "b", "c"]
node.sequence?.style = .flow

do {
  let yamlString = try Yams.serialize(node: node)
  print(yamlString)
} catch {
  print("handle error: \(error)")
}

// Prints:
// [a, b, c]

Customize Parsing

For example, say you only want the literals true and false to represent booleans, unlike the YAML spec compliant boolean which also includes on/off and many others.

You can customize Yams' Constructor map:

import Yams

extension Constructor {
  public static func withBoolAsTrueFalse() -> Constructor {
    var map = defaultScalarMap
    map[.bool] = Bool.constructUsingOnlyTrueAndFalse
    return Constructor(map)
  }
}

private extension Bool {
  static func constructUsingOnlyTrueAndFalse(from scalar: Node.Scalar) -> Bool? {
    switch scalar.string.lowercased() {
    case "true":
      return true
    case "false":
      return false
    default:
      return nil
    }
  }
}

// Usage:

let yamlString = """
  - true
  - on
  - off
  - false
  """
if let array = try? Yams.load(yaml: yamlString, .default, .withBoolAsTrueFalse()) as? [Any] {
  print(array)
}

// Prints:
// [true, "on", "off", false]

Expanding Environment Variables

For example:

import Yams

extension Constructor {
  public static func withEnv(_ env: [String: String]) -> Constructor {
    var map = defaultScalarMap
    map[.str] = String.constructExpandingEnvVars(env: env)
    return Constructor(map)
  }
}

private extension String {
  static func constructExpandingEnvVars(env: [String: String]) -> (_ scalar: Node.Scalar) -> String? {
    return { (scalar: Node.Scalar) -> String? in
      return node.string.expandingEnvVars(env: env)
    }
  }

  func expandingEnvVars(env: [String: String]) -> String {
    var result = self
    for (key, value) in env {
      result = result.replacingOccurrences(of: "${\(key)}", with: value)
    }

    return result
  }
}

// Usage:

let yamlString = """
  - first
  - ${SECOND}
  - SECOND
  """
let env = ["SECOND": "2"]
if let array = try? Yams.load(yaml: yamlString, .default, .withEnv(env)) as? [String] {
  print(array)
}

// Prints:
// ["first", "2", "SECOND"]

Converting Between Formats

Because Yams conforms to Swift 4's Codable protocol and provides a YAML Encoder and Decoder, you can easily convert between YAML and other formats that also provide Swift 4 Encoders and Decoders, such as JSON and Plist.

Error Handling

Failable operations in Yams throw Swift errors.

Types

Name Yams Tag YAML Tag Swift Types
... implicit `` ...
... nonSpecific ! ...
String str tag:yaml.org,2002:str String
Sequence seq tag:yaml.org,2002:seq Array<Any>
Map map tag:yaml.org,2002:map Dictionary<AnyHashable, Any>
Boolean bool tag:yaml.org,2002:bool Bool
Floating Point float tag:yaml.org,2002:float ...
Null null tag:yaml.org,2002:null Void
Integer int tag:yaml.org,2002:int FixedWidthInteger
... binary tag:yaml.org,2002:binary Data
... merge tag:yaml.org,2002:merge ...
... omap tag:yaml.org,2002:omap ...
... pairs tag:yaml.org,2002:pairs ...
Set set tag:yaml.org,2002:set Set<AnyHashable>
Timestamp timestamp tag:yaml.org,2002:timestamp Date
... value tag:yaml.org,2002:value ...
YAML yaml tag:yaml.org,2002:yaml Unsupported