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

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

this(Stream stream);

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

@property void name(string name);

Set stream name. Used in debugging messages.

void resolver(Resolver resolver);

Specify custom Resolver to use.

void representer(Representer representer);

Specify custom Representer to use.

void canonical(in bool canonical);

Write scalars in canonical form?

void indent(in uint indent);

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

void textWidth(in uint width);

Set preferred text width.

void lineBreak(in LineBreak lineBreak);

Set line break to use. Unix by default.

void encoding(in Encoding encoding);

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

void explicitStart(in bool explicit);

Always explicitly write document start?

void explicitEnd(in bool explicit);

Always explicitly write document end?

void YAMLVersion(in string YAMLVersion);

Specify YAML version string. "1.1" by default.

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");
 //This will emit tags starting with "tag:long.org,2011"
 //with a "!short!" prefix instead.
 dumper.tags("short", "tag:long.org,2011:");
 dumper.dump(Node("foo"));

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