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

Doc style change in node.d

Browse source
This commit is contained in:
Ferdinand Majerech 2014-07-19 01:58:24 +02:00
parent 7ae4de4776
commit 28979baa6c
1 changed files with 470 additions and 527 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

805
source/dyaml/node.d
View file

@ -4,10 +4,8 @@
// (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)
/**
* Node of a YAML document. Used to read YAML data once it's loaded,
* and to prepare data to emit.
*/
/// Node of a YAML document. Used to read YAML data once it's loaded,
/// and to prepare data to emit.
module dyaml.node;
@ -34,12 +32,10 @@ import dyaml.tag;
class NodeException : YAMLException
{
package:
/*
* Construct a NodeException.
*
* Params: msg = Error message.
* start = Start position of the node.
*/
// Construct a NodeException.
//
// Params: msg = Error message.
// start = Start position of the node.
this(string msg, Mark start, string file = __FILE__, int line = __LINE__)
@safe
{
@ -121,13 +117,11 @@ package class YAMLContainer(T) if (!Node.allowed!T): YAMLObject
this(T value) @trusted {value_ = value;}
}
/**
* YAML node.
*
* This is a pseudo-dynamic type that can store any YAML value, including a
* sequence or mapping of nodes. You can get data from a Node directly or
* iterate over it if it's a collection.
*/
/// YAML node.
///
/// This is a pseudo-dynamic type that can store any YAML value, including a
/// sequence or mapping of nodes. You can get data from a Node directly or
/// iterate over it if it's a collection.
struct Node
{
public:
@ -170,12 +164,10 @@ struct Node
}
private:
/*
* Comparison with another Pair.
*
* useTag determines whether or not we consider node tags
* in the comparison.
*/
// Comparison with another Pair.
//
// useTag determines whether or not we consider node tags
// in the comparison.
int cmp(Flag!"useTag" useTag)(ref const(Pair) rhs) const @safe
{
const keyCmp = key.cmp!useTag(rhs.key);
@ -226,27 +218,25 @@ struct Node
static assert(Node.sizeof <= 48, "Unexpected YAML node size");
public:
/**
* Construct a Node from a value.
*
* Any type except for Node can be stored in a Node, but default YAML
* types (integers, floats, strings, timestamps, etc.) will be stored
* more efficiently. To create a node representing a null value,
* construct it from YAMLNull.
*
*
* 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.
*
* Params: value = Value to store in the node.
* tag = 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".
*/
/// Construct a Node from a value.
///
/// Any type except for Node can be stored in a Node, but default YAML
/// types (integers, floats, strings, timestamps, etc.) will be stored
/// more efficiently. To create a node representing a null value,
/// construct it from YAMLNull.
///
///
/// 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.
///
/// Params: value = Value to store in the node.
/// tag = 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".
this(T)(T value, const string tag = null) @trusted
if (isSomeString!T || (!isArray!T && !isAssociativeArray!T))
{
@ -280,32 +270,30 @@ struct Node
}
}
/**
* Construct a node from an _array.
*
* 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.
*
* Params: array = Values to store in the node.
* tag = 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".
*
* Examples:
* --------------------
* //Will be emitted as a sequence (default for arrays)
* auto seq = Node([1, 2, 3, 4, 5]);
* //Will be emitted as a set (overriden tag)
* auto set = Node([1, 2, 3, 4, 5], "tag:yaml.org,2002:set");
* --------------------
*/
/// Construct a node from an _array.
///
/// 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.
///
/// Params: array = Values to store in the node.
/// tag = 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".
///
/// Examples:
/// --------------------
/// // Will be emitted as a sequence (default for arrays)
/// auto seq = Node([1, 2, 3, 4, 5]);
/// // Will be emitted as a set (overriden tag)
/// auto set = Node([1, 2, 3, 4, 5], "tag:yaml.org,2002:set");
/// --------------------
this(T)(T[] array, const string tag = null) @safe
if (!isSomeString!(T[]))
{
@ -343,34 +331,32 @@ struct Node
auto set = Node([1, 2, 3, 4, 5], "tag:yaml.org,2002:set");
}
/**
* Construct a node from an associative _array.
*
* If keys and/or values of _array are nodes, they stored directly.
* 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
* 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".
*
* Examples:
* --------------------
* //Will be emitted as an unordered mapping (default for mappings)
* auto map = Node([1 : "a", 2 : "b"]);
* //Will be emitted as an ordered map (overriden tag)
* auto omap = Node([1 : "a", 2 : "b"], "tag:yaml.org,2002:omap");
* //Will be emitted as pairs (overriden tag)
* auto pairs = Node([1 : "a", 2 : "b"], "tag:yaml.org,2002:pairs");
* --------------------
*/
/// Construct a node from an associative _array.
///
/// If keys and/or values of _array are nodes, they stored directly.
/// 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
/// 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".
///
/// Examples:
/// --------------------
/// // Will be emitted as an unordered mapping (default for mappings)
/// auto map = Node([1 : "a", 2 : "b"]);
/// // Will be emitted as an ordered map (overriden tag)
/// auto omap = Node([1 : "a", 2 : "b"], "tag:yaml.org,2002:omap");
/// // Will be emitted as pairs (overriden tag)
/// auto pairs = Node([1 : "a", 2 : "b"], "tag:yaml.org,2002:pairs");
/// --------------------
this(K, V)(V[K] array, const string tag = null) @safe
{
tag_ = Tag(tag);
@ -399,43 +385,41 @@ struct Node
auto pairs = Node([1 : "a", 2 : "b"], "tag:yaml.org,2002:pairs");
}
/**
* 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
* is important (ordered maps, pairs).
*
*
* keys and values must have equal length.
*
*
* 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.
* tag = 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".
*
* Examples:
* --------------------
* //Will be emitted as an unordered mapping (default for mappings)
* auto map = Node([1, 2], ["a", "b"]);
* //Will be emitted as an ordered map (overriden tag)
* auto omap = Node([1, 2], ["a", "b"], "tag:yaml.org,2002:omap");
* //Will be emitted as pairs (overriden tag)
* auto pairs = Node([1, 2], ["a", "b"], "tag:yaml.org,2002:pairs");
* --------------------
*/
/// 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
/// is important (ordered maps, pairs).
///
///
/// keys and values must have equal length.
///
///
/// 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.
/// tag = 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".
///
/// Examples:
/// --------------------
/// // Will be emitted as an unordered mapping (default for mappings)
/// auto map = Node([1, 2], ["a", "b"]);
/// // Will be emitted as an ordered map (overriden tag)
/// auto omap = Node([1, 2], ["a", "b"], "tag:yaml.org,2002:omap");
/// // Will be emitted as pairs (overriden tag)
/// auto pairs = Node([1, 2], ["a", "b"], "tag:yaml.org,2002:pairs");
/// --------------------
this(K, V)(K[] keys, V[] values, const string tag = null) @safe
if(!(isSomeString!(K[]) || isSomeString!(V[])))
in
@ -508,30 +492,28 @@ struct Node
/// Return tag of the node.
@property string tag() const @safe nothrow {return tag_.get;}
/**
* Equality test.
*
* If T is Node, recursively compare all subnodes.
* This might be quite expensive if testing entire documents.
*
* If T is not Node, get a value if type T from the node and test
* equality with that.
*
* To test equality with a null YAML value, use YAMLNull.
*
* Examples:
* --------------------
* auto node = Node(42);
*
* assert(node == 42);
* assert(node != "42");
* assert(node != "43");
* --------------------
*
* Params: rhs = Variable to test equality with.
*
* Returns: true if equal, false otherwise.
*/
/// Equality test.
///
/// If T is Node, recursively compare all subnodes.
/// This might be quite expensive if testing entire documents.
///
/// If T is not Node, get a value if type T from the node and test
/// equality with that.
///
/// To test equality with a null YAML value, use YAMLNull.
///
/// Examples:
/// --------------------
/// auto node = Node(42);
///
/// assert(node == 42);
/// assert(node != "42");
/// assert(node != "43");
/// --------------------
///
/// Params: rhs = Variable to test equality with.
///
/// Returns: true if equal, false otherwise.
bool opEquals(T)(const auto ref T rhs) const @safe
{
return equals!(Yes.useTag)(rhs);
@ -551,50 +533,48 @@ struct Node
/// Shortcut for get().
alias get as;
/**
* Get the value of the node as specified type.
*
* If the specifed type does not match type in the node,
* conversion is attempted. The stringConversion template
* parameter can be used to disable conversion from non-string
* types to strings.
*
* Numeric values are range checked, throwing if out of range of
* requested type.
*
* Timestamps are stored as std.datetime.SysTime.
* Binary values are decoded and stored as ubyte[].
*
* To get a null value, use get!YAMLNull . This is to
* prevent getting null values for types such as strings or classes.
*
* $(BR)$(B Mapping default values:)
*
* $(PBR
* The '=' key can be used to denote the default value of a mapping.
* This can be used when a node is scalar in early versions of a program,
* 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 expect the node to be a scalar.
* )
*
* Examples:
*
* Automatic type conversion:
* --------------------
* auto node = Node(42);
*
* assert(node.as!int == 42);
* assert(node.as!string == "42");
* assert(node.as!double == 42.0);
* --------------------
*
* Returns: Value of the node as specified type.
*
* Throws: NodeException if unable to convert to specified type, or if
* the value is out of range of requested type.
*/
/// Get the value of the node as specified type.
///
/// If the specifed type does not match type in the node,
/// conversion is attempted. The stringConversion template
/// parameter can be used to disable conversion from non-string
/// types to strings.
///
/// Numeric values are range checked, throwing if out of range of
/// requested type.
///
/// Timestamps are stored as std.datetime.SysTime.
/// Binary values are decoded and stored as ubyte[].
///
/// To get a null value, use get!YAMLNull . This is to
/// prevent getting null values for types such as strings or classes.
///
/// $(BR)$(B Mapping default values:)
///
/// $(PBR
/// The '=' key can be used to denote the default value of a mapping.
/// This can be used when a node is scalar in early versions of a program,
/// 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 expect the node to be a scalar.
/// )
///
/// Examples:
///
/// Automatic type conversion:
/// --------------------
/// auto node = Node(42);
///
/// assert(node.as!int == 42);
/// assert(node.as!string == "42");
/// assert(node.as!double == 42.0);
/// --------------------
///
/// Returns: Value of the node as specified type.
///
/// Throws: NodeException if unable to convert to specified type, or if
/// the value is out of range of requested type.
@property T get(T, Flag!"stringConversion" stringConversion = Yes.stringConversion)()
@trusted if(!is(T == const))
{
@ -729,15 +709,13 @@ struct Node
}
}
/**
* If this is a collection, return its _length.
*
* Otherwise, throw NodeException.
*
* Returns: Number of elements in a sequence or key-value pairs in a mapping.
*
* Throws: NodeException if this is not a sequence nor a mapping.
*/
/// If this is a collection, return its _length.
///
/// Otherwise, throw NodeException.
///
/// Returns: Number of elements in a sequence or key-value pairs in a mapping.
///
/// Throws: NodeException if this is not a sequence nor a mapping.
@property size_t length() const @safe
{
if(isSequence) {return value_.get!(const Node[]).length;}
@ -746,25 +724,24 @@ struct Node
startMark_);
}
/**
* 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.
*
* To get element at a null index, use YAMLNull for index.
*
* Params: index = Index to use.
*
* Returns: Value corresponding to the index.
*
* Throws: NodeException if the index could not be found,
* non-integral index is used with a sequence or the node is
* not a collection.
*/
/// 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. containsKey() can be used to determine if a mapping
/// has a specific key.
///
/// To get element at a null index, use YAMLNull for index.
///
/// Params: index = Index to use.
///
/// Returns: Value corresponding to the index.
///
/// Throws: NodeException if the index could not be found,
/// non-integral index is used with a sequence or the node is
/// not a collection.
ref Node opIndex(T)(T index) @trusted
{
if(isSequence)
@ -789,10 +766,10 @@ struct Node
}
throw new Error("Trying to index a " ~ nodeTypeString ~ " node", startMark_);
}
///
unittest
{
writeln("D:YAML Node opIndex unittest");
alias Node.Value Value;
alias Node.Pair Pair;
Node n1 = Node(cast(long)11);
@ -824,40 +801,36 @@ struct Node
assertThrown!NodeException(nmap[14]);
}
/**
* Determine if a collection contains specified value.
*
* If the node is a sequence, check if it contains the specified value.
* If it's a mapping, check if it has a value that matches specified value.
*
* To check for a null value, use YAMLNull for rhs.
*
* Params: rhs = Item to look for.
*
* Returns: true if rhs was found, false otherwise.
*
* Throws: NodeException if the node is not a collection.
*/
/// Determine if a collection contains specified value.
///
/// If the node is a sequence, check if it contains the specified value.
/// If it's a mapping, check if it has a value that matches specified value.
///
/// To check for a null value, use YAMLNull for rhs.
///
/// Params: rhs = Item to look for.
///
/// Returns: true if rhs was found, false otherwise.
///
/// Throws: NodeException if the node is not a collection.
bool contains(T)(T rhs) const @safe
{
return contains_!(T, No.key, "contains")(rhs);
}
/**
* Determine if a collection contains specified key.
*
* If the node is a mapping, check if it has a key
* that matches specified key.
*
* To check for a null key, use YAMLNull for rhs.
*
* Params: rhs = Item to look for.
*
* Returns: true if rhs was found, false otherwise.
*
* Throws: NodeException if the node is not a mapping.
*/
/// Determine if a collection contains specified key.
///
/// If the node is a mapping, check if it has a key
/// that matches specified key.
///
/// To check for a null key, use YAMLNull for rhs.
///
/// Params: rhs = Item to look for.
///
/// Returns: true if rhs was found, false otherwise.
///
/// Throws: NodeException if the node is not a mapping.
bool containsKey(T)(T rhs) const @safe
{
return contains_!(T, Yes.key, "containsKey")(rhs);
@ -942,28 +915,26 @@ struct Node
"Node.opAssign() doesn't produce an equivalent copy");
}
/**
* 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, 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. In sequences the index must be in
* range. This ensures behavior siilar to D arrays and associative
* arrays.
*
* To set element at a null index, use YAMLNull for index.
*
* Params: index = Index of the value to set.
*
* Throws: 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.
*/
/// 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, 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. In sequences the index must be in
/// range. This ensures behavior siilar to D arrays and associative
/// arrays.
///
/// To set element at a null index, use YAMLNull for index.
///
/// Params: index = Index of the value to set.
///
/// Throws: 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.
void opIndexAssign(K, V)(V value, K index) @safe
{
if(isSequence())
@ -1028,15 +999,13 @@ struct Node
}
}
/**
* Foreach over a sequence, getting each element as T.
*
* If T is Node, simply iterate over the nodes in the sequence.
* Otherwise, convert each node to T during iteration.
*
* Throws: NodeException if the node is not a sequence or an
* element could not be converted to specified type.
*/
/// Foreach over a sequence, getting each element as T.
///
/// If T is Node, simply iterate over the nodes in the sequence.
/// Otherwise, convert each node to T during iteration.
///
/// Throws: NodeException if the node is not a sequence or an
/// element could not be converted to specified type.
int opApply(T)(int delegate(ref T) dg) @trusted
{
enforce(isSequence,
@ -1085,15 +1054,13 @@ struct Node
assert(array2 == [11, 12, 13, 14]);
}
/**
* Foreach over a mapping, getting each key/value as K/V.
*
* If the K and/or V is Node, simply iterate over the nodes in the mapping.
* Otherwise, convert each key/value to T during iteration.
*
* Throws: NodeException if the node is not a mapping or an
* element could not be converted to specified type.
*/
/// Foreach over a mapping, getting each key/value as K/V.
///
/// If the K and/or V is Node, simply iterate over the nodes in the mapping.
/// Otherwise, convert each key/value to T during iteration.
///
/// Throws: NodeException if the node is not a mapping or an
/// element could not be converted to specified type.
int opApply(K, V)(int delegate(ref K, ref V) dg) @trusted
{
enforce(isMapping,
@ -1179,21 +1146,19 @@ struct 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.
*
* $(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) YAML code will be
* emitted.)
*
* Params: value = Value to _add to the sequence.
*/
/// 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.
///
/// $(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) YAML code will be
/// emitted.)
///
/// Params: value = Value to _add to the sequence.
void add(T)(T value) @safe
{
enforce(isSequence(),
@ -1215,22 +1180,20 @@ struct 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.
*
* $(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) YAML with "!!map" and "!!omap" tags.)
*
* Params: key = Key to _add.
* value = Value to _add.
*/
/// 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.
///
/// $(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) YAML with "!!map" and "!!omap" tags.)
///
/// Params: key = Key to _add.
/// value = Value to _add.
void add(K, V)(K key, V value) @safe
{
enforce(isMapping(),
@ -1252,21 +1215,19 @@ struct Node
}
}
/**
* Determine whether a key is in a mapping, and access its value.
*
* This method can only be called on mapping nodes.
*
* Params: key = Key to search for.
*
* Returns: A pointer to the value (as a Node) corresponding to key,
* or null if not found.
*
* Note: Any modification to the node can invalidate the returned
* pointer.
*
* See_Also: contains
*/
/// Determine whether a key is in a mapping, and access its value.
///
/// This method can only be called on mapping nodes.
///
/// Params: key = Key to search for.
///
/// Returns: A pointer to the value (as a Node) corresponding to key,
/// or null if not found.
///
/// Note: Any modification to the node can invalidate the returned
/// pointer.
///
/// See_Also: contains
Node* opBinaryRight(string op, K)(K key) @trusted if (op == "in")
{
enforce(isMapping, new Error("Trying to use 'in' on a " ~
@ -1295,19 +1256,17 @@ struct Node
assert(mapping["foo"] == Node("newfoo"));
}
/**
* Remove first (if any) occurence of a value in a collection.
*
* This method can only be called on collection nodes.
*
* If the node is a sequence, the first node matching value is removed.
* If the node is a mapping, the first key-value pair where _value
* matches specified value is removed.
*
* Params: rhs = Value to _remove.
*
* Throws: NodeException if the node is not a collection.
*/
/// Remove first (if any) occurence of a value in a collection.
///
/// This method can only be called on collection nodes.
///
/// If the node is a sequence, the first node matching value is removed.
/// If the node is a mapping, the first key-value pair where _value
/// matches specified value is removed.
///
/// Params: rhs = Value to _remove.
///
/// Throws: NodeException if the node is not a collection.
void remove(T)(T rhs) @trusted
{
remove_!(T, No.key, "remove")(rhs);
@ -1338,25 +1297,23 @@ struct Node
}
}
/**
* Remove element at the specified index of 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, remove the first key-value pair where
* key matches index.
*
* 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.
*
* Params: index = Index to remove at.
*
* Throws: 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.
*/
/// Remove element at the specified index of 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, remove the first key-value pair where
/// key matches index.
///
/// 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.
///
/// Params: index = Index to remove at.
///
/// Throws: 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.
void removeAt(T)(T index) @trusted
{
remove_!(T, Yes.key, "removeAt")(index);
@ -1415,17 +1372,15 @@ struct Node
}
package:
/*
* Construct a node from raw data.
*
* Params: value = Value of the node.
* startMark = Start position of the node in file.
* tag = Tag of the node.
* scalarStyle = Scalar style of the node.
* collectionStyle = Collection style of the node.
*
* Returns: Constructed node.
*/
// Construct a node from raw data.
//
// Params: value = Value of the node.
// startMark = Start position of the node in file.
// tag = Tag of the node.
// scalarStyle = Scalar style of the node.
// collectionStyle = Collection style of the node.
//
// Returns: Constructed node.
static Node rawNode(Value value, const Mark startMark, const Tag tag,
const ScalarStyle scalarStyle,
const CollectionStyle collectionStyle) @safe
@ -1468,11 +1423,9 @@ struct Node
else static assert(false, "Unknown value type. Is value() in sync with allowed()?");
}
/*
* Equality test with any value.
*
* useTag determines whether or not to consider tags in node-node comparisons.
*/
// Equality test with any value.
//
// useTag determines whether or not to consider tags in node-node comparisons.
bool equals(Flag!"useTag" useTag, T)(ref T rhs) const @safe
{
static if(is(Unqual!T == Node))
@ -1498,13 +1451,11 @@ struct Node
}
}
/*
* Comparison with another node.
*
* Used for ordering in mappings and for opEquals.
*
* useTag determines whether or not to consider tags in the comparison.
*/
// Comparison with another node.
//
// Used for ordering in mappings and for opEquals.
//
// useTag determines whether or not to consider tags in the comparison.
int cmp(Flag!"useTag" useTag)(const ref Node rhs) const @trusted
{
// Compare tags - if equal or both null, we need to compare further.
@ -1611,13 +1562,11 @@ struct Node
assert(false, "Unknown type of node for comparison : " ~ type.toString());
}
/*
* Get a string representation of the node tree. Used for debugging.
*
* Params: level = Level of the node in the tree.
*
* Returns: String representing the node tree.
*/
// Get a string representation of the node tree. Used for debugging.
//
// Params: level = Level of the node in the tree.
//
// Returns: String representing the node tree.
@property string debugString(uint level = 0) @trusted
{
string indent;
@ -1660,11 +1609,9 @@ struct Node
return (cast(nothrowType)&value_.type)();
}
/*
* Determine if the value stored by the node is of specified type.
*
* This only works for default YAML types, not for user defined types.
*/
// Determine if the value stored by the node is of specified type.
//
// This only works for default YAML types, not for user defined types.
@property bool isType(T)() const @safe nothrow
{
return this.type is typeid(Unqual!T);
@ -1850,15 +1797,13 @@ struct Node
}
package:
/*
* Merge a pair into an array of pairs based on merge rules in the YAML spec.
*
* The new pair will only be added if there is not already a pair
* with the same key.
*
* Params: pairs = Appender managing the array of pairs to merge into.
* toMerge = Pair to merge.
*/
// Merge a pair into an array of pairs based on merge rules in the YAML spec.
//
// The new pair will only be added if there is not already a pair
// with the same key.
//
// Params: pairs = Appender managing the array of pairs to merge into.
// toMerge = Pair to merge.
void merge(ref Appender!(Node.Pair[], Node.Pair) pairs, ref Node.Pair toMerge) @trusted
{
foreach(ref pair; pairs.data)
@ -1868,15 +1813,13 @@ void merge(ref Appender!(Node.Pair[], Node.Pair) pairs, ref Node.Pair toMerge) @
pairs.put(toMerge);
}
/*
* Merge pairs into an array of pairs based on merge rules in the YAML spec.
*
* Any new pair will only be added if there is not already a pair
* with the same key.
*
* Params: pairs = Appender managing the array of pairs to merge into.
* toMerge = Pairs to merge.
*/
// Merge pairs into an array of pairs based on merge rules in the YAML spec.
//
// Any new pair will only be added if there is not already a pair
// with the same key.
//
// Params: pairs = Appender managing the array of pairs to merge into.
// toMerge = Pairs to merge.
void merge(ref Appender!(Node.Pair[], Node.Pair) pairs, Node.Pair[] toMerge) @trusted
{
bool eq(ref Node.Pair a, ref Node.Pair b){return a.key == b.key;}