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(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(ref Node) ctor);

Add a constructor function from scalar.

The function must take a reference to Node to construct from. The node contains a string for scalars, Node[] for sequences and Node.Pair[] for mappings.
Any exception thrown by this function will be caught by D:YAML and its message will be added to a YAMLException that will also tell the user which type failed to construct, and position in the file.

The value returned by this function will be stored in the resulting node.
Only one constructor function can be set for one tag.

Structs and classes must implement the opCmp() operator for D:YAML support. The signature of the operator that must be implemented is const int opCmp(ref const MyStruct s) for structs where MyStruct is the struct type, and int opCmp(Object o) for classes. Note that the class opCmp() should not alter the compared values - it is not const for compatibility reasons.

Parameters:

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

Example:

 import std.string;

 import yaml;

 struct MyStruct
 {
     int x, y, z;

     //Any D:YAML type must have a custom opCmp operator.
     //This is used for ordering in mappings.
     const int opCmp(ref const MyStruct s)
     {
         if(x != s.x){return x - s.x;}
         if(y != s.y){return y - s.y;}
         if(z != s.z){return z - s.z;}
         return 0;
     }
 }

 MyStruct constructMyStructScalar(ref Node node)
 {
     //Guaranteed to be string as we construct from scalar.
     //!mystruct x:y:z
     auto parts = node.as!string().split(":");
     //If this throws, the D:YAML will handle it and throw a YAMLException.
     return MyStruct(to!int(parts[0]), to!int(parts[1]), to!int(parts[2]));
 }

 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(ref Node) ctor);

Add a constructor function from sequence.

See Also:

addConstructorScalar

Example:

 import std.string;

 import yaml;

 struct MyStruct
 {
     int x, y, z;

     //Any D:YAML type must have a custom opCmp operator.
     //This is used for ordering in mappings.
     const int opCmp(ref const MyStruct s)
     {
         if(x != s.x){return x - s.x;}
         if(y != s.y){return y - s.y;}
         if(z != s.z){return z - s.z;}
         return 0;
     }
 }

 MyStruct constructMyStructSequence(ref Node node)
 {
     //node is guaranteed to be sequence.
     //!mystruct [x, y, z]
     return MyStruct(node[0].as!int, node[1].as!int, node[2].as!int);
 }

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

     //Any D:YAML type must have a custom opCmp operator.
     //This is used for ordering in mappings.
     const int opCmp(ref const MyStruct s)
     {
         if(x != s.x){return x - s.x;}
         if(y != s.y){return y - s.y;}
         if(z != s.z){return z - s.z;}
         return 0;
     }
 }

 MyStruct constructMyStructMapping(ref Node node)
 {
     //node is guaranteed to be mapping.
     //!mystruct {"x": x, "y": y, "z": z}
     return MyStruct(node["x"].as!int, node["y"].as!int, node["z"].as!int);
 }

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

YAMLNull constructNull(ref Node node);

Construct a null node.

YAMLMerge constructMerge(ref Node node);

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

bool constructBool(ref Node node);

Construct a boolean node.

long constructLong(ref Node node);

Construct an integer (long) node.

real constructReal(ref Node node);

Construct a floating point (real) node.

ubyte[] constructBinary(ref Node node);

Construct a binary (base64) node.

SysTime constructTimestamp(ref Node node);

Construct a timestamp (SysTime) node.

string constructString(ref Node node);

Construct a string node.

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

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

Pair[] constructOrderedMap(ref Node node);

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

Pair[] constructPairs(ref Node node);

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

Node[] constructSet(ref Node node);

Construct a set node.

Node[] constructSequence(ref Node node);

Construct a sequence (array) node.

Pair[] constructMap(ref Node node);

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