YAML

Usage

use YAML;

or

import YAML;

Submodules

Warning

The YAML module is considered unstable pending various name and design changes.

Support for parsing and writing YAML files.

Includes a Yaml Serializer/Deserializer as well as an abstract class representation of a YAML file.

The Yaml Serializer/Deserializer is intended to be used with the standard IO module’s serialization/deserialization API. For example:

use Yaml;

record R {
  var a: int;
  var b: string;
}

var myFile = open("r.yaml", ioMode.cwr),
    r1 = new R(1, "hello");

myFile.writer().withSerializer(new yamlSerializer()).write(r1);

/* r.yaml:
  --- R!
  a: 1
  b: hello
  ...
*/

var r2 = myFile.reader().withDeserializer(new yamlDeserializer()).read(R);
assert(r1 == r2);

Yaml files can also be written and parsed directly using the YamlValue class with the writeYamlFile and parseYamlFile procedures.

Dependencies

This module depends on the libyaml library. Installation instructions can be found here. The module was developed and tested with version 0.2.5 of libyaml.

To compile a program that uses the Yaml module, you will either need to set the CHPL_INCLUDE_PATH and CHPL_LIB_PATH environment variables with libyaml``s installation location, or use the ``-l and -L compiler flags to specify the location of the library.

type yamlWriter = fileWriter(serializerType = yamlSerializer, ?)

Type Alias for a fileWriter that uses a yamlSerializer

type yamlReader = fileReader(deserializerType = yamlDeserializer, ?)

Type Alias for a fileReader that uses a yamlDeserializer

record yamlSerializer

A YAML-format serializer for emitting chapel values in Yaml format via the IO module’s fileWriter interface

proc init(seqStyle = YamlSequenceStyle.Any, mapStyle = YamlMappingStyle.Any, scalarStyle = YamlScalarStyle.Any, documentStyle = YamlDocumentStyle.Implicit)

Create a new yamlSerializer

Arguments
  • seqStyle – The style to use for sequences. See YamlSequenceStyle.

  • mapStyle – The style to use for mappings. See YamlMappingStyle.

  • scalarStyle – The style to use for scalar values. See YamlScalarStyle.

  • documentStyle – Whether to print document headers by default.

proc ref serializeValue(writer: yamlWriter, const val: ?t) throws

called by a fileWriter to emit a value

record yamlDeserializer

A YAML-format deserializer for parsing Yaml files into Chapel values via the IO module’s fileReader interface

proc init(strictTypeChecking: bool = false)

Create a new yamlDeserializer

With strictTypeChecking set to true, the deserializer will throw an error if a Yaml value has a type annotation which does not match the type requested by the caller. With strictTypeChecking set to false, the deserializer will essentially ignore scalar type annotations in the Yaml file.

proc ref deserializeValue(reader: yamlReader, ref val: ?t) throws

called by a fileReader to parse into an existing Chapel value

proc ref deserializeType(reader: yamlReader, type t): t throws

called by a fileReader to parse into a new Chapel value

record YamlMapSerializer
var writer
var emitter: shared LibYamlEmitter
var context: shared ContextCounter
record YamlSeqSerializer
var writer
var emitter: shared LibYamlEmitter
var context: shared ContextCounter
record YamlMapDeserializer
proc hasMore(): bool throws
record YamlSeqDeserializer
proc hasMore(): bool throws
enum YamlSequenceStyle { Default, Any, Block, Flow }

The style of a YAML sequence

  • Default: let the emitter choose the style.

  • Any: let the libyaml implementation choose the style.

  • Block: use the block sequence style. I.e., line breaks and indentation.

  • Flow: use the flow sequence style. I.e., comma separated values and square brackets.

enum constant Default
enum constant Any
enum constant Block
enum constant Flow
enum YamlMappingStyle { Default, Any, Block, Flow }

The style of a YAML mapping

  • Default: let the emitter choose the style.

  • Any: let the libyaml implementation choose the style.

  • Block: use the block mapping style. I.e., line breaks and indentation.

  • Flow: use the flow mapping style. I.e., comma separated key: value pairs and curly braces.

enum constant Default
enum constant Any
enum constant Block
enum constant Flow
enum YamlScalarStyle { Default, Any, Plain, SingleQuoted, DoubleQuoted, Literal, Folded }

The style of a YAML scalar

  • Default: let the emitter choose the style.

  • Any: let the libyaml implementation choose the style.

  • Plain: no quotes around scalars

  • SingleQuoted: single quotes around scalars

  • DoubleQuoted: double quotes around scalars

  • Literal: literal style - maintain newlines

  • Folded: folded style - newlines are removed and replaced with spaces when parsed

enum constant Default
enum constant Any
enum constant Plain
enum constant SingleQuoted
enum constant DoubleQuoted
enum constant Literal
enum constant Folded
enum YamlDocumentStyle { Default, Implicit, Explicit }

The style of a YAML document

  • Default: let the emitter choose the style.

  • Implicit: the document is implicitly started. I.e., header and footer are omitted.

  • Explicit: the document is explicitly started. I.e., header and footer are included.

enum constant Default
enum constant Implicit
enum constant Explicit
class YamlEmitterError: Error
proc init(msg: string)
class YamlParserError: Error
proc init(msg: string)
class YamlUnexpectedEventError: YamlParserError
proc init(expected: string, actual: string)
class YamlValue: writeSerializable
proc this(key: shared YamlValue) ref: shared YamlValue throws

index into a YAML mapping by YAML value

proc this(idx: int): borrowed YamlValue throws

index into a YAML sequence

proc size(): int

get the size of a YAML sequence or mapping

proc tag: string

get the tag associated with a YAML value

proc valueType(): YamlValueType
proc asString(strict: bool = false): string throws
proc asBytes(strict: bool = false): bytes throws
proc asReal(strict: bool = false): real throws
proc asInt(strict: bool = false): int throws
proc asBool(strict: bool = false): bool throws
proc asMapOf(type valType): map(string, valType) throws
proc asListOf(type t): list(t) throws
class YamlMapping: YamlValue, writeSerializable
proc init()
override proc this(key: string): shared YamlValue throws

index into a YAML mapping by string

override proc this(key: shared YamlValue) ref: shared YamlValue throws

index into a YAML mapping by YAML value

override proc size(): int
override proc valueType(): YamlValueType
iter these() const ref
proc asMapOf(type kt, type vt): map(kt, vt) throws
override proc writeThis(fw) throws
class YamlSequence: YamlValue, writeSerializable
proc init()
override proc this(idx: int): shared YamlValue throws

index into a YAML sequence

override proc size(): int
override proc valueType(): YamlValueType
iter these(): YamlValue
proc asListOf(type t): list(t) throws
override proc writeThis(fw) throws
class YamlScalar: YamlValue, writeSerializable
proc init(rawValue: string)
override proc valueType(): YamlValueType
override proc asString(strict: bool = false): string throws
override proc asBytes(strict: bool = false): bytes throws
override proc asReal(strict: bool = false): real throws
override proc asInt(strict: bool = false): int throws
override proc asBool(strict: bool = false): bool throws
override proc tag: string
override proc writeThis(fw) throws
class YamlAlias: YamlValue, writeSerializable
proc init(alias: string)
override proc valueType(): YamlValueType
override proc asString(strict: bool = false): string throws
override proc asBytes(strict: bool = false): bytes throws
override proc writeThis(fw) throws
proc writeYamlFile(path: string, value: borrowed YamlValue) throws

write a yaml file to the give path

proc parseYamlFile(path: string): [] shared YamlValue throws

parse a yaml file at the given path and return an array of documents

class YamlIndexError: Error
proc init(msg: string)
class YamlTypeError: Error
proc init(msg: string)