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

Doc style changes in constructor.d

Browse source
This commit is contained in:
Ferdinand Majerech 2014-07-19 03:49:21 +02:00
parent d8f19ffc33
commit 424035601c
1 changed files with 200 additions and 214 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

368
source/dyaml/constructor.d
View file

@ -31,20 +31,16 @@ import dyaml.tag;
import dyaml.style;
/**
* Exception thrown at constructor errors.
*
* Can be thrown by custom constructor functions.
*/
/// Exception thrown at constructor errors.
///
/// Can be thrown by custom constructor functions.
package class ConstructorException : YAMLException
{
/**
* Construct a ConstructorException.
*
* Params: msg = Error message.
* start = Start position of the error context.
* end = End position of the error context.
*/
/// Construct a ConstructorException.
///
/// Params: msg = Error message.
/// start = Start position of the error context.
/// end = End position of the error context.
this(string msg, Mark start, Mark end, string file = __FILE__, int line = __LINE__)
@safe
{
@ -55,21 +51,19 @@ package class ConstructorException : YAMLException
private alias ConstructorException Error;
/**
* Constructs YAML values.
*
* Each YAML scalar, sequence or mapping has a tag specifying its data type.
* Constructor uses user-specifyable functions to create a node of desired
* data type from a scalar, sequence or mapping.
*
*
* Each of these functions is associated with a tag, and can process either
* a scalar, a sequence, or a mapping. The constructor passes each value to
* the function with corresponding tag, which then returns the resulting value
* that can be stored in a node.
*
* If a tag is detected with no known constructor function, it is considered an error.
*/
/// Constructs YAML values.
///
/// Each YAML scalar, sequence or mapping has a tag specifying its data type.
/// Constructor uses user-specifyable functions to create a node of desired
/// data type from a scalar, sequence or mapping.
///
///
/// Each of these functions is associated with a tag, and can process either
/// a scalar, a sequence, or a mapping. The constructor passes each value to
/// the function with corresponding tag, which then returns the resulting value
/// that can be stored in a node.
///
/// If a tag is detected with no known constructor function, it is considered an error.
final class Constructor
{
private:
@ -81,14 +75,12 @@ final class Constructor
Node.Value delegate(ref Node)[Tag] fromMapping_;
public:
/**
* Construct a Constructor.
*
* If you don't want to support default YAML tags/data types, you can use
* defaultConstructors to disable constructor functions for these.
*
* Params: defaultConstructors = Use constructors for default YAML tags?
*/
/// Construct a Constructor.
///
/// If you don't want to support default YAML tags/data types, you can use
/// defaultConstructors to disable constructor functions for these.
///
/// Params: defaultConstructors = Use constructors for default YAML tags?
this(const Flag!"useDefaultConstructors" defaultConstructors = Yes.useDefaultConstructors)
@safe nothrow
{
@ -124,74 +116,72 @@ final class Constructor
fromMapping_ = null;
}
/**
* Add a constructor function from scalar.
*
* The function must take a reference to $(D Node) to construct from.
* The node contains a string for scalars, $(Node[]) for sequences and
* $(Node.Pair[]) for mappings.
*
* Any exception thrown by this function will be caught by D:YAML and
* its message will be added to a $(YAMLException) that will also tell
* the user which type failed to construct, and position in the file.
*
*
* The value returned by this function will be stored in the resulting node.
*
* Only one constructor function can be set for one tag.
*
*
* Structs and classes must implement the $(D opCmp()) operator for D:YAML
* support. The signature of the operator that must be implemented
* is $(D const int opCmp(ref const MyStruct s)) for structs where
* $(I MyStruct) is the struct type, and $(D int opCmp(Object o)) for
* classes. Note that the class $(D opCmp()) should not alter the compared
* values - it is not const for compatibility reasons.
*
* Params: tag = Tag for the function to handle.
* ctor = Constructor function.
*
* Example:
*
* --------------------
* import std.string;
*
* import dyaml.all;
*
* struct MyStruct
* {
* int x, y, z;
*
* //Any D:YAML type must have a custom opCmp operator.
* //This is used for ordering in mappings.
* const int opCmp(ref const MyStruct s)
* {
* if(x != s.x){return x - s.x;}
* if(y != s.y){return y - s.y;}
* if(z != s.z){return z - s.z;}
* return 0;
* }
* }
*
* MyStruct constructMyStructScalar(ref Node node)
* {
* //Guaranteed to be string as we construct from scalar.
* //!mystruct x:y:z
* auto parts = node.as!string().split(":");
* //If this throws, the D:YAML will handle it and throw a YAMLException.
* return MyStruct(to!int(parts[0]), to!int(parts[1]), to!int(parts[2]));
* }
*
* void main()
* {
* auto loader = Loader("file.yaml");
* auto constructor = new Constructor;
* constructor.addConstructorScalar("!mystruct", &constructMyStructScalar);
* loader.constructor = constructor;
* Node node = loader.load();
* }
* --------------------
*/
/// Add a constructor function from scalar.
///
/// The function must take a reference to $(D Node) to construct from.
/// The node contains a string for scalars, $(Node[]) for sequences and
/// $(Node.Pair[]) for mappings.
///
/// Any exception thrown by this function will be caught by D:YAML and
/// its message will be added to a $(YAMLException) that will also tell
/// the user which type failed to construct, and position in the file.
///
///
/// The value returned by this function will be stored in the resulting node.
///
/// Only one constructor function can be set for one tag.
///
///
/// Structs and classes must implement the $(D opCmp()) operator for D:YAML
/// support. The signature of the operator that must be implemented
/// is $(D const int opCmp(ref const MyStruct s)) for structs where
/// $(I MyStruct) is the struct type, and $(D int opCmp(Object o)) for
/// classes. Note that the class $(D opCmp()) should not alter the compared
/// values - it is not const for compatibility reasons.
///
/// Params: tag = Tag for the function to handle.
/// ctor = Constructor function.
///
/// Example:
///
/// --------------------
/// import std.string;
///
/// import dyaml.all;
///
/// struct MyStruct
/// {
/// int x, y, z;
///
/// //Any D:YAML type must have a custom opCmp operator.
/// //This is used for ordering in mappings.
/// const int opCmp(ref const MyStruct s)
/// {
/// if(x != s.x){return x - s.x;}
/// if(y != s.y){return y - s.y;}
/// if(z != s.z){return z - s.z;}
/// return 0;
/// }
/// }
///
/// MyStruct constructMyStructScalar(ref Node node)
/// {
/// //Guaranteed to be string as we construct from scalar.
/// //!mystruct x:y:z
/// auto parts = node.as!string().split(":");
/// // If this throws, the D:YAML will handle it and throw a YAMLException.
/// return MyStruct(to!int(parts[0]), to!int(parts[1]), to!int(parts[2]));
/// }
///
/// 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)(const string tag, T function(ref Node) ctor)
@safe nothrow
{
@ -200,50 +190,48 @@ final class Constructor
(*delegates!string)[t] = deleg;
}
/**
* Add a constructor function from sequence.
*
* See_Also: addConstructorScalar
*
* Example:
*
* --------------------
* import std.string;
*
* import dyaml.all;
*
* struct MyStruct
* {
* int x, y, z;
*
* //Any D:YAML type must have a custom opCmp operator.
* //This is used for ordering in mappings.
* const int opCmp(ref const MyStruct s)
* {
* if(x != s.x){return x - s.x;}
* if(y != s.y){return y - s.y;}
* if(z != s.z){return z - s.z;}
* return 0;
* }
* }
*
* MyStruct constructMyStructSequence(ref Node node)
* {
* //node is guaranteed to be sequence.
* //!mystruct [x, y, z]
* return MyStruct(node[0].as!int, node[1].as!int, node[2].as!int);
* }
*
* void main()
* {
* auto loader = Loader("file.yaml");
* auto constructor = new Constructor;
* constructor.addConstructorSequence("!mystruct", &constructMyStructSequence);
* loader.constructor = constructor;
* Node node = loader.load();
* }
* --------------------
*/
/// Add a constructor function from sequence.
///
/// See_Also: addConstructorScalar
///
/// Example:
///
/// --------------------
/// import std.string;
///
/// import dyaml.all;
///
/// struct MyStruct
/// {
/// int x, y, z;
///
/// //Any D:YAML type must have a custom opCmp operator.
/// //This is used for ordering in mappings.
/// const int opCmp(ref const MyStruct s)
/// {
/// if(x != s.x){return x - s.x;}
/// if(y != s.y){return y - s.y;}
/// if(z != s.z){return z - s.z;}
/// return 0;
/// }
/// }
///
/// MyStruct constructMyStructSequence(ref Node node)
/// {
/// //node is guaranteed to be sequence.
/// //!mystruct [x, y, z]
/// return MyStruct(node[0].as!int, node[1].as!int, node[2].as!int);
/// }
///
/// 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)(const string tag, T function(ref Node) ctor)
@safe nothrow
{
@ -252,50 +240,48 @@ final class Constructor
(*delegates!(Node[]))[t] = deleg;
}
/**
* Add a constructor function from a mapping.
*
* See_Also: addConstructorScalar
*
* Example:
*
* --------------------
* import std.string;
*
* import dyaml.all;
*
* struct MyStruct
* {
* int x, y, z;
*
* //Any D:YAML type must have a custom opCmp operator.
* //This is used for ordering in mappings.
* const int opCmp(ref const MyStruct s)
* {
* if(x != s.x){return x - s.x;}
* if(y != s.y){return y - s.y;}
* if(z != s.z){return z - s.z;}
* return 0;
* }
* }
*
* MyStruct constructMyStructMapping(ref Node node)
* {
* //node is guaranteed to be mapping.
* //!mystruct {"x": x, "y": y, "z": z}
* return MyStruct(node["x"].as!int, node["y"].as!int, node["z"].as!int);
* }
*
* void main()
* {
* auto loader = Loader("file.yaml");
* auto constructor = new Constructor;
* constructor.addConstructorMapping("!mystruct", &constructMyStructMapping);
* loader.constructor = constructor;
* Node node = loader.load();
* }
* --------------------
*/
/// Add a constructor function from a mapping.
///
/// See_Also: addConstructorScalar
///
/// Example:
///
/// --------------------
/// import std.string;
///
/// import dyaml.all;
///
/// struct MyStruct
/// {
/// int x, y, z;
///
/// //Any D:YAML type must have a custom opCmp operator.
/// //This is used for ordering in mappings.
/// const int opCmp(ref const MyStruct s)
/// {
/// if(x != s.x){return x - s.x;}
/// if(y != s.y){return y - s.y;}
/// if(z != s.z){return z - s.z;}
/// return 0;
/// }
/// }
///
/// MyStruct constructMyStructMapping(ref Node node)
/// {
/// //node is guaranteed to be mapping.
/// //!mystruct {"x": x, "y": y, "z": z}
/// return MyStruct(node["x"].as!int, node["y"].as!int, node["z"].as!int);
/// }
///
/// 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)(const string tag, T function(ref Node) ctor)
@safe nothrow
{