327 lines
14 KiB
HTML
327 lines
14 KiB
HTML
<!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.3 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.3 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.encoding.html">dyaml.encoding</a></li>
|
|
<li><a href="dyaml.exception.html">dyaml.exception</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.std.variant.html">dyaml.std.variant</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">class <a name="ConstructorException"></a><span class="ddoc_psymbol">ConstructorException</span>: dyaml.exception.YAMLException;
|
|
</dt>
|
|
<dd><p>Exception thrown at constructor errors.
|
|
</p>
|
|
<p>Can be thrown by custom constructor functions.</p>
|
|
|
|
<dl><dt class="d_decl">this(string <b>msg</b>, Mark <b>start</b>, Mark <b>end</b>, string <b>file</b> = __FILE__, int <b>line</b> = __LINE__);
|
|
</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>
|
|
<dt class="d_decl">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>
|
|
|
|
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">this(in const(bool) <b>defaultConstructors</b> = true);
|
|
</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>
|
|
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>const(bool) <b>defaultConstructors</b></td>
|
|
<td valign=top>Use constructors for default YAML tags?</td></tr>
|
|
</table></div>
|
|
|
|
</dd>
|
|
<dt class="d_decl">void <a name="addConstructorScalar"></a><span class="ddoc_psymbol">addConstructorScalar</span>(T)(in string <b>tag</b>, T function(Mark, Mark, ref Node) <b>ctor</b>);
|
|
</dt>
|
|
<dd><p>Add a constructor function from scalar.
|
|
</p>
|
|
<p>The function must take two Marks (start and end positions of
|
|
the node in file) and a reference to Node to construct from.
|
|
The node contains a string for scalars, Node[] for sequences and
|
|
Node.Pair[] for mappings.
|
|
The value returned by this function will be stored in the resulting node.
|
|
<br>
|
|
|
|
Only one constructor function can be set for one tag.
|
|
|
|
</p>
|
|
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>tag</td>
|
|
<td valign=top>Tag for the function to handle.</td></tr>
|
|
<tr><td valign=top>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> yaml;
|
|
|
|
<span class="d_keyword">struct</span> MyStruct
|
|
{
|
|
<span class="d_keyword">int</span> x, y, z;
|
|
}
|
|
|
|
MyStruct constructMyStructScalar(Mark start, Mark end, <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_keyword">try</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">catch</span>(Exception e)
|
|
{
|
|
<span class="d_keyword">throw</span> <span class="d_keyword">new</span> ConstructorException(<span class="d_string">"Could not construct MyStruct: "</span> ~ e.msg,
|
|
start, end);
|
|
}
|
|
}
|
|
|
|
<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">void <a name="addConstructorSequence"></a><span class="ddoc_psymbol">addConstructorSequence</span>(T)(in string <b>tag</b>, T function(Mark, Mark, 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> yaml;
|
|
|
|
<span class="d_keyword">struct</span> MyStruct
|
|
{
|
|
<span class="d_keyword">int</span> x, y, z;
|
|
}
|
|
|
|
MyStruct constructMyStructSequence(Mark start, Mark end, <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">try</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">catch</span>(NodeException e)
|
|
{
|
|
<span class="d_keyword">throw</span> <span class="d_keyword">new</span> ConstructorException(<span class="d_string">"Could not construct MyStruct: "</span> ~ e.msg,
|
|
start, end);
|
|
}
|
|
}
|
|
|
|
<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">void <a name="addConstructorMapping"></a><span class="ddoc_psymbol">addConstructorMapping</span>(T)(in string <b>tag</b>, T function(Mark, Mark, 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> yaml;
|
|
|
|
<span class="d_keyword">struct</span> MyStruct
|
|
{
|
|
<span class="d_keyword">int</span> x, y, z;
|
|
}
|
|
|
|
MyStruct constructMyStructMapping(Mark start, Mark end, <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">try</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">catch</span>(NodeException e)
|
|
{
|
|
<span class="d_keyword">throw</span> <span class="d_keyword">new</span> ConstructorException(<span class="d_string">"Could not construct MyStruct: "</span> ~ e.msg,
|
|
start, end);
|
|
}
|
|
}
|
|
|
|
<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">YAMLNull <a name="constructNull"></a><span class="ddoc_psymbol">constructNull</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a <b>null</b> <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">YAMLMerge <a name="constructMerge"></a><span class="ddoc_psymbol">constructMerge</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a merge <b>node</b> - a <b>node</b> that merges another <b>node</b> into a mapping.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">bool <a name="constructBool"></a><span class="ddoc_psymbol">constructBool</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a boolean <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">long <a name="constructLong"></a><span class="ddoc_psymbol">constructLong</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct an integer (long) <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">real <a name="constructReal"></a><span class="ddoc_psymbol">constructReal</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a floating point (real) <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">ubyte[] <a name="constructBinary"></a><span class="ddoc_psymbol">constructBinary</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a binary (base64) <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">SysTime <a name="constructTimestamp"></a><span class="ddoc_psymbol">constructTimestamp</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a timestamp (SysTime) <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">string <a name="constructString"></a><span class="ddoc_psymbol">constructString</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a string <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">Pair[] <a name="getPairs"></a><span class="ddoc_psymbol">getPairs</span>(string <b>type</b>, Mark <b>start</b>, Mark <b>end</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">Pair[] <a name="constructOrderedMap"></a><span class="ddoc_psymbol">constructOrderedMap</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct an ordered map (ordered sequence of key:value pairs without duplicates) <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">Pair[] <a name="constructPairs"></a><span class="ddoc_psymbol">constructPairs</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a pairs (ordered sequence of key: value pairs allowing duplicates) <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">Node[] <a name="constructSet"></a><span class="ddoc_psymbol">constructSet</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a set <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">Node[] <a name="constructSequence"></a><span class="ddoc_psymbol">constructSequence</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct a sequence (array) <b>node</b>.</p>
|
|
|
|
</dd>
|
|
<dt class="d_decl">Pair[] <a name="constructMap"></a><span class="ddoc_psymbol">constructMap</span>(Mark <b>start</b>, Mark <b>end</b>, ref Node <b>node</b>);
|
|
</dt>
|
|
<dd><p>Construct an unordered map (unordered set of key: value pairs without duplicates) <b>node</b>.</p>
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<div id="copyright">
|
|
Copyright © Ferdinand Majerech 2011. Based on <a href="http://www.pyyaml.org">PyYAML</a> by Kirill Simonov. |
|
|
Page generated by Autodoc and <a href="http://www.digitalmars.com/d/2.0/ddoc.html">Ddoc</a>.
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|