Updated the API documentation.

Updated examples based on the new Loader API.
(Dumper API still needs examples)

autoddoc.cfg

@@ -29,7 +29,7 @@ links = ../index.html Documentation home
 # Source files or patterns to ignore. Supports regexp syntax.
 # E.g; To ignore main.d and all source files in the test/ directory,
 # you would use: "main.d test/*"
-ignore = test/*, examples/*, docsrc/*, autoddoc/*, yaml.d, unittest.d, cdc.d, dyaml/composer.d, dyaml/event.d, dyaml/parser.d, dyaml/reader.d, dyaml/scanner.d, dyaml/token.d, dyaml/util.d
+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
 
 [DDOC]
 # Command to use to generate the documentation. 

doc/html/_sources/articles/spec_differences.txt

@@ -9,7 +9,7 @@ are caused by difficulty of implementation of some features, such as multiple
 Unicode encodings within single stream, and some by unnecessary restrictions or
 ambiguities in the specification. 
 
-Still, D:YAML tries to be as close to the specification as possible. D:YAML should
+Still, D:YAML tries to be as close to the specification as possible. It should
 never load documents with different meaning than according to the specification, 
 and documents that fail to load should be very rare (for instance, very few 
 files use multiple Unicode encodings).
@@ -21,10 +21,6 @@ List of known differences:
 
 Differences that can cause valid YAML documents not to load:
 
-* At the moment, all mappings in the internal representation are ordered,
-  and a comparison for equality between equal mappings with differing order
-  will return false. This will be fixed once Phobos has a usable map type or
-  D associative arrays work with variants.
 * No support for byte order marks and multiple Unicode encodings in a stream.
 * Plain scalars in flow context cannot contain ``,``, ``:`` and ``?``.
   This might change with ``:`` in the future. 

doc/html/_sources/tutorials/custom_types.txt

@@ -2,10 +2,10 @@
 Custom YAML data types
 ======================
 
-Often you will want to serialize complex data types such as classes. You can use
+Often you might want to serialize complex data types such as classes. You can 
-functions to process nodes; e.g. a mapping containing class data members indexed 
+use functions to process nodes such as a mapping containing class data members 
-by name. Alternatively, YAML supports custom data types using identifiers called
+indexed by name. Alternatively, YAML supports custom data types using 
-*tags*. That is the topic of this tutorial.
+identifiers called *tags*. That is the topic of this tutorial.
 
 Each YAML node has a tag specifying its type. For instance: strings use the tag 
 ``tag:yaml.org,2002:str``. Tags of most default types are *implicitly resolved* 
@@ -19,9 +19,9 @@ Constructor
 
 D:YAML uses the *Constructor* class to process each node to hold data type
 corresponding to its tag. *Constructor* stores a function for each supported 
-tag to process it. These functions can be supplied by the user using the 
+tag to process it. These functions are supplied by the user using the 
-*addConstructor()* method. *Constructor* is then passed to *Loader*, which will
+*addConstructor()* method. *Constructor* is then passed to *Loader*, which 
-parse YAML input.
+parses YAML input.
 
 We will implement support for an RGB color type. It is implemented as the 
 following struct:
@@ -111,7 +111,7 @@ RRGGBB, or from a mapping, where we use the following format:
        return Color(cast(ubyte)r, cast(ubyte)g, cast(ubyte)b);
    }
 
-Next, we need some YAML code using our new tag. Create a file called input.yaml 
+Next, we need some YAML data using our new tag. Create a file called input.yaml 
 with the following contents:
 
 .. code-block:: yaml
@@ -144,9 +144,10 @@ Finally, the code to put it all together:
            constructor.addConstructor("!color", &constructColorScalar);
            constructor.addConstructor("!color-mapping", &constructColorMapping);
 
-           auto loader = new Loader("input.yaml", constructor, new Resolver);
+           auto loader = Loader("input.yaml");
+           loader.constructor = constructor;
 
-           auto root = loader.loadSingleDocument();
+           auto root = loader.load();
 
            if(root["scalar-red"].get!Color == red && 
               root["mapping-red"].get!Color == red && 
@@ -166,10 +167,9 @@ Finally, the code to put it all together:
    }
 
 First, we create a *Constructor* and pass functions to handle the ``!color`` 
-and ``!color-mapping`` tag. We construct a *Loader* using the *Constructor*. 
+and ``!color-mapping`` tag. We construct a *Loader*m and pass the *Constructor*
-We also need a *Resolver*, but for now we just default-construct it. We then 
+to it. We then load the YAML document, and finally, read the colors using 
-load the YAML document, and finally, read the colors using *get()* method to
+*get()* method to test if they were loaded as expected.
-test if they were loaded as expected.
 
 You can find the source code for what we've done so far in the 
 ``examples/constructor`` directory in the D:YAML package.
@@ -180,14 +180,13 @@ Resolver
 --------
 
 Specifying tag for every color value can be tedious. D:YAML can implicitly 
-resolve tag of a scalar using a regular expression. This is how default types, 
+resolve scalar tags using regular expressions. This is how default types such as
-e.g. int, are resolved. We will use the *Resolver* class to add implicit tag 
+int are resolved. We will use the *Resolver* class to add implicit tag 
 resolution for the Color data type (in its scalar form).
 
 We use the *addImplicitResolver* method of *Resolver*, passing the tag, regular
 expression the value must match to resolve to this tag, and a string of possible
-starting characters of the value. Then we pass the *Resolver* to the constructor 
+starting characters of the value. Then we pass the *Resolver* to *Loader*.
-of *Loader*.
 
 Note that resolvers added first override ones added later. If no resolver 
 matches a scalar, YAML string tag is used. Therefore our custom values must not 
@@ -203,11 +202,14 @@ Add this to your code to add implicit resolution of ``!color``.
    resolver.addImplicitResolver("!color", std.regex.regex("[0-9a-fA-F]{6}",
                                 "0123456789abcdefABCDEF"));
    
-   auto loader = new Loader("input.yaml", constructor, resolver);
+   auto loader = Loader("input.yaml");
+   
+   loader.constructor = constructor;
+   loader.resolver = resolver;
 
    //code from the previous example...
 
-Now, change contents of input.dyaml to this:
+Now, change contents of input.yaml to this:
 
 .. code-block:: yaml
 

doc/html/_sources/tutorials/getting_started.txt

@@ -26,10 +26,8 @@ Download the version of DMD for your operating system and install it.
 .. note:: 
    Other D compilers exist, such as 
    `GDC <http://bitbucket.org/goshawk/gdc/wiki/Home>`_ and 
-   `LDC <http://www.dsource.org/projects/ldc/>`_. 
+   `LDC <http://www.dsource.org/projects/ldc/>`_. Setting up with either one of
-   Setting up with either one of them should be similar to DMD,
+   them should be similar to DMD, but they are not yet as stable as DMD.
-   however, at the moment they are not as up to date as DMD.
-
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Download and compile D:YAML
@@ -84,7 +82,7 @@ into the file:
 
    void main()
    {
-       yaml.Node root = yaml.load("input.yaml");
+       Node root = Loader("input.yaml").load();
        foreach(string word; root["Hello World"])
        {
            writeln(word);
@@ -100,22 +98,23 @@ Explanation of the code
 First, we import the *yaml* module. This is the only module you need to import 
 to use D:YAML - it automatically imports all needed modules.
 
-Next we load the file using the *yaml.load()* function - this loads the file as
+Next we load the file using the *Loader.load()* method. *Loader* is the struct 
-**one** YAML document and throws *YAMLException*, D:YAML exception type, if the 
+used for parsing YAML documents, and *load()* is a method that loads the file as
+**one** YAML document, or throws *YAMLException*, D:YAML exception type, if the 
 file could not be parsed or does not contain exactly one document. Note that we 
 don't do any error checking here in order to keep the example as simple as 
 possible.
 
-*yaml.Node* represents a node in a YAML document. It can be a sequence (array), 
+*Node* represents a node in a YAML document. It can be a sequence (array), 
 mapping (associative array) or a scalar (value). Here the root node is a 
 mapping, and we use the index operator to get subnodes with keys "Hello World"
 and "Answer". We iterate over the first, as it is a sequence, and use the 
-*yaml.Node.get()* method on the second to get its value as an integer.
+*Node.get()* method on the second to get its value as an integer.
 
 You can iterate over a mapping or sequence as if it was an associative or normal 
 array. If you try to iterate over a scalar, it will throw a *YAMLException*. 
 
-You can iterate over subnodes using yaml.Node as the iterated type, or specify 
+You can iterate over subnodes using *Node* as the iterated type, or specify 
 the type subnodes are expected to have. D:YAML will automatically convert 
 iterated subnodes to that type if possible. Here we specify the *string* type, 
 so we iterate over the "Hello World" sequence as an array of strings. If it is
@@ -123,8 +122,8 @@ not possible to convert to iterated type, a *YAMLException* is thrown. For
 instance, if we specified *int* here, we would get an error, as "Hello" 
 cannot be converted to an integer.
 
-The *yaml.Node.get()* method is used to get value of a scalar node as specified 
+The *Node.get()* method is used to get value of a scalar node, allowing to 
-type. D:YAML will try to return the scalar as specified type, converting if 
+specify type. D:YAML will try to return the scalar as this type, converting if 
 needed, throwing *YAMLException* if not possible.
 
 
@@ -135,16 +134,15 @@ Compiling
 To compile your project, you must give DMD the directories containing import 
 modules and the library. You also need to tell it to link with D:YAML. The import
 directory should be the D:YAML package directory. You can specify it using the 
-``-I`` option of DMD.  The library directory should point to where you put the
+``-I`` option of DMD. The library directory should be where you put the compiled
-compiled D:YAML library. On Unix/Linux you can specify it using the ``-L-L`` 
+D:YAML library. On Unix/Linux you can specify it using the ``-L-L`` option, and 
-option, and link with D:YAML using the ``-L-l`` option. On Windows, the import
+link with D:YAML using the ``-L-l`` option. On Windows, the import directory is
-directory is used as the library directory. To link with the library on Windows,
+used as the library directory. To link with the library on Windows, just add the
-just add the path to it relative to the current directory.
+path to it relative to the current directory.
 
-For example, if you extracted D:YAML to ``/home/xxx/dyaml`` and compiled it in 
+For example, if you extracted and compiled D:YAML in ``/home/xxx/dyaml``, your
-that directory, your project is in ``/home/xxx/dyaml-project``, and you are 
+project is in ``/home/xxx/dyaml-project``, and you are currently in that 
-currently in that directory, you can compile the project with the following 
+directory, you can compile the project with the following command on Unix/Linux::
-command on Unix/Linux::
 
    dmd -I../dyaml -L-L../dyaml -L-ldyaml main.d
 

doc/html/_sources/tutorials/yaml_syntax.txt

@@ -8,14 +8,14 @@ which this article is based on,
 `Chapter 2 of the YAML specification <http://yaml.org/spec/1.1/#id857168>`_
 or the `Wikipedia page <http://en.wikipedia.org/wiki/YAML>`_.
 
-YAML is a data serialization format designed to be as human readable as 
+YAML is a data serialization format designed for human readability. YAML is a 
-possible. YAML is a recursive acronym for "YAML Ain't Markup Language".
+recursive acronym for "YAML Ain't Markup Language".
 
 YAML is similar to JSON, and in fact, JSON is a subset of YAML 1.2; but YAML has
-some more advanced features and is easier to read. However, YAML is also more
+some more advanced features and is easier to read. However, it is also more
 difficult to parse (and probably somewhat slower). Data is stored in mappings
 (associative arrays), sequences (lists) and scalars (single values). Data 
-structure hierarchy either depends on indentation (block context, similar to
+structure hierarchy depends either on indentation (block context, similar to
 Python code), or nesting of brackets and braces (flow context, similar to JSON).
 YAML comments begin with ``#`` and continue until the end of line.
 
@@ -25,8 +25,7 @@ Documents
 ---------
 
 A YAML stream consists of one or more documents starting with ``---`` and
-optionally ending with ``...`` . If there is only one document, ``---`` can be
+optionally ending with ``...`` . ``---`` can be left out for the first document.
-left out.
 
 Single document with no explicit start or end:
 

doc/html/_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -213,6 +213,24 @@ p.rubric {
     font-weight: bold;
 }
 
+img.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
 .align-left {
     text-align: left;
 }
@@ -395,7 +413,7 @@ dl.glossary dt {
 }
 
 .footnote:target  {
-    background-color: #ffa
+    background-color: #ffa;
 }
 
 .line-block {
@@ -426,6 +444,7 @@ dl.glossary dt {
 
 pre {
     overflow: auto;
+    overflow-y: hidden;  /* fixes display issues on Chrome browsers */
 }
 
 td.linenos pre {

doc/html/_static/default.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- default theme.
  *
- * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -114,6 +114,7 @@ div.sphinxsidebar input {
 }
 
 
+
 /* -- hyperlink styles ------------------------------------------------------ */
 
 a {

doc/html/_static/doctools.js

@@ -4,7 +4,7 @@
  *
  * Sphinx JavaScript utilties for all documentation.
  *
- * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */

doc/html/_static/pygments.css

@@ -1,61 +1,62 @@
-.hll { background-color: #ffffcc }
+.highlight .hll { background-color: #ffffcc }
-.c { color: #408090; font-style: italic } /* Comment */
+.highlight  { background: #eeffcc; }
-.err { border: 1px solid #FF0000 } /* Error */
+.highlight .c { color: #408090; font-style: italic } /* Comment */
-.k { color: #007020; font-weight: bold } /* Keyword */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
-.o { color: #666666 } /* Operator */
+.highlight .k { color: #007020; font-weight: bold } /* Keyword */
-.cm { color: #408090; font-style: italic } /* Comment.Multiline */
+.highlight .o { color: #666666 } /* Operator */
-.cp { color: #007020 } /* Comment.Preproc */
+.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */
-.c1 { color: #408090; font-style: italic } /* Comment.Single */
+.highlight .cp { color: #007020 } /* Comment.Preproc */
-.cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
+.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */
-.gd { color: #A00000 } /* Generic.Deleted */
+.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
-.ge { font-style: italic } /* Generic.Emph */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
-.gr { color: #FF0000 } /* Generic.Error */
+.highlight .ge { font-style: italic } /* Generic.Emph */
-.gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gr { color: #FF0000 } /* Generic.Error */
-.gi { color: #00A000 } /* Generic.Inserted */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
-.go { color: #303030 } /* Generic.Output */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
-.gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
+.highlight .go { color: #303030 } /* Generic.Output */
-.gs { font-weight: bold } /* Generic.Strong */
+.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
-.gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
-.gt { color: #0040D0 } /* Generic.Traceback */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
-.kc { color: #007020; font-weight: bold } /* Keyword.Constant */
+.highlight .gt { color: #0040D0 } /* Generic.Traceback */
-.kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
+.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
-.kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
+.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
-.kp { color: #007020 } /* Keyword.Pseudo */
+.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
-.kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
+.highlight .kp { color: #007020 } /* Keyword.Pseudo */
-.kt { color: #902000 } /* Keyword.Type */
+.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
-.m { color: #208050 } /* Literal.Number */
+.highlight .kt { color: #902000 } /* Keyword.Type */
-.s { color: #4070a0 } /* Literal.String */
+.highlight .m { color: #208050 } /* Literal.Number */
-.na { color: #4070a0 } /* Name.Attribute */
+.highlight .s { color: #4070a0 } /* Literal.String */
-.nb { color: #007020 } /* Name.Builtin */
+.highlight .na { color: #4070a0 } /* Name.Attribute */
-.nc { color: #0e84b5; font-weight: bold } /* Name.Class */
+.highlight .nb { color: #007020 } /* Name.Builtin */
-.no { color: #60add5 } /* Name.Constant */
+.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
-.nd { color: #555555; font-weight: bold } /* Name.Decorator */
+.highlight .no { color: #60add5 } /* Name.Constant */
-.ni { color: #d55537; font-weight: bold } /* Name.Entity */
+.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */
-.ne { color: #007020 } /* Name.Exception */
+.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */
-.nf { color: #06287e } /* Name.Function */
+.highlight .ne { color: #007020 } /* Name.Exception */
-.nl { color: #002070; font-weight: bold } /* Name.Label */
+.highlight .nf { color: #06287e } /* Name.Function */
-.nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
+.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */
-.nt { color: #062873; font-weight: bold } /* Name.Tag */
+.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
-.nv { color: #bb60d5 } /* Name.Variable */
+.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */
-.ow { color: #007020; font-weight: bold } /* Operator.Word */
+.highlight .nv { color: #bb60d5 } /* Name.Variable */
-.w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */
-.mf { color: #208050 } /* Literal.Number.Float */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
-.mh { color: #208050 } /* Literal.Number.Hex */
+.highlight .mf { color: #208050 } /* Literal.Number.Float */
-.mi { color: #208050 } /* Literal.Number.Integer */
+.highlight .mh { color: #208050 } /* Literal.Number.Hex */
-.mo { color: #208050 } /* Literal.Number.Oct */
+.highlight .mi { color: #208050 } /* Literal.Number.Integer */
-.sb { color: #4070a0 } /* Literal.String.Backtick */
+.highlight .mo { color: #208050 } /* Literal.Number.Oct */
-.sc { color: #4070a0 } /* Literal.String.Char */
+.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */
-.sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
+.highlight .sc { color: #4070a0 } /* Literal.String.Char */
-.s2 { color: #4070a0 } /* Literal.String.Double */
+.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
-.se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
+.highlight .s2 { color: #4070a0 } /* Literal.String.Double */
-.sh { color: #4070a0 } /* Literal.String.Heredoc */
+.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
-.si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
+.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */
-.sx { color: #c65d09 } /* Literal.String.Other */
+.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
-.sr { color: #235388 } /* Literal.String.Regex */
+.highlight .sx { color: #c65d09 } /* Literal.String.Other */
-.s1 { color: #4070a0 } /* Literal.String.Single */
+.highlight .sr { color: #235388 } /* Literal.String.Regex */
-.ss { color: #517918 } /* Literal.String.Symbol */
+.highlight .s1 { color: #4070a0 } /* Literal.String.Single */
-.bp { color: #007020 } /* Name.Builtin.Pseudo */
+.highlight .ss { color: #517918 } /* Literal.String.Symbol */
-.vc { color: #bb60d5 } /* Name.Variable.Class */
+.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
-.vg { color: #bb60d5 } /* Name.Variable.Global */
+.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */
-.vi { color: #bb60d5 } /* Name.Variable.Instance */
+.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */
-.il { color: #208050 } /* Literal.Number.Integer.Long */
+.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */
+.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */

doc/html/_static/searchtools.js

@@ -4,7 +4,7 @@
  *
  * Sphinx JavaScript utilties for the full-text search.
  *
- * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -489,7 +489,7 @@ var Search = {
             listItem.slideDown(5, function() {
               displayNextItem();
             });
-          });
+          }, "text");
         } else {
           // no source available, just display title
           Search.output.append(listItem);

doc/html/_static/sidebar.js

@@ -16,7 +16,7 @@
  * Once the browser is closed the cookie is deleted and the position
  * reset to the default (expanded).
  *
- * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -91,6 +91,7 @@ $(function() {
         '<div id="sidebarbutton"><span>&laquo;</span></div>'
     );
     var sidebarbutton = $('#sidebarbutton');
+    light_color = sidebarbutton.css('background-color');
     // find the height of the viewport to center the '<<' in the page
     var viewport_height;
     if (window.innerHeight)
@@ -144,4 +145,4 @@ $(function() {
   add_sidebar_button();
   var sidebarbutton = $('#sidebarbutton');
   set_position_from_cookie();
-});
+});

doc/html/_static/underscore.js

@@ -1,16 +1,807 @@
-(function(){var j=this,n=j._,i=function(a){this._wrapped=a},m=typeof StopIteration!=="undefined"?StopIteration:"__break__",b=j._=function(a){return new i(a)};if(typeof exports!=="undefined")exports._=b;var k=Array.prototype.slice,o=Array.prototype.unshift,p=Object.prototype.toString,q=Object.prototype.hasOwnProperty,r=Object.prototype.propertyIsEnumerable;b.VERSION="0.5.5";b.each=function(a,c,d){try{if(a.forEach)a.forEach(c,d);else if(b.isArray(a)||b.isArguments(a))for(var e=0,f=a.length;e<f;e++)c.call(d,
+//     Underscore.js 1.1.6
-a[e],e,a);else{var g=b.keys(a);f=g.length;for(e=0;e<f;e++)c.call(d,a[g[e]],g[e],a)}}catch(h){if(h!=m)throw h;}return a};b.map=function(a,c,d){if(a&&b.isFunction(a.map))return a.map(c,d);var e=[];b.each(a,function(f,g,h){e.push(c.call(d,f,g,h))});return e};b.reduce=function(a,c,d,e){if(a&&b.isFunction(a.reduce))return a.reduce(b.bind(d,e),c);b.each(a,function(f,g,h){c=d.call(e,c,f,g,h)});return c};b.reduceRight=function(a,c,d,e){if(a&&b.isFunction(a.reduceRight))return a.reduceRight(b.bind(d,e),c);
+//     (c) 2011 Jeremy Ashkenas, DocumentCloud Inc.
-var f=b.clone(b.toArray(a)).reverse();b.each(f,function(g,h){c=d.call(e,c,g,h,a)});return c};b.detect=function(a,c,d){var e;b.each(a,function(f,g,h){if(c.call(d,f,g,h)){e=f;b.breakLoop()}});return e};b.select=function(a,c,d){if(a&&b.isFunction(a.filter))return a.filter(c,d);var e=[];b.each(a,function(f,g,h){c.call(d,f,g,h)&&e.push(f)});return e};b.reject=function(a,c,d){var e=[];b.each(a,function(f,g,h){!c.call(d,f,g,h)&&e.push(f)});return e};b.all=function(a,c,d){c=c||b.identity;if(a&&b.isFunction(a.every))return a.every(c,
+//     Underscore is freely distributable under the MIT license.
-d);var e=true;b.each(a,function(f,g,h){(e=e&&c.call(d,f,g,h))||b.breakLoop()});return e};b.any=function(a,c,d){c=c||b.identity;if(a&&b.isFunction(a.some))return a.some(c,d);var e=false;b.each(a,function(f,g,h){if(e=c.call(d,f,g,h))b.breakLoop()});return e};b.include=function(a,c){if(b.isArray(a))return b.indexOf(a,c)!=-1;var d=false;b.each(a,function(e){if(d=e===c)b.breakLoop()});return d};b.invoke=function(a,c){var d=b.rest(arguments,2);return b.map(a,function(e){return(c?e[c]:e).apply(e,d)})};b.pluck=
+//     Portions of Underscore are inspired or borrowed from Prototype,
-function(a,c){return b.map(a,function(d){return d[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a))return Math.max.apply(Math,a);var e={computed:-Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;g>=e.computed&&(e={value:f,computed:g})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);var e={computed:Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;g<e.computed&&(e={value:f,computed:g})});return e.value};b.sortBy=function(a,c,d){return b.pluck(b.map(a,
+//     Oliver Steele's Functional, and John Resig's Micro-Templating.
-function(e,f,g){return{value:e,criteria:c.call(d,e,f,g)}}).sort(function(e,f){e=e.criteria;f=f.criteria;return e<f?-1:e>f?1:0}),"value")};b.sortedIndex=function(a,c,d){d=d||b.identity;for(var e=0,f=a.length;e<f;){var g=e+f>>1;d(a[g])<d(c)?(e=g+1):(f=g)}return e};b.toArray=function(a){if(!a)return[];if(a.toArray)return a.toArray();if(b.isArray(a))return a;if(b.isArguments(a))return k.call(a);return b.values(a)};b.size=function(a){return b.toArray(a).length};b.first=function(a,c,d){return c&&!d?k.call(a,
+//     For all details and documentation:
-0,c):a[0]};b.rest=function(a,c,d){return k.call(a,b.isUndefined(c)||d?1:c)};b.last=function(a){return a[a.length-1]};b.compact=function(a){return b.select(a,function(c){return!!c})};b.flatten=function(a){return b.reduce(a,[],function(c,d){if(b.isArray(d))return c.concat(b.flatten(d));c.push(d);return c})};b.without=function(a){var c=b.rest(arguments);return b.select(a,function(d){return!b.include(c,d)})};b.uniq=function(a,c){return b.reduce(a,[],function(d,e,f){if(0==f||(c===true?b.last(d)!=e:!b.include(d,
+//     http://documentcloud.github.com/underscore
-e)))d.push(e);return d})};b.intersect=function(a){var c=b.rest(arguments);return b.select(b.uniq(a),function(d){return b.all(c,function(e){return b.indexOf(e,d)>=0})})};b.zip=function(){for(var a=b.toArray(arguments),c=b.max(b.pluck(a,"length")),d=new Array(c),e=0;e<c;e++)d[e]=b.pluck(a,String(e));return d};b.indexOf=function(a,c){if(a.indexOf)return a.indexOf(c);for(var d=0,e=a.length;d<e;d++)if(a[d]===c)return d;return-1};b.lastIndexOf=function(a,c){if(a.lastIndexOf)return a.lastIndexOf(c);for(var d=
+
-a.length;d--;)if(a[d]===c)return d;return-1};b.range=function(a,c,d){var e=b.toArray(arguments),f=e.length<=1;a=f?0:e[0];c=f?e[0]:e[1];d=e[2]||1;e=Math.ceil((c-a)/d);if(e<=0)return[];e=new Array(e);f=a;for(var g=0;1;f+=d){if((d>0?f-c:c-f)>=0)return e;e[g++]=f}};b.bind=function(a,c){var d=b.rest(arguments,2);return function(){return a.apply(c||j,d.concat(b.toArray(arguments)))}};b.bindAll=function(a){var c=b.rest(arguments);if(c.length==0)c=b.functions(a);b.each(c,function(d){a[d]=b.bind(a[d],a)});
+(function() {
-return a};b.delay=function(a,c){var d=b.rest(arguments,2);return setTimeout(function(){return a.apply(a,d)},c)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(b.rest(arguments)))};b.wrap=function(a,c){return function(){var d=[a].concat(b.toArray(arguments));return c.apply(c,d)}};b.compose=function(){var a=b.toArray(arguments);return function(){for(var c=b.toArray(arguments),d=a.length-1;d>=0;d--)c=[a[d].apply(this,c)];return c[0]}};b.keys=function(a){if(b.isArray(a))return b.range(0,a.length);
+
-var c=[];for(var d in a)q.call(a,d)&&c.push(d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=function(a){return b.select(b.keys(a),function(c){return b.isFunction(a[c])}).sort()};b.extend=function(a,c){for(var d in c)a[d]=c[d];return a};b.clone=function(a){if(b.isArray(a))return a.slice(0);return b.extend({},a)};b.tap=function(a,c){c(a);return a};b.isEqual=function(a,c){if(a===c)return true;var d=typeof a;if(d!=typeof c)return false;if(a==c)return true;if(!a&&c||a&&!c)return false;
+  // Baseline setup
-if(a.isEqual)return a.isEqual(c);if(b.isDate(a)&&b.isDate(c))return a.getTime()===c.getTime();if(b.isNaN(a)&&b.isNaN(c))return true;if(b.isRegExp(a)&&b.isRegExp(c))return a.source===c.source&&a.global===c.global&&a.ignoreCase===c.ignoreCase&&a.multiline===c.multiline;if(d!=="object")return false;if(a.length&&a.length!==c.length)return false;d=b.keys(a);var e=b.keys(c);if(d.length!=e.length)return false;for(var f in a)if(!b.isEqual(a[f],c[f]))return false;return true};b.isEmpty=function(a){return b.keys(a).length==
+  // --------------
-0};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=function(a){return!!(a&&a.concat&&a.unshift)};b.isArguments=function(a){return a&&b.isNumber(a.length)&&!b.isArray(a)&&!r.call(a,"length")};b.isFunction=function(a){return!!(a&&a.constructor&&a.call&&a.apply)};b.isString=function(a){return!!(a===""||a&&a.charCodeAt&&a.substr)};b.isNumber=function(a){return p.call(a)==="[object Number]"};b.isDate=function(a){return!!(a&&a.getTimezoneOffset&&a.setUTCFullYear)};b.isRegExp=function(a){return!!(a&&
+
-a.test&&a.exec&&(a.ignoreCase||a.ignoreCase===false))};b.isNaN=function(a){return b.isNumber(a)&&isNaN(a)};b.isNull=function(a){return a===null};b.isUndefined=function(a){return typeof a=="undefined"};b.noConflict=function(){j._=n;return this};b.identity=function(a){return a};b.breakLoop=function(){throw m;};var s=0;b.uniqueId=function(a){var c=s++;return a?a+c:c};b.template=function(a,c){a=new Function("obj","var p=[],print=function(){p.push.apply(p,arguments);};with(obj){p.push('"+a.replace(/[\r\t\n]/g,
+  // Establish the root object, `window` in the browser, or `global` on the server.
-" ").replace(/'(?=[^%]*%>)/g,"\t").split("'").join("\\'").split("\t").join("'").replace(/<%=(.+?)%>/g,"',$1,'").split("<%").join("');").split("%>").join("p.push('")+"');}return p.join('');");return c?a(c):a};b.forEach=b.each;b.foldl=b.inject=b.reduce;b.foldr=b.reduceRight;b.filter=b.select;b.every=b.all;b.some=b.any;b.head=b.first;b.tail=b.rest;b.methods=b.functions;var l=function(a,c){return c?b(a).chain():a};b.each(b.functions(b),function(a){var c=b[a];i.prototype[a]=function(){var d=b.toArray(arguments);
+  var root = this;
-o.call(d,this._wrapped);return l(c.apply(b,d),this._chain)}});b.each(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){c.apply(this._wrapped,arguments);return l(this._wrapped,this._chain)}});b.each(["concat","join","slice"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){return l(c.apply(this._wrapped,arguments),this._chain)}});i.prototype.chain=function(){this._chain=true;return this};i.prototype.value=function(){return this._wrapped}})();
+
+  // Save the previous value of the `_` variable.
+  var previousUnderscore = root._;
+
+  // Establish the object that gets returned to break out of a loop iteration.
+  var breaker = {};
+
+  // Save bytes in the minified (but not gzipped) version:
+  var ArrayProto = Array.prototype, ObjProto = Object.prototype, FuncProto = Function.prototype;
+
+  // Create quick reference variables for speed access to core prototypes.
+  var slice            = ArrayProto.slice,
+      unshift          = ArrayProto.unshift,
+      toString         = ObjProto.toString,
+      hasOwnProperty   = ObjProto.hasOwnProperty;
+
+  // All **ECMAScript 5** native function implementations that we hope to use
+  // are declared here.
+  var
+    nativeForEach      = ArrayProto.forEach,
+    nativeMap          = ArrayProto.map,
+    nativeReduce       = ArrayProto.reduce,
+    nativeReduceRight  = ArrayProto.reduceRight,
+    nativeFilter       = ArrayProto.filter,
+    nativeEvery        = ArrayProto.every,
+    nativeSome         = ArrayProto.some,
+    nativeIndexOf      = ArrayProto.indexOf,
+    nativeLastIndexOf  = ArrayProto.lastIndexOf,
+    nativeIsArray      = Array.isArray,
+    nativeKeys         = Object.keys,
+    nativeBind         = FuncProto.bind;
+
+  // Create a safe reference to the Underscore object for use below.
+  var _ = function(obj) { return new wrapper(obj); };
+
+  // Export the Underscore object for **CommonJS**, with backwards-compatibility
+  // for the old `require()` API. If we're not in CommonJS, add `_` to the
+  // global object.
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = _;
+    _._ = _;
+  } else {
+    root._ = _;
+  }
+
+  // Current version.
+  _.VERSION = '1.1.6';
+
+  // Collection Functions
+  // --------------------
+
+  // The cornerstone, an `each` implementation, aka `forEach`.
+  // Handles objects implementing `forEach`, arrays, and raw objects.
+  // Delegates to **ECMAScript 5**'s native `forEach` if available.
+  var each = _.each = _.forEach = function(obj, iterator, context) {
+    if (obj == null) return;
+    if (nativeForEach && obj.forEach === nativeForEach) {
+      obj.forEach(iterator, context);
+    } else if (_.isNumber(obj.length)) {
+      for (var i = 0, l = obj.length; i < l; i++) {
+        if (iterator.call(context, obj[i], i, obj) === breaker) return;
+      }
+    } else {
+      for (var key in obj) {
+        if (hasOwnProperty.call(obj, key)) {
+          if (iterator.call(context, obj[key], key, obj) === breaker) return;
+        }
+      }
+    }
+  };
+
+  // Return the results of applying the iterator to each element.
+  // Delegates to **ECMAScript 5**'s native `map` if available.
+  _.map = function(obj, iterator, context) {
+    var results = [];
+    if (obj == null) return results;
+    if (nativeMap && obj.map === nativeMap) return obj.map(iterator, context);
+    each(obj, function(value, index, list) {
+      results[results.length] = iterator.call(context, value, index, list);
+    });
+    return results;
+  };
+
+  // **Reduce** builds up a single result from a list of values, aka `inject`,
+  // or `foldl`. Delegates to **ECMAScript 5**'s native `reduce` if available.
+  _.reduce = _.foldl = _.inject = function(obj, iterator, memo, context) {
+    var initial = memo !== void 0;
+    if (obj == null) obj = [];
+    if (nativeReduce && obj.reduce === nativeReduce) {
+      if (context) iterator = _.bind(iterator, context);
+      return initial ? obj.reduce(iterator, memo) : obj.reduce(iterator);
+    }
+    each(obj, function(value, index, list) {
+      if (!initial && index === 0) {
+        memo = value;
+        initial = true;
+      } else {
+        memo = iterator.call(context, memo, value, index, list);
+      }
+    });
+    if (!initial) throw new TypeError("Reduce of empty array with no initial value");
+    return memo;
+  };
+
+  // The right-associative version of reduce, also known as `foldr`.
+  // Delegates to **ECMAScript 5**'s native `reduceRight` if available.
+  _.reduceRight = _.foldr = function(obj, iterator, memo, context) {
+    if (obj == null) obj = [];
+    if (nativeReduceRight && obj.reduceRight === nativeReduceRight) {
+      if (context) iterator = _.bind(iterator, context);
+      return memo !== void 0 ? obj.reduceRight(iterator, memo) : obj.reduceRight(iterator);
+    }
+    var reversed = (_.isArray(obj) ? obj.slice() : _.toArray(obj)).reverse();
+    return _.reduce(reversed, iterator, memo, context);
+  };
+
+  // Return the first value which passes a truth test. Aliased as `detect`.
+  _.find = _.detect = function(obj, iterator, context) {
+    var result;
+    any(obj, function(value, index, list) {
+      if (iterator.call(context, value, index, list)) {
+        result = value;
+        return true;
+      }
+    });
+    return result;
+  };
+
+  // Return all the elements that pass a truth test.
+  // Delegates to **ECMAScript 5**'s native `filter` if available.
+  // Aliased as `select`.
+  _.filter = _.select = function(obj, iterator, context) {
+    var results = [];
+    if (obj == null) return results;
+    if (nativeFilter && obj.filter === nativeFilter) return obj.filter(iterator, context);
+    each(obj, function(value, index, list) {
+      if (iterator.call(context, value, index, list)) results[results.length] = value;
+    });
+    return results;
+  };
+
+  // Return all the elements for which a truth test fails.
+  _.reject = function(obj, iterator, context) {
+    var results = [];
+    if (obj == null) return results;
+    each(obj, function(value, index, list) {
+      if (!iterator.call(context, value, index, list)) results[results.length] = value;
+    });
+    return results;
+  };
+
+  // Determine whether all of the elements match a truth test.
+  // Delegates to **ECMAScript 5**'s native `every` if available.
+  // Aliased as `all`.
+  _.every = _.all = function(obj, iterator, context) {
+    var result = true;
+    if (obj == null) return result;
+    if (nativeEvery && obj.every === nativeEvery) return obj.every(iterator, context);
+    each(obj, function(value, index, list) {
+      if (!(result = result && iterator.call(context, value, index, list))) return breaker;
+    });
+    return result;
+  };
+
+  // Determine if at least one element in the object matches a truth test.
+  // Delegates to **ECMAScript 5**'s native `some` if available.
+  // Aliased as `any`.
+  var any = _.some = _.any = function(obj, iterator, context) {
+    iterator || (iterator = _.identity);
+    var result = false;
+    if (obj == null) return result;
+    if (nativeSome && obj.some === nativeSome) return obj.some(iterator, context);
+    each(obj, function(value, index, list) {
+      if (result = iterator.call(context, value, index, list)) return breaker;
+    });
+    return result;
+  };
+
+  // Determine if a given value is included in the array or object using `===`.
+  // Aliased as `contains`.
+  _.include = _.contains = function(obj, target) {
+    var found = false;
+    if (obj == null) return found;
+    if (nativeIndexOf && obj.indexOf === nativeIndexOf) return obj.indexOf(target) != -1;
+    any(obj, function(value) {
+      if (found = value === target) return true;
+    });
+    return found;
+  };
+
+  // Invoke a method (with arguments) on every item in a collection.
+  _.invoke = function(obj, method) {
+    var args = slice.call(arguments, 2);
+    return _.map(obj, function(value) {
+      return (method.call ? method || value : value[method]).apply(value, args);
+    });
+  };
+
+  // Convenience version of a common use case of `map`: fetching a property.
+  _.pluck = function(obj, key) {
+    return _.map(obj, function(value){ return value[key]; });
+  };
+
+  // Return the maximum element or (element-based computation).
+  _.max = function(obj, iterator, context) {
+    if (!iterator && _.isArray(obj)) return Math.max.apply(Math, obj);
+    var result = {computed : -Infinity};
+    each(obj, function(value, index, list) {
+      var computed = iterator ? iterator.call(context, value, index, list) : value;
+      computed >= result.computed && (result = {value : value, computed : computed});
+    });
+    return result.value;
+  };
+
+  // Return the minimum element (or element-based computation).
+  _.min = function(obj, iterator, context) {
+    if (!iterator && _.isArray(obj)) return Math.min.apply(Math, obj);
+    var result = {computed : Infinity};
+    each(obj, function(value, index, list) {
+      var computed = iterator ? iterator.call(context, value, index, list) : value;
+      computed < result.computed && (result = {value : value, computed : computed});
+    });
+    return result.value;
+  };
+
+  // Sort the object's values by a criterion produced by an iterator.
+  _.sortBy = function(obj, iterator, context) {
+    return _.pluck(_.map(obj, function(value, index, list) {
+      return {
+        value : value,
+        criteria : iterator.call(context, value, index, list)
+      };
+    }).sort(function(left, right) {
+      var a = left.criteria, b = right.criteria;
+      return a < b ? -1 : a > b ? 1 : 0;
+    }), 'value');
+  };
+
+  // Use a comparator function to figure out at what index an object should
+  // be inserted so as to maintain order. Uses binary search.
+  _.sortedIndex = function(array, obj, iterator) {
+    iterator || (iterator = _.identity);
+    var low = 0, high = array.length;
+    while (low < high) {
+      var mid = (low + high) >> 1;
+      iterator(array[mid]) < iterator(obj) ? low = mid + 1 : high = mid;
+    }
+    return low;
+  };
+
+  // Safely convert anything iterable into a real, live array.
+  _.toArray = function(iterable) {
+    if (!iterable)                return [];
+    if (iterable.toArray)         return iterable.toArray();
+    if (_.isArray(iterable))      return iterable;
+    if (_.isArguments(iterable))  return slice.call(iterable);
+    return _.values(iterable);
+  };
+
+  // Return the number of elements in an object.
+  _.size = function(obj) {
+    return _.toArray(obj).length;
+  };
+
+  // Array Functions
+  // ---------------
+
+  // Get the first element of an array. Passing **n** will return the first N
+  // values in the array. Aliased as `head`. The **guard** check allows it to work
+  // with `_.map`.
+  _.first = _.head = function(array, n, guard) {
+    return (n != null) && !guard ? slice.call(array, 0, n) : array[0];
+  };
+
+  // Returns everything but the first entry of the array. Aliased as `tail`.
+  // Especially useful on the arguments object. Passing an **index** will return
+  // the rest of the values in the array from that index onward. The **guard**
+  // check allows it to work with `_.map`.
+  _.rest = _.tail = function(array, index, guard) {
+    return slice.call(array, (index == null) || guard ? 1 : index);
+  };
+
+  // Get the last element of an array.
+  _.last = function(array) {
+    return array[array.length - 1];
+  };
+
+  // Trim out all falsy values from an array.
+  _.compact = function(array) {
+    return _.filter(array, function(value){ return !!value; });
+  };
+
+  // Return a completely flattened version of an array.
+  _.flatten = function(array) {
+    return _.reduce(array, function(memo, value) {
+      if (_.isArray(value)) return memo.concat(_.flatten(value));
+      memo[memo.length] = value;
+      return memo;
+    }, []);
+  };
+
+  // Return a version of the array that does not contain the specified value(s).
+  _.without = function(array) {
+    var values = slice.call(arguments, 1);
+    return _.filter(array, function(value){ return !_.include(values, value); });
+  };
+
+  // Produce a duplicate-free version of the array. If the array has already
+  // been sorted, you have the option of using a faster algorithm.
+  // Aliased as `unique`.
+  _.uniq = _.unique = function(array, isSorted) {
+    return _.reduce(array, function(memo, el, i) {
+      if (0 == i || (isSorted === true ? _.last(memo) != el : !_.include(memo, el))) memo[memo.length] = el;
+      return memo;
+    }, []);
+  };
+
+  // Produce an array that contains every item shared between all the
+  // passed-in arrays.
+  _.intersect = function(array) {
+    var rest = slice.call(arguments, 1);
+    return _.filter(_.uniq(array), function(item) {
+      return _.every(rest, function(other) {
+        return _.indexOf(other, item) >= 0;
+      });
+    });
+  };
+
+  // Zip together multiple lists into a single array -- elements that share
+  // an index go together.
+  _.zip = function() {
+    var args = slice.call(arguments);
+    var length = _.max(_.pluck(args, 'length'));
+    var results = new Array(length);
+    for (var i = 0; i < length; i++) results[i] = _.pluck(args, "" + i);
+    return results;
+  };
+
+  // If the browser doesn't supply us with indexOf (I'm looking at you, **MSIE**),
+  // we need this function. Return the position of the first occurrence of an
+  // item in an array, or -1 if the item is not included in the array.
+  // Delegates to **ECMAScript 5**'s native `indexOf` if available.
+  // If the array is large and already in sort order, pass `true`
+  // for **isSorted** to use binary search.
+  _.indexOf = function(array, item, isSorted) {
+    if (array == null) return -1;
+    var i, l;
+    if (isSorted) {
+      i = _.sortedIndex(array, item);
+      return array[i] === item ? i : -1;
+    }
+    if (nativeIndexOf && array.indexOf === nativeIndexOf) return array.indexOf(item);
+    for (i = 0, l = array.length; i < l; i++) if (array[i] === item) return i;
+    return -1;
+  };
+
+
+  // Delegates to **ECMAScript 5**'s native `lastIndexOf` if available.
+  _.lastIndexOf = function(array, item) {
+    if (array == null) return -1;
+    if (nativeLastIndexOf && array.lastIndexOf === nativeLastIndexOf) return array.lastIndexOf(item);
+    var i = array.length;
+    while (i--) if (array[i] === item) return i;
+    return -1;
+  };
+
+  // Generate an integer Array containing an arithmetic progression. A port of
+  // the native Python `range()` function. See
+  // [the Python documentation](http://docs.python.org/library/functions.html#range).
+  _.range = function(start, stop, step) {
+    if (arguments.length <= 1) {
+      stop = start || 0;
+      start = 0;
+    }
+    step = arguments[2] || 1;
+
+    var len = Math.max(Math.ceil((stop - start) / step), 0);
+    var idx = 0;
+    var range = new Array(len);
+
+    while(idx < len) {
+      range[idx++] = start;
+      start += step;
+    }
+
+    return range;
+  };
+
+  // Function (ahem) Functions
+  // ------------------
+
+  // Create a function bound to a given object (assigning `this`, and arguments,
+  // optionally). Binding with arguments is also known as `curry`.
+  // Delegates to **ECMAScript 5**'s native `Function.bind` if available.
+  // We check for `func.bind` first, to fail fast when `func` is undefined.
+  _.bind = function(func, obj) {
+    if (func.bind === nativeBind && nativeBind) return nativeBind.apply(func, slice.call(arguments, 1));
+    var args = slice.call(arguments, 2);
+    return function() {
+      return func.apply(obj, args.concat(slice.call(arguments)));
+    };
+  };
+
+  // Bind all of an object's methods to that object. Useful for ensuring that
+  // all callbacks defined on an object belong to it.
+  _.bindAll = function(obj) {
+    var funcs = slice.call(arguments, 1);
+    if (funcs.length == 0) funcs = _.functions(obj);
+    each(funcs, function(f) { obj[f] = _.bind(obj[f], obj); });
+    return obj;
+  };
+
+  // Memoize an expensive function by storing its results.
+  _.memoize = function(func, hasher) {
+    var memo = {};
+    hasher || (hasher = _.identity);
+    return function() {
+      var key = hasher.apply(this, arguments);
+      return hasOwnProperty.call(memo, key) ? memo[key] : (memo[key] = func.apply(this, arguments));
+    };
+  };
+
+  // Delays a function for the given number of milliseconds, and then calls
+  // it with the arguments supplied.
+  _.delay = function(func, wait) {
+    var args = slice.call(arguments, 2);
+    return setTimeout(function(){ return func.apply(func, args); }, wait);
+  };
+
+  // Defers a function, scheduling it to run after the current call stack has
+  // cleared.
+  _.defer = function(func) {
+    return _.delay.apply(_, [func, 1].concat(slice.call(arguments, 1)));
+  };
+
+  // Internal function used to implement `_.throttle` and `_.debounce`.
+  var limit = function(func, wait, debounce) {
+    var timeout;
+    return function() {
+      var context = this, args = arguments;
+      var throttler = function() {
+        timeout = null;
+        func.apply(context, args);
+      };
+      if (debounce) clearTimeout(timeout);
+      if (debounce || !timeout) timeout = setTimeout(throttler, wait);
+    };
+  };
+
+  // Returns a function, that, when invoked, will only be triggered at most once
+  // during a given window of time.
+  _.throttle = function(func, wait) {
+    return limit(func, wait, false);
+  };
+
+  // Returns a function, that, as long as it continues to be invoked, will not
+  // be triggered. The function will be called after it stops being called for
+  // N milliseconds.
+  _.debounce = function(func, wait) {
+    return limit(func, wait, true);
+  };
+
+  // Returns a function that will be executed at most one time, no matter how
+  // often you call it. Useful for lazy initialization.
+  _.once = function(func) {
+    var ran = false, memo;
+    return function() {
+      if (ran) return memo;
+      ran = true;
+      return memo = func.apply(this, arguments);
+    };
+  };
+
+  // Returns the first function passed as an argument to the second,
+  // allowing you to adjust arguments, run code before and after, and
+  // conditionally execute the original function.
+  _.wrap = function(func, wrapper) {
+    return function() {
+      var args = [func].concat(slice.call(arguments));
+      return wrapper.apply(this, args);
+    };
+  };
+
+  // Returns a function that is the composition of a list of functions, each
+  // consuming the return value of the function that follows.
+  _.compose = function() {
+    var funcs = slice.call(arguments);
+    return function() {
+      var args = slice.call(arguments);
+      for (var i=funcs.length-1; i >= 0; i--) {
+        args = [funcs[i].apply(this, args)];
+      }
+      return args[0];
+    };
+  };
+
+  // Returns a function that will only be executed after being called N times.
+  _.after = function(times, func) {
+    return function() {
+      if (--times < 1) { return func.apply(this, arguments); }
+    };
+  };
+
+
+  // Object Functions
+  // ----------------
+
+  // Retrieve the names of an object's properties.
+  // Delegates to **ECMAScript 5**'s native `Object.keys`
+  _.keys = nativeKeys || function(obj) {
+    if (obj !== Object(obj)) throw new TypeError('Invalid object');
+    var keys = [];
+    for (var key in obj) if (hasOwnProperty.call(obj, key)) keys[keys.length] = key;
+    return keys;
+  };
+
+  // Retrieve the values of an object's properties.
+  _.values = function(obj) {
+    return _.map(obj, _.identity);
+  };
+
+  // Return a sorted list of the function names available on the object.
+  // Aliased as `methods`
+  _.functions = _.methods = function(obj) {
+    return _.filter(_.keys(obj), function(key){ return _.isFunction(obj[key]); }).sort();
+  };
+
+  // Extend a given object with all the properties in passed-in object(s).
+  _.extend = function(obj) {
+    each(slice.call(arguments, 1), function(source) {
+      for (var prop in source) {
+        if (source[prop] !== void 0) obj[prop] = source[prop];
+      }
+    });
+    return obj;
+  };
+
+  // Fill in a given object with default properties.
+  _.defaults = function(obj) {
+    each(slice.call(arguments, 1), function(source) {
+      for (var prop in source) {
+        if (obj[prop] == null) obj[prop] = source[prop];
+      }
+    });
+    return obj;
+  };
+
+  // Create a (shallow-cloned) duplicate of an object.
+  _.clone = function(obj) {
+    return _.isArray(obj) ? obj.slice() : _.extend({}, obj);
+  };
+
+  // Invokes interceptor with the obj, and then returns obj.
+  // The primary purpose of this method is to "tap into" a method chain, in
+  // order to perform operations on intermediate results within the chain.
+  _.tap = function(obj, interceptor) {
+    interceptor(obj);
+    return obj;
+  };
+
+  // Perform a deep comparison to check if two objects are equal.
+  _.isEqual = function(a, b) {
+    // Check object identity.
+    if (a === b) return true;
+    // Different types?
+    var atype = typeof(a), btype = typeof(b);
+    if (atype != btype) return false;
+    // Basic equality test (watch out for coercions).
+    if (a == b) return true;
+    // One is falsy and the other truthy.
+    if ((!a && b) || (a && !b)) return false;
+    // Unwrap any wrapped objects.
+    if (a._chain) a = a._wrapped;
+    if (b._chain) b = b._wrapped;
+    // One of them implements an isEqual()?
+    if (a.isEqual) return a.isEqual(b);
+    // Check dates' integer values.
+    if (_.isDate(a) && _.isDate(b)) return a.getTime() === b.getTime();
+    // Both are NaN?
+    if (_.isNaN(a) && _.isNaN(b)) return false;
+    // Compare regular expressions.
+    if (_.isRegExp(a) && _.isRegExp(b))
+      return a.source     === b.source &&
+             a.global     === b.global &&
+             a.ignoreCase === b.ignoreCase &&
+             a.multiline  === b.multiline;
+    // If a is not an object by this point, we can't handle it.
+    if (atype !== 'object') return false;
+    // Check for different array lengths before comparing contents.
+    if (a.length && (a.length !== b.length)) return false;
+    // Nothing else worked, deep compare the contents.
+    var aKeys = _.keys(a), bKeys = _.keys(b);
+    // Different object sizes?
+    if (aKeys.length != bKeys.length) return false;
+    // Recursive comparison of contents.
+    for (var key in a) if (!(key in b) || !_.isEqual(a[key], b[key])) return false;
+    return true;
+  };
+
+  // Is a given array or object empty?
+  _.isEmpty = function(obj) {
+    if (_.isArray(obj) || _.isString(obj)) return obj.length === 0;
+    for (var key in obj) if (hasOwnProperty.call(obj, key)) return false;
+    return true;
+  };
+
+  // Is a given value a DOM element?
+  _.isElement = function(obj) {
+    return !!(obj && obj.nodeType == 1);
+  };
+
+  // Is a given value an array?
+  // Delegates to ECMA5's native Array.isArray
+  _.isArray = nativeIsArray || function(obj) {
+    return toString.call(obj) === '[object Array]';
+  };
+
+  // Is a given variable an arguments object?
+  _.isArguments = function(obj) {
+    return !!(obj && hasOwnProperty.call(obj, 'callee'));
+  };
+
+  // Is a given value a function?
+  _.isFunction = function(obj) {
+    return !!(obj && obj.constructor && obj.call && obj.apply);
+  };
+
+  // Is a given value a string?
+  _.isString = function(obj) {
+    return !!(obj === '' || (obj && obj.charCodeAt && obj.substr));
+  };
+
+  // Is a given value a number?
+  _.isNumber = function(obj) {
+    return !!(obj === 0 || (obj && obj.toExponential && obj.toFixed));
+  };
+
+  // Is the given value `NaN`? `NaN` happens to be the only value in JavaScript
+  // that does not equal itself.
+  _.isNaN = function(obj) {
+    return obj !== obj;
+  };
+
+  // Is a given value a boolean?
+  _.isBoolean = function(obj) {
+    return obj === true || obj === false;
+  };
+
+  // Is a given value a date?
+  _.isDate = function(obj) {
+    return !!(obj && obj.getTimezoneOffset && obj.setUTCFullYear);
+  };
+
+  // Is the given value a regular expression?
+  _.isRegExp = function(obj) {
+    return !!(obj && obj.test && obj.exec && (obj.ignoreCase || obj.ignoreCase === false));
+  };
+
+  // Is a given value equal to null?
+  _.isNull = function(obj) {
+    return obj === null;
+  };
+
+  // Is a given variable undefined?
+  _.isUndefined = function(obj) {
+    return obj === void 0;
+  };
+
+  // Utility Functions
+  // -----------------
+
+  // Run Underscore.js in *noConflict* mode, returning the `_` variable to its
+  // previous owner. Returns a reference to the Underscore object.
+  _.noConflict = function() {
+    root._ = previousUnderscore;
+    return this;
+  };
+
+  // Keep the identity function around for default iterators.
+  _.identity = function(value) {
+    return value;
+  };
+
+  // Run a function **n** times.
+  _.times = function (n, iterator, context) {
+    for (var i = 0; i < n; i++) iterator.call(context, i);
+  };
+
+  // Add your own custom functions to the Underscore object, ensuring that
+  // they're correctly added to the OOP wrapper as well.
+  _.mixin = function(obj) {
+    each(_.functions(obj), function(name){
+      addToWrapper(name, _[name] = obj[name]);
+    });
+  };
+
+  // Generate a unique integer id (unique within the entire client session).
+  // Useful for temporary DOM ids.
+  var idCounter = 0;
+  _.uniqueId = function(prefix) {
+    var id = idCounter++;
+    return prefix ? prefix + id : id;
+  };
+
+  // By default, Underscore uses ERB-style template delimiters, change the
+  // following template settings to use alternative delimiters.
+  _.templateSettings = {
+    evaluate    : /<%([\s\S]+?)%>/g,
+    interpolate : /<%=([\s\S]+?)%>/g
+  };
+
+  // JavaScript micro-templating, similar to John Resig's implementation.
+  // Underscore templating handles arbitrary delimiters, preserves whitespace,
+  // and correctly escapes quotes within interpolated code.
+  _.template = function(str, data) {
+    var c  = _.templateSettings;
+    var tmpl = 'var __p=[],print=function(){__p.push.apply(__p,arguments);};' +
+      'with(obj||{}){__p.push(\'' +
+      str.replace(/\\/g, '\\\\')
+         .replace(/'/g, "\\'")
+         .replace(c.interpolate, function(match, code) {
+           return "'," + code.replace(/\\'/g, "'") + ",'";
+         })
+         .replace(c.evaluate || null, function(match, code) {
+           return "');" + code.replace(/\\'/g, "'")
+                              .replace(/[\r\n\t]/g, ' ') + "__p.push('";
+         })
+         .replace(/\r/g, '\\r')
+         .replace(/\n/g, '\\n')
+         .replace(/\t/g, '\\t')
+         + "');}return __p.join('');";
+    var func = new Function('obj', tmpl);
+    return data ? func(data) : func;
+  };
+
+  // The OOP Wrapper
+  // ---------------
+
+  // If Underscore is called as a function, it returns a wrapped object that
+  // can be used OO-style. This wrapper holds altered versions of all the
+  // underscore functions. Wrapped objects may be chained.
+  var wrapper = function(obj) { this._wrapped = obj; };
+
+  // Expose `wrapper.prototype` as `_.prototype`
+  _.prototype = wrapper.prototype;
+
+  // Helper function to continue chaining intermediate results.
+  var result = function(obj, chain) {
+    return chain ? _(obj).chain() : obj;
+  };
+
+  // A method to easily add functions to the OOP wrapper.
+  var addToWrapper = function(name, func) {
+    wrapper.prototype[name] = function() {
+      var args = slice.call(arguments);
+      unshift.call(args, this._wrapped);
+      return result(func.apply(_, args), this._chain);
+    };
+  };
+
+  // Add all of the Underscore functions to the wrapper object.
+  _.mixin(_);
+
+  // Add all mutator Array functions to the wrapper.
+  each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) {
+    var method = ArrayProto[name];
+    wrapper.prototype[name] = function() {
+      method.apply(this._wrapped, arguments);
+      return result(this._wrapped, this._chain);
+    };
+  });
+
+  // Add all accessor Array functions to the wrapper.
+  each(['concat', 'join', 'slice'], function(name) {
+    var method = ArrayProto[name];
+    wrapper.prototype[name] = function() {
+      return result(method.apply(this._wrapped, arguments), this._chain);
+    };
+  });
+
+  // Start chaining a wrapped Underscore object.
+  wrapper.prototype.chain = function() {
+    this._chain = true;
+    return this;
+  };
+
+  // Extracts the result from a wrapped and chained object.
+  wrapper.prototype.value = function() {
+    return this._wrapped;
+  };
+
+})();

doc/html/api/dyaml.constructor.html

@@ -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>

doc/html/api/dyaml.dumper.html

@@ -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>

doc/html/api/dyaml.encoding.html

@@ -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>

doc/html/api/dyaml.exception.html

@@ -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>
+<p>Exceptions thrown by D:YAML and exception related code.</p>
-YAML exceptions and <a name="exception"></a><span class="ddoc_psymbol">exception</span> 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>

doc/html/api/dyaml.linebreak.html

@@ -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>

doc/html/api/dyaml.loader.html

@@ -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.
+<p>User specified Constructor and/or Resolver can be used to support new
- Use <a href="#loadAll"><span class="d_inlinecode">loadAll</span></a> for such files.
+ tags / data types.
 
 </p>
-<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>string <b>filename</b></td>
+<b>Examples:</b><div class="pbr">Load single YAML document from a file:
-<td valign=top>Name of the file to load from.</td></tr>
+<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();
-</table></div>
+ ...
-<b>Returns:</b><div class="pbr">Root node of the document.
+</pre>
 
-</div>
+ Load all YAML documents from a file:
-<b>Throws:</b><div class="pbr">YAMLException if there wasn't exactly one document in the 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();
-          the file could not be opened or on a YAML parsing error.</div>
+ ...
+</pre>
 
-</dd>
+ Iterate over YAML documents in a file, lazily loading them:
-<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;");
+<pre class="d_code"> <span class="d_keyword">auto</span> loader = <span class="d_psymbol">Loader</span>(<span class="d_string">"file.yaml"</span>);
-</dt>
-<dd><p>Load single YAML document from a stream.
-</p>
-<p>You can use this to e.g load YAML from memory.
-<br>
 
- If there is no or more than one YAML document in the stream, this will throw.
+ <span class="d_keyword">foreach</span>(<span class="d_keyword">ref</span> node; loader)
- Use <a href="#loadAll"><span class="d_inlinecode">loadAll</span></a> for such files.
+ {
+     ...
+ }
+</pre>
 
-</p>
+ Load YAML from memory:
-<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:
 <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.
+<b>Parameters:</b><div class="pbr"><table class=parms><tr><td valign=top>Stream <b>stream</b></td>
-
-</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>
 <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>

doc/html/api/dyaml.node.html

@@ -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
+<p>This is a pseudo-dynamic type that can store any YAML value, including a
- 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
+ sequence or mapping of nodes. You can get data from a <a name="Node"></a><span class="ddoc_psymbol">Node</span> directly or
- if it's a sequence or a mapping.</p>
+ 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
+<p>If T is Node, recursively compare all subnodes.
- subnodes and might be quite expensive if testing entire documents.
+ 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
+<b>Examples:</b><div class="pbr"><pre class="d_code"> <span class="d_keyword">auto</span> node = Node(42);
-</span> <span class="d_keyword">assert</span>(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
+<pre class="d_code"> <span class="d_keyword">auto</span> node = Node(42);
-</span> <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>!<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,
+<p>If the target type does not match node type,
- conversion is attempted, if possible.
+ 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>

doc/html/api/dyaml.representer.html

@@ -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>

doc/html/api/dyaml.resolver.html

@@ -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>

doc/html/api/index.html

@@ -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>

doc/html/articles/spec_differences.html

@@ -47,7 +47,7 @@
 are caused by difficulty of implementation of some features, such as multiple
 Unicode encodings within single stream, and some by unnecessary restrictions or
 ambiguities in the specification.</p>
-<p>Still, D:YAML tries to be as close to the specification as possible. D:YAML should
+<p>Still, D:YAML tries to be as close to the specification as possible. It should
 never load documents with different meaning than according to the specification,
 and documents that fail to load should be very rare (for instance, very few
 files use multiple Unicode encodings).</p>
@@ -55,11 +55,6 @@ files use multiple Unicode encodings).</p>
 <h2>List of known differences:<a class="headerlink" href="#list-of-known-differences" title="Permalink to this headline">¶</a></h2>
 <p>Differences that can cause valid YAML documents not to load:</p>
 <ul>
-<li><p class="first">At the moment, all mappings in the internal representation are ordered,
-and a comparison for equality between equal mappings with differing order
-will return false. This will be fixed once Phobos has a usable map type or
-D associative arrays work with variants.</p>
-</li>
 <li><p class="first">No support for byte order marks and multiple Unicode encodings in a stream.</p>
 </li>
 <li><p class="first">Plain scalars in flow context cannot contain <tt class="docutils literal"><span class="pre">,</span></tt>, <tt class="docutils literal"><span class="pre">:</span></tt> and <tt class="docutils literal"><span class="pre">?</span></tt>.
@@ -143,8 +138,8 @@ struct appears in Phobos.</p>
     </div>
     <div class="footer">
         &copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
-      Last updated on Aug 16, 2011.
+      Last updated on Oct 14, 2011.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
     </div>
   </body>
 </html>

doc/html/index.html

@@ -103,8 +103,8 @@
     </div>
     <div class="footer">
         &copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
-      Last updated on Aug 16, 2011.
+      Last updated on Oct 14, 2011.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
     </div>
   </body>
 </html>

doc/html/search.html

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

doc/html/tutorials/custom_types.html

@@ -47,10 +47,10 @@
             
   <div class="section" id="custom-yaml-data-types">
 <h1>Custom YAML data types<a class="headerlink" href="#custom-yaml-data-types" title="Permalink to this headline">¶</a></h1>
-<p>Often you will want to serialize complex data types such as classes. You can use
+<p>Often you might want to serialize complex data types such as classes. You can
-functions to process nodes; e.g. a mapping containing class data members indexed
+use functions to process nodes such as a mapping containing class data members
-by name. Alternatively, YAML supports custom data types using identifiers called
+indexed by name. Alternatively, YAML supports custom data types using
-<em>tags</em>. That is the topic of this tutorial.</p>
+identifiers called <em>tags</em>. That is the topic of this tutorial.</p>
 <p>Each YAML node has a tag specifying its type. For instance: strings use the tag
 <tt class="docutils literal"><span class="pre">tag:yaml.org,2002:str</span></tt>. Tags of most default types are <em>implicitly resolved</em>
 during parsing, so you don&#8217;t need to specify tag for each float, integer, etc.
@@ -59,9 +59,9 @@ It is also possible to implicitly resolve custom tags, as we will show later.</p
 <h2>Constructor<a class="headerlink" href="#constructor" title="Permalink to this headline">¶</a></h2>
 <p>D:YAML uses the <em>Constructor</em> class to process each node to hold data type
 corresponding to its tag. <em>Constructor</em> stores a function for each supported
-tag to process it. These functions can be supplied by the user using the
+tag to process it. These functions are supplied by the user using the
-<em>addConstructor()</em> method. <em>Constructor</em> is then passed to <em>Loader</em>, which will
+<em>addConstructor()</em> method. <em>Constructor</em> is then passed to <em>Loader</em>, which
-parse YAML input.</p>
+parses YAML input.</p>
 <p>We will implement support for an RGB color type. It is implemented as the
 following struct:</p>
 <div class="highlight-d"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Color</span>
@@ -146,7 +146,7 @@ RRGGBB, or from a mapping, where we use the following format:
 <span class="p">}</span>
 </pre></div>
 </div>
-<p>Next, we need some YAML code using our new tag. Create a file called input.yaml
+<p>Next, we need some YAML data using our new tag. Create a file called input.yaml
 with the following contents:</p>
 <div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">scalar-red</span><span class="p-Indicator">:</span> <span class="kt">!color</span> <span class="l-Scalar-Plain">FF0000</span>
 <span class="l-Scalar-Plain">scalar-orange</span><span class="p-Indicator">:</span> <span class="kt">!color</span> <span class="l-Scalar-Plain">FFFF00</span>
@@ -173,9 +173,10 @@ with the following contents:</p>
         <span class="n">constructor</span><span class="p">.</span><span class="n">addConstructor</span><span class="p">(</span><span class="s">&quot;!color&quot;</span><span class="p">,</span> <span class="p">&amp;</span><span class="n">constructColorScalar</span><span class="p">);</span>
         <span class="n">constructor</span><span class="p">.</span><span class="n">addConstructor</span><span class="p">(</span><span class="s">&quot;!color-mapping&quot;</span><span class="p">,</span> <span class="p">&amp;</span><span class="n">constructColorMapping</span><span class="p">);</span>
 
-        <span class="k">auto</span> <span class="n">loader</span> <span class="p">=</span> <span class="k">new</span> <span class="n">Loader</span><span class="p">(</span><span class="s">&quot;input.yaml&quot;</span><span class="p">,</span> <span class="n">constructor</span><span class="p">,</span> <span class="k">new</span> <span class="n">Resolver</span><span class="p">);</span>
+        <span class="k">auto</span> <span class="n">loader</span> <span class="p">=</span> <span class="n">Loader</span><span class="p">(</span><span class="s">&quot;input.yaml&quot;</span><span class="p">);</span>
+        <span class="n">loader</span><span class="p">.</span><span class="n">constructor</span> <span class="p">=</span> <span class="n">constructor</span><span class="p">;</span>
 
-        <span class="k">auto</span> <span class="n">root</span> <span class="p">=</span> <span class="n">loader</span><span class="p">.</span><span class="n">loadSingleDocument</span><span class="p">();</span>
+        <span class="k">auto</span> <span class="n">root</span> <span class="p">=</span> <span class="n">loader</span><span class="p">.</span><span class="n">load</span><span class="p">();</span>
 
         <span class="k">if</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">&quot;scalar-red&quot;</span><span class="p">].</span><span class="n">get</span><span class="p">!</span><span class="n">Color</span> <span class="p">==</span> <span class="n">red</span> <span class="p">&amp;&amp;</span>
            <span class="n">root</span><span class="p">[</span><span class="s">&quot;mapping-red&quot;</span><span class="p">].</span><span class="n">get</span><span class="p">!</span><span class="n">Color</span> <span class="p">==</span> <span class="n">red</span> <span class="p">&amp;&amp;</span>
@@ -196,23 +197,21 @@ with the following contents:</p>
 </pre></div>
 </div>
 <p>First, we create a <em>Constructor</em> and pass functions to handle the <tt class="docutils literal"><span class="pre">!color</span></tt>
-and <tt class="docutils literal"><span class="pre">!color-mapping</span></tt> tag. We construct a <em>Loader</em> using the <em>Constructor</em>.
+and <tt class="docutils literal"><span class="pre">!color-mapping</span></tt> tag. We construct a <em>Loader*m and pass the *Constructor</em>
-We also need a <em>Resolver</em>, but for now we just default-construct it. We then
+to it. We then load the YAML document, and finally, read the colors using
-load the YAML document, and finally, read the colors using <em>get()</em> method to
+<em>get()</em> method to test if they were loaded as expected.</p>
-test if they were loaded as expected.</p>
 <p>You can find the source code for what we&#8217;ve done so far in the
 <tt class="docutils literal"><span class="pre">examples/constructor</span></tt> directory in the D:YAML package.</p>
 </div>
 <div class="section" id="resolver">
 <h2>Resolver<a class="headerlink" href="#resolver" title="Permalink to this headline">¶</a></h2>
 <p>Specifying tag for every color value can be tedious. D:YAML can implicitly
-resolve tag of a scalar using a regular expression. This is how default types,
+resolve scalar tags using regular expressions. This is how default types such as
-e.g. int, are resolved. We will use the <em>Resolver</em> class to add implicit tag
+int are resolved. We will use the <em>Resolver</em> class to add implicit tag
 resolution for the Color data type (in its scalar form).</p>
 <p>We use the <em>addImplicitResolver</em> method of <em>Resolver</em>, passing the tag, regular
 expression the value must match to resolve to this tag, and a string of possible
-starting characters of the value. Then we pass the <em>Resolver</em> to the constructor
+starting characters of the value. Then we pass the <em>Resolver</em> to <em>Loader</em>.</p>
-of <em>Loader</em>.</p>
 <p>Note that resolvers added first override ones added later. If no resolver
 matches a scalar, YAML string tag is used. Therefore our custom values must not
 be resolvable as any non-string YAML data type.</p>
@@ -223,12 +222,15 @@ be resolvable as any non-string YAML data type.</p>
 <span class="n">resolver</span><span class="p">.</span><span class="n">addImplicitResolver</span><span class="p">(</span><span class="s">&quot;!color&quot;</span><span class="p">,</span> <span class="n">std</span><span class="p">.</span><span class="n">regex</span><span class="p">.</span><span class="n">regex</span><span class="p">(</span><span class="s">&quot;[0-9a-fA-F]{6}&quot;</span><span class="p">,</span>
                              <span class="s">&quot;0123456789abcdefABCDEF&quot;</span><span class="p">));</span>
 
-<span class="k">auto</span> <span class="n">loader</span> <span class="p">=</span> <span class="k">new</span> <span class="n">Loader</span><span class="p">(</span><span class="s">&quot;input.yaml&quot;</span><span class="p">,</span> <span class="n">constructor</span><span class="p">,</span> <span class="n">resolver</span><span class="p">);</span>
+<span class="k">auto</span> <span class="n">loader</span> <span class="p">=</span> <span class="n">Loader</span><span class="p">(</span><span class="s">&quot;input.yaml&quot;</span><span class="p">);</span>
+
+<span class="n">loader</span><span class="p">.</span><span class="n">constructor</span> <span class="p">=</span> <span class="n">constructor</span><span class="p">;</span>
+<span class="n">loader</span><span class="p">.</span><span class="n">resolver</span> <span class="p">=</span> <span class="n">resolver</span><span class="p">;</span>
 
 <span class="c1">//code from the previous example...</span>
 </pre></div>
 </div>
-<p>Now, change contents of input.dyaml to this:</p>
+<p>Now, change contents of input.yaml to this:</p>
 <div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">scalar-red</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">FF0000</span>
 <span class="l-Scalar-Plain">scalar-orange</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">FFFF00</span>
 <span class="l-Scalar-Plain">mapping-red</span><span class="p-Indicator">:</span> <span class="kt">!color-mapping</span> <span class="p-Indicator">{</span><span class="nv">r</span><span class="p-Indicator">:</span> <span class="nv">255</span><span class="p-Indicator">,</span> <span class="nv">g</span><span class="p-Indicator">:</span> <span class="nv">0</span><span class="p-Indicator">,</span> <span class="nv">b</span><span class="p-Indicator">:</span> <span class="nv">0</span><span class="p-Indicator">}</span>
@@ -282,8 +284,8 @@ D:YAML package.</p>
     </div>
     <div class="footer">
         &copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
-      Last updated on Aug 16, 2011.
+      Last updated on Oct 14, 2011.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
     </div>
   </body>
 </html>

doc/html/tutorials/getting_started.html

@@ -64,9 +64,8 @@ Download the version of DMD for your operating system and install it.</p>
 <p class="first admonition-title">Note</p>
 <p class="last">Other D compilers exist, such as
 <a class="reference external" href="http://bitbucket.org/goshawk/gdc/wiki/Home">GDC</a> and
-<a class="reference external" href="http://www.dsource.org/projects/ldc/">LDC</a>.
+<a class="reference external" href="http://www.dsource.org/projects/ldc/">LDC</a>. Setting up with either one of
-Setting up with either one of them should be similar to DMD,
+them should be similar to DMD, but they are not yet as stable as DMD.</p>
-however, at the moment they are not as up to date as DMD.</p>
 </div>
 </div>
 <div class="section" id="download-and-compile-d-yaml">
@@ -109,7 +108,7 @@ into the file:</p>
 
 <span class="kt">void</span> <span class="n">main</span><span class="p">()</span>
 <span class="p">{</span>
-    <span class="n">yaml</span><span class="p">.</span><span class="n">Node</span> <span class="n">root</span> <span class="p">=</span> <span class="n">yaml</span><span class="p">.</span><span class="n">load</span><span class="p">(</span><span class="s">&quot;input.yaml&quot;</span><span class="p">);</span>
+    <span class="n">Node</span> <span class="n">root</span> <span class="p">=</span> <span class="n">Loader</span><span class="p">(</span><span class="s">&quot;input.yaml&quot;</span><span class="p">).</span><span class="n">load</span><span class="p">();</span>
     <span class="k">foreach</span><span class="p">(</span><span class="nb">string</span> <span class="n">word</span><span class="p">;</span> <span class="n">root</span><span class="p">[</span><span class="s">&quot;Hello World&quot;</span><span class="p">])</span>
     <span class="p">{</span>
         <span class="n">writeln</span><span class="p">(</span><span class="n">word</span><span class="p">);</span>
@@ -122,27 +121,28 @@ into the file:</p>
 <h3>Explanation of the code<a class="headerlink" href="#explanation-of-the-code" title="Permalink to this headline">¶</a></h3>
 <p>First, we import the <em>yaml</em> module. This is the only module you need to import
 to use D:YAML - it automatically imports all needed modules.</p>
-<p>Next we load the file using the <em>yaml.load()</em> function - this loads the file as
+<p>Next we load the file using the <em>Loader.load()</em> method. <em>Loader</em> is the struct
-<strong>one</strong> YAML document and throws <em>YAMLException</em>, D:YAML exception type, if the
+used for parsing YAML documents, and <em>load()</em> is a method that loads the file as
+<strong>one</strong> YAML document, or throws <em>YAMLException</em>, D:YAML exception type, if the
 file could not be parsed or does not contain exactly one document. Note that we
 don&#8217;t do any error checking here in order to keep the example as simple as
 possible.</p>
-<p><em>yaml.Node</em> represents a node in a YAML document. It can be a sequence (array),
+<p><em>Node</em> represents a node in a YAML document. It can be a sequence (array),
 mapping (associative array) or a scalar (value). Here the root node is a
 mapping, and we use the index operator to get subnodes with keys &#8220;Hello World&#8221;
 and &#8220;Answer&#8221;. We iterate over the first, as it is a sequence, and use the
-<em>yaml.Node.get()</em> method on the second to get its value as an integer.</p>
+<em>Node.get()</em> method on the second to get its value as an integer.</p>
 <p>You can iterate over a mapping or sequence as if it was an associative or normal
 array. If you try to iterate over a scalar, it will throw a <em>YAMLException</em>.</p>
-<p>You can iterate over subnodes using yaml.Node as the iterated type, or specify
+<p>You can iterate over subnodes using <em>Node</em> as the iterated type, or specify
 the type subnodes are expected to have. D:YAML will automatically convert
 iterated subnodes to that type if possible. Here we specify the <em>string</em> type,
 so we iterate over the &#8220;Hello World&#8221; sequence as an array of strings. If it is
 not possible to convert to iterated type, a <em>YAMLException</em> is thrown. For
 instance, if we specified <em>int</em> here, we would get an error, as &#8220;Hello&#8221;
 cannot be converted to an integer.</p>
-<p>The <em>yaml.Node.get()</em> method is used to get value of a scalar node as specified
+<p>The <em>Node.get()</em> method is used to get value of a scalar node, allowing to
-type. D:YAML will try to return the scalar as specified type, converting if
+specify type. D:YAML will try to return the scalar as this type, converting if
 needed, throwing <em>YAMLException</em> if not possible.</p>
 </div>
 <div class="section" id="compiling">
@@ -150,15 +150,14 @@ needed, throwing <em>YAMLException</em> if not possible.</p>
 <p>To compile your project, you must give DMD the directories containing import
 modules and the library. You also need to tell it to link with D:YAML. The import
 directory should be the D:YAML package directory. You can specify it using the
-<tt class="docutils literal"><span class="pre">-I</span></tt> option of DMD.  The library directory should point to where you put the
+<tt class="docutils literal"><span class="pre">-I</span></tt> option of DMD. The library directory should be where you put the compiled
-compiled D:YAML library. On Unix/Linux you can specify it using the <tt class="docutils literal"><span class="pre">-L-L</span></tt>
+D:YAML library. On Unix/Linux you can specify it using the <tt class="docutils literal"><span class="pre">-L-L</span></tt> option, and
-option, and link with D:YAML using the <tt class="docutils literal"><span class="pre">-L-l</span></tt> option. On Windows, the import
+link with D:YAML using the <tt class="docutils literal"><span class="pre">-L-l</span></tt> option. On Windows, the import directory is
-directory is used as the library directory. To link with the library on Windows,
+used as the library directory. To link with the library on Windows, just add the
-just add the path to it relative to the current directory.</p>
+path to it relative to the current directory.</p>
-<p>For example, if you extracted D:YAML to <tt class="docutils literal"><span class="pre">/home/xxx/dyaml</span></tt> and compiled it in
+<p>For example, if you extracted and compiled D:YAML in <tt class="docutils literal"><span class="pre">/home/xxx/dyaml</span></tt>, your
-that directory, your project is in <tt class="docutils literal"><span class="pre">/home/xxx/dyaml-project</span></tt>, and you are
+project is in <tt class="docutils literal"><span class="pre">/home/xxx/dyaml-project</span></tt>, and you are currently in that
-currently in that directory, you can compile the project with the following
+directory, you can compile the project with the following command on Unix/Linux:</p>
-command on Unix/Linux:</p>
 <div class="highlight-python"><pre>dmd -I../dyaml -L-L../dyaml -L-ldyaml main.d</pre>
 </div>
 <p>And the following on Windows:</p>
@@ -225,8 +224,8 @@ example in the <tt class="docutils literal"><span class="pre">example/getting_st
     </div>
     <div class="footer">
         &copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
-      Last updated on Aug 16, 2011.
+      Last updated on Oct 14, 2011.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
     </div>
   </body>
 </html>

doc/html/tutorials/yaml_syntax.html

@@ -52,20 +52,19 @@ information, see <a class="reference external" href="http://pyyaml.org/wiki/PyYA
 which this article is based on,
 <a class="reference external" href="http://yaml.org/spec/1.1/#id857168">Chapter 2 of the YAML specification</a>
 or the <a class="reference external" href="http://en.wikipedia.org/wiki/YAML">Wikipedia page</a>.</p>
-<p>YAML is a data serialization format designed to be as human readable as
+<p>YAML is a data serialization format designed for human readability. YAML is a
-possible. YAML is a recursive acronym for &#8220;YAML Ain&#8217;t Markup Language&#8221;.</p>
+recursive acronym for &#8220;YAML Ain&#8217;t Markup Language&#8221;.</p>
 <p>YAML is similar to JSON, and in fact, JSON is a subset of YAML 1.2; but YAML has
-some more advanced features and is easier to read. However, YAML is also more
+some more advanced features and is easier to read. However, it is also more
 difficult to parse (and probably somewhat slower). Data is stored in mappings
 (associative arrays), sequences (lists) and scalars (single values). Data
-structure hierarchy either depends on indentation (block context, similar to
+structure hierarchy depends either on indentation (block context, similar to
 Python code), or nesting of brackets and braces (flow context, similar to JSON).
 YAML comments begin with <tt class="docutils literal"><span class="pre">#</span></tt> and continue until the end of line.</p>
 <div class="section" id="documents">
 <h2>Documents<a class="headerlink" href="#documents" title="Permalink to this headline">¶</a></h2>
 <p>A YAML stream consists of one or more documents starting with <tt class="docutils literal"><span class="pre">---</span></tt> and
-optionally ending with <tt class="docutils literal"><span class="pre">...</span></tt> . If there is only one document, <tt class="docutils literal"><span class="pre">---</span></tt> can be
+optionally ending with <tt class="docutils literal"><span class="pre">...</span></tt> . <tt class="docutils literal"><span class="pre">---</span></tt> can be left out for the first document.</p>
-left out.</p>
 <p>Single document with no explicit start or end:</p>
 <div class="highlight-yaml"><div class="highlight"><pre><span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Red</span>
 <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Green</span>
@@ -96,7 +95,7 @@ left out.</p>
 <div class="section" id="sequences">
 <h2>Sequences<a class="headerlink" href="#sequences" title="Permalink to this headline">¶</a></h2>
 <p>Sequences are arrays of nodes of any type, similar e.g. to Python lists.
-In block context, each item begins with hyphen+space &#8220;- &#8220;. In flow context,
+In block context, each item begins with hyphen+space &#8220;- &#8221;. In flow context,
 sequences have syntax similar to D arrays.</p>
 <div class="highlight-yaml"><div class="highlight"><pre><span class="c1">#Block context</span>
 <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Red</span>
@@ -137,7 +136,7 @@ sequences have syntax similar to D arrays.</p>
 <h2>Mappings<a class="headerlink" href="#mappings" title="Permalink to this headline">¶</a></h2>
 <p>Mappings are associative arrays where each key and value can be of any type,
 similar e.g. to Python dictionaries. In block context, keys and values are
-separated by colon+space &#8220;: &#8220;. In flow context, mappings have syntax similar
+separated by colon+space &#8221;: &#8221;. In flow context, mappings have syntax similar
 to D associative arrays, but with braces instead of brackets:</p>
 <div class="highlight-yaml"><div class="highlight"><pre><span class="c1">#Block context</span>
 <span class="l-Scalar-Plain">CPU</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Athlon</span>
@@ -174,7 +173,7 @@ to D associative arrays, but with braces instead of brackets:</p>
   <span class="l-Scalar-Plain">OS</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Android</span>
 </pre></div>
 </div>
-<p>Complex keys start with question mark+space &#8220;? &#8220;.</p>
+<p>Complex keys start with question mark+space &#8221;? &#8221;.</p>
 <div class="highlight-yaml"><div class="highlight"><pre><span class="c1">#Nested in a sequence</span>
 <span class="p-Indicator">?</span> <span class="p-Indicator">[</span><span class="nv">CPU</span><span class="p-Indicator">,</span> <span class="nv">GPU</span><span class="p-Indicator">]:</span> <span class="p-Indicator">[</span><span class="nv">Athlon</span><span class="p-Indicator">,</span> <span class="nv">Radeon</span><span class="p-Indicator">]</span>
 <span class="l-Scalar-Plain">OS</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Debian</span>
@@ -331,8 +330,8 @@ Some of these might change in the future (especially !!map and !!set).</p>
     </div>
     <div class="footer">
         &copy; Copyright 2011, Ferdinand Majerech. Based on PyYAML http://www.pyyaml.org by Kirill Simonov.
-      Last updated on Aug 16, 2011.
+      Last updated on Oct 14, 2011.
-      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
     </div>
   </body>
 </html>

docsrc/tutorials/custom_types.rst

@@ -186,8 +186,7 @@ resolution for the Color data type (in its scalar form).
 
 We use the *addImplicitResolver* method of *Resolver*, passing the tag, regular
 expression the value must match to resolve to this tag, and a string of possible
-starting characters of the value. Then we pass the *Resolver* to the constructor 
+starting characters of the value. Then we pass the *Resolver* to *Loader*.
-of *Loader*.
 
 Note that resolvers added first override ones added later. If no resolver 
 matches a scalar, YAML string tag is used. Therefore our custom values must not 

docsrc/tutorials/getting_started.rst

@@ -100,7 +100,7 @@ to use D:YAML - it automatically imports all needed modules.
 
 Next we load the file using the *Loader.load()* method. *Loader* is the struct 
 used for parsing YAML documents, and *load()* is a method that loads the file as
-**one** YAML document and throws *YAMLException*, D:YAML exception type, if the 
+**one** YAML document, or throws *YAMLException*, D:YAML exception type, if the 
 file could not be parsed or does not contain exactly one document. Note that we 
 don't do any error checking here in order to keep the example as simple as 
 possible.

dyaml/dumper.d

@@ -5,8 +5,9 @@
 //          http://www.boost.org/LICENSE_1_0.txt)
 
 /**
- * YAML dumper.
+ * YAML _dumper.
- * Code based on PyYAML: http://www.pyyaml.org
+ *
+ * Code based on $(LINK2 http://www.pyyaml.org, PyYAML).
  */
 module dyaml.dumper;
 
@@ -33,7 +34,7 @@ import dyaml.tagdirectives;
  * User specified Representer and/or Resolver can be used to support new 
  * tags / data types.
  *
- * Setters are provided to affect the output (style, encoding)..
+ * Setters are provided to affect output details (style, encoding, etc.).
  * 
  * Examples: 
  *
@@ -48,6 +49,11 @@ import dyaml.tagdirectives;
  * auto node1 = Node([1, 2, 3, 4, 5]);
  * auto node2 = Node("This document contains only one string");
  * Dumper("file.yaml").dump(node1, node2);
+ *
+ * //Or with an array:
+ * //Dumper("file.yaml").dump([node1, node2]);
+ *
+ *
  * --------------------
  *
  * Write to memory:
@@ -142,7 +148,7 @@ struct Dumper
          *
          * Params: filename = File name to write to.
          *
-         * Throws: YAMLException if the file can not be dumped to (e.g. cannot be read).
+         * Throws: YAMLException if the file can not be dumped to (e.g. cannot be opened).
          */
         this(string filename)
         {
@@ -153,7 +159,7 @@ struct Dumper
             }
         }
 
-        ///Construct a Dumper writing to a stream. This is useful to e.g. write to memory.
+        ///Construct a Dumper writing to a _stream. This is useful to e.g. write to memory.
         this(Stream stream)
         {
             resolver_ = new Resolver();
@@ -185,7 +191,7 @@ struct Dumper
             representer_ = representer;
         }
 
-        ///Write scalars in canonical form?
+        ///Write scalars in _canonical form?
         void canonical(in bool canonical)
         {
             canonical_ = canonical;
@@ -202,7 +208,7 @@ struct Dumper
             indent_ = indent;
         }
 
-        ///Set preferred text width.
+        ///Set preferred text _width.
         void textWidth(in uint width)
         {
             textWidth_ = width;
@@ -214,7 +220,7 @@ struct Dumper
             lineBreak_ = lineBreak;
         }
 
-        ///Set character encoding to use. UTF-8 by default.
+        ///Set character _encoding to use. UTF-8 by default.
         void encoding(in Encoding encoding)
         {
             encoding_ = encoding;
@@ -241,18 +247,18 @@ struct Dumper
         /**
          * Specify tag directives. 
          *
-         * A tag directive specifies a shorthand notation for specifying tags.
+         * 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.
          *
          * Each handle specified MUST start and end with a '!' character
          * (a single character "!" handle is allowed as well).
          *
-         * Only alphanumeric characters, '-', and '_' may be used in handles.
+         * Only alphanumeric characters, '-', and '__' may be used in handles.
          *
          * Each prefix MUST not be empty.
          *
-         * The "!!" handle is used for default YAML tags with prefix 
+         * The "!!" handle is used for default YAML _tags with prefix 
          * "tag:yaml.org,2002:". This can be overridden.
          *
          * Params:  tags = Tag directives (keys are handles, values are prefixes).
@@ -281,13 +287,13 @@ struct Dumper
         }
 
         /**
-         * Dump one or more YAML documents to the file/stream.
+         * Dump one or more YAML _documents to the file/stream.
          *
          * Note that while you can call dump() multiple times on the same 
          * dumper, you will end up writing multiple YAML "files" to the same
          * file/stream.
          *
-         * Params:  documents = Documents to dump (root nodes of the documents).
+         * Params:  documents = Documents to _dump (root nodes of the _documents).
          *
          * Throws:  YAMLException on error (e.g. invalid nodes, 
          *          unable to write to file/stream).

dyaml/encoding.d

@@ -7,10 +7,13 @@
 module dyaml.encoding;
 
 
-///Text encodings.
+///Text encodings supported by D:YAML.
 enum Encoding : ubyte
 {
+    ///Unicode UTF-8
     UTF_8,
+    ///Unicode UTF-16
     UTF_16,
+    ///Unicode UTF-32
     UTF_32
 }

dyaml/exception.d

@@ -4,7 +4,7 @@
 //    (See accompanying file LICENSE_1_0.txt or copy at
 //          http://www.boost.org/LICENSE_1_0.txt)
 
-///D:YAML exceptions and exception related code.
+///Exceptions thrown by D:YAML and _exception related code.
 module dyaml.exception;
 
 
@@ -78,7 +78,7 @@ abstract class MarkedYAMLException : YAMLException
     }
 }
 
-///Constructors of YAML exceptions are mostly the same, so we use a mixin.
+//Constructors of YAML exceptions are mostly the same, so we use a mixin.
 template ExceptionCtors()
 {
     public:
@@ -88,7 +88,7 @@ template ExceptionCtors()
         }
 }
 
-///Constructors of marked YAML exceptions are mostly the same, so we use a mixin.
+//Constructors of marked YAML exceptions are mostly the same, so we use a mixin.
 template MarkedExceptionCtors()
 {
     public:

dyaml/linebreak.d

@@ -4,19 +4,23 @@
 //    (See accompanying file LICENSE_1_0.txt or copy at
 //          http://www.boost.org/LICENSE_1_0.txt)
 
-///Line break enum.
 module dyaml.linebreak;
 
 
 ///Enumerates platform specific line breaks.
 enum LineBreak
 {
+    ///Unix line break ("\n").
     Unix,
+    ///Windows line break ("\r\n").
     Windows,
+    ///Macintosh line break ("\r").
     Macintosh
 }
 
-///Get line break string for specified line break.
+package:
+
+//Get line break string for specified line break.
 string lineBreak(in LineBreak b) pure
 {
     final switch(b)

dyaml/loader.d

@@ -5,7 +5,7 @@
 //          http://www.boost.org/LICENSE_1_0.txt)
 
 /**
- * Class and convenience functions used to load YAML documents.
+ * Class used to load YAML documents.
  */
 module dyaml.loader;
 
@@ -125,11 +125,11 @@ struct Loader
         }
         
         /**
-         * Construct a Loader to load YAML from a stream.
+         * Construct a Loader to load YAML from a _stream.
          *
          * Params:  stream = Stream to read from. Must be readable.
          *
-         * Throws:  YAMLException if the stream could not be read from.
+         * Throws:  YAMLException if stream could not be read from.
          */
         this(Stream stream)
         {
@@ -160,19 +160,19 @@ struct Loader
             clear(parser_);
         }
 
-        ///Set stream name. Used in debugging messages.
+        ///Set stream _name. Used in debugging messages.
         @property void name(string name)
         {
             name_ = name;
         }
 
-        ///Set Resolver to use.
+        ///Specify custom Resolver to use.
         @property void resolver(Resolver resolver)
         {
             resolver_ = resolver;
         }
 
-        ///Set Constructor to use.
+        ///Specify custom Constructor to use.
         @property void constructor(Constructor constructor)
         {
             constructor_ = constructor;
@@ -181,7 +181,7 @@ struct Loader
         /**
          * Load single YAML document.
          *
-         * If no or more than one YAML document is found, this will throw a YAMLException.
+         * If none or more than one YAML document is found, this will throw a YAMLException.
          *                  
          * Returns: Root node of the document.
          *
@@ -208,8 +208,7 @@ struct Loader
          *                  
          * Returns: Array of root nodes of all documents in the file/stream.
          *
-         * Throws:  YAMLException if there wasn't exactly one document
+         * Throws:  YAMLException on a YAML parsing error.
-         *          or on a YAML parsing error.
          */
         Node[] loadAll()
         {
@@ -224,7 +223,7 @@ struct Loader
         /**
          * Foreach over YAML documents.
          *
-         * Parses documents lazily, as they are needed.
+         * Parses documents lazily, when they are needed.
          *
          * Throws: YAMLException on a parsing error.
          */

dyaml/node.d

@@ -57,7 +57,7 @@ struct YAMLNull{}
 //Merge YAML type, used to support "tag:yaml.org,2002:merge".
 package struct YAMLMerge{}
 
-///Base class for YAMLContainer - used for user defined YAML types.
+//Base class for YAMLContainer - used for user defined YAML types.
 package abstract class YAMLObject
 {
     public:
@@ -110,14 +110,14 @@ package class YAMLContainer(T) : YAMLObject
 /**
  * YAML node.
  *
- * This is a pseudo-dynamic type that can store any YAML value, including sequence 
+ * This is a pseudo-dynamic type that can store any YAML value, including a 
- * or a mapping of nodes. You can get data from a Node directly or iterate over it
+ * sequence or mapping of nodes. You can get data from a Node directly or 
- * if it's a sequence or a mapping.
+ * iterate over it if it's a collection.
  */
 struct Node
 {
     public:
-        ///Pair of YAML nodes, used in mappings.
+        ///Key-value pair of YAML nodes, used in mappings.
         struct Pair
         {
             public:
@@ -174,10 +174,11 @@ struct Node
          * Construct a Node from a value.
          *
          * Any type except of Node can be stored in a Node, but default YAML 
-         * types (integers, floats, strings, timestamp, etc.) will be stored
+         * types (integers, floats, strings, timestamps, etc.) will be stored
          * more efficiently. 
          *
-         * Note that for any non-default types you store 
+         *
+         * 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.
          *
@@ -186,8 +187,8 @@ struct Node
          *                  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:omap", not 
+         *                  be in full form, e.g. "tag:yaml.org,2002:int", not 
-         *                  a shortcut, like "!!omap".            
+         *                  a shortcut, like "!!int".            
          */
         this(T)(T value, in string tag = null) if (isSomeString!T || 
                                                   (!isArray!T && !isAssociativeArray!T))
@@ -221,11 +222,11 @@ struct Node
         }
 
         /**
-         * Construct a node from an array_.
+         * Construct a node from an _array.
          *
-         * If array is an array_ of nodes or node pairs, it is stored in the 
+         * If _array is an _array of nodes or pairs, it is stored directly. 
-         * node directly. Otherwise, every value in the array is converted to a
+         * Otherwise, every value in the array is converted to a node, and 
-         * node, and those nodes are stored.
+         * those nodes are stored.
          *
          * Params:  array = Values to store in the node.
          *          tag   = Overrides tag of the node when emitted, regardless 
@@ -233,10 +234,10 @@ struct Node
          *                  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 
+         *                  ("!!seq") and sets ("!!set"), which both are 
-         *                  represented as an array_ of nodes. Tag must be in 
+         *                  internally represented as an array_ of nodes. Tag 
-         *                  full form, e.g. "tag:yaml.org,2002:set", not a 
+         *                  must be in full form, e.g. "tag:yaml.org,2002:set",
-         *                  shortcut, like "!!set".
+         *                  not a shortcut, like "!!set".
          *
          * Examples:
          * --------------------
@@ -282,10 +283,10 @@ struct Node
         }
 
         /**
-         * Construct a node from an associative array_.
+         * Construct a node from an associative _array.
          *
-         * If keys and/or values of array are nodes, they are copied to the node
+         * If keys and/or values of _array are nodes, they stored directly. 
-         * directly. Otherwise they are converted to nodes and then stored.
+         * Otherwise they are converted to nodes and then stored.
          *
          * Params:  array = Values to store in the node.
          *          tag   = Overrides tag of the node when emitted, regardless 
@@ -293,11 +294,11 @@ struct Node
          *                  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 
+         *                  mappings ("!!map"), ordered mappings ("!!omap"), and 
-         *                  pairs (!!pairs) which are all internally represented
+         *                  pairs ("!!pairs") which are all internally 
-         *                  as an array_ of node pairs. Tag must be in full 
+         *                  represented as an _array of node pairs. Tag must be 
-         *                  form, e.g. "tag:yaml.org,2002:omap", not a shortcut, 
+         *                  in full form, e.g. "tag:yaml.org,2002:omap", not a
-         *                  like "!!omap".
+         *                  shortcut, like "!!omap".
          *
          * Examples:
          * --------------------
@@ -338,16 +339,18 @@ struct Node
         }
 
         /**
-         * Construct a node from arrays of keys_ and values_.
+         * Construct a node from arrays of _keys and _values.
          *
          * Constructs a mapping node with key-value pairs from
-         * keys_ and values_, keeping their order. Useful when order
+         * _keys and _values, keeping their order. Useful when order
          * is important (ordered maps, pairs).
          *
+         *
          * keys and values must have equal length.
          *
-         * If keys_ and/or values_ of are nodes, they are copied to the node
+         *
-         * directly. Otherwise they are converted to nodes and then stored.
+         * If _keys and/or _values are nodes, they are stored directly/
+         * Otherwise they are converted to nodes and then stored.
          *
          * Params:  keys   = Keys of the mapping, from first to last pair.
          *          values = Values of the mapping, from first to last pair.
@@ -356,11 +359,11 @@ struct Node
          *                   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 
+         *                   mappings ("!!map"), ordered mappings ("!!omap"), and 
-         *                   pairs (!!pairs) which are all internally represented
+         *                   pairs ("!!pairs") which are all internally 
-         *                   as an array_ of node pairs. Tag must be in full 
+         *                   represented as an array of node pairs. Tag must be 
-         *                   form, e.g. "tag:yaml.org,2002:omap", not a shortcut, 
+         *                   in full form, e.g. "tag:yaml.org,2002:omap", not a 
-         *                   like "!!omap".
+         *                   shortcut, like "!!omap".
          *
          * Examples:
          * --------------------
@@ -411,10 +414,10 @@ struct Node
         ///Is this node a scalar value?
         @property bool isScalar()   const {return !(isMapping || isSequence);}
                                             
-        ///Is this node a sequence of nodes?
+        ///Is this node a sequence?
         @property bool isSequence() const {return isType!(Node[]);}
                                             
-        ///Is this node a mapping of nodes?
+        ///Is this node a mapping?
         @property bool isMapping()  const {return isType!(Pair[]);}
 
         ///Is this node a user defined type?
@@ -423,14 +426,15 @@ struct Node
         /**
          * Equality test.
          *
-         * If T is Node, recursively compare all 
+         * If T is Node, recursively compare all subnodes. 
-         * subnodes and might be quite expensive if testing entire documents.
+         * This might be quite expensive if testing entire documents.
          *
          * If T is not Node, convert the node to T and test equality with that.
          *
          * Examples:
          * --------------------
-         * //node is a Node that contains integer 42
+         * auto node = Node(42);
+         *
          * assert(node == 42);
          * assert(node == "42");
          * assert(node != "43");
@@ -449,7 +453,7 @@ struct Node
          * Get the value of the node as specified type.
          *
          * If the specifed type does not match type in the node,
-         * conversion is attempted if possible.
+         * conversion is attempted.
          *
          * Timestamps are stored as std.datetime.SysTime.
          * Binary values are decoded and stored as ubyte[]. 
@@ -462,14 +466,15 @@ struct Node
          * but is replaced by a mapping later. Even if the node is a mapping, the
          * get 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.
          * )
          *
          * Examples:
          *
          * Automatic type conversion:
          * --------------------
-         * //node is a node that contains integer 42
+         * auto node = Node(42);
+         *
          * assert(node.get!int == 42);
          * assert(node.get!string == "42");
          * assert(node.get!double == 42.0);
@@ -489,8 +494,8 @@ struct Node
         /**
          * Write the value of the node to target.
          *
-         * If the type of target does not match type of the node,
+         * If the target type does not match node type,
-         * conversion is attempted, if possible.
+         * conversion is attempted.
          *
          * Params:  target = Variable to write to.
          *
@@ -580,7 +585,7 @@ struct Node
         }
 
         /**
-         * If this is a sequence or a mapping, return its length.
+         * If this is a collection, return its _length.
          *
          * Otherwise, throw NodeException.
          *
@@ -597,10 +602,11 @@ struct Node
         }
 
         /**
-         * Get the element with specified index.
+         * Get the element at specified index.
          *
          * If the node is a sequence, index must be integral.
          *
+         *
          * If the node is a mapping, return the value corresponding to the first 
          * key equal to index, even after conversion. I.e; node["12"] will 
          * return value of the first key that equals "12", even if it's an integer.
@@ -663,17 +669,17 @@ struct Node
         }
 
         /**
-         * Set element at the specified index of a collection.
+         * Set element at specified index in a collection.
          *
          * This method can only be called on collection nodes.
          * 
          * If the node is a sequence, index must be integral.
          *
-         * If the node is a mapping, set the value_ corresponding to the first 
+         * If the node is a mapping, sets the _value corresponding to the first 
          * key matching index (including conversion, so e.g. "42" matches 42).
          * 
          * If the node is a mapping and no key matches index, a new key-value
-         * pair is added to the mapping. With sequences the index must be in 
+         * pair is added to the mapping. In sequences the index must be in 
          * range. This ensures behavior siilar to D arrays and associative 
          * arrays.
          *
@@ -887,18 +893,19 @@ struct Node
         }
 
         /**
-         * Add an element to a sequence node.
+         * Add an element to a sequence.
          *
          * This method can only be called on sequence nodes.
          *
          * 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.
          *
-         * When emitting, all values in the sequence will be emitted. If using 
+         * $(P When emitting, all values in the sequence will be emitted. When 
-         * the !!set tag, the user needs to ensure that all elements in the 
+         * using the !!set tag, the user needs to ensure that all elements in 
-         * sequence are unique, otherwise invalid YAML code will be emitted.
+         * the sequence are unique, otherwise $(B invalid) YAML code will be 
+         * emitted.)
          *
-         * Params:  value = Value to add to the sequence.
+         * Params:  value = Value to _add to the sequence.
          */
         void add(T)(T value)
         {
@@ -923,20 +930,20 @@ struct Node
         }
 
         /**
-         * Add a key-value pair to a mapping node.
+         * Add a key-value pair to a mapping.
          *
          * This method can only be called on mapping nodes.
          *
          * 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.
          *
-         * It is possible to for the same key to be present more than once in a
+         * $(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 invalid YAML
+         * This is useful with the "!!pairs" tag, but will result in 
-         * with !!map and !!omap tags.
+         * $(B invalid) YAML with "!!map" and "!!omap" tags.)
          *
-         * Params:  key   = Key to add.
+         * Params:  key   = Key to _add.
-         *          value = Value to add.
+         *          value = Value to _add.
          */
         void add(K, V)(K key, V value)
         {
@@ -965,10 +972,10 @@ struct Node
          *
          * 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_ 
+         * If the node is a mapping, the first key-value pair where _value 
-         * matches value is removed.
+         * matches specified value is removed.
          * 
-         * Params:  value = Value to remove.
+         * Params:  value = Value to _remove.
          *
          * Throws:  NodeException if the node is not a collection.
          */

dyaml/representer.d

@@ -5,8 +5,9 @@
 //          http://www.boost.org/LICENSE_1_0.txt)
 
 /**
- * YAML representer.
+ * YAML node _representer.
- * Code based on PyYAML: http://www.pyyaml.org
+ *
+ * Code based on $(LINK2 http://www.pyyaml.org, PyYAML).
  */
 module dyaml.representer;
 
@@ -33,7 +34,7 @@ class RepresenterException : YAMLException
     mixin ExceptionCtors;
 }
 
-///Used to represent YAML nodes various data types into scalar/sequence/mapping nodes ready for output.
+///Used to represent YAML nodes various data types into scalar, sequence and mapping nodes ready for output.
 final class Representer
 {
     private:
@@ -43,7 +44,7 @@ final class Representer
         /**
          * Construct a Representer.
          * 
-         * Params:  useDefaultRepresenters = Use defualt representer functions
+         * Params:  useDefaultRepresenters = Use default representer functions
          *                                   for default YAML types? This can be
          *                                   disabled to use custom representer
          *                                   functions for default types.
@@ -180,11 +181,11 @@ final class Representer
         //user code.
 
         /**
-         * Represent a scalar with specified tag.
+         * Represent a _scalar with specified _tag.
          *
          * This is used by representer functions that produce scalars.
          *
-         * Params:  tag    = Tag of the scalar.
+         * Params:  tag    = Tag of the _scalar.
          *          scalar = Scalar value.
          *
          * Returns: The represented node.
@@ -210,7 +211,7 @@ final class Representer
         }
 
         /**
-         * Represent a sequence with specified tag, representing children first.
+         * Represent a _sequence with specified _tag, representing children first.
          *
          * This is used by representer functions that produce sequences.
          *
@@ -248,12 +249,12 @@ final class Representer
         }
 
         /**
-         * Represent a mapping with specified tag, representing children first.
+         * Represent a mapping with specified _tag, representing children first.
          *
          * This is used by representer functions that produce mappings.
          *
          * Params:  tag   = Tag of the mapping.
-         *          pairs = Key-value pairs of the mapping.
+         *          pairs = Key-value _pairs of the mapping.
          *
          * Returns: The represented node.
          *
@@ -288,7 +289,7 @@ final class Representer
         }
 
     package:
-        ///Represent a node based on its type, and return the represented result.
+        //Represent a node based on its type, and return the represented result.
         Node representData(ref Node data)
         {
             //User types are wrapped in YAMLObject.
@@ -302,7 +303,7 @@ final class Representer
             return result;
         }
 
-        ///Represent a node, serializing with specified Serializer.
+        //Represent a node, serializing with specified Serializer.
         void represent(ref Serializer serializer, ref Node node)
         {
             auto data = representData(node);
@@ -310,13 +311,14 @@ final class Representer
         }
 }
 
-///Represent a null node as a null.
+
+///Represent a _null _node as a _null YAML value.
 Node representNull(ref Node node, Representer representer)
 {
     return representer.representScalar("tag:yaml.org,2002:null", "null");
 }
 
-///Represent a string node as a string scalar.
+///Represent a string _node as a string scalar.
 Node representString(ref Node node, Representer representer)
 {
     string value = node.get!string;
@@ -324,7 +326,7 @@ Node representString(ref Node node, Representer representer)
                          : representer.representScalar("tag:yaml.org,2002:str", value);
 }
 
-///Represent a bytes node as a binary scalar.
+///Represent a bytes _node as a binary scalar.
 Node representBytes(ref Node node, Representer representer)
 {
     const ubyte[] value = node.get!(ubyte[]);
@@ -333,21 +335,21 @@ Node representBytes(ref Node node, Representer representer)
                                        cast(string)Base64.encode(value));
 }
 
-///Represent a bool node as a bool scalar.
+///Represent a bool _node as a bool scalar.
 Node representBool(ref Node node, Representer representer)
 {
     return representer.representScalar("tag:yaml.org,2002:bool", 
                                        node.get!bool ? "true" : "false");
 }
 
-///Represent a long node as an integer scalar.
+///Represent a long _node as an integer scalar.
 Node representLong(ref Node node, Representer representer)
 {
     return representer.representScalar("tag:yaml.org,2002:int", 
                                        to!string(node.get!long));
 }
 
-///Represent a real node as a floating point scalar.
+///Represent a real _node as a floating point scalar.
 Node representReal(ref Node node, Representer representer)
 {
     real f = node.get!real;
@@ -361,7 +363,14 @@ Node representReal(ref Node node, Representer representer)
     return representer.representScalar("tag:yaml.org,2002:float", value);
 }
 
-///Represent a sequence node as sequence/set.
+///Represent a SysTime _node as a timestamp.
+Node representSysTime(ref Node node, Representer representer)
+{
+    return representer.representScalar("tag:yaml.org,2002:timestamp", 
+                                       node.get!SysTime.toISOExtString());
+}
+
+///Represent a sequence _node as sequence/set.
 Node representNodes(ref Node node, Representer representer)
 {
     auto nodes = node.get!(Node[]);
@@ -383,7 +392,7 @@ Node representNodes(ref Node node, Representer representer)
     }
 }
 
-///Represent a mapping node as map/ordered map/pairs.
+///Represent a mapping _node as map/ordered map/pairs.
 Node representPairs(ref Node node, Representer representer)
 {
     auto pairs = node.get!(Node.Pair[]);
@@ -433,13 +442,6 @@ Node representPairs(ref Node node, Representer representer)
     }
 }
 
-///Represent a SysTime node as a timestamp.
-Node representSysTime(ref Node node, Representer representer)
-{
-    return representer.representScalar("tag:yaml.org,2002:timestamp", 
-                                       node.get!SysTime.toISOExtString());
-}
-
 //Unittests
 private: