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 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 totrue
, the deserializer will throw an error if a Yaml value has a type annotation which does not match the type requested by the caller. WithstrictTypeChecking
set tofalse
, 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¶
- 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 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