<!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" > <title>dyaml.constructor - D:YAML 0.5 API documentation</title> <link rel="stylesheet" type="text/css" href="css/style.css"> </head> <body><div id="top"> <div id="header"> <img id="logo" alt="D:YAML logo" src="images/logo.png"><a id="main-heading" href="index.html">D:YAML 0.5 API documentation</a> </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> <li><a href="dyaml.dumper.html">dyaml.dumper</a></li> <li><a href="dyaml.exception.html">dyaml.exception</a></li> <li><a href="dyaml.hacks.html">dyaml.hacks</a></li> <li><a href="dyaml.linebreak.html">dyaml.linebreak</a></li> <li><a href="dyaml.loader.html">dyaml.loader</a></li> <li><a href="dyaml.node.html">dyaml.node</a></li> <li><a href="dyaml.representer.html">dyaml.representer</a></li> <li><a href="dyaml.resolver.html">dyaml.resolver</a></li> <li><a href="dyaml.style.html">dyaml.style</a></li> </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> <dl><dt class="d_decl"><a name="Constructor"></a>class <a name="Constructor"></a><span class="ddoc_psymbol">Constructor</span>; </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. <br> <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> <dl><dt class="d_decl"><a name="Constructor.this"></a>nothrow @safe this(const Flag!"useDefaultConstructors" <b>defaultConstructors</b> = Yes.useDefaultConstructors); </dt> <dd><p>Construct a Constructor. </p> <p>If you don't want to support default YAML tags/data types, you can use <br> <b>defaultConstructors</b> to disable constructor functions for these. <br> <br> </p> <b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>Flag!"useDefaultConstructors" <b>defaultConstructors</b></td> <td valign=top>Use constructors for default YAML tags?</td></tr> </table></div> </dd> <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>); </dt> <dd><p>Add a constructor function from scalar. </p> <p>The function must take a reference to <span class="d_inlinecode">Node</span> to construct from. The node contains a string for scalars, <span class="d_inlinecode">Node[]</span> for sequences and <span class="d_inlinecode">Node.Pair[]</span> for mappings. <br> Any exception thrown by this function will be caught by D:YAML and its message will be added to a <span class="d_inlinecode">YAMLException</span> that will also tell the user which type failed to construct, and position in the file. <br> <br> The value returned by this function will be stored in the resulting node. <br> Only one constructor function can be set for one tag. <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. </p> <b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string tag</td> <td valign=top>Tag for the function to handle.</td></tr> <tr><td valign=top>T function(ref Node) ctor</td> <td valign=top>Constructor function.</td></tr> </table></div> <p><b>Example:</b><br> <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(); } </pre> </p> </dd> <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>); </dt> <dd><p>Add a constructor function from sequence. </p> <b>See Also:</b><div class="pbr">addConstructorScalar </div> <p><b>Example:</b><br> <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(); } </pre> </p> </dd> <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>); </dt> <dd><p>Add a constructor function from a mapping. </p> <b>See Also:</b><div class="pbr">addConstructorScalar </div> <p><b>Example:</b><br> <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(); } </pre> </p> </dd> </dl> </dd> <dt class="d_decl"><a name="constructNull"></a>YAMLNull <a name="constructNull"></a><span class="ddoc_psymbol">constructNull</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a null node.</p> </dd> <dt class="d_decl"><a name="constructMerge"></a>YAMLMerge <a name="constructMerge"></a><span class="ddoc_psymbol">constructMerge</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a merge node - a node that merges another node into a mapping.</p> </dd> <dt class="d_decl"><a name="constructBool"></a>bool <a name="constructBool"></a><span class="ddoc_psymbol">constructBool</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a boolean node.</p> </dd> <dt class="d_decl"><a name="constructLong"></a>long <a name="constructLong"></a><span class="ddoc_psymbol">constructLong</span>(ref Node <b>node</b>); </dt> <dd><p>Construct an integer (long) node.</p> </dd> <dt class="d_decl"><a name="constructReal"></a>real <a name="constructReal"></a><span class="ddoc_psymbol">constructReal</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a floating point (real) node.</p> </dd> <dt class="d_decl"><a name="constructBinary"></a>ubyte[] <a name="constructBinary"></a><span class="ddoc_psymbol">constructBinary</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a binary (base64) node.</p> </dd> <dt class="d_decl"><a name="constructTimestamp"></a>SysTime <a name="constructTimestamp"></a><span class="ddoc_psymbol">constructTimestamp</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a timestamp (SysTime) node.</p> </dd> <dt class="d_decl"><a name="constructString"></a>string <a name="constructString"></a><span class="ddoc_psymbol">constructString</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a string node.</p> </dd> <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>); </dt> <dd><p>Convert a sequence of single-element mappings into a sequence of pairs.</p> </dd> <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>); </dt> <dd><p>Construct an ordered map (ordered sequence of key:value pairs without duplicates) node.</p> </dd> <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>); </dt> <dd><p>Construct a pairs (ordered sequence of key: value pairs allowing duplicates) node.</p> </dd> <dt class="d_decl"><a name="constructSet"></a>Node[] <a name="constructSet"></a><span class="ddoc_psymbol">constructSet</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a set node.</p> </dd> <dt class="d_decl"><a name="constructSequence"></a>Node[] <a name="constructSequence"></a><span class="ddoc_psymbol">constructSequence</span>(ref Node <b>node</b>); </dt> <dd><p>Construct a sequence (array) node.</p> </dd> <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>); </dt> <dd><p>Construct an unordered map (unordered set of key:value pairs without duplicates) node.</p> </dd> </dl> </div> <div id="copyright"> Copyright © Ferdinand Majerech 2011-2014. Based on <a href="http://www.pyyaml.org">PyYAML</a> by Kirill Simonov. | Page generated by AutoDDoc and <a href="http://www.digitalmars.com/d/2.0/ddoc.html">Ddoc</a>. </div> </body> </html>