public this(T)(
    T value, 
    const string tag = null) @trusted 
if(!scalarCtorNothrow!T && (!isArray!T && !isAssociativeArray!T))

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.

Parameters

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".

public this(T)(
    T value, 
    const string tag = null) @safe pure nothrow 
if(scalarCtorNothrow!T)

Ditto.

public this(T)(
    T[] array, 
    const string tag = null) @safe 
if(!isSomeString!(T[]))

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.

Parameters

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");

public this(K, V)(
    V[K] array, 
    const string tag = null) @safe

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.

Parameters

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");

public this(K, V)(
    K[] keys, 
    V[] values, 
    const string tag = null) @safe 
if(!(isSomeString!(K[]) || isSomeString!(V[])))

Construct a node from arrays of _keys and _values.

Contracts

in
{
    assert (keys.length == values.length, "Lengths of keys and values arrays to construct ""a YAML node from don't match");
}

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.

Parameters

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");

public @property bool isValid() const @safe pure nothrow

Is this node valid (initialized)?

public @property bool isScalar() const @safe nothrow

Is this node a scalar value?

public @property bool isSequence() const @safe nothrow

Is this node a sequence?

public @property bool isMapping() const @safe nothrow

Is this node a mapping?

public @property bool isUserType() const @safe nothrow

Is this node a user defined type?

public @property bool isNull() const @safe nothrow

Is this node null?

public @property string tag() const @safe nothrow

Return tag of the node.

public bool opEquals(T)(const auto ref T rhs) const @safe

Equality test.

If T is Node, recursively compares all subnodes. This might be quite expensive if testing entire documents.

If T is not Node, gets a value of type T from the node and tests equality with that.

To test equality with a null YAML value, use YAMLNull.

Parameters

rhs	Variable to test equality with.

Returns

true if equal, false otherwise.

Example

auto node = Node(42);

assert(node == 42);
assert(node != "42");
assert(node != "43");

auto node2 = Node(YAMLNull());
assert(node2 == YAMLNull());

alias as = get

Shortcut for get().

public @property T get(T, Flag!"stringConversion" stringConversion = Yes.stringConversion)() @trusted 
if(!is(T == const))

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.

Mapping default values:

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.

public @property T get(T, Flag!"stringConversion" stringConversion = Yes.stringConversion)() const @trusted 
if(is(T == const))

Ditto.

public @property size_t length() const @safe

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.

public ref Node opIndex(T)(T index) @trusted

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.

Parameters

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.

Example

writeln("D:YAML Node opIndex unittest");
alias Node.Value Value;
alias Node.Pair Pair;

Node narray = Node([11, 12, 13, 14]);
Node nmap   = Node(["11", "12", "13", "14"], [11, 12, 13, 14]);

assert(narray[0].as!int == 11);
assert(null !is collectException(narray[42]));
assert(nmap["11"].as!int == 11);
assert(nmap["14"].as!int == 14);

public bool contains(T)(T rhs) const @safe

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.

Parameters

rhs	Item to look for. Use YAMLNull to check for a null value.

Returns

true if rhs was found, false otherwise.

Throws

NodeException if the node is not a collection.

public bool containsKey(T)(T rhs) const @safe

Determine if a mapping contains specified key.

Parameters

rhs	Key to look for. Use YAMLNull to check for a null key.

Returns

true if rhs was found, false otherwise.

Throws

NodeException if the node is not a mapping.

public void opAssign(Node rhs) @safe nothrow

Assignment (shallow copy) by value.

public void opAssign(ref Node rhs) @trusted nothrow

Assignment (shallow copy) by reference.

public void opIndexAssign(K, V)(
    V value, 
    K index) @safe

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.

Parameters

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.

public int opApply(T)(int delegate(ref T) dg) @trusted

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.

public int opApply(K, V)(int delegate(
    ref K, 
    ref V) dg) @trusted

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.

public void add(T)(T value) @safe

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.

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 invalid YAML code will be emitted.

Parameters

value

Value to _add to the sequence.

public void add(K, V)(
    K key, 
    V value) @safe

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.

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 invalid YAML with "!!map" and "!!omap" tags.

Parameters

key	Key to _add.
value	Value to _add.

public Node* opBinaryRight(string op, K)(K key) @system 
if(op == "in")

Determine whether a key is in a mapping, and access its value.

This method can only be called on mapping nodes.

Parameters

key	Key to search for.

Returns

A pointer to the value (as a Node) corresponding to key, or null if not found.

 Any modification to the node can invalidate the returned
       pointer.

public void remove(T)(T rhs) @trusted

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.

Parameters

rhs	Value to _remove.

Throws

NodeException if the node is not a collection.

public void removeAt(T)(T index) @trusted

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.

Parameters

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.

public int opCmp(ref const Node node) const @safe

Compare with another _node.