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;

Represents YAML nodes of various data types as scalar, sequence and mapping nodes ready for output.

This class is used to add support for dumping of custom data types.
It can also override default node formatting styles 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.
@property void defaultScalarStyle(ScalarStyle style);

Set default style for scalars. Invalid means the style is chosen automatically.

@property void defaultCollectionStyle(CollectionStyle style);

Set default style for collections. Invalid means the style is chosen automatically.

void addRepresenter(T)(Node function(ref Node, Representer) representer);

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

The representer function takes references 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 the 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.as!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.yaml");
     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.as!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.as!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.yaml");
     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, ScalarStyle style = (ScalarStyle).Invalid);

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.
ScalarStyle style Style of the scalar. If invalid, default style will be used. If the node was loaded before, previous style will always be used.
Returns:
The represented node.

Example:

 struct MyStruct
 {
     int x, y, z;
 }

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

 }

Node representSequence(in string tag, Node[] sequence, CollectionStyle style = (CollectionStyle).Invalid);

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.
CollectionStyle style Style of the sequence. If invalid, default style will be used. If the node was loaded before, previous style will always be used.
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.as!MyStruct;
     auto nodes = [Node(value.x), Node(value.y), Node(value.z)];
     //use flow style
     return representer.representSequence("!mystruct.tag", nodes,
                                          CollectionStyle.Flow);
 }

Node representMapping(in string tag, Pair[] pairs, CollectionStyle style = (CollectionStyle).Invalid);

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.
CollectionStyle style Style of the mapping. If invalid, default style will be used. If the node was loaded before, previous style will always be used.
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.as!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.