From 2cd2de44ffcba99e0d5c71312c7ec983d0915442 Mon Sep 17 00:00:00 2001 From: Ferdinand Majerech Date: Tue, 18 Oct 2011 21:40:37 +0200 Subject: [PATCH] Updated Constructor API documentation with examples. --- doc/doctrees/environment.pickle | Bin 12705 -> 12705 bytes doc/html/api/dyaml.constructor.html | 114 ++++++++++++++- doc/html/api/dyaml.representer.html | 4 +- doc/html/api/dyaml.resolver.html | 2 +- dyaml/constructor.d | 206 ++++++++++++++++++++++++++++ dyaml/representer.d | 4 +- dyaml/resolver.d | 2 +- 7 files changed, 324 insertions(+), 8 deletions(-) diff --git a/doc/doctrees/environment.pickle b/doc/doctrees/environment.pickle index b8faa2befb088693fbc7544bd8359d1afb73004b..1db15b6eb6d1b06ca310dcb6035e940dea2e150e 100644 GIT binary patch delta 62 zcmZ3OyfAq~o4#RbbIg~P3}tu6%galfLymZ4=s=iJg5?>e5N7zt3mJA0X6WLjo44z~ GVgvw%Qynk> delta 62 zcmZ3OyfAq~o4#SP`+-P-3}tu6%gdA9ci1;(=s=izYp-OOLYTV~&t%v^m^-DrH*eQ} G#RvdaM;p}u diff --git a/doc/html/api/dyaml.constructor.html b/doc/html/api/dyaml.constructor.html index 27b96d6..c7ed879 100644 --- a/doc/html/api/dyaml.constructor.html +++ b/doc/html/api/dyaml.constructor.html @@ -113,20 +113,130 @@ 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 addConstructorSequence(T)(in string tag, T function(Mark, Mark, ref Node) ctor);

Add a constructor function from sequence.

-See Also:
addConstructorScalar
+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 addConstructorMapping(T)(in string tag, T function(Mark, Mark, ref Node) ctor);

Add a constructor function from a mapping.

-See Also:
addConstructorScalar
+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();
+ }
+
+

diff --git a/doc/html/api/dyaml.representer.html b/doc/html/api/dyaml.representer.html index bed446e..e02ff46 100644 --- a/doc/html/api/dyaml.representer.html +++ b/doc/html/api/dyaml.representer.html @@ -104,7 +104,7 @@ void main() { - auto dumper = Dumper("file.txt"); + auto dumper = Dumper("file.yaml"); auto representer = new Representer; representer.addRepresenter!MyStruct(&representMyStruct); dumper.representer = representer; @@ -156,7 +156,7 @@ void main() { - auto dumper = Dumper("file.txt"); + auto dumper = Dumper("file.yaml"); auto representer = new Representer; representer.addRepresenter!MyClass(&representMyClass); dumper.representer = representer; diff --git a/doc/html/api/dyaml.resolver.html b/doc/html/api/dyaml.resolver.html index 60351b6..f465f74 100644 --- a/doc/html/api/dyaml.resolver.html +++ b/doc/html/api/dyaml.resolver.html @@ -87,7 +87,7 @@ string first String of possible starting characters of the scalar. -Examples:
Resolve scalars starting with 'A' to !tag : +Examples:
Resolve scalars starting with 'A' to !tag : 
 import std.regex;
 
  import yaml;
diff --git a/dyaml/constructor.d b/dyaml/constructor.d
index a4427a6..c7ebcf5 100644
--- a/dyaml/constructor.d
+++ b/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));
+}
diff --git a/dyaml/representer.d b/dyaml/representer.d
index c72eb70..a865364 100644
--- a/dyaml/representer.d
+++ b/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;
diff --git a/dyaml/resolver.d b/dyaml/resolver.d
index 722da89..a466712 100644
--- a/dyaml/resolver.d
+++ b/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;
          *