dyaml.representer

YAML node representer. Prepares YAML nodes for output. A tutorial can be found here.

Code based on PyYAML.

class RepresenterException: dyaml.exception.YAMLException;

Exception thrown on Representer errors.

class Representer;

Used to represent YAML nodes various data types into scalar, sequence and mapping nodes ready for output.

this(bool useDefaultRepresenters = true);

Construct a Representer.

Parameters:
bool useDefaultRepresenters Use default representer functions for default YAML types? This can be disabled to use custom representer functions for default types.
void addRepresenter(T)(Node function(ref Node, Representer) representer);

Add a function to represent nodes with a specific data type.

The representer function takes a reference to a Node storing the data type and to the Representer. It returns the represented node and may throw a RepresenterException. See the example for more information.
Only one function may be specified for one data type. Default data types already have representer functions unless disabled in these Representer constructor.

Parameters:
representer Representer function to add.
Examples:
Representing a simple struct: 
 import std.string;

 import yaml;

 struct MyStruct
 {
     int x, y, z;
 }

 Node representMyStruct(ref Node node, Representer representer)
 {
     //The node is guaranteed to be MyStruct as we add representer for MyStruct.
     auto value = node.get!MyStruct;
     //Using custom scalar format, x:y:z.
     auto scalar = format(value.x, ":", value.y, ":", value.z);
     //Representing as a scalar, with custom tag to specify this data type.
     return representer.representScalar("!mystruct.tag", scalar);
 }

 void main()
 {
     auto dumper = Dumper("file.txt");
     auto representer = new Representer;
     representer.addRepresenter!MyStruct(&representMyStruct);
     dumper.representer = representer;
     dumper.dump(Node(MyStruct(1,2,3)));
 }
Representing a class: 
 import std.string;

 import yaml;

 class MyClass
 {
     int x, y, z;

     this(int x, int y, int z)
     {
         this.x = x;
         this.y = y;
         this.z = z;
     }

     ///We need custom opEquals for node equality, as default opEquals compares references.
     override bool opEquals(Object rhs)
     {
         if(typeid(rhs) != typeid(MyClass)){return false;}
         auto t = cast(MyClass)rhs;
         return x == t.x && y == t.y && z == t.z;
     }

     ///Useful for Node.get!string .
     override string toString()
     {
         return format("MyClass("), x, ", ", y, ", ", z, "");
     }
 }

 //Same as representMyStruct.
 Node representMyClass(ref Node node, Representer representer)
 {
     //The node is guaranteed to be MyClass as we add representer for MyClass.
     auto value = node.get!MyClass;
     //Using custom scalar format, x:y:z.
     auto scalar = format(value.x, ":", value.y, ":", value.z);
     //Representing as a scalar, with custom tag to specify this data type.
     return representer.representScalar("!myclass.tag", scalar);
 }

 void main()
 {
     auto dumper = Dumper("file.txt");
     auto representer = new Representer;
     representer.addRepresenter!MyClass(&representMyClass);
     dumper.representer = representer;
     dumper.dump(Node(new MyClass(1,2,3)));
 }
Node representScalar(in string tag, string scalar);

Represent a scalar with specified tag.

This is used by representer functions that produce scalars.

Parameters:
string tag Tag of the scalar.
string scalar Scalar value.
Returns:
The represented node.

Example:

 struct MyStruct
 {
     int x, y, z;
 }

 Node representMyStruct(ref Node node, Representer representer)
 {
     auto value = node.get!MyStruct;
     auto scalar = format(value.x, ":", value.y, ":", value.z);
     return representer.representScalar("!mystruct.tag", scalar);
 }

Node representSequence(in string tag, Node[] sequence);

Represent a sequence with specified tag, representing children first.

This is used by representer functions that produce sequences.

Parameters:
string tag Tag of the sequence.
Node[] sequence Sequence of nodes.
Returns:
The represented node.
Throws:
RepresenterException if a child could not be represented.

Example:

 struct MyStruct
 {
     int x, y, z;
 }

 Node representMyStruct(ref Node node, Representer representer)
 {
     auto value = node.get!MyStruct;
     auto nodes = [Node(value.x), Node(value.y), Node(value.z)];
     return representer.representSequence("!mystruct.tag", nodes);
 }

Node representMapping(in string tag, Pair[] pairs);

Represent a mapping with specified tag, representing children first.

This is used by representer functions that produce mappings.

Parameters:
string tag Tag of the mapping.
Pair[] pairs Key-value pairs of the mapping.
Returns:
The represented node.
Throws:
RepresenterException if a child could not be represented.

Example:

 struct MyStruct
 {
     int x, y, z;
 }

 Node representMyStruct(ref Node node, Representer representer)
 {
     auto value = node.get!MyStruct;
     auto pairs = [Node.Pair("x", value.x),
                   Node.Pair("y", value.y),
                   Node.Pair("z", value.z)];
     return representer.representMapping("!mystruct.tag", pairs);
 }

Node representNull(ref Node node, Representer representer);

Represent a null node as a null YAML value.

Node representString(ref Node node, Representer representer);

Represent a string node as a string scalar.

Node representBytes(ref Node node, Representer representer);

Represent a bytes node as a binary scalar.

Node representBool(ref Node node, Representer representer);

Represent a bool node as a bool scalar.

Node representLong(ref Node node, Representer representer);

Represent a long node as an integer scalar.

Node representReal(ref Node node, Representer representer);

Represent a real node as a floating point scalar.

Node representSysTime(ref Node node, Representer representer);

Represent a SysTime node as a timestamp.

Node representNodes(ref Node node, Representer representer);

Represent a sequence node as sequence/set.

Node representPairs(ref Node node, Representer representer);

Represent a mapping node as map/ordered map/pairs.