Updated Constructor API documentation with examples.

doc/html/api/dyaml.constructor.html

@@ -113,20 +113,130 @@
 <tr><td valign=top>ctor</td>
 <td valign=top>Constructor function.</td></tr>
 </table></div>
+<p><b>Example:</b><br>
+<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;
+ }
+
+ MyStruct constructMyStructScalar(Mark start, Mark end, <span class="d_keyword">ref</span> Node node)
+ {
+     <span class="d_comment">//Guaranteed to be string as we construct from scalar.
+</span>     <span class="d_comment">//!mystruct x:y:z
+</span>     <span class="d_keyword">auto</span> parts = node.get!string().split(<span class="d_string">":"</span>);
+     <span class="d_keyword">try</span>
+     {
+         <span class="d_keyword">return</span> MyStruct(to!<span class="d_keyword">int</span>(parts[0]), to!<span class="d_keyword">int</span>(parts[1]), to!<span class="d_keyword">int</span>(parts[2]));
+     }
+     <span class="d_keyword">catch</span>(Exception e)
+     {
+         <span class="d_keyword">throw</span> <span class="d_keyword">new</span> ConstructorException(<span class="d_string">"Could not construct MyStruct: "</span> ~ e.msg,
+                                        start, end);
+     }
+ }
+
+ <span class="d_keyword">void</span> main()
+ {
+     <span class="d_keyword">auto</span> loader = Loader(<span class="d_string">"file.yaml"</span>);
+     <span class="d_keyword">auto</span> constructor = <span class="d_keyword">new</span> Constructor;
+     constructor.<span class="d_psymbol">addConstructorScalar</span>(<span class="d_string">"!mystruct"</span>, &amp;constructMyStructScalar);
+     loader.constructor = constructor;
+     Node node = loader.load();
+ }
+</pre>
+</p>
 
 </dd>
 <dt class="d_decl">void <a name="addConstructorSequence"></a><span class="ddoc_psymbol">addConstructorSequence</span>(T)(in string <b>tag</b>, T function(Mark, Mark, ref Node) <b>ctor</b>);
 </dt>
 <dd><p>Add a constructor function from sequence.
 </p>
-<b>See Also:</b><div class="pbr">addConstructorScalar</div>
+<b>See Also:</b><div class="pbr">addConstructorScalar
+
+</div>
+<p><b>Example:</b><br>
+<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;
+ }
+
+ MyStruct constructMyStructSequence(Mark start, Mark end, <span class="d_keyword">ref</span> Node node)
+ {
+     <span class="d_comment">//node is guaranteed to be sequence.
+</span>     <span class="d_comment">//!mystruct [x, y, z]
+</span>     <span class="d_keyword">try</span>
+     {
+         <span class="d_keyword">return</span> MyStruct(node[0].get!<span class="d_keyword">int</span>, node[1].get!<span class="d_keyword">int</span>, node[2].get!<span class="d_keyword">int</span>);
+     }
+     <span class="d_keyword">catch</span>(NodeException e)
+     {
+         <span class="d_keyword">throw</span> <span class="d_keyword">new</span> ConstructorException(<span class="d_string">"Could not construct MyStruct: "</span> ~ e.msg,
+                                        start, end);
+     }
+ }
+
+ <span class="d_keyword">void</span> main()
+ {
+     <span class="d_keyword">auto</span> loader = Loader(<span class="d_string">"file.yaml"</span>);
+     <span class="d_keyword">auto</span> constructor = <span class="d_keyword">new</span> Constructor;
+     constructor.<span class="d_psymbol">addConstructorSequence</span>(<span class="d_string">"!mystruct"</span>, &amp;constructMyStructSequence);
+     loader.constructor = constructor;
+     Node node = loader.load();
+ }
+</pre>
+</p>
 
 </dd>
 <dt class="d_decl">void <a name="addConstructorMapping"></a><span class="ddoc_psymbol">addConstructorMapping</span>(T)(in string <b>tag</b>, T function(Mark, Mark, ref Node) <b>ctor</b>);
 </dt>
 <dd><p>Add a constructor function from a mapping.
 </p>
-<b>See Also:</b><div class="pbr">addConstructorScalar</div>
+<b>See Also:</b><div class="pbr">addConstructorScalar
+
+</div>
+<p><b>Example:</b><br>
+<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;
+ }
+
+ MyStruct constructMyStructMapping(Mark start, Mark end, <span class="d_keyword">ref</span> Node node)
+ {
+     <span class="d_comment">//node is guaranteed to be mapping.
+</span>     <span class="d_comment">//!mystruct {"x": x, "y": y, "z": z}
+</span>     <span class="d_keyword">try</span>
+     {
+         <span class="d_keyword">return</span> MyStruct(node[<span class="d_string">"x"</span>].get!<span class="d_keyword">int</span>, node[<span class="d_string">"y"</span>].get!<span class="d_keyword">int</span>, node[<span class="d_string">"z"</span>].get!<span class="d_keyword">int</span>);
+     }
+     <span class="d_keyword">catch</span>(NodeException e)
+     {
+         <span class="d_keyword">throw</span> <span class="d_keyword">new</span> ConstructorException(<span class="d_string">"Could not construct MyStruct: "</span> ~ e.msg,
+                                        start, end);
+     }
+ }
+
+ <span class="d_keyword">void</span> main()
+ {
+     <span class="d_keyword">auto</span> loader = Loader(<span class="d_string">"file.yaml"</span>);
+     <span class="d_keyword">auto</span> constructor = <span class="d_keyword">new</span> Constructor;
+     constructor.<span class="d_psymbol">addConstructorMapping</span>(<span class="d_string">"!mystruct"</span>, &amp;constructMyStructMapping);
+     loader.constructor = constructor;
+     Node node = loader.load();
+ }
+</pre>
+</p>
 
 </dd>
 </dl>

doc/html/api/dyaml.representer.html

@@ -104,7 +104,7 @@
 
  <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> dumper = Dumper(<span class="d_string">"file.yaml"</span>);
      <span class="d_keyword">auto</span> representer = <span class="d_keyword">new</span> Representer;
      representer.<span class="d_psymbol">addRepresenter</span>!MyStruct(&amp;representMyStruct);
      dumper.representer = representer;
@@ -156,7 +156,7 @@
 
  <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> dumper = Dumper(<span class="d_string">"file.yaml"</span>);
      <span class="d_keyword">auto</span> representer = <span class="d_keyword">new</span> Representer;
      representer.<span class="d_psymbol">addRepresenter</span>!MyClass(&amp;representMyClass);
      dumper.representer = representer;

doc/html/api/dyaml.resolver.html

@@ -87,7 +87,7 @@
 <tr><td valign=top>string <b>first</b></td>
 <td valign=top>String of possible starting characters of the scalar.</td></tr>
 </table></div>
-<b>Examples:</b><div class="pbr">Resolve scalars starting with 'A' to !<b>tag</b> :
+<b>Examples:</b><div class="pbr">Resolve scalars starting with 'A' to !tag :
 <pre class="d_code"> <span class="d_keyword">import</span> std.regex;
 
  <span class="d_keyword">import</span> yaml;

dyaml/constructor.d

@@ -132,6 +132,44 @@ final class Constructor
          *
          * Params:  tag  = Tag for the function to handle.
          *          ctor = Constructor function.
+         *
+         * Example:
+         *
+         * --------------------
+         * import std.string;
+         *
+         * import yaml;
+         *
+         * struct MyStruct
+         * {
+         *     int x, y, z;
+         * }
+         *
+         * MyStruct constructMyStructScalar(Mark start, Mark end, ref Node node)
+         * { 
+         *     //Guaranteed to be string as we construct from scalar.
+         *     //!mystruct x:y:z
+         *     auto parts = node.get!string().split(":");
+         *     try
+         *     {
+         *         return MyStruct(to!int(parts[0]), to!int(parts[1]), to!int(parts[2]));
+         *     }
+         *     catch(Exception e)
+         *     {
+         *         throw new ConstructorException("Could not construct MyStruct: " ~ e.msg, 
+         *                                        start, end);
+         *     }
+         * }
+         *
+         * void main()
+         * {
+         *     auto loader = Loader("file.yaml");
+         *     auto constructor = new Constructor;
+         *     constructor.addConstructorScalar("!mystruct", &constructMyStructScalar);
+         *     loader.constructor = constructor;
+         *     Node node = loader.load();
+         * }
+         * --------------------
          */
         void addConstructorScalar(T)(in string tag, T function(Mark, Mark, ref Node) ctor)
         {
@@ -144,6 +182,43 @@ final class Constructor
          * Add a constructor function from sequence.
          *
          * See_Also:    addConstructorScalar
+         * 
+         * Example:
+         *
+         * --------------------
+         * import std.string;
+         *
+         * import yaml;
+         *
+         * struct MyStruct
+         * {
+         *     int x, y, z;
+         * }
+         *
+         * MyStruct constructMyStructSequence(Mark start, Mark end, ref Node node)
+         * { 
+         *     //node is guaranteed to be sequence.
+         *     //!mystruct [x, y, z]
+         *     try
+         *     {
+         *         return MyStruct(node[0].get!int, node[1].get!int, node[2].get!int);
+         *     }
+         *     catch(NodeException e)
+         *     {
+         *         throw new ConstructorException("Could not construct MyStruct: " ~ e.msg, 
+         *                                        start, end);
+         *     }
+         * }
+         *
+         * void main()
+         * {
+         *     auto loader = Loader("file.yaml");
+         *     auto constructor = new Constructor;
+         *     constructor.addConstructorSequence("!mystruct", &constructMyStructSequence);
+         *     loader.constructor = constructor;
+         *     Node node = loader.load();
+         * }
+         * --------------------
          */
         void addConstructorSequence(T)(in string tag, T function(Mark, Mark, ref Node) ctor)
         {
@@ -156,6 +231,43 @@ final class Constructor
          * Add a constructor function from a mapping.
          *
          * See_Also:    addConstructorScalar
+         * 
+         * Example:
+         *
+         * --------------------
+         * import std.string;
+         *
+         * import yaml;
+         *
+         * struct MyStruct
+         * {
+         *     int x, y, z;
+         * }
+         *
+         * MyStruct constructMyStructMapping(Mark start, Mark end, ref Node node)
+         * { 
+         *     //node is guaranteed to be mapping.
+         *     //!mystruct {"x": x, "y": y, "z": z}
+         *     try
+         *     {
+         *         return MyStruct(node["x"].get!int, node["y"].get!int, node["z"].get!int);
+         *     }
+         *     catch(NodeException e)
+         *     {
+         *         throw new ConstructorException("Could not construct MyStruct: " ~ e.msg, 
+         *                                        start, end);
+         *     }
+         * }
+         *
+         * void main()
+         * {
+         *     auto loader = Loader("file.yaml");
+         *     auto constructor = new Constructor;
+         *     constructor.addConstructorMapping("!mystruct", &constructMyStructMapping);
+         *     loader.constructor = constructor;
+         *     Node node = loader.load();
+         * }
+         * --------------------
          */
         void addConstructorMapping(T)(in string tag, T function(Mark, Mark, ref Node) ctor)
         {
@@ -680,3 +792,97 @@ Node.Pair[] constructMap(Mark start, Mark end, ref Node node)
     }
     return pairs;
 }
+
+
+//Unittests
+private:
+
+import std.stream;
+import dyaml.loader;
+
+struct MyStruct
+{
+    int x, y, z;
+}
+
+MyStruct constructMyStructScalar(Mark start, Mark end, ref Node node)
+{ 
+    //Guaranteed to be string as we construct from scalar.
+    auto parts = node.get!string().split(":");
+    try
+    {
+        return MyStruct(to!int(parts[0]), to!int(parts[1]), to!int(parts[2]));
+    }
+    catch(Exception e)
+    {
+        throw new ConstructorException("Could not construct MyStruct: " ~ e.msg, 
+                                       start, end);
+    }
+}
+
+MyStruct constructMyStructSequence(Mark start, Mark end, ref Node node)
+{ 
+    //node is guaranteed to be sequence.
+    try
+    {
+        return MyStruct(node[0].get!int, node[1].get!int, node[2].get!int);
+    }
+    catch(NodeException e)
+    {
+        throw new ConstructorException("Could not construct MyStruct: " ~ e.msg, 
+                                       start, end);
+    }
+}
+
+MyStruct constructMyStructMapping(Mark start, Mark end, ref Node node)
+{ 
+    //node is guaranteed to be mapping.
+    try
+    {
+        return MyStruct(node["x"].get!int, node["y"].get!int, node["z"].get!int);
+    }
+    catch(NodeException e)
+    {
+        throw new ConstructorException("Could not construct MyStruct: " ~ e.msg, 
+                                       start, end);
+    }
+}
+
+unittest
+{
+    char[] data = cast(char[])"!mystruct 1:2:3";
+    auto loadStream  = new MemoryStream(data);
+    auto loader = Loader(loadStream);
+    auto constructor = new Constructor;
+    constructor.addConstructorScalar("!mystruct", &constructMyStructScalar);
+    loader.constructor = constructor;
+    Node node = loader.load();
+
+    assert(node.get!MyStruct == MyStruct(1, 2, 3));
+}
+
+unittest
+{
+    char[] data = cast(char[])"!mystruct [1, 2, 3]";
+    auto loadStream  = new MemoryStream(data);
+    auto loader = Loader(loadStream);
+    auto constructor = new Constructor;
+    constructor.addConstructorSequence("!mystruct", &constructMyStructSequence);
+    loader.constructor = constructor;
+    Node node = loader.load();
+
+    assert(node.get!MyStruct == MyStruct(1, 2, 3));
+}
+
+unittest
+{
+    char[] data = cast(char[])"!mystruct {x: 1, y: 2, z: 3}";
+    auto loadStream  = new MemoryStream(data);
+    auto loader = Loader(loadStream);
+    auto constructor = new Constructor;
+    constructor.addConstructorMapping("!mystruct", &constructMyStructMapping);
+    loader.constructor = constructor;
+    Node node = loader.load();
+
+    assert(node.get!MyStruct == MyStruct(1, 2, 3));
+}

dyaml/representer.d

@@ -108,7 +108,7 @@ final class Representer
          *
          * void main()
          * {
-         *     auto dumper = Dumper("file.txt");
+         *     auto dumper = Dumper("file.yaml");
          *     auto representer = new Representer;
          *     representer.addRepresenter!MyStruct(&representMyStruct);
          *     dumper.representer = representer;
@@ -161,7 +161,7 @@ final class Representer
          *
          * void main()
          * {
-         *     auto dumper = Dumper("file.txt");
+         *     auto dumper = Dumper("file.yaml");
          *     auto representer = new Representer;
          *     representer.addRepresenter!MyClass(&representMyClass);
          *     dumper.representer = representer;

dyaml/resolver.d

@@ -91,7 +91,7 @@ final class Resolver
          *
          * Examples:
          *
-         * Resolve scalars starting with 'A' to !tag :
+         * Resolve scalars starting with 'A' to !_tag :
          * --------------------
          * import std.regex;
          *