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 writer = openWriter("r.yaml", serializer = new yamlSerializer()),
    r1 = new R(1, "hello");

writer.write(r1);

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

var r2 = myFile.reader(locking=false).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.

enum constant Default¶: Let the emitter choose the style.

enum constant Any¶: Let the libyaml implementation choose the style.

enum constant Block¶: Use the block sequence style. I.e., line breaks and indentation.

enum constant Flow¶: Use the flow sequence style. I.e., comma separated values and square brackets.

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

The style of a YAML mapping.

enum constant Default¶: Let the emitter choose the style.

enum constant Any¶: Let the libyaml implementation choose the style.

enum constant Block¶: Use the block mapping style. I.e., line breaks and indentation.

enum constant Flow¶: Use the flow mapping style. I.e., comma separated key: value pairs and curly braces.

enum YamlScalarStyle { Default, Any, Plain, SingleQuoted, DoubleQuoted, Literal, Folded }¶

The style of a YAML scalar.

enum constant Default¶: Let the emitter choose the style.

enum constant Any¶: Let the libyaml implementation choose the style.

enum constant Plain¶: No quotes around scalars

enum constant SingleQuoted¶: Single quotes around scalars

enum constant DoubleQuoted¶: Double quotes around scalars

enum constant Literal¶: Literal style - maintain newlines

enum constant Folded¶: Folded style - newlines are removed and replaced with spaces when parsed

enum YamlDocumentStyle { Default, Implicit, Explicit }¶

The style of a YAML document.

enum constant Default¶: Let the emitter choose the style.

enum constant Implicit¶: The document is implicitly started. I.e., header and footer are omitted.

enum constant Explicit¶: The document is explicitly started. I.e., header and footer are included.

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¶

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¶

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¶

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¶

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