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. # Source files or patterns to ignore. Supports regexp syntax.
# E.g; To ignore main.d and all source files in the test/ directory, # E.g; To ignore main.d and all source files in the test/ directory,
# you would use: "main.d test/*" # 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] [DDOC]
# Command to use to generate the documentation. # 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.

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

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

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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</div> </div>
@ -81,7 +83,7 @@
If a tag is detected with no known constructor function, it is considered an error.</p> 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> </dt>
<dd><p>Construct a Constructor. <dd><p>Construct a Constructor.
</p> </p>
@ -89,7 +91,7 @@
<b>defaultConstructors</b> to disable constructor functions for these. <b>defaultConstructors</b> to disable constructor functions for these.
</p> </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> <td valign=top>Use constructors for default YAML tags?</td></tr>
</table></div> </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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</div> </div>
@ -56,7 +58,7 @@
</dt> </dt>
<dd><p>Position in a YAML stream, used for error messages.</p> <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> </dt>
<dd><p>Construct a Mark with specified <b>line</b> and <b>column</b> in the file.</p> <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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</div> </div>
@ -97,11 +99,11 @@
</pre> </pre>
</div> </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> </dt>
<dd><p>Construct a Loader to load YAML from a file. <dd><p>Construct a Loader to load YAML from a file.
</p> </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> <td valign=top>Name of the file to load from.</td></tr>
</table></div> </table></div>
<b>Throws:</b><div class="pbr">YAMLException if the file could not be opened or read.</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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</div> </div>
@ -74,7 +76,7 @@
<dd><p>Value node.</p> <dd><p>Value node.</p>
</dd> </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> </dt>
<dd><p>Construct a Pair from two values. Will be converted to Nodes if needed.</p> <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><p>Node collection style. Used to remember style this node was loaded with.</p>
</dd> </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> </dt>
<dd><p>Construct a Node from a value. <dd><p>Construct a Node from a value.
</p> </p>
@ -124,7 +126,7 @@
</table></div> </table></div>
</dd> </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> </dt>
<dd><p>Construct a node from an array. <dd><p>Construct a node from an array.
</p> </p>
@ -154,7 +156,7 @@
</div> </div>
</dd> </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> </dt>
<dd><p>Construct a node from an associative array. <dd><p>Construct a node from an associative array.
</p> </p>
@ -186,7 +188,7 @@
</div> </div>
</dd> </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> </dt>
<dd><p>Construct a node from arrays of keys and values. <dd><p>Construct a node from arrays of keys and values.
</p> </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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</div> </div>
@ -72,12 +74,12 @@
</dd> </dd>
<dt class="d_decl">@property void <a name="defaultScalarStyle"></a><span class="ddoc_psymbol">defaultScalarStyle</span>(ScalarStyle <b>style</b>); <dt class="d_decl">@property void <a name="defaultScalarStyle"></a><span class="ddoc_psymbol">defaultScalarStyle</span>(ScalarStyle <b>style</b>);
</dt> </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> </dd>
<dt class="d_decl">@property void <a name="defaultCollectionStyle"></a><span class="ddoc_psymbol">defaultCollectionStyle</span>(CollectionStyle <b>style</b>); <dt class="d_decl">@property void <a name="defaultCollectionStyle"></a><span class="ddoc_psymbol">defaultCollectionStyle</span>(CollectionStyle <b>style</b>);
</dt> </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> </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 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> <tr><td valign=top>string <b>scalar</b></td>
<td valign=top>Scalar value.</td></tr> <td valign=top>Scalar value.</td></tr>
<tr><td valign=top>ScalarStyle <b>style</b></td> <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> </table></div>
<b>Returns:</b><div class="pbr">The represented node. <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> 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">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>); <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> </pre>
</p> </p>
@ -226,7 +230,8 @@
<tr><td valign=top>Node[] <b>sequence</b></td> <tr><td valign=top>Node[] <b>sequence</b></td>
<td valign=top>Sequence of nodes.</td></tr> <td valign=top>Sequence of nodes.</td></tr>
<tr><td valign=top>CollectionStyle <b>style</b></td> <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> </table></div>
<b>Returns:</b><div class="pbr">The represented node. <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> value = node.as!MyStruct;
<span class="d_keyword">auto</span> nodes = [Node(value.x), Node(value.y), Node(value.z)]; <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> </pre>
</p> </p>
@ -262,7 +269,8 @@
<tr><td valign=top>Pair[] <b>pairs</b></td> <tr><td valign=top>Pair[] <b>pairs</b></td>
<td valign=top>Key-value pairs of the mapping.</td></tr> <td valign=top>Key-value pairs of the mapping.</td></tr>
<tr><td valign=top>CollectionStyle <b>style</b></td> <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> </table></div>
<b>Returns:</b><div class="pbr">The represented node. <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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</div> </div>
@ -52,7 +54,7 @@
</p> </p>
<p>Can be used to implicitly resolve custom data types of scalar values.</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> </dt>
<dd><p>Construct a Resolver. <dd><p>Construct a Resolver.
</p> </p>
@ -60,7 +62,7 @@
you can use <b>defaultImplicitResolvers</b> to disable default resolvers. you can use <b>defaultImplicitResolvers</b> to disable default resolvers.
</p> </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> <td valign=top>Use default YAML implicit resolvers?</td></tr>
</table></div> </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.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</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.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> </ul>
</div> </div>
</div> </div>

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

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

2
doc/html/index.html
View file

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

2
doc/html/search.html
View file

@ -87,7 +87,7 @@
</div> </div>
<div class="footer"> <div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov. &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. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div> </div>
</body> </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"> <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> <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 <p>Sometimes you need to serialize complex data types such as classes. To do this
use functions to process nodes such as a mapping containing class data members you could use plain nodes such as mappings with class data members. However,
indexed by name. Alternatively, YAML supports custom data types using YAML supports custom types with identifiers called <em>tags</em>. That is the topic of
identifiers called <em>tags</em>. That is the topic of this tutorial.</p> this tutorial.</p>
<p>Each YAML node has a tag specifying its type. For instance: strings use the tag <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> <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. 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"> <div class="section" id="constructor">
<h2>Constructor<a class="headerlink" href="#constructor" title="Permalink to this headline"></a></h2> <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 <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 each node to hold data type corresponding to its tag. <em>Constructor</em> stores
function for each supported tag to process it. These functions are supplied by functions to process each supported tag. These are supplied by the user using
the user using the <em>addConstructorXXX()</em> methods, where <em>XXX</em> is <em>Scalar</em>, the <em>addConstructorXXX()</em> methods, where <em>XXX</em> is <em>Scalar</em>, <em>Sequence</em> or
<em>Sequence</em> or <em>Mapping</em>. <em>Constructor</em> is then passed to <em>Loader</em>, which parses <em>Mapping</em>. <em>Constructor</em> is then passed to <em>Loader</em>, which parses YAML input.</p>
YAML input.</p>
<p>Struct types have no specific requirements for YAML support. Class types should <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 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 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 <p>We will implement support for an RGB color type. It is implemented as the
following struct:</p> following struct:</p>
<div class="highlight-d"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Color</span> <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>
<div class="section" id="resolver"> <div class="section" id="resolver">
<h2>Resolver<a class="headerlink" href="#resolver" title="Permalink to this headline"></a></h2> <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 <p>Specifying tag for every color can be tedious. D:YAML can implicitly resolve
resolve scalar tags using regular expressions. This is how default types such as scalar tags using regular expressions. This is how default types are resolved.
int are resolved. We will use the <a class="reference external" href="../api/dyaml.resolver.html">Resolver</a> class We will use the <a class="reference external" href="../api/dyaml.resolver.html">Resolver</a> class to add implicit
to add implicit tag resolution for the Color data type (in its scalar form).</p> 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, <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 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 possible starting characters of the scalar. Then we pass the <em>Resolver</em> to
@ -242,23 +242,22 @@ D:YAML package.</p>
</div> </div>
<div class="section" id="representer"> <div class="section" id="representer">
<h2>Representer<a class="headerlink" href="#representer" title="Permalink to this headline"></a></h2> <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 <p>Now that you can load custom data types, it might be good to know how to dump
how to dump them. D:YAML uses the <a class="reference external" href="../api/dyaml.representer.html">Representer</a> them. D:YAML uses the <a class="reference external" href="../api/dyaml.representer.html">Representer</a> class for
class for this purpose.</p> this purpose.</p>
<p><em>Representer</em> processes YAML nodes into plain mapping, sequence or scalar nodes <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 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 functions. These functions take references to a node to process and to the
<em>Representer</em>, and return the processed node.</p> <em>Representer</em>, and return the processed node.</p>
<p>Representer functions can be added with the <em>addRepresenter()</em> method. The <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 <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> function per type can be specified. This is asserted in <em>addRepresenter()</em>
preconditions. By default, the default YAML types already have representer preconditions. Default YAML types already have representer functions specified,
functions, but you can disable them by constructing <em>Representer</em> with the but you can disable them by constructing <em>Representer</em> with the
<em>useDefaultRepresenters</em> parameter set to false.</p> <em>useDefaultRepresenters</em> parameter set to false.</p>
<p>By default, tags are explicitly specified for all non-default types. If you <p>By default, tags are explicitly output for all non-default types. To make dumped
want the tags to be implicit, you can pass a <em>Resolver</em> that will resolve them tags implicit, you can pass a <em>Resolver</em> that will resolve them implicitly. Of
implicitly. Of course, you will then need to use an identical <em>Resolver</em> when course, you will need to use an identical <em>Resolver</em> when loading the output.</p>
loading the output.</p>
<p>With the following code, we will add support for dumping the our Color type.</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> <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> <span class="p">{</span>
@ -282,8 +281,8 @@ loading the output.</p>
</div> </div>
<p>First we get the <em>Color</em> from the node. Then we convert it to a string with the <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> 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. method of <em>Representer</em> to get a scalar node ready for output. There are
There are corresponding <em>representMapping()</em> and <em>representSequence()</em> methods corresponding <em>representMapping()</em> and <em>representSequence()</em> methods
as well, with examples in the as well, with examples in the
<a class="reference external" href="../api/dyaml.resolver.html">Resolver API documentation</a>.</p> <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 <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>
<div class="footer"> <div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov. &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. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div> </div>
</body> </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>
<div class="footer"> <div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov. &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. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div> </div>
</body> </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>
<div class="footer"> <div class="footer">
&copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov. &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. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div> </div>
</body> </body>

53
docsrc/tutorials/custom_types.rst
View file

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

18
dyaml/representer.d
View file

@ -82,13 +82,13 @@ final class Representer
representers_ = null; 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) @property void defaultScalarStyle(ScalarStyle style)
{ {
defaultScalarStyle_ = 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) @property void defaultCollectionStyle(CollectionStyle style)
{ {
defaultCollectionStyle_ = style; defaultCollectionStyle_ = style;
@ -212,7 +212,8 @@ final class Representer
* *
* Params: tag = Tag of the _scalar. * Params: tag = Tag of the _scalar.
* scalar = Scalar value. * 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. * Returns: The represented node.
* *
@ -228,6 +229,7 @@ final class Representer
* auto value = node.as!MyStruct; * auto value = node.as!MyStruct;
* auto scalar = format(value.x, ":", value.y, ":", value.z); * auto scalar = format(value.x, ":", value.y, ":", value.z);
* return representer.representScalar("!mystruct.tag", scalar); * return representer.representScalar("!mystruct.tag", scalar);
*
* } * }
* -------------------- * --------------------
*/ */
@ -246,7 +248,8 @@ final class Representer
* *
* Params: tag = Tag of the sequence. * Params: tag = Tag of the sequence.
* sequence = Sequence of nodes. * 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. * Returns: The represented node.
* *
@ -263,7 +266,9 @@ final class Representer
* { * {
* auto value = node.as!MyStruct; * auto value = node.as!MyStruct;
* auto nodes = [Node(value.x), Node(value.y), Node(value.z)]; * 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. * Params: tag = Tag of the mapping.
* pairs = Key-value _pairs 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. * Returns: The represented node.
* *