Loader

⌂ dyaml.loader.Loader

public struct Loader

Loads YAML documents from files or streams.

User specified Constructor and/or Resolver can be used to support new tags / data types.

Examples

Load single YAML document from a file:

 auto rootNode = Loader("file.yaml").load();
 ...

Load all YAML documents from a file:

 auto nodes = Loader("file.yaml").loadAll();
 ...

Iterate over YAML documents in a file, lazily loading them:

 auto loader = Loader("file.yaml");

 foreach(ref node; loader)
 {
     ...
 }

Load YAML from a string:

 char[] yaml_input = "red:   '#ff0000'\n"
                     "green: '#00ff00'\n"
                     "blue:  '#0000ff'".dup;

 auto colors = Loader.fromString(yaml_input).load();

 foreach(string color, string value; colors)
 {
     import std.stdio;
     writeln(color, " is ", value, " in HTML/CSS");
 }

Load a file into a buffer in memory and then load YAML from that buffer:

 try
 {
     import std.file;
     void[] buffer = std.file.read("file.yaml");
     auto yamlNode = Loader(buffer);

     // Read data from yamlNode here...
 }
 catch(FileException e)
 {
     writeln("Failed to read file 'file.yaml'");
 }

Use a custom constructor/resolver to support custom data types and/or implicit tags:

 auto constructor = new Constructor();
 auto resolver    = new Resolver();

 // Add constructor functions / resolver expressions here...

 auto loader = Loader("file.yaml");
 loader.constructor = constructor;
 loader.resolver    = resolver;
 auto rootNode      = loader.load(node);

public this(string filename) @trusted

Construct a Loader to load YAML from a file.

Parameters

filename

Name of the file to load from.

Throws

YAMLException if the file could not be opened or read.

public static Loader fromString(char[] data) @safe

Construct a Loader to load YAML from a string (char []).

Parameters

data	String to load YAML from. will be overwritten during parsing as D:YAML reuses memory. Use data.dup if you don't want to modify the original string.

Returns

Loader loading YAML from given string.

Throws

YAMLException if data could not be read (e.g. a decoding error)

Example

assert(Loader.fromString(cast(char[])"42").load().as!int == 42);

public this(void[] yamlData) @safe

Construct a Loader to load YAML from a buffer.

Parameters

yamlData

Buffer with YAML data to load. This may be e.g. a file loaded to memory or a string with YAML data. Note that buffer will be overwritten, as D:YAML minimizes memory allocations by reusing the input _buffer. Must not be deleted or modified by the user as long as nodes loaded by this Loader are in use! - Nodes may refer to data in this buffer. Note that D:YAML looks for byte-order-marks YAML files encoded in UTF-16/UTF-32 (and sometimes UTF-8) use to specify the encoding and endianness, so it should be enough to load an entire file to a buffer and pass it to D:YAML, regardless of Unicode encoding.

Throws

YAMLException if yamlData contains data illegal in YAML.

public void name(string name) pure @safe nothrow @nogc

Set stream _name. Used in debugging messages.

public void resolver(Resolver resolver) pure @safe nothrow @nogc

Specify custom Resolver to use.

public void constructor(Constructor constructor) pure @safe nothrow @nogc

Specify custom Constructor to use.

public Node load() @safe

Load single YAML document.

Contracts

in
{
    assert (!done_, "Loader: Trying to load YAML twice");
}

If none or more than one YAML document is found, this throws a YAMLException.

This can only be called once; this is enforced by contract.

Returns

Root node of the document.

Throws

YAMLException if there wasn't exactly one document or on a YAML parsing error.

public Node[] loadAll() @trusted

Load all YAML documents.

This is just a shortcut that iterates over all documents and returns them all at once. Calling loadAll after iterating over the node or vice versa will not return any documents, as they have all been parsed already.

This can only be called once; this is enforced by contract.

Returns

Array of root nodes of all documents in the file/stream.

Throws

YAMLException on a parsing error.

public int opApply(int delegate(ref Node) dg) @trusted

Foreach over YAML documents.

Contracts

in
{
    assert (!done_, "Loader: Trying to load YAML twice");
}

Parses documents lazily, when they are needed.

Foreach over a Loader can only be used once; this is enforced by contract.

Throws

YAMLException on a parsing error.

Functions

this		Construct a Loader to load YAML from a file.
staticfromString@safe		Construct a Loader to load YAML from a string (char []).
this		Construct a Loader to load YAML from a buffer.
namepure, @safe, nothrow, @nogc		Set stream _name. Used in debugging messages.
resolverpure, @safe, nothrow, @nogc		Specify custom Resolver to use.
constructorpure, @safe, nothrow, @nogc		Specify custom Constructor to use.
load@safe		Load single YAML document.
loadAll@trusted		Load all YAML documents.
opApply@trusted		Foreach over YAML documents.