2011-08-16 12:53:13 +00:00
< !DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
< html lang = 'en' >
< head >
< meta http-equiv = "content-type" content = "text/html; charset=utf-8" >
2012-01-23 17:40:05 +00:00
< title > dyaml.constructor - D:YAML 0.4 API documentation< / title >
2011-08-16 12:53:13 +00:00
< link rel = "stylesheet" type = "text/css" href = "css/style.css" >
< / head >
< body > < div id = "top" >
< div id = "header" >
2012-01-23 17:40:05 +00:00
< img id = "logo" alt = "D:YAML logo" src = "images/logo.png" > < a id = "main-heading" href = "index.html" > D:YAML 0.4 API documentation< / a >
2011-08-16 12:53:13 +00:00
< / div >
< / div >
< div id = "navigation" >
< div class = "navblock" >
< div id = "toctop" >
< ul > < li > < a href = "../index.html" > Documentation home< / a > < / li >
< / ul >
< / div >
< / div >
< div class = "navblock" >
< ul > < li > < a href = "index.html" > Main page< / a > < / li >
< li > < a href = "dyaml.constructor.html" > dyaml.constructor< / a > < / li >
2011-10-14 08:34:53 +00:00
< li > < a href = "dyaml.dumper.html" > dyaml.dumper< / a > < / li >
< li > < a href = "dyaml.encoding.html" > dyaml.encoding< / a > < / li >
2011-08-16 12:53:13 +00:00
< li > < a href = "dyaml.exception.html" > dyaml.exception< / a > < / li >
2011-10-14 08:34:53 +00:00
< li > < a href = "dyaml.linebreak.html" > dyaml.linebreak< / a > < / li >
2011-08-16 12:53:13 +00:00
< li > < a href = "dyaml.loader.html" > dyaml.loader< / a > < / li >
< li > < a href = "dyaml.node.html" > dyaml.node< / a > < / li >
2011-10-14 08:34:53 +00:00
< li > < a href = "dyaml.representer.html" > dyaml.representer< / a > < / li >
2011-08-16 12:53:13 +00:00
< li > < a href = "dyaml.resolver.html" > dyaml.resolver< / a > < / li >
2011-10-29 18:43:30 +00:00
< li > < a href = "dyaml.style.html" > dyaml.style< / a > < / li >
2011-08-16 12:53:13 +00:00
< / ul >
< / div >
< / div >
< div id = "content" >
< h1 > dyaml.constructor< / h1 >
<!-- Generated by Ddoc from dyaml/constructor.d -->
< p > 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 < a href = "../tutorials/custom_types.html" > here< / a > .< / p >
2013-12-17 14:19:01 +00:00
< dl > < dt class = "d_decl" > < a name = "ConstructorException" > < / a > class < a name = "ConstructorException" > < / a > < span class = "ddoc_psymbol" > ConstructorException< / span > : dyaml.exception.YAMLException;
2011-08-16 12:53:13 +00:00
< / dt >
< dd > < p > Exception thrown at constructor errors.
< / p >
< p > Can be thrown by custom constructor functions.< / p >
2013-12-17 14:19:01 +00:00
< dl > < dt class = "d_decl" > < a name = "ConstructorException.this" > < / a > @safe this(string < b > msg< / b > , Mark < b > start< / b > , Mark < b > end< / b > , string < b > file< / b > = __FILE__, int < b > line< / b > = __LINE__);
2011-08-16 12:53:13 +00:00
< / dt >
< dd > < p > Construct a ConstructorException.
< / p >
< b > Parameters:< / b > < div class = "pbr" > < table class = parms > < tr > < td valign = top > string < b > msg< / b > < / td >
< td valign = top > Error message.< / td > < / tr >
< tr > < td valign = top > Mark < b > start< / b > < / td >
< td valign = top > Start position of the error context.< / td > < / tr >
< tr > < td valign = top > Mark < b > end< / b > < / td >
< td valign = top > End position of the error context.< / td > < / tr >
< / table > < / div >
< / dd >
< / dl >
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "Constructor" > < / a > class < a name = "Constructor" > < / a > < span class = "ddoc_psymbol" > Constructor< / span > ;
2011-08-16 12:53:13 +00:00
< / dt >
< dd > < p > Constructs YAML values.
< / p >
< p > Each YAML scalar, sequence or mapping has a tag specifying its data type.
< a name = "Constructor" > < / a > < span class = "ddoc_psymbol" > Constructor< / span > uses user-specifyable functions to create a node of desired
data type from a scalar, sequence or mapping.
2012-01-23 14:57:26 +00:00
< br >
2011-08-16 12:53:13 +00:00
< br >
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.
< br >
If a tag is detected with no known constructor function, it is considered an error.< / p >
2013-12-17 14:19:01 +00:00
< dl > < dt class = "d_decl" > < a name = "Constructor.this" > < / a > nothrow @safe this(const Flag!"useDefaultConstructors" < b > defaultConstructors< / b > = Yes.useDefaultConstructors);
2011-08-16 12:53:13 +00:00
< / dt >
< dd > < p > Construct a Constructor.
< / p >
< p > If you don't want to support default YAML tags/data types, you can use
< b > defaultConstructors< / b > to disable constructor functions for these.
< / p >
2013-12-17 14:19:01 +00:00
< b > Parameters:< / b > < div class = "pbr" > < table class = parms > < tr > < td valign = top > Flag!"useDefaultConstructors" < b > defaultConstructors< / b > < / td >
2011-08-16 12:53:13 +00:00
< td valign = top > Use constructors for default YAML tags?< / td > < / tr >
< / table > < / div >
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "Constructor.addConstructorScalar" > < / a > nothrow @safe void < a name = "addConstructorScalar" > < / a > < span class = "ddoc_psymbol" > addConstructorScalar< / span > (T)(const string < b > tag< / b > , T function(ref Node) < b > ctor< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2011-10-17 10:53:38 +00:00
< dd > < p > Add a constructor function from scalar.
2011-08-16 12:53:13 +00:00
< / p >
2013-12-17 14:19:01 +00:00
< p > The function must take a reference to < span class = "d_inlinecode" > Node< / span > to construct from.
The node contains a string for scalars, for sequences and
for mappings.
2011-11-17 22:53:24 +00:00
< br >
Any exception thrown by this function will be caught by D:YAML and
2013-12-17 14:19:01 +00:00
its message will be added to a that will also tell
the user which type failed to construct, and position in the file.
2012-01-23 14:57:26 +00:00
< br >
2011-11-17 22:53:24 +00:00
< br >
2011-10-17 10:53:38 +00:00
The value returned by this function will be stored in the resulting node.
2011-10-14 08:34:53 +00:00
< br >
Only one constructor function can be set for one tag.
2012-01-23 14:57:26 +00:00
< br >
< br >
Structs and classes must implement the < span class = "d_inlinecode" > opCmp()< / span > operator for D:YAML
support. The signature of the operator that must be implemented
is < span class = "d_inlinecode" > const int opCmp(ref const MyStruct s)< / span > for structs where
< i > MyStruct< / i > is the struct type, and < span class = "d_inlinecode" > int opCmp(Object o)< / span > for
classes. Note that the class < span class = "d_inlinecode" > opCmp()< / span > should not alter the compared
values - it is not const for compatibility reasons.
2011-08-16 12:53:13 +00:00
< / p >
2013-12-17 14:19:01 +00:00
< b > Parameters:< / b > < div class = "pbr" > < table class = parms > < tr > < td valign = top > string tag< / td >
2011-08-16 12:53:13 +00:00
< td valign = top > Tag for the function to handle.< / td > < / tr >
2013-12-17 14:19:01 +00:00
< tr > < td valign = top > T function(ref Node) ctor< / td >
2011-08-16 12:53:13 +00:00
< td valign = top > Constructor function.< / td > < / tr >
< / table > < / div >
2011-10-18 19:40:37 +00:00
< p > < b > Example:< / b > < br >
2013-12-17 14:19:01 +00:00
< pre class = "d_code" > < span class = "d_keyword" > import< / span > std.string;
< span class = "d_keyword" > import< / span > dyaml.all;
< span class = "d_keyword" > struct< / span > MyStruct
{
< span class = "d_keyword" > int< / span > x, y, z;
< span class = "d_comment" > //Any D:YAML type must have a custom opCmp operator.
< / span > < span class = "d_comment" > //This is used for ordering in mappings.
< / span > < span class = "d_keyword" > const< / span > < span class = "d_keyword" > int< / span > opCmp(< span class = "d_keyword" > ref< / span > < span class = "d_keyword" > const< / span > MyStruct s)
{
< span class = "d_keyword" > if< / span > (x != s.x){< span class = "d_keyword" > return< / span > x - s.x;}
< span class = "d_keyword" > if< / span > (y != s.y){< span class = "d_keyword" > return< / span > y - s.y;}
< span class = "d_keyword" > if< / span > (z != s.z){< span class = "d_keyword" > return< / span > z - s.z;}
< span class = "d_keyword" > return< / span > 0;
}
}
MyStruct constructMyStructScalar(< span class = "d_keyword" > ref< / span > Node node)
{
< span class = "d_comment" > //Guaranteed to be string as we construct from scalar.
< / span > < span class = "d_comment" > //!mystruct x:y:z
< / span > < span class = "d_keyword" > auto< / span > parts = node.as!string().split(< span class = "d_string" > ":"< / span > );
< span class = "d_comment" > //If this throws, the D:YAML will handle it and throw a YAMLException.
< / span > < span class = "d_keyword" > return< / span > MyStruct(to!< span class = "d_keyword" > int< / span > (parts[0]), to!< span class = "d_keyword" > int< / span > (parts[1]), to!< span class = "d_keyword" > int< / span > (parts[2]));
}
< span class = "d_keyword" > void< / span > main()
{
< span class = "d_keyword" > auto< / span > loader = Loader(< span class = "d_string" > "file.yaml"< / span > );
< span class = "d_keyword" > auto< / span > constructor = < span class = "d_keyword" > new< / span > Constructor;
constructor.< span class = "d_psymbol" > addConstructorScalar< / span > (< span class = "d_string" > "!mystruct"< / span > , & constructMyStructScalar);
loader.constructor = constructor;
Node node = loader.load();
}
2011-10-18 19:40:37 +00:00
< / pre >
< / p >
2011-08-16 12:53:13 +00:00
2011-10-17 10:53:38 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "Constructor.addConstructorSequence" > < / a > nothrow @safe void < a name = "addConstructorSequence" > < / a > < span class = "ddoc_psymbol" > addConstructorSequence< / span > (T)(const string < b > tag< / b > , T function(ref Node) < b > ctor< / b > );
2011-10-17 10:53:38 +00:00
< / dt >
< dd > < p > Add a constructor function from sequence.
< / p >
2011-10-18 19:40:37 +00:00
< b > See Also:< / b > < div class = "pbr" > addConstructorScalar
< / div >
< p > < b > Example:< / b > < br >
2013-12-17 14:19:01 +00:00
< pre class = "d_code" > < span class = "d_keyword" > import< / span > std.string;
< span class = "d_keyword" > import< / span > dyaml.all;
< span class = "d_keyword" > struct< / span > MyStruct
{
< span class = "d_keyword" > int< / span > x, y, z;
< span class = "d_comment" > //Any D:YAML type must have a custom opCmp operator.
< / span > < span class = "d_comment" > //This is used for ordering in mappings.
< / span > < span class = "d_keyword" > const< / span > < span class = "d_keyword" > int< / span > opCmp(< span class = "d_keyword" > ref< / span > < span class = "d_keyword" > const< / span > MyStruct s)
{
< span class = "d_keyword" > if< / span > (x != s.x){< span class = "d_keyword" > return< / span > x - s.x;}
< span class = "d_keyword" > if< / span > (y != s.y){< span class = "d_keyword" > return< / span > y - s.y;}
< span class = "d_keyword" > if< / span > (z != s.z){< span class = "d_keyword" > return< / span > z - s.z;}
< span class = "d_keyword" > return< / span > 0;
}
}
MyStruct constructMyStructSequence(< span class = "d_keyword" > ref< / span > Node node)
{
< span class = "d_comment" > //node is guaranteed to be sequence.
< / span > < span class = "d_comment" > //!mystruct [x, y, z]
< / span > < span class = "d_keyword" > return< / span > MyStruct(node[0].as!< span class = "d_keyword" > int< / span > , node[1].as!< span class = "d_keyword" > int< / span > , node[2].as!< span class = "d_keyword" > int< / span > );
}
< span class = "d_keyword" > void< / span > main()
{
< span class = "d_keyword" > auto< / span > loader = Loader(< span class = "d_string" > "file.yaml"< / span > );
< span class = "d_keyword" > auto< / span > constructor = < span class = "d_keyword" > new< / span > Constructor;
constructor.< span class = "d_psymbol" > addConstructorSequence< / span > (< span class = "d_string" > "!mystruct"< / span > , & constructMyStructSequence);
loader.constructor = constructor;
Node node = loader.load();
}
2011-10-18 19:40:37 +00:00
< / pre >
< / p >
2011-10-17 10:53:38 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "Constructor.addConstructorMapping" > < / a > nothrow @safe void < a name = "addConstructorMapping" > < / a > < span class = "ddoc_psymbol" > addConstructorMapping< / span > (T)(const string < b > tag< / b > , T function(ref Node) < b > ctor< / b > );
2011-10-17 10:53:38 +00:00
< / dt >
< dd > < p > Add a constructor function from a mapping.
< / p >
2011-10-18 19:40:37 +00:00
< b > See Also:< / b > < div class = "pbr" > addConstructorScalar
< / div >
< p > < b > Example:< / b > < br >
2013-12-17 14:19:01 +00:00
< pre class = "d_code" > < span class = "d_keyword" > import< / span > std.string;
< span class = "d_keyword" > import< / span > dyaml.all;
< span class = "d_keyword" > struct< / span > MyStruct
{
< span class = "d_keyword" > int< / span > x, y, z;
< span class = "d_comment" > //Any D:YAML type must have a custom opCmp operator.
< / span > < span class = "d_comment" > //This is used for ordering in mappings.
< / span > < span class = "d_keyword" > const< / span > < span class = "d_keyword" > int< / span > opCmp(< span class = "d_keyword" > ref< / span > < span class = "d_keyword" > const< / span > MyStruct s)
{
< span class = "d_keyword" > if< / span > (x != s.x){< span class = "d_keyword" > return< / span > x - s.x;}
< span class = "d_keyword" > if< / span > (y != s.y){< span class = "d_keyword" > return< / span > y - s.y;}
< span class = "d_keyword" > if< / span > (z != s.z){< span class = "d_keyword" > return< / span > z - s.z;}
< span class = "d_keyword" > return< / span > 0;
}
}
MyStruct constructMyStructMapping(< span class = "d_keyword" > ref< / span > Node node)
{
< span class = "d_comment" > //node is guaranteed to be mapping.
< / span > < span class = "d_comment" > //!mystruct {"x": x, "y": y, "z": z}
< / span > < span class = "d_keyword" > return< / span > MyStruct(node[< span class = "d_string" > "x"< / span > ].as!< span class = "d_keyword" > int< / span > , node[< span class = "d_string" > "y"< / span > ].as!< span class = "d_keyword" > int< / span > , node[< span class = "d_string" > "z"< / span > ].as!< span class = "d_keyword" > int< / span > );
}
< span class = "d_keyword" > void< / span > main()
{
< span class = "d_keyword" > auto< / span > loader = Loader(< span class = "d_string" > "file.yaml"< / span > );
< span class = "d_keyword" > auto< / span > constructor = < span class = "d_keyword" > new< / span > Constructor;
constructor.< span class = "d_psymbol" > addConstructorMapping< / span > (< span class = "d_string" > "!mystruct"< / span > , & constructMyStructMapping);
loader.constructor = constructor;
Node node = loader.load();
}
2011-10-18 19:40:37 +00:00
< / pre >
< / p >
2011-10-17 10:53:38 +00:00
2011-08-16 12:53:13 +00:00
< / dd >
< / dl >
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructNull" > < / a > YAMLNull < a name = "constructNull" > < / a > < span class = "ddoc_psymbol" > constructNull< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a null node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructMerge" > < / a > YAMLMerge < a name = "constructMerge" > < / a > < span class = "ddoc_psymbol" > constructMerge< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a merge node - a node that merges another node into a mapping.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructBool" > < / a > bool < a name = "constructBool" > < / a > < span class = "ddoc_psymbol" > constructBool< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a boolean node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructLong" > < / a > long < a name = "constructLong" > < / a > < span class = "ddoc_psymbol" > constructLong< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct an integer (long) node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructReal" > < / a > real < a name = "constructReal" > < / a > < span class = "ddoc_psymbol" > constructReal< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a floating point (real) node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructBinary" > < / a > ubyte[] < a name = "constructBinary" > < / a > < span class = "ddoc_psymbol" > constructBinary< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a binary (base64) node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructTimestamp" > < / a > SysTime < a name = "constructTimestamp" > < / a > < span class = "ddoc_psymbol" > constructTimestamp< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a timestamp (SysTime) node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructString" > < / a > string < a name = "constructString" > < / a > < span class = "ddoc_psymbol" > constructString< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a string node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "getPairs" > < / a > Node.Pair[] < a name = "getPairs" > < / a > < span class = "ddoc_psymbol" > getPairs< / span > (string < b > type< / b > , Node[] < b > nodes< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
< dd > < p > Convert a sequence of single-element mappings into a sequence of pairs.< / p >
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructOrderedMap" > < / a > Node.Pair[] < a name = "constructOrderedMap" > < / a > < span class = "ddoc_psymbol" > constructOrderedMap< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct an ordered map (ordered sequence of key:value pairs without duplicates) node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructPairs" > < / a > Node.Pair[] < a name = "constructPairs" > < / a > < span class = "ddoc_psymbol" > constructPairs< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a pairs (ordered sequence of key: value pairs allowing duplicates) node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructSet" > < / a > Node[] < a name = "constructSet" > < / a > < span class = "ddoc_psymbol" > constructSet< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a set node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructSequence" > < / a > Node[] < a name = "constructSequence" > < / a > < span class = "ddoc_psymbol" > constructSequence< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct a sequence (array) node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
2013-12-17 14:19:01 +00:00
< dt class = "d_decl" > < a name = "constructMap" > < / a > Node.Pair[] < a name = "constructMap" > < / a > < span class = "ddoc_psymbol" > constructMap< / span > (ref Node < b > node< / b > );
2011-08-16 12:53:13 +00:00
< / dt >
2012-01-23 14:57:26 +00:00
< dd > < p > Construct an unordered map (unordered set of key:value pairs without duplicates) node.< / p >
2011-08-16 12:53:13 +00:00
< / dd >
< / dl >
< / div >
< div id = "copyright" >
Copyright © Ferdinand Majerech 2011. Based on < a href = "http://www.pyyaml.org" > PyYAML< / a > by Kirill Simonov. |
2012-01-23 14:57:26 +00:00
Page generated by AutoDDoc and < a href = "http://www.digitalmars.com/d/2.0/ddoc.html" > Ddoc< / a > .
2011-08-16 12:53:13 +00:00
< / div >
< / body >
< / html >
