dyaml.node

Node of a YAML document. Used to read YAML data once it's loaded, and to prepare data to emit.

class NodeException: dyaml.exception.YAMLException;

Exception thrown at node related errors.

struct YAMLNull;

Null YAML type. Used in nodes with null values.

struct Node;

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 Pair;

Key-value pair of YAML nodes, used in mappings.

Node key;

Key node.

Node value;

Value node.

auto this(K, V)(K key, V value);

Construct a Pair from two values. Will be converted to Nodes if needed.

bool equals(ref Pair rhs);

Equality test with another Pair.

auto this(T)(T value, in string tag = null);

Construct a Node from a value.

Any type except of Node can be stored in a Node, but default YAML types (integers, floats, strings, timestamps, etc.) will be stored more efficiently.

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

auto this(T)(T[] array, in string tag = null);

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

auto this(K, V)(V[K] array, in string tag = null);

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

auto this(K, V)(K[] keys, V[] values, in string tag = null);

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.

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

const @property bool isValid();

Is this node valid (initialized)?

const @property bool isScalar();

Is this node a scalar value?

const @property bool isSequence();

Is this node a sequence?

const @property bool isMapping();

Is this node a mapping?

const @property bool isUserType();

Is this node a user defined type?

bool opEquals(T)(ref T rhs);

Equality test.

If T is Node, recursively compare all subnodes. This might be quite expensive if testing entire documents.
If T is not Node, convert the node to T and test equality with that.

Examples:

 auto node = Node(42);

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

Parameters:

rhs	Variable to test equality with.

Returns:

true if equal, false otherwise.

T get(T)();

Get the value of the node as specified type.

If the specifed type does not match type in the node, conversion is attempted.
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[].

Mapping default values:

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.get!int == 42);
 assert(node.get!string == "42");
 assert(node.get!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.

void getToVar(T)(out T target);

Write the value of the node to target.

If the target type does not match node type, conversion is attempted.

Parameters:

target

Variable to write to.

Throws:

NodeException if unable to convert to specified type.

@property size_t length();

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.

Node opIndex(T)(T index);

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, even after conversion. I.e; node["12"] will return value of the first key that equals "12", even if it's an integer.

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.

void opIndexAssign(K, V)(V value, K index);

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.

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.

int opApply(T)(int delegate(ref T) dg);

Iterate 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(K, V)(int delegate(ref K, ref V) dg);

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

void add(T)(T value);

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.

void add(K, V)(K key, V value);

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.

void remove(T)(T value);

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 (including conversion, so e.g. "42" matches 42) is removed. If the node is a mapping, the first key-value pair where value matches specified value is removed.

Parameters:

value

Value to remove.

Throws:

NodeException if the node is not a collection.

void removeAt(T)(T index);

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 (including conversion, so e.g. "42" matches 42).
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.