YAML¶

Usage

use YAML;

or

import YAML;

Submodules

LibYamlUtils

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)¶