dyaml.dumper

YAML dumper.

Code based on PyYAML.

struct Dumper;

Dumps YAML documents to files or streams.

User specified Representer and/or Resolver can be used to support new tags / data types.
Setters are provided to affect output details (style, encoding, etc.).

Examples:

Write to a file:

auto node = Node([1, 2, 3, 4, 5]);
Dumper("file.yaml").dump(node);

Write multiple YAML documents to a file:

auto node1 = Node([1, 2, 3, 4, 5]);
auto node2 = Node("This document contains only one string");
Dumper("file.yaml").dump(node1, node2);

//Or with an array:
//Dumper("file.yaml").dump([node1, node2]);

Write to memory:

import std.stream;
auto stream = new MemoryStream();
auto node = Node([1, 2, 3, 4, 5]);
Dumper(stream).dump(node);

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

auto node = Node([1, 2, 3, 4, 5]);
auto representer = new Representer();
auto resolver = new Resolver();

//Add representer functions / resolver expressions here...

auto dumper = Dumper("file.yaml");
dumper.representer = representer;
dumper.resolver = resolver;
dumper.dump(node);

@trusted this(string filename);

Construct a Dumper writing to a file.

Parameters:

string filename

File name to write to.

Throws:

YAMLException if the file can not be dumped to (e.g. cannot be opened).

@safe this(Stream stream);

Construct a Dumper writing to a stream. This is useful to e.g. write to memory.

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

Set stream name. Used in debugging messages.

@property @trusted void resolver(Resolver resolver);

Specify custom Resolver to use.

@property @trusted void representer(Representer representer);

Specify custom Representer to use.

pure nothrow @property @safe void canonical(bool canonical);

Write scalars in canonical form?

pure nothrow @property @safe void indent(uint indent);

Set indentation width. 2 by default. Must not be zero.

pure nothrow @property @safe void textWidth(uint width);

Set preferred text width.

pure nothrow @property @safe void lineBreak(LineBreak lineBreak);

Set line break to use. Unix by default.

pure nothrow @property @safe void encoding(Encoding encoding);

Set character encoding to use. UTF-8 by default.

pure nothrow @property @safe void explicitStart(bool explicit);

Always explicitly write document start?

pure nothrow @property @safe void explicitEnd(bool explicit);

Always explicitly write document end?

pure nothrow @property @safe void YAMLVersion(string YAMLVersion);

Specify YAML version string. "1.1" by default.

pure @property @trusted void tagDirectives(string[string] tags);

Specify tag directives.

A tag directive specifies a shorthand notation for specifying tags. Each tag directive associates a handle with a prefix. This allows for compact tag notation.
Each handle specified MUST start and end with a '!' character (a single character "!" handle is allowed as well).
Only alphanumeric characters, '-', and '_' may be used in handles.
Each prefix MUST not be empty.
The "!!" handle is used for default YAML tags with prefix "tag:yaml.org,2002:". This can be overridden.

Parameters:

string[string] tags

Tag directives (keys are handles, values are prefixes).

Example:

Dumper dumper = Dumper("file.yaml");
string[string] directives;
directives["!short!"] = "tag:long.org,2011:";
//This will emit tags starting with "tag:long.org,2011"
//with a "!short!" prefix instead.
dumper.tagDirectives(directives);
dumper.dump(Node("foo"));

@trusted void dump(Node[] documents...);

Dump one or more YAML documents to the file/stream.

Note that while you can call dump() multiple times on the same dumper, you will end up writing multiple YAML "files" to the same file/stream.

Parameters:

Node[] documents

Documents to dump (root nodes of the documents).

Throws:

YAMLException on error (e.g. invalid nodes, unable to write to file/stream).