debian-packages/dyaml
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
dyaml/doc/html/api/dyaml.representer.html

328 lines
14 KiB
HTML
Raw Normal View History

Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +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" >
Bumped version strings to 0.3 so it won't get forgotten later.
2011-10-18 19:46:05 +00:00
<title>dyaml.representer - D:YAML 0.3 API documentation</title>
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
<link rel="stylesheet" type="text/css" href="css/style.css">
</head>
<body><div id="top">
<div id="header">
Bumped version strings to 0.3 so it won't get forgotten later.
2011-10-18 19:46:05 +00:00
<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>
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +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>
<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>
</ul>
</div>
</div>
<div id="content">
<h1>dyaml.representer</h1>
<!-- Generated by Ddoc from dyaml/representer.d -->
Fixed a bug which prevented dumping to file. Updated tutorials and example with new information.
2011-10-15 14:31:23 +00:00
<p>YAML node representer. Prepares YAML nodes for output. A tutorial can be
found <a href="../tutorials/custom_types.html">here</a>.
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
</p>
<p>Code based on <a href="http://www.pyyaml.org">PyYAML</a>.</p>
<dl><dt class="d_decl">class <a name="RepresenterException"></a><span class="ddoc_psymbol">RepresenterException</span>: dyaml.exception.YAMLException;
</dt>
<dd><p>Exception thrown on Representer errors.</p>
</dd>
<dt class="d_decl">class <a name="Representer"></a><span class="ddoc_psymbol">Representer</span>;
</dt>
<dd><p>Used to represent YAML nodes various data types into scalar, sequence and mapping nodes ready for output.</p>
<dl><dt class="d_decl">this(bool <b>useDefaultRepresenters</b> = true);
</dt>
<dd><p>Construct a Representer.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>bool <b>useDefaultRepresenters</b></td>
<td valign=top>Use default representer functions
for default YAML types? This can be
disabled to use custom representer
functions for default types.</td></tr>
</table></div>
</dd>
<dt class="d_decl">void <a name="addRepresenter"></a><span class="ddoc_psymbol">addRepresenter</span>(T)(Node function(ref Node, Representer) <b>representer</b>);
</dt>
<dd><p>Add a function to represent nodes with a specific data type.
</p>
Cleaned up exceptions and their messages. Some minor dog fixes.
2011-10-18 14:12:22 +00:00
<p>The representer function takes references to a Node storing the data
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
type and to the Representer. It returns the represented node and may
throw a RepresenterException. See the example for more information.
<br>
Only one function may be specified for one data type. Default data
Cleaned up exceptions and their messages. Some minor dog fixes.
2011-10-18 14:12:22 +00:00
types already have representer functions unless disabled in the
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
Representer constructor.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>representer</td>
<td valign=top>Representer function to add.</td></tr>
</table></div>
<b>Examples:</b><div class="pbr">Representing a simple struct:
<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;
}
Node representMyStruct(<span class="d_keyword">ref</span> Node node, Representer representer)
{
<span class="d_comment">//The node is guaranteed to be MyStruct as we add representer for MyStruct.
Added a shortcut alias called "as" for Node.get(), and replaced get() with as() all over the code, tutorials, examples and docs. Fixed a bug in YAML benchmark makefile. Fixed a bug in autoddoc configuration.
2011-10-22 15:06:32 +00:00
</span> <span class="d_keyword">auto</span> value = node.as!MyStruct;
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
<span class="d_comment">//Using custom scalar format, x:y:z.
</span> <span class="d_keyword">auto</span> scalar = format(value.x, <span class="d_string">":"</span>, value.y, <span class="d_string">":"</span>, value.z);
<span class="d_comment">//Representing as a scalar, with custom tag to specify this data type.
</span> <span class="d_keyword">return</span> representer.representScalar(<span class="d_string">"!mystruct.tag"</span>, scalar);
}
<span class="d_keyword">void</span> main()
{
Updated Constructor API documentation with examples.
2011-10-18 19:40:37 +00:00
<span class="d_keyword">auto</span> dumper = Dumper(<span class="d_string">"file.yaml"</span>);
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
<span class="d_keyword">auto</span> representer = <span class="d_keyword">new</span> Representer;
representer.<span class="d_psymbol">addRepresenter</span>!MyStruct(&amp;representMyStruct);
dumper.representer = representer;
dumper.dump(Node(MyStruct(1,2,3)));
}
</pre>
Representing a class:
<pre class="d_code"> <span class="d_keyword">import</span> std.string;
<span class="d_keyword">import</span> yaml;
<span class="d_keyword">class</span> MyClass
{
<span class="d_keyword">int</span> x, y, z;
<span class="d_keyword">this</span>(<span class="d_keyword">int</span> x, <span class="d_keyword">int</span> y, <span class="d_keyword">int</span> z)
{
<span class="d_keyword">this</span>.x = x;
<span class="d_keyword">this</span>.y = y;
<span class="d_keyword">this</span>.z = z;
}
<span class="d_comment">///We need custom opEquals for node equality, as default opEquals compares references.
</span> <span class="d_keyword">override</span> <span class="d_keyword">bool</span> opEquals(Object rhs)
{
<span class="d_keyword">if</span>(<span class="d_keyword">typeid</span>(rhs) != <span class="d_keyword">typeid</span>(MyClass)){<span class="d_keyword">return</span> <span class="d_keyword">false</span>;}
<span class="d_keyword">auto</span> t = <span class="d_keyword">cast</span>(MyClass)rhs;
<span class="d_keyword">return</span> x == t.x &amp;&amp; y == t.y &amp;&amp; z == t.z;
}
Added a shortcut alias called "as" for Node.get(), and replaced get() with as() all over the code, tutorials, examples and docs. Fixed a bug in YAML benchmark makefile. Fixed a bug in autoddoc configuration.
2011-10-22 15:06:32 +00:00
<span class="d_comment">///Useful for Node.as!string .
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
</span> <span class="d_keyword">override</span> string toString()
{
<span class="d_keyword">return</span> format(<span class="d_string">"MyClass("), x, <span class="d_string">", "</span>, y, <span class="d_string">", "</span>, z, <span class="d_string">"</span>"</span>);
}
}
<span class="d_comment">//Same as representMyStruct.
</span> Node representMyClass(<span class="d_keyword">ref</span> Node node, Representer representer)
{
<span class="d_comment">//The node is guaranteed to be MyClass as we add representer for MyClass.
Added a shortcut alias called "as" for Node.get(), and replaced get() with as() all over the code, tutorials, examples and docs. Fixed a bug in YAML benchmark makefile. Fixed a bug in autoddoc configuration.
2011-10-22 15:06:32 +00:00
</span> <span class="d_keyword">auto</span> value = node.as!MyClass;
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
<span class="d_comment">//Using custom scalar format, x:y:z.
</span> <span class="d_keyword">auto</span> scalar = format(value.x, <span class="d_string">":"</span>, value.y, <span class="d_string">":"</span>, value.z);
<span class="d_comment">//Representing as a scalar, with custom tag to specify this data type.
</span> <span class="d_keyword">return</span> representer.representScalar(<span class="d_string">"!myclass.tag"</span>, scalar);
}
<span class="d_keyword">void</span> main()
{
Updated Constructor API documentation with examples.
2011-10-18 19:40:37 +00:00
<span class="d_keyword">auto</span> dumper = Dumper(<span class="d_string">"file.yaml"</span>);
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
<span class="d_keyword">auto</span> representer = <span class="d_keyword">new</span> Representer;
representer.<span class="d_psymbol">addRepresenter</span>!MyClass(&amp;representMyClass);
dumper.representer = representer;
dumper.dump(Node(<span class="d_keyword">new</span> MyClass(1,2,3)));
}
</pre>
</div>
</dd>
<dt class="d_decl">Node <a name="representScalar"></a><span class="ddoc_psymbol">representScalar</span>(in string <b>tag</b>, string <b>scalar</b>);
</dt>
<dd><p>Represent a scalar with specified tag.
</p>
<p>This is used by representer functions that produce scalars.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>tag</b></td>
<td valign=top>Tag of the scalar.</td></tr>
<tr><td valign=top>string <b>scalar</b></td>
<td valign=top>Scalar value.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">The represented node.
</div>
<p><b>Example:</b><br>
<pre class="d_code"> <span class="d_keyword">struct</span> MyStruct
{
<span class="d_keyword">int</span> x, y, z;
}
Node representMyStruct(<span class="d_keyword">ref</span> Node node, Representer representer)
{
Added a shortcut alias called "as" for Node.get(), and replaced get() with as() all over the code, tutorials, examples and docs. Fixed a bug in YAML benchmark makefile. Fixed a bug in autoddoc configuration.
2011-10-22 15:06:32 +00:00
<span class="d_keyword">auto</span> value = node.as!MyStruct;
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
<span class="d_keyword">auto</span> <span class="d_param">scalar</span> = format(value.x, <span class="d_string">":"</span>, value.y, <span class="d_string">":"</span>, value.z);
<span class="d_keyword">return</span> representer.<span class="d_psymbol">representScalar</span>(<span class="d_string">"!mystruct.tag"</span>, <span class="d_param">scalar</span>);
}
</pre>
</p>
</dd>
<dt class="d_decl">Node <a name="representSequence"></a><span class="ddoc_psymbol">representSequence</span>(in string <b>tag</b>, Node[] <b>sequence</b>);
</dt>
<dd><p>Represent a sequence with specified tag, representing children first.
</p>
<p>This is used by representer functions that produce sequences.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>tag</b></td>
<td valign=top>Tag of the <b>sequence</b>.</td></tr>
<tr><td valign=top>Node[] <b>sequence</b></td>
<td valign=top>Sequence of nodes.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">The represented node.
</div>
<b>Throws:</b><div class="pbr">RepresenterException if a child could not be represented.
</div>
<p><b>Example:</b><br>
<pre class="d_code"> <span class="d_keyword">struct</span> MyStruct
{
<span class="d_keyword">int</span> x, y, z;
}
Node representMyStruct(<span class="d_keyword">ref</span> Node node, Representer representer)
{
Added a shortcut alias called "as" for Node.get(), and replaced get() with as() all over the code, tutorials, examples and docs. Fixed a bug in YAML benchmark makefile. Fixed a bug in autoddoc configuration.
2011-10-22 15:06:32 +00:00
<span class="d_keyword">auto</span> value = node.as!MyStruct;
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
<span class="d_keyword">auto</span> nodes = [Node(value.x), Node(value.y), Node(value.z)];
<span class="d_keyword">return</span> representer.<span class="d_psymbol">representSequence</span>(<span class="d_string">"!mystruct.tag"</span>, nodes);
}
</pre>
</p>
</dd>
<dt class="d_decl">Node <a name="representMapping"></a><span class="ddoc_psymbol">representMapping</span>(in string <b>tag</b>, Pair[] <b>pairs</b>);
</dt>
<dd><p>Represent a mapping with specified tag, representing children first.
</p>
<p>This is used by representer functions that produce mappings.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>tag</b></td>
<td valign=top>Tag of the mapping.</td></tr>
<tr><td valign=top>Pair[] <b>pairs</b></td>
<td valign=top>Key-value pairs of the mapping.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">The represented node.
</div>
<b>Throws:</b><div class="pbr">RepresenterException if a child could not be represented.
</div>
<p><b>Example:</b><br>
<pre class="d_code"> <span class="d_keyword">struct</span> MyStruct
{
<span class="d_keyword">int</span> x, y, z;
}
Node representMyStruct(<span class="d_keyword">ref</span> Node node, Representer representer)
{
Added a shortcut alias called "as" for Node.get(), and replaced get() with as() all over the code, tutorials, examples and docs. Fixed a bug in YAML benchmark makefile. Fixed a bug in autoddoc configuration.
2011-10-22 15:06:32 +00:00
<span class="d_keyword">auto</span> value = node.as!MyStruct;
Updated the API documentation. Updated examples based on the new Loader API. (Dumper API still needs examples)
2011-10-14 08:34:53 +00:00
<span class="d_keyword">auto</span> <span class="d_param">pairs</span> = [Node.Pair(<span class="d_string">"x"</span>, value.x),
Node.Pair(<span class="d_string">"y"</span>, value.y),
Node.Pair(<span class="d_string">"z"</span>, value.z)];
<span class="d_keyword">return</span> representer.<span class="d_psymbol">representMapping</span>(<span class="d_string">"!mystruct.tag"</span>, <span class="d_param">pairs</span>);
}
</pre>
</p>
</dd>
</dl>
</dd>
<dt class="d_decl">Node <a name="representNull"></a><span class="ddoc_psymbol">representNull</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a null node as a null YAML value.</p>
</dd>
<dt class="d_decl">Node <a name="representString"></a><span class="ddoc_psymbol">representString</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a string node as a string scalar.</p>
</dd>
<dt class="d_decl">Node <a name="representBytes"></a><span class="ddoc_psymbol">representBytes</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a bytes node as a binary scalar.</p>
</dd>
<dt class="d_decl">Node <a name="representBool"></a><span class="ddoc_psymbol">representBool</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a bool node as a bool scalar.</p>
</dd>
<dt class="d_decl">Node <a name="representLong"></a><span class="ddoc_psymbol">representLong</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a long node as an integer scalar.</p>
</dd>
<dt class="d_decl">Node <a name="representReal"></a><span class="ddoc_psymbol">representReal</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a real node as a floating point scalar.</p>
</dd>
<dt class="d_decl">Node <a name="representSysTime"></a><span class="ddoc_psymbol">representSysTime</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a SysTime node as a timestamp.</p>
</dd>
<dt class="d_decl">Node <a name="representNodes"></a><span class="ddoc_psymbol">representNodes</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a sequence node as sequence/set.</p>
</dd>
<dt class="d_decl">Node <a name="representPairs"></a><span class="ddoc_psymbol">representPairs</span>(ref Node <b>node</b>, Representer <b>representer</b>);
</dt>
<dd><p>Represent a mapping node as map/ordered map/pairs.</p>
</dd>
</dl>
</div>
<div id="copyright">
Copyright &copy; 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>
Reference in a new issue Copy permalink