dyaml.loader

Class used to load YAML documents.

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

@trusted this(string filename);

Construct a Loader to load YAML from a file.

Parameters:

string filename

Name of the file to load from.

Throws:

YAMLException if the file could not be opened or read.

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

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

Parameters:

char[] 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)

Examples:

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

@safe this(void[] yamlData);

Construct a Loader to load YAML from a buffer.

Parameters:

void[] 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. 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.

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

Set stream name. Used in debugging messages.

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

Specify custom Resolver to use.

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

Specify custom Constructor to use.

@safe Node load();

Load single YAML document.

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.

@trusted Node[] loadAll();

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.

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

Foreach over YAML documents.

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.