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 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. If style is ScalarStyle.Invalid, the style is chosen automatically.

@property void defaultCollectionStyle(CollectionStyle style);

Set default style for collections. If style is CollectionStyle.Invalid, 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.

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:

representer

Representer function to add.

Examples:

Representing a simple struct:

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

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

     //Any D:YAML type must have a custom opCmp operator.
     //This is used for ordering in mappings.
     override int opCmp(Object o)
     {
         MyClass s = cast(MyClass)o;
         if(s is null){return -1;}
         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;
     }

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

     //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;
     }
 }

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

     //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;
     }
 }

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

     //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;
     }
 }

 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.

Copyright © Ferdinand Majerech 2011. Based on PyYAML by Kirill Simonov. | Page generated by AutoDDoc and Ddoc.