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