debian-packages/dyaml
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Updated Representer API doc, minor documentation changes.

Browse source
This commit is contained in:
Ferdinand Majerech 2011-10-29 20:43:30 +02:00
parent 0e0113ef0e
commit e835f1a191
23 changed files with 144 additions and 115 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
autoddoc.cfg
View file

@ -29,7 +29,7 @@ links = ../index.html Documentation home
# Source files or patterns to ignore. Supports regexp syntax.
# E.g; To ignore main.d and all source files in the test/ directory,
# you would use: "main.d test/*"
ignore = test/*, examples/*, docsrc/*, autoddoc/*, yaml.d, unittest.d, cdc.d, dyaml/composer.d, dyaml/event.d, dyaml/parser.d, dyaml/reader.d, dyaml/scanner.d, dyaml/token.d, dyaml/util.d, dyaml/anchor.d, dyaml/emitter.d, dyaml/flags.d, dyaml/serializer.d, dyaml/sharedobject.d, dyaml/tag.d, dyaml/tagdirectives.d, dyaml/queue.d, dyaml/escapes.d, dyaml/fastcharsearch.d, dyaml/style.d
ignore = test/*, examples/*, docsrc/*, autoddoc/*, yaml.d, unittest.d, cdc.d, dyaml/composer.d, dyaml/event.d, dyaml/parser.d, dyaml/reader.d, dyaml/scanner.d, dyaml/token.d, dyaml/util.d, dyaml/anchor.d, dyaml/emitter.d, dyaml/flags.d, dyaml/serializer.d, dyaml/sharedobject.d, dyaml/tag.d, dyaml/tagdirectives.d, dyaml/queue.d, dyaml/escapes.d, dyaml/fastcharsearch.d
[DDOC]
# Command to use to generate the documentation.

BIN
doc/doctrees/environment.pickle
View file

Binary file not shown.

BIN
doc/doctrees/tutorials/custom_types.doctree
View file

Binary file not shown.

55
doc/html/_sources/tutorials/custom_types.txt
View file

@ -2,15 +2,15 @@
Custom YAML data types
======================
Often you might want to serialize complex data types such as classes. You can
use functions to process nodes such as a mapping containing class data members
indexed by name. Alternatively, YAML supports custom data types using
identifiers called *tags*. That is the topic of this tutorial.
Sometimes you need to serialize complex data types such as classes. To do this
you could use plain nodes such as mappings with class data members. However,
YAML supports custom types with identifiers called *tags*. That is the topic of
this tutorial.
Each YAML node has a tag specifying its type. For instance: strings use the tag
``tag:yaml.org,2002:str``. Tags of most default types are *implicitly resolved*
during parsing, so you don't need to specify tag for each float, integer, etc.
It is also possible to implicitly resolve custom tags, as we will show later.
D:YAML can also implicitly resolve custom tags, as we will show later.
-----------
@ -18,16 +18,16 @@ Constructor
-----------
D:YAML uses the `Constructor <../api/dyaml.constructor.html>`_ class to process
each node to hold data type corresponding to its tag. *Constructor* stores a
function for each supported tag to process it. These functions are supplied by
the user using the *addConstructorXXX()* methods, where *XXX* is *Scalar*,
*Sequence* or *Mapping*. *Constructor* is then passed to *Loader*, which parses
YAML input.
each node to hold data type corresponding to its tag. *Constructor* stores
functions to process each supported tag. These are supplied by the user using
the *addConstructorXXX()* methods, where *XXX* is *Scalar*, *Sequence* or
*Mapping*. *Constructor* is then passed to *Loader*, which parses YAML input.
Struct types have no specific requirements for YAML support. Class types should
define the *opEquals()* operator, as this is used in equality comparisons of
nodes. Default class *opEquals()* compares references, which means two identical
objects might be considered unequal.
objects might be considered unequal. (Default struct *opEquals()* compares
byte-by-byte, sometimes you might want to override that as well.)
We will implement support for an RGB color type. It is implemented as the
following struct:
@ -173,10 +173,10 @@ You can find the source code for what we've done so far in the
Resolver
--------
Specifying tag for every color value can be tedious. D:YAML can implicitly
resolve scalar tags using regular expressions. This is how default types such as
int are resolved. We will use the `Resolver <../api/dyaml.resolver.html>`_ class
to add implicit tag resolution for the Color data type (in its scalar form).
Specifying tag for every color can be tedious. D:YAML can implicitly resolve
scalar tags using regular expressions. This is how default types are resolved.
We will use the `Resolver <../api/dyaml.resolver.html>`_ class to add implicit
tag resolution for the Color data type (in its scalar form).
We use the *addImplicitResolver()* method of *Resolver*, passing the tag,
regular expression the scalar must match to resolve to this tag, and a string of
@ -228,9 +228,9 @@ D:YAML package.
Representer
-----------
Now that you know how to load custom data types, it might also be useful to know
how to dump them. D:YAML uses the `Representer <../api/dyaml.representer.html>`_
class for this purpose.
Now that you can load custom data types, it might be good to know how to dump
them. D:YAML uses the `Representer <../api/dyaml.representer.html>`_ class for
this purpose.
*Representer* processes YAML nodes into plain mapping, sequence or scalar nodes
ready for output. Just like with *Constructor*, this is done by user specified
@ -239,15 +239,14 @@ functions. These functions take references to a node to process and to the
Representer functions can be added with the *addRepresenter()* method. The
*Representer* is then passed to *Dumper*, which dumps YAML documents. Only one
representer can be added for a type. This is asserted in *addRepresenter()*
preconditions. By default, the default YAML types already have representer
functions, but you can disable them by constructing *Representer* with the
function per type can be specified. This is asserted in *addRepresenter()*
preconditions. Default YAML types already have representer functions specified,
but you can disable them by constructing *Representer* with the
*useDefaultRepresenters* parameter set to false.
By default, tags are explicitly specified for all non-default types. If you
want the tags to be implicit, you can pass a *Resolver* that will resolve them
implicitly. Of course, you will then need to use an identical *Resolver* when
loading the output.
By default, tags are explicitly output for all non-default types. To make dumped
tags implicit, you can pass a *Resolver* that will resolve them implicitly. Of
course, you will need to use an identical *Resolver* when loading the output.
With the following code, we will add support for dumping the our Color type.
@ -274,10 +273,10 @@ With the following code, we will add support for dumping the our Color type.
First we get the *Color* from the node. Then we convert it to a string with the
CSS-like format we've used before. Finally, we use the *representScalar()*
method of *Representer* to get a scalar node ready for output.
There are corresponding *representMapping()* and *representSequence()* methods
method of *Representer* to get a scalar node ready for output. There are
corresponding *representMapping()* and *representSequence()* methods
as well, with examples in the
`Resolver API documentation <../api/dyaml.resolver.html>`_.
`Resolver API documentation <../api/dyaml.resolver.html>`_.
Since a type can only have one representer function, we don't dump *Color* both
in the scalar and mapping formats we've used before. However, you can decide to

6
doc/html/api/dyaml.constructor.html
View file

@ -32,6 +32,8 @@
<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>
@ -81,7 +83,7 @@
If a tag is detected with no known constructor function, it is considered an error.</p>
<dl><dt class="d_decl">this(in bool <b>defaultConstructors</b> = true);
<dl><dt class="d_decl">this(in const(bool) <b>defaultConstructors</b> = true);
</dt>
<dd><p>Construct a Constructor.
</p>
@ -89,7 +91,7 @@
<b>defaultConstructors</b> to disable constructor functions for these.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>bool <b>defaultConstructors</b></td>
<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>

2
doc/html/api/dyaml.dumper.html
View file

@ -32,6 +32,8 @@
<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>

2
doc/html/api/dyaml.encoding.html
View file

@ -32,6 +32,8 @@
<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>

4
doc/html/api/dyaml.exception.html
View file

@ -32,6 +32,8 @@
<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>
@ -56,7 +58,7 @@
</dt>
<dd><p>Position in a YAML stream, used for error messages.</p>
<dl><dt class="d_decl">this(in uint <b>line</b>, in uint <b>column</b>);
<dl><dt class="d_decl">this(in const(uint) <b>line</b>, in const(uint) <b>column</b>);
</dt>
<dd><p>Construct a Mark with specified <b>line</b> and <b>column</b> in the file.</p>

2
doc/html/api/dyaml.linebreak.html
View file

@ -32,6 +32,8 @@
<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>

6
doc/html/api/dyaml.loader.html
View file

@ -32,6 +32,8 @@
<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>
@ -97,11 +99,11 @@
</pre>
</div>
<dl><dt class="d_decl">this(in string <b>filename</b>);
<dl><dt class="d_decl">this(in const(immutable(char)[]) <b>filename</b>);
</dt>
<dd><p>Construct a Loader to load YAML from a file.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>filename</b></td>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>const(immutable(char)[]) <b>filename</b></td>
<td valign=top>Name of the file to load from.</td></tr>
</table></div>
<b>Throws:</b><div class="pbr">YAMLException if the file could not be opened or read.</div>

12
doc/html/api/dyaml.node.html
View file

@ -32,6 +32,8 @@
<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>
@ -74,7 +76,7 @@
<dd><p>Value node.</p>
</dd>
<dt class="d_decl">auto this(K, V)(K <b>key</b>, V <b>value</b>);
<dt class="d_decl">this(K, V)(K <b>key</b>, V <b>value</b>);
</dt>
<dd><p>Construct a Pair from two values. Will be converted to Nodes if needed.</p>
@ -96,7 +98,7 @@
<dd><p>Node collection style. Used to remember style this node was loaded with.</p>
</dd>
<dt class="d_decl">auto this(T)(T <b>value</b>, in string <b>tag</b> = null);
<dt class="d_decl">this(T)(T <b>value</b>, in string <b>tag</b> = null);
</dt>
<dd><p>Construct a Node from a value.
</p>
@ -124,7 +126,7 @@
</table></div>
</dd>
<dt class="d_decl">auto this(T)(T[] <b>array</b>, in string <b>tag</b> = null);
<dt class="d_decl">this(T)(T[] <b>array</b>, in string <b>tag</b> = null);
</dt>
<dd><p>Construct a node from an array.
</p>
@ -154,7 +156,7 @@
</div>
</dd>
<dt class="d_decl">auto this(K, V)(V[K] <b>array</b>, in string <b>tag</b> = null);
<dt class="d_decl">this(K, V)(V[K] <b>array</b>, in string <b>tag</b> = null);
</dt>
<dd><p>Construct a node from an associative array.
</p>
@ -186,7 +188,7 @@
</div>
</dd>
<dt class="d_decl">auto this(K, V)(K[] <b>keys</b>, V[] <b>values</b>, in string <b>tag</b> = null);
<dt class="d_decl">this(K, V)(K[] <b>keys</b>, V[] <b>values</b>, in string <b>tag</b> = null);
</dt>
<dd><p>Construct a node from arrays of keys and values.
</p>

20
doc/html/api/dyaml.representer.html
View file

@ -32,6 +32,8 @@
<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>
@ -72,12 +74,12 @@
</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 <b>style</b> for scalars. Invalid means the <b>style</b> is chosen automatically.</p>
<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 <b>style</b> for collections. Invalid means the <b>style</b> is chosen automatically. </p>
<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>);
@ -193,7 +195,8 @@
<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 <b>scalar</b> (will be default if invalid).</td></tr>
<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.
@ -209,6 +212,7 @@
<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>
@ -226,7 +230,8 @@
<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 <b>sequence</b> (will be default if invalid).</td></tr>
<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.
@ -244,7 +249,9 @@
{
<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_keyword">return</span> representer.<span class="d_psymbol">representSequence</span>(<span class="d_string">"!mystruct.tag"</span>, nodes);
<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>
@ -262,7 +269,8 @@
<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 (will be default if invalid).</td></tr>
<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.

6
doc/html/api/dyaml.resolver.html
View file

@ -32,6 +32,8 @@
<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>
@ -52,7 +54,7 @@
</p>
<p>Can be used to implicitly resolve custom data types of scalar values.</p>
<dl><dt class="d_decl">this(in bool <b>defaultImplicitResolvers</b> = true);
<dl><dt class="d_decl">this(in const(bool) <b>defaultImplicitResolvers</b> = true);
</dt>
<dd><p>Construct a Resolver.
</p>
@ -60,7 +62,7 @@
you can use <b>defaultImplicitResolvers</b> to disable default resolvers.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>bool <b>defaultImplicitResolvers</b></td>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>const(bool) <b>defaultImplicitResolvers</b></td>
<td valign=top>Use default YAML implicit resolvers?</td></tr>
</table></div>

2
doc/html/api/index.html
View file

@ -32,6 +32,8 @@
<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>

2
doc/html/articles/spec_differences.html
View file

@ -138,7 +138,7 @@ struct appears in Phobos.</p>
</div>
<div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
Last updated on Oct 27, 2011.
Last updated on Oct 29, 2011.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>

2
doc/html/index.html
View file

@ -104,7 +104,7 @@
</div>
<div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
Last updated on Oct 27, 2011.
Last updated on Oct 29, 2011.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>

2
doc/html/search.html
View file

@ -87,7 +87,7 @@
</div>
<div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
Last updated on Oct 27, 2011.
Last updated on Oct 29, 2011.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>

2
doc/html/searchindex.js
View file

File diff suppressed because one or more lines are too long

55
doc/html/tutorials/custom_types.html
View file

@ -47,26 +47,26 @@
<div class="section" id="custom-yaml-data-types">
<h1>Custom YAML data types<a class="headerlink" href="#custom-yaml-data-types" title="Permalink to this headline"></a></h1>
<p>Often you might want to serialize complex data types such as classes. You can
use functions to process nodes such as a mapping containing class data members
indexed by name. Alternatively, YAML supports custom data types using
identifiers called <em>tags</em>. That is the topic of this tutorial.</p>
<p>Sometimes you need to serialize complex data types such as classes. To do this
you could use plain nodes such as mappings with class data members. However,
YAML supports custom types with identifiers called <em>tags</em>. That is the topic of
this tutorial.</p>
<p>Each YAML node has a tag specifying its type. For instance: strings use the tag
<tt class="docutils literal"><span class="pre">tag:yaml.org,2002:str</span></tt>. Tags of most default types are <em>implicitly resolved</em>
during parsing, so you don&#8217;t need to specify tag for each float, integer, etc.
It is also possible to implicitly resolve custom tags, as we will show later.</p>
D:YAML can also implicitly resolve custom tags, as we will show later.</p>
<div class="section" id="constructor">
<h2>Constructor<a class="headerlink" href="#constructor" title="Permalink to this headline"></a></h2>
<p>D:YAML uses the <a class="reference external" href="../api/dyaml.constructor.html">Constructor</a> class to process
each node to hold data type corresponding to its tag. <em>Constructor</em> stores a
function for each supported tag to process it. These functions are supplied by
the user using the <em>addConstructorXXX()</em> methods, where <em>XXX</em> is <em>Scalar</em>,
<em>Sequence</em> or <em>Mapping</em>. <em>Constructor</em> is then passed to <em>Loader</em>, which parses
YAML input.</p>
each node to hold data type corresponding to its tag. <em>Constructor</em> stores
functions to process each supported tag. These are supplied by the user using
the <em>addConstructorXXX()</em> methods, where <em>XXX</em> is <em>Scalar</em>, <em>Sequence</em> or
<em>Mapping</em>. <em>Constructor</em> is then passed to <em>Loader</em>, which parses YAML input.</p>
<p>Struct types have no specific requirements for YAML support. Class types should
define the <em>opEquals()</em> operator, as this is used in equality comparisons of
nodes. Default class <em>opEquals()</em> compares references, which means two identical
objects might be considered unequal.</p>
objects might be considered unequal. (Default struct <em>opEquals()</em> compares
byte-by-byte, sometimes you might want to override that as well.)</p>
<p>We will implement support for an RGB color type. It is implemented as the
following struct:</p>
<div class="highlight-d"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Color</span>
@ -198,10 +198,10 @@ they were loaded as expected.</p>
</div>
<div class="section" id="resolver">
<h2>Resolver<a class="headerlink" href="#resolver" title="Permalink to this headline"></a></h2>
<p>Specifying tag for every color value can be tedious. D:YAML can implicitly
resolve scalar tags using regular expressions. This is how default types such as
int are resolved. We will use the <a class="reference external" href="../api/dyaml.resolver.html">Resolver</a> class
to add implicit tag resolution for the Color data type (in its scalar form).</p>
<p>Specifying tag for every color can be tedious. D:YAML can implicitly resolve
scalar tags using regular expressions. This is how default types are resolved.
We will use the <a class="reference external" href="../api/dyaml.resolver.html">Resolver</a> class to add implicit
tag resolution for the Color data type (in its scalar form).</p>
<p>We use the <em>addImplicitResolver()</em> method of <em>Resolver</em>, passing the tag,
regular expression the scalar must match to resolve to this tag, and a string of
possible starting characters of the scalar. Then we pass the <em>Resolver</em> to
@ -242,23 +242,22 @@ D:YAML package.</p>
</div>
<div class="section" id="representer">
<h2>Representer<a class="headerlink" href="#representer" title="Permalink to this headline"></a></h2>
<p>Now that you know how to load custom data types, it might also be useful to know
how to dump them. D:YAML uses the <a class="reference external" href="../api/dyaml.representer.html">Representer</a>
class for this purpose.</p>
<p>Now that you can load custom data types, it might be good to know how to dump
them. D:YAML uses the <a class="reference external" href="../api/dyaml.representer.html">Representer</a> class for
this purpose.</p>
<p><em>Representer</em> processes YAML nodes into plain mapping, sequence or scalar nodes
ready for output. Just like with <em>Constructor</em>, this is done by user specified
functions. These functions take references to a node to process and to the
<em>Representer</em>, and return the processed node.</p>
<p>Representer functions can be added with the <em>addRepresenter()</em> method. The
<em>Representer</em> is then passed to <em>Dumper</em>, which dumps YAML documents. Only one
representer can be added for a type. This is asserted in <em>addRepresenter()</em>
preconditions. By default, the default YAML types already have representer
functions, but you can disable them by constructing <em>Representer</em> with the
function per type can be specified. This is asserted in <em>addRepresenter()</em>
preconditions. Default YAML types already have representer functions specified,
but you can disable them by constructing <em>Representer</em> with the
<em>useDefaultRepresenters</em> parameter set to false.</p>
<p>By default, tags are explicitly specified for all non-default types. If you
want the tags to be implicit, you can pass a <em>Resolver</em> that will resolve them
implicitly. Of course, you will then need to use an identical <em>Resolver</em> when
loading the output.</p>
<p>By default, tags are explicitly output for all non-default types. To make dumped
tags implicit, you can pass a <em>Resolver</em> that will resolve them implicitly. Of
course, you will need to use an identical <em>Resolver</em> when loading the output.</p>
<p>With the following code, we will add support for dumping the our Color type.</p>
<div class="highlight-d"><div class="highlight"><pre><span class="n">Node</span> <span class="n">representColor</span><span class="p">(</span><span class="k">ref</span> <span class="n">Node</span> <span class="n">node</span><span class="p">,</span> <span class="n">Representer</span> <span class="n">representer</span><span class="p">)</span>
<span class="p">{</span>
@ -282,8 +281,8 @@ loading the output.</p>
</div>
<p>First we get the <em>Color</em> from the node. Then we convert it to a string with the
CSS-like format we&#8217;ve used before. Finally, we use the <em>representScalar()</em>
method of <em>Representer</em> to get a scalar node ready for output.
There are corresponding <em>representMapping()</em> and <em>representSequence()</em> methods
method of <em>Representer</em> to get a scalar node ready for output. There are
corresponding <em>representMapping()</em> and <em>representSequence()</em> methods
as well, with examples in the
<a class="reference external" href="../api/dyaml.resolver.html">Resolver API documentation</a>.</p>
<p>Since a type can only have one representer function, we don&#8217;t dump <em>Color</em> both
@ -369,7 +368,7 @@ directory of the D:YAML package.</p>
</div>
<div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
Last updated on Oct 27, 2011.
Last updated on Oct 29, 2011.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>

2
doc/html/tutorials/getting_started.html
View file

@ -237,7 +237,7 @@ example in the <tt class="docutils literal"><span class="pre">example/getting_st
</div>
<div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
Last updated on Oct 27, 2011.
Last updated on Oct 29, 2011.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>

2
doc/html/tutorials/yaml_syntax.html
View file

@ -330,7 +330,7 @@ Some of these might change in the future (especially !!map and !!set).</p>
</div>
<div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
Last updated on Oct 27, 2011.
Last updated on Oct 29, 2011.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>

55
docsrc/tutorials/custom_types.rst
View file

@ -2,15 +2,15 @@
Custom YAML data types
======================
Often you might want to serialize complex data types such as classes. You can
use functions to process nodes such as a mapping containing class data members
indexed by name. Alternatively, YAML supports custom data types using
identifiers called *tags*. That is the topic of this tutorial.
Sometimes you need to serialize complex data types such as classes. To do this
you could use plain nodes such as mappings with class data members. However,
YAML supports custom types with identifiers called *tags*. That is the topic of
this tutorial.
Each YAML node has a tag specifying its type. For instance: strings use the tag
``tag:yaml.org,2002:str``. Tags of most default types are *implicitly resolved*
during parsing, so you don't need to specify tag for each float, integer, etc.
It is also possible to implicitly resolve custom tags, as we will show later.
D:YAML can also implicitly resolve custom tags, as we will show later.
-----------
@ -18,16 +18,16 @@ Constructor
-----------
D:YAML uses the `Constructor <../api/dyaml.constructor.html>`_ class to process
each node to hold data type corresponding to its tag. *Constructor* stores a
function for each supported tag to process it. These functions are supplied by
the user using the *addConstructorXXX()* methods, where *XXX* is *Scalar*,
*Sequence* or *Mapping*. *Constructor* is then passed to *Loader*, which parses
YAML input.
each node to hold data type corresponding to its tag. *Constructor* stores
functions to process each supported tag. These are supplied by the user using
the *addConstructorXXX()* methods, where *XXX* is *Scalar*, *Sequence* or
*Mapping*. *Constructor* is then passed to *Loader*, which parses YAML input.
Struct types have no specific requirements for YAML support. Class types should
define the *opEquals()* operator, as this is used in equality comparisons of
nodes. Default class *opEquals()* compares references, which means two identical
objects might be considered unequal.
objects might be considered unequal. (Default struct *opEquals()* compares
byte-by-byte, sometimes you might want to override that as well.)
We will implement support for an RGB color type. It is implemented as the
following struct:
@ -173,10 +173,10 @@ You can find the source code for what we've done so far in the
Resolver
--------
Specifying tag for every color value can be tedious. D:YAML can implicitly
resolve scalar tags using regular expressions. This is how default types such as
int are resolved. We will use the `Resolver <../api/dyaml.resolver.html>`_ class
to add implicit tag resolution for the Color data type (in its scalar form).
Specifying tag for every color can be tedious. D:YAML can implicitly resolve
scalar tags using regular expressions. This is how default types are resolved.
We will use the `Resolver <../api/dyaml.resolver.html>`_ class to add implicit
tag resolution for the Color data type (in its scalar form).
We use the *addImplicitResolver()* method of *Resolver*, passing the tag,
regular expression the scalar must match to resolve to this tag, and a string of
@ -228,9 +228,9 @@ D:YAML package.
Representer
-----------
Now that you know how to load custom data types, it might also be useful to know
how to dump them. D:YAML uses the `Representer <../api/dyaml.representer.html>`_
class for this purpose.
Now that you can load custom data types, it might be good to know how to dump
them. D:YAML uses the `Representer <../api/dyaml.representer.html>`_ class for
this purpose.
*Representer* processes YAML nodes into plain mapping, sequence or scalar nodes
ready for output. Just like with *Constructor*, this is done by user specified
@ -239,15 +239,14 @@ functions. These functions take references to a node to process and to the
Representer functions can be added with the *addRepresenter()* method. The
*Representer* is then passed to *Dumper*, which dumps YAML documents. Only one
representer can be added for a type. This is asserted in *addRepresenter()*
preconditions. By default, the default YAML types already have representer
functions, but you can disable them by constructing *Representer* with the
function per type can be specified. This is asserted in *addRepresenter()*
preconditions. Default YAML types already have representer functions specified,
but you can disable them by constructing *Representer* with the
*useDefaultRepresenters* parameter set to false.
By default, tags are explicitly specified for all non-default types. If you
want the tags to be implicit, you can pass a *Resolver* that will resolve them
implicitly. Of course, you will then need to use an identical *Resolver* when
loading the output.
By default, tags are explicitly output for all non-default types. To make dumped
tags implicit, you can pass a *Resolver* that will resolve them implicitly. Of
course, you will need to use an identical *Resolver* when loading the output.
With the following code, we will add support for dumping the our Color type.
@ -274,10 +273,10 @@ With the following code, we will add support for dumping the our Color type.
First we get the *Color* from the node. Then we convert it to a string with the
CSS-like format we've used before. Finally, we use the *representScalar()*
method of *Representer* to get a scalar node ready for output.
There are corresponding *representMapping()* and *representSequence()* methods
method of *Representer* to get a scalar node ready for output. There are
corresponding *representMapping()* and *representSequence()* methods
as well, with examples in the
`Resolver API documentation <../api/dyaml.resolver.html>`_.
`Resolver API documentation <../api/dyaml.resolver.html>`_.
Since a type can only have one representer function, we don't dump *Color* both
in the scalar and mapping formats we've used before. However, you can decide to

18
dyaml/representer.d
View file

@ -82,13 +82,13 @@ final class Representer
representers_ = null;
}
///Set default style for scalars. Invalid means the style is chosen automatically.
///Set default _style for scalars. Invalid means the _style is chosen automatically.
@property void defaultScalarStyle(ScalarStyle style)
{
defaultScalarStyle_ = style;
}
///Set default style for collections. Invalid means the style is chosen automatically.
///Set default _style for collections. Invalid means the _style is chosen automatically.
@property void defaultCollectionStyle(CollectionStyle style)
{
defaultCollectionStyle_ = style;
@ -212,7 +212,8 @@ final class Representer
*
* Params: tag = Tag of the _scalar.
* scalar = Scalar value.
* style = Style of the scalar (will be default if invalid).
* style = Style of the _scalar. If invalid, default _style will be used.
* If the node was loaded before, previous _style will always be used.
*
* Returns: The represented node.
*
@ -228,6 +229,7 @@ final class Representer
* auto value = node.as!MyStruct;
* auto scalar = format(value.x, ":", value.y, ":", value.z);
* return representer.representScalar("!mystruct.tag", scalar);
*
* }
* --------------------
*/
@ -246,7 +248,8 @@ final class Representer
*
* Params: tag = Tag of the sequence.
* sequence = Sequence of nodes.
* style = Style of the sequence (will be default if invalid).
* style = Style of the _sequence. If invalid, default _style will be used.
* If the node was loaded before, previous _style will always be used.
*
* Returns: The represented node.
*
@ -263,7 +266,9 @@ final class Representer
* {
* auto value = node.as!MyStruct;
* auto nodes = [Node(value.x), Node(value.y), Node(value.z)];
* return representer.representSequence("!mystruct.tag", nodes);
* //use flow style
* return representer.representSequence("!mystruct.tag", nodes,
* CollectionStyle.Flow);
* }
* --------------------
*/
@ -302,7 +307,8 @@ final class Representer
*
* Params: tag = Tag of the mapping.
* pairs = Key-value _pairs of the mapping.
* style = Style of the mapping (will be default if invalid).
* style = Style of the _mapping. If invalid, default _style will be used.
* If the node was loaded before, previous _style will always be used.
*
* Returns: The represented node.
*