# dyaml.representer - D:YAML 0.5 API documentation

D:YAML 0.5 API documentation

# 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.

  pure @safe this(const Flag!"useDefaultRepresenters" useDefaultRepresenters = Yes.useDefaultRepresenters);

    Construct a Representer.

    Parameters:

    Flag!"useDefaultRepresenters" useDefaultRepresenters | Use default representer functions for default YAML types? This can be disabled to use custom representer functions for default types.

  pure nothrow @property @safe void defaultScalarStyle(ScalarStyle style);

    Set default style for scalars. If style is ScalarStyle.Invalid, the style is chosen automatically.

  pure nothrow @property @safe void defaultCollectionStyle(CollectionStyle style);

    Set default style for collections. If style is CollectionStyle.Invalid, the style is chosen automatically.

  pure @trusted 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:

    Node function(ref Node, Representer) representer | Representer function to add.

    Examples:
    Representing a simple struct:

        import std.string;

        import dyaml.all;

        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("%s:%s:%s", 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 dyaml.all;

        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(%s, %s, %s)", 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("%s:%s:%s", 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)));
        }

  @safe 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("%s:%s:%s", value.x, value.y, value.z);
            return representer.representScalar("!mystruct.tag", scalar);
        }

  @trusted 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);
        }

  @trusted Node representMapping(string tag, Node.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.
    Node.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);
        }

@safe Node representNull(ref Node node, Representer representer);

  Represent a null node as a null YAML value.

@safe Node representString(ref Node node, Representer representer);

  Represent a string node as a string scalar.

@system Node representBytes(ref Node node, Representer representer);

  Represent a bytes node as a binary scalar.

@safe Node representBool(ref Node node, Representer representer);

  Represent a bool node as a bool scalar.

@system Node representLong(ref Node node, Representer representer);

  Represent a long node as an integer scalar.

@system Node representReal(ref Node node, Representer representer);

  Represent a real node as a floating point scalar.

@system Node representSysTime(ref Node node, Representer representer);

  Represent a SysTime node as a timestamp.

@safe Node representNodes(ref Node node, Representer representer);

  Represent a sequence node as sequence/set.

@system Node representPairs(ref Node node, Representer representer);

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

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