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

Updated the API documentation.

Browse source 
Updated examples based on the new Loader API.
(Dumper API still needs examples)
This commit is contained in:
Ferdinand Majerech 2011-10-14 10:34:53 +02:00
parent 21001b36b9
commit 765b74ffca
48 changed files with 4555 additions and 1978 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -24,9 +24,13 @@
<div class="navblock">
<ul><li><a href="index.html">Main page</a></li>
<li><a href="dyaml.constructor.html">dyaml.constructor</a></li>
<li><a href="dyaml.dumper.html">dyaml.dumper</a></li>
<li><a href="dyaml.encoding.html">dyaml.encoding</a></li>
<li><a href="dyaml.exception.html">dyaml.exception</a></li>
<li><a href="dyaml.linebreak.html">dyaml.linebreak</a></li>
<li><a href="dyaml.loader.html">dyaml.loader</a></li>
<li><a href="dyaml.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</a></li>
<li><a href="dyaml.resolver.html">dyaml.resolver</a></li>
</ul>
</div>
@ -45,7 +49,7 @@
</p>
<p>Can be thrown by custom constructor functions.</p>
<dl><dt class="d_decl">this(string <b>msg</b>, Mark <b>start</b>, Mark <b>end</b>);
<dl><dt class="d_decl">this(string <b>msg</b>, Mark <b>start</b>, Mark <b>end</b>, string <b>file</b> = __FILE__, int <b>line</b> = __LINE__);
</dt>
<dd><p>Construct a ConstructorException.
</p>
@ -98,6 +102,9 @@
the node in file) and either a string (if constructing from scalar),
an array of Nodes (from sequence) or an array of Node.Pair (from mapping).
The value returned by this function will be stored in the resulring node.
<br>
Only one constructor function can be set for one tag.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>tag</td>

223
doc/html/api/dyaml.dumper.html Normal file
View file

@ -0,0 +1,223 @@
<!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.dumper - D:YAML 0.1 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.1 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>
</ul>
</div>
</div>
<div id="content">
<h1>dyaml.dumper</h1>
<!-- Generated by Ddoc from dyaml/dumper.d -->
<p>YAML dumper.
</p>
<p>Code based on <a href="http://www.pyyaml.org">PyYAML</a>.</p>
<dl><dt class="d_decl">struct <a name="Dumper"></a><span class="ddoc_psymbol">Dumper</span>;
</dt>
<dd><p>Dumps YAML documents to files or streams.
</p>
<p>User specified Representer and/or Resolver can be used to support new
tags / data types.
<br>
Setters are provided to affect output details (style, encoding, etc.).
</p>
<b>Examples:</b><div class="pbr">Write to a file:
<pre class="d_code"> <span class="d_keyword">auto</span> node = Node([1, 2, 3, 4, 5]);
<span class="d_psymbol">Dumper</span>(<span class="d_string">"file.yaml"</span>).dump(node);
</pre>
Write multiple YAML documents to a file:
<pre class="d_code"> <span class="d_keyword">auto</span> node1 = Node([1, 2, 3, 4, 5]);
<span class="d_keyword">auto</span> node2 = Node(<span class="d_string">"This document contains only one string"</span>);
<span class="d_psymbol">Dumper</span>(<span class="d_string">"file.yaml"</span>).dump(node1, node2);
<span class="d_comment">//Or with an array:
</span> <span class="d_comment">//Dumper("file.yaml").dump([node1, node2]);
</span>
</pre>
Write to memory:
<pre class="d_code"> <span class="d_keyword">import</span> std.stream;
<span class="d_keyword">auto</span> stream = <span class="d_keyword">new</span> MemoryStream();
<span class="d_keyword">auto</span> node = Node([1, 2, 3, 4, 5]);
<span class="d_psymbol">Dumper</span>(stream).dump(node);
</pre>
Use a custom representer/resolver to support custom data types and/or implicit tags:
<pre class="d_code"> <span class="d_keyword">auto</span> node = Node([1, 2, 3, 4, 5]);
<span class="d_keyword">auto</span> representer = <span class="d_keyword">new</span> Representer();
<span class="d_keyword">auto</span> resolver = <span class="d_keyword">new</span> Resolver();
<span class="d_comment">//Add representer functions / resolver expressions here...
</span>
<span class="d_keyword">auto</span> dumper = <span class="d_psymbol">Dumper</span>(<span class="d_string">"file.yaml"</span>);
dumper.representer = representer;
dumper.resolver = resolver;
dumper.dump(node);
</pre>
</div>
<dl><dt class="d_decl">this(string <b>filename</b>);
</dt>
<dd><p>Construct a Dumper writing to a file.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>filename</b></td>
<td valign=top>File name to write to.</td></tr>
</table></div>
<b>Throws:</b><div class="pbr">YAMLException if the file can not be dumped to (e.g. cannot be opened).</div>
</dd>
<dt class="d_decl">this(Stream <b>stream</b>);
</dt>
<dd><p>Construct a Dumper writing to a stream. This is useful to e.g. write to memory.</p>
</dd>
<dt class="d_decl">void <a name="resolver"></a><span class="ddoc_psymbol">resolver</span>(Resolver <a name="resolver"></a><span class="ddoc_psymbol">resolver</span>);
</dt>
<dd><p>Specify custom Resolver to use.</p>
</dd>
<dt class="d_decl">void <a name="representer"></a><span class="ddoc_psymbol">representer</span>(Representer <a name="representer"></a><span class="ddoc_psymbol">representer</span>);
</dt>
<dd><p>Specify custom Representer to use.</p>
</dd>
<dt class="d_decl">void <a name="canonical"></a><span class="ddoc_psymbol">canonical</span>(in bool <a name="canonical"></a><span class="ddoc_psymbol">canonical</span>);
</dt>
<dd><p>Write scalars in canonical form?</p>
</dd>
<dt class="d_decl">void <a name="indent"></a><span class="ddoc_psymbol">indent</span>(in uint <a name="indent"></a><span class="ddoc_psymbol">indent</span>);
</dt>
<dd><p>Set indentation width. 2 by default. Must not be zero.</p>
</dd>
<dt class="d_decl">void <a name="textWidth"></a><span class="ddoc_psymbol">textWidth</span>(in uint <b>width</b>);
</dt>
<dd><p>Set preferred text width.</p>
</dd>
<dt class="d_decl">void <a name="lineBreak"></a><span class="ddoc_psymbol">lineBreak</span>(in LineBreak <a name="lineBreak"></a><span class="ddoc_psymbol">lineBreak</span>);
</dt>
<dd><p>Set line break to use. Unix by default.</p>
</dd>
<dt class="d_decl">void <a name="encoding"></a><span class="ddoc_psymbol">encoding</span>(in Encoding <a name="encoding"></a><span class="ddoc_psymbol">encoding</span>);
</dt>
<dd><p>Set character encoding to use. UTF-8 by default.</p>
</dd>
<dt class="d_decl">void <a name="explicitStart"></a><span class="ddoc_psymbol">explicitStart</span>(in bool <b>explicit</b>);
</dt>
<dd><p>Always explicitly write document start?</p>
</dd>
<dt class="d_decl">void <a name="explicitEnd"></a><span class="ddoc_psymbol">explicitEnd</span>(in bool <b>explicit</b>);
</dt>
<dd><p>Always explicitly write document end?</p>
</dd>
<dt class="d_decl">void <a name="YAMLVersion"></a><span class="ddoc_psymbol">YAMLVersion</span>(in string <a name="YAMLVersion"></a><span class="ddoc_psymbol">YAMLVersion</span>);
</dt>
<dd><p>Specify YAML version string. "1.1" by default.</p>
</dd>
<dt class="d_decl">void <a name="tagDirectives"></a><span class="ddoc_psymbol">tagDirectives</span>(string[string] <b>tags</b>);
</dt>
<dd><p>Specify tag directives.
</p>
<p>A tag directive specifies a shorthand notation for specifying tags.
Each tag directive associates a handle with a prefix. This allows for
compact tag notation.
<br>
Each handle specified MUST start and end with a '!' character
(a single character "!" handle is allowed as well).
<br>
Only alphanumeric characters, '-', and '_' may be used in handles.
<br>
Each prefix MUST not be empty.
<br>
The "!!" handle is used for default YAML tags with prefix
"tag:yaml.org,2002:". This can be overridden.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string[string] <b>tags</b></td>
<td valign=top>Tag directives (keys are handles, values are prefixes).</td></tr>
</table></div>
<p><b>Example:</b><br>
<pre class="d_code"> Dumper dumper = Dumper(<span class="d_string">"file.yaml"</span>);
<span class="d_comment">//This will emit tags starting with "tag:long.org,2011"
</span> <span class="d_comment">//with a "!short!" prefix instead.
</span> dumper.<span class="d_param">tags</span>(<span class="d_string">"short"</span>, <span class="d_string">"tag:long.org,2011:"</span>);
dumper.dump(Node(<span class="d_string">"foo"</span>));
</pre>
</p>
</dd>
<dt class="d_decl">void <a name="dump"></a><span class="ddoc_psymbol">dump</span>(Node[] <b>documents</b>...);
</dt>
<dd><p>Dump one or more YAML documents to the file/stream.
</p>
<p>Note that while you can call <a name="dump"></a><span class="ddoc_psymbol">dump</span>() multiple times on the same
dumper, you will end up writing multiple YAML "files" to the same
file/stream.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>Node[] <b>documents</b></td>
<td valign=top>Documents to dump (root nodes of the documents).</td></tr>
</table></div>
<b>Throws:</b><div class="pbr">YAMLException on error (e.g. invalid nodes,
unable to write to file/stream).</div>
</dd>
</dl>
</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>

71
doc/html/api/dyaml.encoding.html Normal file
View file

@ -0,0 +1,71 @@
<!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.encoding - D:YAML 0.1 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.1 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>
</ul>
</div>
</div>
<div id="content">
<h1>dyaml.encoding</h1>
<!-- Generated by Ddoc from dyaml/encoding.d -->
<br>
<dl><dt class="d_decl">enum <a name="Encoding"></a><span class="ddoc_psymbol">Encoding</span>;
</dt>
<dd><p>Text encodings supported by D:YAML.</p>
<dl><dt class="d_decl"><a name="UTF_8"></a><span class="ddoc_psymbol">UTF_8</span></dt>
<dd><p>Unicode UTF-8</p>
</dd>
<dt class="d_decl"><a name="UTF_16"></a><span class="ddoc_psymbol">UTF_16</span></dt>
<dd><p>Unicode UTF-16</p>
</dd>
<dt class="d_decl"><a name="UTF_32"></a><span class="ddoc_psymbol">UTF_32</span></dt>
<dd><p>Unicode UTF-32</p>
</dd>
</dl>
</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>

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

@ -24,9 +24,13 @@
<div class="navblock">
<ul><li><a href="index.html">Main page</a></li>
<li><a href="dyaml.constructor.html">dyaml.constructor</a></li>
<li><a href="dyaml.dumper.html">dyaml.dumper</a></li>
<li><a href="dyaml.encoding.html">dyaml.encoding</a></li>
<li><a href="dyaml.exception.html">dyaml.exception</a></li>
<li><a href="dyaml.linebreak.html">dyaml.linebreak</a></li>
<li><a href="dyaml.loader.html">dyaml.loader</a></li>
<li><a href="dyaml.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</a></li>
<li><a href="dyaml.resolver.html">dyaml.resolver</a></li>
</ul>
</div>
@ -35,16 +39,15 @@
<div id="content">
<h1>dyaml.exception</h1>
<!-- Generated by Ddoc from dyaml/exception.d -->
<p><b>D:</b><br>
YAML exceptions and <a name="exception"></a><span class="ddoc_psymbol">exception</span> related code.</p>
<p>Exceptions thrown by D:YAML and exception related code.</p>
<dl><dt class="d_decl">class <a name="YAMLException"></a><span class="ddoc_psymbol">YAMLException</span>: object.Exception;
</dt>
<dd><p>Base class for all exceptions thrown by D:YAML.</p>
<dl><dt class="d_decl">this(string <b>msg</b>);
<dl><dt class="d_decl">this(string <b>msg</b>, string <b>file</b> = __FILE__, int <b>line</b> = __LINE__);
</dt>
<dd><p>Construct a YAMLException with specified message.</p>
<dd><p>Construct a YAMLException with specified message, and position where it was thrown.</p>
</dd>
</dl>

71
doc/html/api/dyaml.linebreak.html Normal file
View file

@ -0,0 +1,71 @@
<!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.linebreak - D:YAML 0.1 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.1 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>
</ul>
</div>
</div>
<div id="content">
<h1>dyaml.linebreak</h1>
<!-- Generated by Ddoc from dyaml/linebreak.d -->
<br>
<dl><dt class="d_decl">enum <a name="LineBreak"></a><span class="ddoc_psymbol">LineBreak</span>;
</dt>
<dd><p>Enumerates platform specific line breaks.</p>
<dl><dt class="d_decl"><a name="Unix"></a><span class="ddoc_psymbol">Unix</span></dt>
<dd><p><a name="Unix"></a><span class="ddoc_psymbol">Unix</span> line break ("\n").</p>
</dd>
<dt class="d_decl"><a name="Windows"></a><span class="ddoc_psymbol">Windows</span></dt>
<dd><p><a name="Windows"></a><span class="ddoc_psymbol">Windows</span> line break ("\r\n").</p>
</dd>
<dt class="d_decl"><a name="Macintosh"></a><span class="ddoc_psymbol">Macintosh</span></dt>
<dd><p><a name="Macintosh"></a><span class="ddoc_psymbol">Macintosh</span> line break ("\r").</p>
</dd>
</dl>
</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>

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

@ -24,9 +24,13 @@
<div class="navblock">
<ul><li><a href="index.html">Main page</a></li>
<li><a href="dyaml.constructor.html">dyaml.constructor</a></li>
<li><a href="dyaml.dumper.html">dyaml.dumper</a></li>
<li><a href="dyaml.encoding.html">dyaml.encoding</a></li>
<li><a href="dyaml.exception.html">dyaml.exception</a></li>
<li><a href="dyaml.linebreak.html">dyaml.linebreak</a></li>
<li><a href="dyaml.loader.html">dyaml.loader</a></li>
<li><a href="dyaml.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</a></li>
<li><a href="dyaml.resolver.html">dyaml.resolver</a></li>
</ul>
</div>
@ -35,50 +39,36 @@
<div id="content">
<h1>dyaml.loader</h1>
<!-- Generated by Ddoc from dyaml/loader.d -->
<p>Class and convenience functions used to load YAML documents.</p>
<p>Class used to load YAML documents.</p>
<dl><dt class="d_decl">Node <a name="load"></a><span class="ddoc_psymbol">load</span>(in string <b>filename</b>);
<dl><dt class="d_decl">struct <a name="Loader"></a><span class="ddoc_psymbol">Loader</span>;
</dt>
<dd><p>Load single YAML document from a file.
<dd><p>Loads YAML documents from files or streams.
</p>
<p>If there is no or more than one YAML document in the file, this will throw.
Use <a href="#loadAll"><span class="d_inlinecode">loadAll</span></a> for such files.
<p>User specified Constructor and/or Resolver can be used to support new
tags / data types.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>filename</b></td>
<td valign=top>Name of the file to load from.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">Root node of the document.
<b>Examples:</b><div class="pbr">Load single YAML document from a file:
<pre class="d_code"> <span class="d_keyword">auto</span> rootNode = <span class="d_psymbol">Loader</span>(<span class="d_string">"file.yaml"</span>).load();
...
</pre>
</div>
<b>Throws:</b><div class="pbr">YAMLException if there wasn't exactly one document in the file,
the file could not be opened or on a YAML parsing error.</div>
Load all YAML documents from a file:
<pre class="d_code"> <span class="d_keyword">auto</span> nodes = <span class="d_psymbol">Loader</span>(<span class="d_string">"file.yaml"</span>).loadAll();
...
</pre>
</dd>
<dt class="d_decl">Node <a name="load"></a><span class="ddoc_psymbol">load</span>(Stream <b>input</b>, in string <b>name</b> = "&lt;unknown&gt;");
</dt>
<dd><p>Load single YAML document from a stream.
</p>
<p>You can use this to e.g load YAML from memory.
<br>
Iterate over YAML documents in a file, lazily loading them:
<pre class="d_code"> <span class="d_keyword">auto</span> loader = <span class="d_psymbol">Loader</span>(<span class="d_string">"file.yaml"</span>);
If there is no or more than one YAML document in the stream, this will throw.
Use <a href="#loadAll"><span class="d_inlinecode">loadAll</span></a> for such files.
<span class="d_keyword">foreach</span>(<span class="d_keyword">ref</span> node; loader)
{
...
}
</pre>
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>Stream <b>input</b></td>
<td valign=top>Stream to read from. Must be readable.</td></tr>
<tr><td valign=top>string <b>name</b></td>
<td valign=top>Name of the stream, used in error messages.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">Root node of the document.
</div>
<b>Throws:</b><div class="pbr">YAMLException if there wasn't exactly one document in the stream,
the stream could not be read from or on a YAML parsing error.
</div>
<b>Examples:</b><div class="pbr">Loading YAML from memory:
Load YAML from memory:
<pre class="d_code"> <span class="d_keyword">import</span> std.stream;
<span class="d_keyword">import</span> std.stdio;
@ -86,50 +76,27 @@
<span class="d_string">"green: '#00ff00'\n"</span>
<span class="d_string">"blue: '#0000ff'"</span>;
<span class="d_keyword">auto</span> colors = yaml.<span class="d_psymbol">load</span>(<span class="d_keyword">new</span> MemoryStream(<span class="d_keyword">cast</span>(<span class="d_keyword">char</span>[])yaml_input));
<span class="d_keyword">auto</span> colors = <span class="d_psymbol">Loader</span>(<span class="d_keyword">new</span> MemoryStream(<span class="d_keyword">cast</span>(<span class="d_keyword">char</span>[])yaml_input)).load();
<span class="d_keyword">foreach</span>(string color, string value; colors)
{
writeln(color, <span class="d_string">" is "</span>, value, <span class="d_string">" in HTML/CSS"</span>);
}
</pre>
Use a custom constructor/resolver to support custom data types and/or implicit tags:
<pre class="d_code"> <span class="d_keyword">auto</span> constructor = <span class="d_keyword">new</span> Constructor();
<span class="d_keyword">auto</span> resolver = <span class="d_keyword">new</span> Resolver();
<span class="d_comment">//Add constructor functions / resolver expressions here...
</span>
<span class="d_keyword">auto</span> loader = <span class="d_psymbol">Loader</span>(<span class="d_string">"file.yaml"</span>);
loader.constructor = constructor;
loader.resolver = resolver;
<span class="d_keyword">auto</span> rootNode = loader.load(node);
</pre>
</div>
</dd>
<dt class="d_decl">Node[] <a name="loadAll"></a><span class="ddoc_psymbol">loadAll</span>(in string <b>filename</b>);
</dt>
<dd><p>Load all YAML documents from a file.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>filename</b></td>
<td valign=top>Name of the file to load from.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">Array of root nodes of documents in the stream.
If the stream is empty, empty array will be returned.
</div>
<b>Throws:</b><div class="pbr">YAMLException if the file could not be opened or on a YAML parsing error.</div>
</dd>
<dt class="d_decl">Node[] <a name="loadAll"></a><span class="ddoc_psymbol">loadAll</span>(Stream <b>input</b>, in string <b>name</b> = "&lt;unknown&gt;");
</dt>
<dd><p>Load all YAML documents from a stream.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>Stream <b>input</b></td>
<td valign=top>Stream to read from. Must be readable.</td></tr>
<tr><td valign=top>string <b>name</b></td>
<td valign=top>Name of the stream, used in error messages.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">Array of root nodes of documents in the file.
If the file is empty, empty array will be returned.
</div>
<b>Throws:</b><div class="pbr">YAMLException if the stream could not be read from or on a YAML parsing error.</div>
</dd>
<dt class="d_decl">struct <a name="Loader"></a><span class="ddoc_psymbol">Loader</span>;
</dt>
<dd><p>Loads YAML documents from files or streams.</p>
<dl><dt class="d_decl">this(in string <b>filename</b>);
</dt>
<dd><p>Construct a Loader to load YAML from a file.
@ -140,48 +107,36 @@
<b>Throws:</b><div class="pbr">YAMLException if the file could not be opened or read from.</div>
</dd>
<dt class="d_decl">this(in string <b>filename</b>, Constructor <b>constructor</b>, Resolver <b>resolver</b>);
<dt class="d_decl">this(Stream <b>stream</b>);
</dt>
<dd><p>Construct a Loader to load YAML from a file, with provided constructor and resolver.
<dd><p>Construct a Loader to load YAML from a stream.
</p>
<p>Constructor and resolver can be used to implement custom data types in YAML.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>filename</b></td>
<td valign=top>Name of the file to load from.</td></tr>
<tr><td valign=top>Constructor <b>constructor</b></td>
<td valign=top>Constructor to use.</td></tr>
<tr><td valign=top>Resolver <b>resolver</b></td>
<td valign=top>Resolver to use.</td></tr>
</table></div>
<b>Throws:</b><div class="pbr">YAMLException if the file could not be opened or read from.</div>
</dd>
<dt class="d_decl">this(Stream <b>input</b>, in string <b>name</b>, Constructor <b>constructor</b>, Resolver <b>resolver</b>);
</dt>
<dd><p>Construct a Loader to load YAML from a stream with provided constructor and resolver.
</p>
<p>Stream can be used to load YAML from memory and other sources.
Constructor and resolver can be used to implement custom data types in YAML.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>Stream <b>input</b></td>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>Stream <b>stream</b></td>
<td valign=top>Stream to read from. Must be readable.</td></tr>
<tr><td valign=top>string <b>name</b></td>
<td valign=top>Name of the stream. Used in error messages.</td></tr>
<tr><td valign=top>Constructor <b>constructor</b></td>
<td valign=top>Constructor to use.</td></tr>
<tr><td valign=top>Resolver <b>resolver</b></td>
<td valign=top>Resolver to use.</td></tr>
</table></div>
<b>Throws:</b><div class="pbr">YAMLException if the stream could not be read from.</div>
<b>Throws:</b><div class="pbr">YAMLException if <b>stream</b> could not be read from.</div>
</dd>
<dt class="d_decl">Node <a name="loadSingleDocument"></a><span class="ddoc_psymbol">loadSingleDocument</span>();
<dt class="d_decl">@property void <a name="name"></a><span class="ddoc_psymbol">name</span>(string <a name="name"></a><span class="ddoc_psymbol">name</span>);
</dt>
<dd><p>Set stream name. Used in debugging messages.</p>
</dd>
<dt class="d_decl">@property void <a name="resolver"></a><span class="ddoc_psymbol">resolver</span>(Resolver <a name="resolver"></a><span class="ddoc_psymbol">resolver</span>);
</dt>
<dd><p>Specify custom Resolver to use.</p>
</dd>
<dt class="d_decl">@property void <a name="constructor"></a><span class="ddoc_psymbol">constructor</span>(Constructor <a name="constructor"></a><span class="ddoc_psymbol">constructor</span>);
</dt>
<dd><p>Specify custom Constructor to use.</p>
</dd>
<dt class="d_decl">Node <a name="load"></a><span class="ddoc_psymbol">load</span>();
</dt>
<dd><p>Load single YAML document.
</p>
<p>If no or more than one YAML document is found, this will throw a YAMLException.
<p>If none or more than one YAML document is found, this will throw a YAMLException.
</p>
<b>Returns:</b><div class="pbr">Root node of the document.
@ -190,12 +145,22 @@
<b>Throws:</b><div class="pbr">YAMLException if there wasn't exactly one document
or on a YAML parsing error.</div>
</dd>
<dt class="d_decl">Node[] <a name="loadAll"></a><span class="ddoc_psymbol">loadAll</span>();
</dt>
<dd><p>Load all YAML documents.
</p>
<b>Returns:</b><div class="pbr">Array of root nodes of all documents in the file/stream.
</div>
<b>Throws:</b><div class="pbr">YAMLException on a YAML parsing error.</div>
</dd>
<dt class="d_decl">int <a name="opApply"></a><span class="ddoc_psymbol">opApply</span>(int delegate(ref Node) <b>dg</b>);
</dt>
<dd><p>Foreach over YAML documents.
</p>
<p>Parses documents lazily, as they are needed.
<p>Parses documents lazily, when they are needed.
</p>
<b>Throws:</b><div class="pbr">YAMLException on a parsing error.</div>

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

@ -24,9 +24,13 @@
<div class="navblock">
<ul><li><a href="index.html">Main page</a></li>
<li><a href="dyaml.constructor.html">dyaml.constructor</a></li>
<li><a href="dyaml.dumper.html">dyaml.dumper</a></li>
<li><a href="dyaml.encoding.html">dyaml.encoding</a></li>
<li><a href="dyaml.exception.html">dyaml.exception</a></li>
<li><a href="dyaml.linebreak.html">dyaml.linebreak</a></li>
<li><a href="dyaml.loader.html">dyaml.loader</a></li>
<li><a href="dyaml.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</a></li>
<li><a href="dyaml.resolver.html">dyaml.resolver</a></li>
</ul>
</div>
@ -35,7 +39,8 @@
<div id="content">
<h1>dyaml.node</h1>
<!-- Generated by Ddoc from dyaml/node.d -->
<p>Node of a YAML document. Used to read YAML data once it's loaded.</p>
<p>Node of a YAML document. Used to read YAML data once it's loaded,
and to prepare data to emit.</p>
<dl><dt class="d_decl">class <a name="NodeException"></a><span class="ddoc_psymbol">NodeException</span>: dyaml.exception.YAMLException;
</dt>
@ -51,13 +56,13 @@
</dt>
<dd><p>YAML node.
</p>
<p>This is a pseudo-dynamic type that can store any YAML value, including sequence
or a mapping of nodes. You can get data from a <a name="Node"></a><span class="ddoc_psymbol">Node</span> directly or iterate over it
if it's a sequence or a mapping.</p>
<p>This is a pseudo-dynamic type that can store any YAML value, including a
sequence or mapping of nodes. You can get data from a <a name="Node"></a><span class="ddoc_psymbol">Node</span> directly or
iterate over it if it's a collection.</p>
<dl><dt class="d_decl">struct <a name="Pair"></a><span class="ddoc_psymbol">Pair</span>;
</dt>
<dd><p><a name="Pair"></a><span class="ddoc_psymbol">Pair</span> of YAML nodes, used in mappings.</p>
<dd><p>Key-value pair of YAML nodes, used in mappings.</p>
<dl><dt class="d_decl">Node <a name="key"></a><span class="ddoc_psymbol">key</span>;
</dt>
@ -68,13 +73,154 @@
</dt>
<dd><p>Value node.</p>
</dd>
<dt class="d_decl">auto 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>
</dd>
<dt class="d_decl">bool <a name="equals"></a><span class="ddoc_psymbol">equals</span>(ref Pair <b>rhs</b>);
</dt>
<dd><p>Test for equality with another Pair.</p>
<dd><p>Equality test with another Pair.</p>
</dd>
</dl>
</dd>
<dt class="d_decl">auto this(T)(T <b>value</b>, in string <b>tag</b> = null);
</dt>
<dd><p>Construct a Node from a value.
</p>
<p>Any type except of Node can be stored in a Node, but default YAML
types (integers, floats, strings, timestamps, etc.) will be stored
more efficiently.
<br>
<br>
Note that to emit any non-default types you store
in a node, you need a Representer to represent them in YAML -
otherwise emitting will fail.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>value</td>
<td valign=top>Value to store in the node.</td></tr>
<tr><td valign=top>tag</td>
<td valign=top>Overrides tag of the node when emitted, regardless
of tag determined by Representer. Representer uses
this to determine YAML data type when a D data type
maps to multiple different YAML data types. Tag must
be in full form, e.g. "tag:yaml.org,2002:int", not
a shortcut, like "!!int".</td></tr>
</table></div>
</dd>
<dt class="d_decl">auto this(T)(T[] <b>array</b>, in string <b>tag</b> = null);
</dt>
<dd><p>Construct a node from an array.
</p>
<p>If array is an array of nodes or pairs, it is stored directly.
Otherwise, every value in the array is converted to a node, and
those nodes are stored.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>array</td>
<td valign=top>Values to store in the node.</td></tr>
<tr><td valign=top>tag</td>
<td valign=top>Overrides tag of the node when emitted, regardless
of tag determined by Representer. Representer uses
this to determine YAML data type when a D data type
maps to multiple different YAML data types.
This is used to differentiate between YAML sequences
("!!seq") and sets ("!!set"), which both are
internally represented as an array_ of nodes. Tag
must be in full form, e.g. "tag:yaml.org,2002:set",
not a shortcut, like "!!set".</td></tr>
</table></div>
<b>Examples:</b><div class="pbr"><pre class="d_code"> <span class="d_comment">//Will be emitted as a sequence (default for arrays)
</span> <span class="d_keyword">auto</span> seq = Node([1, 2, 3, 4, 5]);
<span class="d_comment">//Will be emitted as a set (overriden tag)
</span> <span class="d_keyword">auto</span> set = Node([1, 2, 3, 4, 5], <span class="d_string">"tag:yaml.org,2002:set"</span>);
</pre>
</div>
</dd>
<dt class="d_decl">auto 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>
<p>If keys and/or values of array are nodes, they stored directly.
Otherwise they are converted to nodes and then stored.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>array</td>
<td valign=top>Values to store in the node.</td></tr>
<tr><td valign=top>tag</td>
<td valign=top>Overrides tag of the node when emitted, regardless
of tag determined by Representer. Representer uses
this to determine YAML data type when a D data type
maps to multiple different YAML data types.
This is used to differentiate between YAML unordered
mappings ("!!map"), ordered mappings ("!!omap"), and
pairs ("!!pairs") which are all internally
represented as an array of node pairs. Tag must be
in full form, e.g. "tag:yaml.org,2002:omap", not a
shortcut, like "!!omap".</td></tr>
</table></div>
<b>Examples:</b><div class="pbr"><pre class="d_code"> <span class="d_comment">//Will be emitted as an unordered mapping (default for mappings)
</span> <span class="d_keyword">auto</span> map = Node([1 : <span class="d_string">"a"</span>, 2 : <span class="d_string">"b"</span>]);
<span class="d_comment">//Will be emitted as an ordered map (overriden tag)
</span> <span class="d_keyword">auto</span> omap = Node([1 : <span class="d_string">"a"</span>, 2 : <span class="d_string">"b"</span>], <span class="d_string">"tag:yaml.org,2002:omap"</span>);
<span class="d_comment">//Will be emitted as pairs (overriden tag)
</span> <span class="d_keyword">auto</span> pairs = Node([1 : <span class="d_string">"a"</span>, 2 : <span class="d_string">"b"</span>], <span class="d_string">"tag:yaml.org,2002:pairs"</span>);
</pre>
</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>
<dd><p>Construct a node from arrays of keys and values.
</p>
<p>Constructs a mapping node with key-value pairs from
keys and values, keeping their order. Useful when order
is important (ordered maps, pairs).
<br>
<br>
keys and values must have equal length.
<br>
<br>
If keys and/or values are nodes, they are stored directly/
Otherwise they are converted to nodes and then stored.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>keys</td>
<td valign=top>Keys of the mapping, from first to last pair.</td></tr>
<tr><td valign=top>values</td>
<td valign=top>Values of the mapping, from first to last pair.</td></tr>
<tr><td valign=top>tag</td>
<td valign=top>Overrides tag of the node when emitted, regardless
of tag determined by Representer. Representer uses
this to determine YAML data type when a D data type
maps to multiple different YAML data types.
This is used to differentiate between YAML unordered
mappings ("!!map"), ordered mappings ("!!omap"), and
pairs ("!!pairs") which are all internally
represented as an array of node pairs. Tag must be
in full form, e.g. "tag:yaml.org,2002:omap", not a
shortcut, like "!!omap".</td></tr>
</table></div>
<b>Examples:</b><div class="pbr"><pre class="d_code"> <span class="d_comment">//Will be emitted as an unordered mapping (default for mappings)
</span> <span class="d_keyword">auto</span> map = Node([1, 2], [<span class="d_string">"a"</span>, <span class="d_string">"b"</span>]);
<span class="d_comment">//Will be emitted as an ordered map (overriden tag)
</span> <span class="d_keyword">auto</span> omap = Node([1, 2], [<span class="d_string">"a"</span>, <span class="d_string">"b"</span>], <span class="d_string">"tag:yaml.org,2002:omap"</span>);
<span class="d_comment">//Will be emitted as pairs (overriden tag)
</span> <span class="d_keyword">auto</span> pairs = Node([1, 2], [<span class="d_string">"a"</span>, <span class="d_string">"b"</span>], <span class="d_string">"tag:yaml.org,2002:pairs"</span>);
</pre>
</div>
</dd>
<dt class="d_decl">const @property bool <a name="isValid"></a><span class="ddoc_psymbol">isValid</span>();
</dt>
@ -88,12 +234,12 @@
</dd>
<dt class="d_decl">const @property bool <a name="isSequence"></a><span class="ddoc_psymbol">isSequence</span>();
</dt>
<dd><p>Is this node a sequence of nodes?</p>
<dd><p>Is this node a sequence?</p>
</dd>
<dt class="d_decl">const @property bool <a name="isMapping"></a><span class="ddoc_psymbol">isMapping</span>();
</dt>
<dd><p>Is this node a mapping of nodes?</p>
<dd><p>Is this node a mapping?</p>
</dd>
<dt class="d_decl">const @property bool <a name="isUserType"></a><span class="ddoc_psymbol">isUserType</span>();
@ -105,15 +251,16 @@
</dt>
<dd><p>Equality test.
</p>
<p>If T is Node, recursively compare all
subnodes and might be quite expensive if testing entire documents.
<p>If T is Node, recursively compare all subnodes.
This might be quite expensive if testing entire documents.
<br>
If T is not Node, convert the node to T and test equality with that.
</p>
<b>Examples:</b><div class="pbr"><pre class="d_code"> <span class="d_comment">//node is a Node that contains integer 42
</span> <span class="d_keyword">assert</span>(node == 42);
<b>Examples:</b><div class="pbr"><pre class="d_code"> <span class="d_keyword">auto</span> node = Node(42);
<span class="d_keyword">assert</span>(node == 42);
<span class="d_keyword">assert</span>(node == <span class="d_string">"42"</span>);
<span class="d_keyword">assert</span>(node != <span class="d_string">"43"</span>);
</pre>
@ -130,7 +277,7 @@
<dd><p>Get the value of the node as specified type.
</p>
<p>If the specifed type does not match type in the node,
conversion is attempted if possible.
conversion is attempted.
<br>
Timestamps are stored as std.datetime.SysTime.
@ -145,13 +292,14 @@
but is replaced by a mapping later. Even if the node is a mapping, the
<a name="get"></a><span class="ddoc_psymbol">get</span> method can be used as if it was a scalar if it has a default value.
This way, new YAML files where the node is a mapping can still be read
by old versions of the program, which expects the node to be a scalar.
by old versions of the program, which expect the node to be a scalar.
</div>
</p>
<b>Examples:</b><div class="pbr">Automatic type conversion:
<pre class="d_code"> <span class="d_comment">//node is a node that contains integer 42
</span> <span class="d_keyword">assert</span>(node.<span class="d_psymbol">get</span>!<span class="d_keyword">int</span> == 42);
<pre class="d_code"> <span class="d_keyword">auto</span> node = Node(42);
<span class="d_keyword">assert</span>(node.<span class="d_psymbol">get</span>!<span class="d_keyword">int</span> == 42);
<span class="d_keyword">assert</span>(node.<span class="d_psymbol">get</span>!string == <span class="d_string">"42"</span>);
<span class="d_keyword">assert</span>(node.<span class="d_psymbol">get</span>!<span class="d_keyword">double</span> == 42.0);
</pre>
@ -167,8 +315,8 @@
</dt>
<dd><p>Write the value of the node to target.
</p>
<p>If the type of target does not match type of the node,
conversion is attempted, if possible.
<p>If the target type does not match node type,
conversion is attempted.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>target</td>
@ -179,7 +327,7 @@
</dd>
<dt class="d_decl">@property size_t <a name="length"></a><span class="ddoc_psymbol">length</span>();
</dt>
<dd><p>If this is a sequence or a mapping, return its <a name="length"></a><span class="ddoc_psymbol">length</span>.
<dd><p>If this is a collection, return its length.
</p>
<p>Otherwise, throw NodeException.
@ -190,11 +338,13 @@
<b>Throws:</b><div class="pbr">NodeException if this is not a sequence nor a mapping.</div>
</dd>
<dt class="d_decl">Node <a name="opIndex"></a><span class="ddoc_psymbol">opIndex</span>(T)(in T <b>index</b>);
<dt class="d_decl">Node <a name="opIndex"></a><span class="ddoc_psymbol">opIndex</span>(T)(T <b>index</b>);
</dt>
<dd><p>Get the element with specified index.
<dd><p>Get the element at specified index.
</p>
<p>If the node is a sequence, index must be integral.
<br>
<br>
If the node is a mapping, return the value corresponding to the first
@ -208,7 +358,36 @@
<b>Returns:</b><div class="pbr">Value corresponding to the index.
</div>
<b>Throws:</b><div class="pbr">NodeException if the index could not be found.</div>
<b>Throws:</b><div class="pbr">NodeException if the index could not be found,
non-integral index is used with a sequence or the node is
not a collection.</div>
</dd>
<dt class="d_decl">void <a name="opIndexAssign"></a><span class="ddoc_psymbol">opIndexAssign</span>(K, V)(V <b>value</b>, K <b>index</b>);
</dt>
<dd><p>Set element at specified index in a collection.
</p>
<p>This method can only be called on collection nodes.
<br>
If the node is a sequence, index must be integral.
<br>
If the node is a mapping, sets the value corresponding to the first
key matching index (including conversion, so e.g. "42" matches 42).
<br>
If the node is a mapping and no key matches index, a new key-value
pair is added to the mapping. In sequences the index must be in
range. This ensures behavior siilar to D arrays and associative
arrays.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>index</td>
<td valign=top>Index of the value to set.</td></tr>
</table></div>
<b>Throws:</b><div class="pbr">NodeException if the node is not a collection, index is out
of range or if a non-integral index is used on a sequence node.</div>
</dd>
<dt class="d_decl">int <a name="opApply"></a><span class="ddoc_psymbol">opApply</span>(T)(int delegate(ref T) <b>dg</b>);
@ -235,14 +414,95 @@
element could not be converted to specified type.</div>
</dd>
<dt class="d_decl">alias <a name="isInt"></a><span class="ddoc_psymbol">isInt</span>;
<dt class="d_decl">void <a name="add"></a><span class="ddoc_psymbol">add</span>(T)(T <b>value</b>);
</dt>
<dd><p>Is the value an integer of some kind?</p>
<dd><p>Add an element to a sequence.
</p>
<p>This method can only be called on sequence nodes.
<br>
If value is a node, it is copied to the sequence directly. Otherwise
value is converted to a node and then stored in the sequence.
<br>
<p>When emitting, all values in the sequence will be emitted. When
using the !!set tag, the user needs to ensure that all elements in
the sequence are unique, otherwise <b>invalid</b> YAML code will be
emitted.</p>
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>value</td>
<td valign=top>Value to add to the sequence.</td></tr>
</table></div>
</dd>
<dt class="d_decl">alias <a name="isFloat"></a><span class="ddoc_psymbol">isFloat</span>;
<dt class="d_decl">void <a name="add"></a><span class="ddoc_psymbol">add</span>(K, V)(K <b>key</b>, V <b>value</b>);
</dt>
<dd><p>Is the value a floating point number of some kind?</p>
<dd><p>Add a key-value pair to a mapping.
</p>
<p>This method can only be called on mapping nodes.
<br>
If key and/or value is a node, it is copied to the mapping directly.
Otherwise it is converted to a node and then stored in the mapping.
<br>
<p>It is possible for the same key to be present more than once in a
mapping. When emitting, all key-value pairs will be emitted.
This is useful with the "!!pairs" tag, but will result in
<b>invalid</b> YAML with "!!map" and "!!omap" tags.</p>
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>key</td>
<td valign=top>Key to add.</td></tr>
<tr><td valign=top>value</td>
<td valign=top>Value to add.</td></tr>
</table></div>
</dd>
<dt class="d_decl">void <a name="remove"></a><span class="ddoc_psymbol">remove</span>(T)(T <b>value</b>);
</dt>
<dd><p>Remove first (if any) occurence of a value in a collection.
</p>
<p>This method can only be called on collection nodes.
<br>
If the node is a sequence, the first node matching value (including
conversion, so e.g. "42" matches 42) is removed.
If the node is a mapping, the first key-value pair where value
matches specified value is removed.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>value</td>
<td valign=top>Value to remove.</td></tr>
</table></div>
<b>Throws:</b><div class="pbr">NodeException if the node is not a collection.</div>
</dd>
<dt class="d_decl">void <a name="removeAt"></a><span class="ddoc_psymbol">removeAt</span>(T)(T <b>index</b>);
</dt>
<dd><p>Remove element at the specified index of a collection.
</p>
<p>This method can only be called on collection nodes.
<br>
If the node is a sequence, index must be integral.
<br>
If the node is a mapping, remove the first key-value pair where
key matches index (including conversion, so e.g. "42" matches 42).
<br>
If the node is a mapping and no key matches index, nothing is removed
and no exception is thrown. This ensures behavior siilar to D arrays
and associative arrays.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>index</td>
<td valign=top>Index to remove at.</td></tr>
</table></div>
<b>Throws:</b><div class="pbr">NodeException if the node is not a collection, index is out
of range or if a non-integral index is used on a sequence node.</div>
</dd>
</dl>

326
doc/html/api/dyaml.representer.html Normal file
View file

@ -0,0 +1,326 @@
<!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.1 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.1 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>
</ul>
</div>
</div>
<div id="content">
<h1>dyaml.representer</h1>
<!-- Generated by Ddoc from dyaml/representer.d -->
<p>YAML node representer.
</p>
<p>Code based on <a href="http://www.pyyaml.org">PyYAML</a>.</p>
<dl><dt class="d_decl">class <a name="RepresenterException"></a><span class="ddoc_psymbol">RepresenterException</span>: dyaml.exception.YAMLException;
</dt>
<dd><p>Exception thrown on Representer errors.</p>
</dd>
<dt class="d_decl">class <a name="Representer"></a><span class="ddoc_psymbol">Representer</span>;
</dt>
<dd><p>Used to represent YAML nodes various data types into scalar, sequence and mapping nodes ready for output.</p>
<dl><dt class="d_decl">this(bool <b>useDefaultRepresenters</b> = true);
</dt>
<dd><p>Construct a Representer.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>bool <b>useDefaultRepresenters</b></td>
<td valign=top>Use default representer functions
for default YAML types? This can be
disabled to use custom representer
functions for default types.</td></tr>
</table></div>
</dd>
<dt class="d_decl">void <a name="addRepresenter"></a><span class="ddoc_psymbol">addRepresenter</span>(T)(Node function(ref Node, Representer) <b>representer</b>);
</dt>
<dd><p>Add a function to represent nodes with a specific data type.
</p>
<p>The representer function takes a reference 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 these
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.get!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.txt"</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.get!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.get!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.txt"</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>(in string <b>tag</b>, string <b>scalar</b>);
</dt>
<dd><p>Represent a scalar with specified tag.
</p>
<p>This is used by representer functions that produce scalars.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>tag</b></td>
<td valign=top>Tag of the scalar.</td></tr>
<tr><td valign=top>string <b>scalar</b></td>
<td valign=top>Scalar value.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">The represented node.
</div>
<p><b>Example:</b><br>
<pre class="d_code"> <span class="d_keyword">struct</span> MyStruct
{
<span class="d_keyword">int</span> x, y, z;
}
Node representMyStruct(<span class="d_keyword">ref</span> Node node, Representer representer)
{
<span class="d_keyword">auto</span> value = node.get!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>(in string <b>tag</b>, Node[] <b>sequence</b>);
</dt>
<dd><p>Represent a sequence with specified tag, representing children first.
</p>
<p>This is used by representer functions that produce sequences.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>tag</b></td>
<td valign=top>Tag of the <b>sequence</b>.</td></tr>
<tr><td valign=top>Node[] <b>sequence</b></td>
<td valign=top>Sequence of nodes.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">The represented node.
</div>
<b>Throws:</b><div class="pbr">RepresenterException if a child could not be represented.
</div>
<p><b>Example:</b><br>
<pre class="d_code"> <span class="d_keyword">struct</span> MyStruct
{
<span class="d_keyword">int</span> x, y, z;
}
Node representMyStruct(<span class="d_keyword">ref</span> Node node, Representer representer)
{
<span class="d_keyword">auto</span> value = node.get!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);
}
</pre>
</p>
</dd>
<dt class="d_decl">Node <a name="representMapping"></a><span class="ddoc_psymbol">representMapping</span>(in string <b>tag</b>, Pair[] <b>pairs</b>);
</dt>
<dd><p>Represent a mapping with specified tag, representing children first.
</p>
<p>This is used by representer functions that produce mappings.
</p>
<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>tag</b></td>
<td valign=top>Tag of the mapping.</td></tr>
<tr><td valign=top>Pair[] <b>pairs</b></td>
<td valign=top>Key-value pairs of the mapping.</td></tr>
</table></div>
<b>Returns:</b><div class="pbr">The represented node.
</div>
<b>Throws:</b><div class="pbr">RepresenterException if a child could not be represented.
</div>
<p><b>Example:</b><br>
<pre class="d_code"> <span class="d_keyword">struct</span> MyStruct
{
<span class="d_keyword">int</span> x, y, z;
}
Node representMyStruct(<span class="d_keyword">ref</span> Node node, Representer representer)
{
<span class="d_keyword">auto</span> value = node.get!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>

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

@ -24,9 +24,13 @@
<div class="navblock">
<ul><li><a href="index.html">Main page</a></li>
<li><a href="dyaml.constructor.html">dyaml.constructor</a></li>
<li><a href="dyaml.dumper.html">dyaml.dumper</a></li>
<li><a href="dyaml.encoding.html">dyaml.encoding</a></li>
<li><a href="dyaml.exception.html">dyaml.exception</a></li>
<li><a href="dyaml.linebreak.html">dyaml.linebreak</a></li>
<li><a href="dyaml.loader.html">dyaml.loader</a></li>
<li><a href="dyaml.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</a></li>
<li><a href="dyaml.resolver.html">dyaml.resolver</a></li>
</ul>
</div>
@ -83,6 +87,21 @@
<td valign=top>String of possible starting characters of the scalar.</td></tr>
</table></div>
</dd>
<dt class="d_decl">package const @property Tag <a name="defaultScalarTag"></a><span class="ddoc_psymbol">defaultScalarTag</span>();
</dt>
<dd><p>Return default scalar tag.</p>
</dd>
<dt class="d_decl">package const @property Tag <a name="defaultSequenceTag"></a><span class="ddoc_psymbol">defaultSequenceTag</span>();
</dt>
<dd><p>Return default sequence tag.</p>
</dd>
<dt class="d_decl">package const @property Tag <a name="defaultMappingTag"></a><span class="ddoc_psymbol">defaultMappingTag</span>();
</dt>
<dd><p>Return default mapping tag.</p>
</dd>
</dl>
</dd>

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

@ -24,9 +24,13 @@
<div class="navblock">
<ul><li><a href="index.html">Main page</a></li>
<li><a href="dyaml.constructor.html">dyaml.constructor</a></li>
<li><a href="dyaml.dumper.html">dyaml.dumper</a></li>
<li><a href="dyaml.encoding.html">dyaml.encoding</a></li>
<li><a href="dyaml.exception.html">dyaml.exception</a></li>
<li><a href="dyaml.linebreak.html">dyaml.linebreak</a></li>
<li><a href="dyaml.loader.html">dyaml.loader</a></li>
<li><a href="dyaml.node.html">dyaml.node</a></li>
<li><a href="dyaml.representer.html">dyaml.representer</a></li>
<li><a href="dyaml.resolver.html">dyaml.resolver</a></li>
</ul>
</div>