debian-packages/dyaml
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
dyaml/doc/html/api/dyaml.representer.html
Ferdinand Majerech 2c9d464389 Reader was reimplemented. 
After experiments with loading the whole file at once, and
with decoding and parsing in separate thread, lazy reader
turned to be the fastest/least memory intensive solution.
Characters are now decoded in small batches.
This improved parsing speed by ~20%.

No global state anymore. Anchors are now zero terminated strings
and TagDirectives are a simple array. Event structure was changed
to prevent size increase.
Minor fixes and improvements.
2011-11-16 03:10:29 +01:00

356 lines
16 KiB
HTML
Raw Blame History

<!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.representer - 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.style.html">dyaml.style</a></li>
</ul>
</div>
</div>
<div id="content">
<h1>dyaml.representer</h1>
<!-- Generated by Ddoc from dyaml/representer.d -->
<p>YAML node representer. Prepares YAML nodes for output. A tutorial can be
found <a href="../tutorials/custom_types.html">here</a>.
</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>Represents YAML nodes of various data types as scalar, sequence and mapping nodes ready for output.
</p>
<p>This class is used to add support for dumping of custom data types.
<br>
It can also override default node formatting styles 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">@property void <a name="defaultScalarStyle"></a><span class="ddoc_psymbol">defaultScalarStyle</span>(ScalarStyle <b>style</b>);
</dt>
<dd><p>Set default style for scalars. Invalid means the style is chosen automatically.</p>
</dd>
<dt class="d_decl">@property void <a name="defaultCollectionStyle"></a><span class="ddoc_psymbol">defaultCollectionStyle</span>(CollectionStyle <b>style</b>);
</dt>
<dd><p>Set default style for collections. Invalid means the style is chosen automatically. </p>
</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>
<p>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.
<br>
Only one function may be specified for one data type. Default data
types already have representer functions unless disabled in the
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.
</span> <span class="d_keyword">auto</span> value = node.as!MyStruct;
<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()
{
<span class="d_keyword">auto</span> dumper = Dumper(<span class="d_string">"file.yaml"</span>);
<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;
}
<span class="d_comment">///Useful for Node.as!string .
</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.
</span> <span class="d_keyword">auto</span> value = node.as!MyClass;
<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()
{
<span class="d_keyword">auto</span> dumper = Dumper(<span class="d_string">"file.yaml"</span>);
<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>(string <b>tag</b>, string <b>scalar</b>, ScalarStyle <b>style</b> = (ScalarStyle).Invalid);
</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>
<tr><td valign=top>ScalarStyle <b>style</b></td>
<td valign=top>Style of the scalar. If invalid, default style will be used.
If the node was loaded before, previous style will always be used.</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)
{
<span class="d_keyword">auto</span> value = node.as!MyStruct;
<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>(string <b>tag</b>, Node[] <b>sequence</b>, CollectionStyle <b>style</b> = (CollectionStyle).Invalid);
</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>
<tr><td valign=top>CollectionStyle <b>style</b></td>
<td valign=top>Style of the sequence. If invalid, default style will be used.
If the node was loaded before, previous style will always be used.</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)
{
<span class="d_keyword">auto</span> value = node.as!MyStruct;
<span class="d_keyword">auto</span> nodes = [Node(value.x), Node(value.y), Node(value.z)];
<span class="d_comment">//use flow style
</span> <span class="d_keyword">return</span> representer.<span class="d_psymbol">representSequence</span>(<span class="d_string">"!mystruct.tag"</span>, nodes,
CollectionStyle.Flow);
}
</pre>
</p>
</dd>
<dt class="d_decl">Node <a name="representMapping"></a><span class="ddoc_psymbol">representMapping</span>(string <b>tag</b>, Pair[] <b>pairs</b>, CollectionStyle <b>style</b> = (CollectionStyle).Invalid);
</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>
<tr><td valign=top>CollectionStyle <b>style</b></td>
<td valign=top>Style of the mapping. If invalid, default style will be used.
If the node was loaded before, previous style will always be used.</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)
{
<span class="d_keyword">auto</span> value = node.as!MyStruct;
<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 View git blame Copy permalink