dyaml.constructor

Implements a class that processes YAML mappings, sequences and scalars into nodes. This can be used to implement custom data types. A tutorial can be found here.

class ConstructorException: dyaml.exception.YAMLException;

Exception thrown at constructor errors.

Can be thrown by custom constructor functions.

this(string msg, Mark start, Mark end, string file = __FILE__, int line = __LINE__);

Construct a ConstructorException.

Parameters:

string msg	Error message.
Mark start	Start position of the error context.
Mark end	End position of the error context.

class Constructor;

Constructs YAML values.

Each YAML scalar, sequence or mapping has a tag specifying its data type. Constructor uses user-specifyable functions to create a node of desired data type from a scalar, sequence or mapping.
Each of these functions is associated with a tag, and can process either a scalar, a sequence, or a mapping. The constructor passes each value to the function with corresponding tag, which then returns the resulting value that can be stored in a node.
If a tag is detected with no known constructor function, it is considered an error.

this(in const(bool) defaultConstructors = true);

Construct a Constructor.

If you don't want to support default YAML tags/data types, you can use defaultConstructors to disable constructor functions for these.

Parameters:

const(bool) defaultConstructors

Use constructors for default YAML tags?

void addConstructorScalar(T)(in string tag, T function(Mark, Mark, ref Node) ctor);

Add a constructor function from scalar.

The function must take two Marks (start and end positions of the node in file) and a reference to Node to construct from. The node contains a string for scalars, Node[] for sequences and Node.Pair[] for mappings. The value returned by this function will be stored in the resulting node.
Only one constructor function can be set for one tag.

Parameters:

tag	Tag for the function to handle.
ctor	Constructor function.

Example:

 import std.string;

 import yaml;

 struct MyStruct
 {
     int x, y, z;
 }

 MyStruct constructMyStructScalar(Mark start, Mark end, ref Node node)
 {
     //Guaranteed to be string as we construct from scalar.
     //!mystruct x:y:z
     auto parts = node.as!string().split(":");
     try
     {
         return MyStruct(to!int(parts[0]), to!int(parts[1]), to!int(parts[2]));
     }
     catch(Exception e)
     {
         throw new ConstructorException("Could not construct MyStruct: " ~ e.msg,
                                        start, end);
     }
 }

 void main()
 {
     auto loader = Loader("file.yaml");
     auto constructor = new Constructor;
     constructor.addConstructorScalar("!mystruct", &constructMyStructScalar);
     loader.constructor = constructor;
     Node node = loader.load();
 }

void addConstructorSequence(T)(in string tag, T function(Mark, Mark, ref Node) ctor);

Add a constructor function from sequence.

See Also:

addConstructorScalar

Example:

 import std.string;

 import yaml;

 struct MyStruct
 {
     int x, y, z;
 }

 MyStruct constructMyStructSequence(Mark start, Mark end, ref Node node)
 {
     //node is guaranteed to be sequence.
     //!mystruct [x, y, z]
     try
     {
         return MyStruct(node[0].as!int, node[1].as!int, node[2].as!int);
     }
     catch(NodeException e)
     {
         throw new ConstructorException("Could not construct MyStruct: " ~ e.msg,
                                        start, end);
     }
 }

 void main()
 {
     auto loader = Loader("file.yaml");
     auto constructor = new Constructor;
     constructor.addConstructorSequence("!mystruct", &constructMyStructSequence);
     loader.constructor = constructor;
     Node node = loader.load();
 }

void addConstructorMapping(T)(in string tag, T function(Mark, Mark, ref Node) ctor);

Add a constructor function from a mapping.

See Also:

addConstructorScalar

Example:

 import std.string;

 import yaml;

 struct MyStruct
 {
     int x, y, z;
 }

 MyStruct constructMyStructMapping(Mark start, Mark end, ref Node node)
 {
     //node is guaranteed to be mapping.
     //!mystruct {"x": x, "y": y, "z": z}
     try
     {
         return MyStruct(node["x"].as!int, node["y"].as!int, node["z"].as!int);
     }
     catch(NodeException e)
     {
         throw new ConstructorException("Could not construct MyStruct: " ~ e.msg,
                                        start, end);
     }
 }

 void main()
 {
     auto loader = Loader("file.yaml");
     auto constructor = new Constructor;
     constructor.addConstructorMapping("!mystruct", &constructMyStructMapping);
     loader.constructor = constructor;
     Node node = loader.load();
 }

YAMLNull constructNull(Mark start, Mark end, ref Node node);

Construct a null node.

YAMLMerge constructMerge(Mark start, Mark end, ref Node node);

Construct a merge node - a node that merges another node into a mapping.

bool constructBool(Mark start, Mark end, ref Node node);

Construct a boolean node.

long constructLong(Mark start, Mark end, ref Node node);

Construct an integer (long) node.

real constructReal(Mark start, Mark end, ref Node node);

Construct a floating point (real) node.

ubyte[] constructBinary(Mark start, Mark end, ref Node node);

Construct a binary (base64) node.

SysTime constructTimestamp(Mark start, Mark end, ref Node node);

Construct a timestamp (SysTime) node.

string constructString(Mark start, Mark end, ref Node node);

Construct a string node.

Pair[] getPairs(string type, Mark start, Mark end, Node[] nodes);

Convert a sequence of single-element mappings into a sequence of pairs.

Pair[] constructOrderedMap(Mark start, Mark end, ref Node node);

Construct an ordered map (ordered sequence of key:value pairs without duplicates) node.

Pair[] constructPairs(Mark start, Mark end, ref Node node);

Construct a pairs (ordered sequence of key: value pairs allowing duplicates) node.

Node[] constructSet(Mark start, Mark end, ref Node node);

Construct a set node.

Node[] constructSequence(Mark start, Mark end, ref Node node);

Construct a sequence (array) node.

Pair[] constructMap(Mark start, Mark end, ref Node node);

Construct an unordered map (unordered set of key: value pairs without duplicates) node.