Yaml Value¶

1

import "std/text/yaml-value";

YamlValue struct¶

Represents a single YAML node.

Composite nodes (sequences and mappings) own their children as heap pointers, so a YamlValue is always reached via YamlValue* once it has been parsed. Destroying a node recursively destroys everything below it, so a whole tree is released with a single deleteYamlValue call on its root. Accessors like getField hand out borrowed pointers that stay owned by their parent, while addSequenceItem and addMappingField take ownership of what they are given.

Note that the root cannot simply be held in a heap YamlValue* and left to the compiler: the heap qualifier only emits a raw deallocation when the variable goes out of scope and never runs the destructor of the pointee, so the children below the root would be lost.

Following the YAML 1.2 core schema, plain scalars resolve to null, booleans, integers or floats and everything else stays a string, while quoted scalars are always strings. Mapping entries preserve document order, and unlike TOML tables a mapping may hold an explicit null value.

Parsing lives in "std/text/yaml/yaml-parser" and serialization in "std/text/yaml/yaml-serializer", so programs only pull in what they use.

Constructors¶

ctor¶

1

public p YamlValue.ctor()

Construct an empty YAML mapping, which is what a YAML document is usually rooted at

ctor¶

1

public p YamlValue.ctor(YamlValueKind kind)

Construct an empty YAML node of the given kind. Useful for building sequences and mappings from scratch.

Parameters

ctor¶

1

public p YamlValue.ctor(const String& value)

Construct a YAML string node

Parameters

ctor¶

1

public p YamlValue.ctor(bool value)

Construct a YAML boolean node

Parameters

ctor¶

1

public p YamlValue.ctor(long value)

Construct a YAML integer node

Parameters

ctor¶

1

public p YamlValue.ctor(double value)

Construct a YAML float node

Parameters

dtor¶

1

public p YamlValue.dtor()

Destruct the YAML node, releasing every sequence item and mapping entry it owns. Since the children are destroyed the same way, this tears down the whole subtree below the node.

Methods¶

getKind¶

1

public f<YamlValueKind> YamlValue.getKind()

Retrieve the kind of the YAML node

Returns: YamlValueKind — Kind of the node

isNull¶

1

public f<bool> YamlValue.isNull()

Check whether the YAML node is null

Returns: bool — true if the node is null, false otherwise

isString¶

1

public f<bool> YamlValue.isString()

Check whether the YAML node is a string

Returns: bool — true if the node is a string, false otherwise

isInteger¶

1

public f<bool> YamlValue.isInteger()

Check whether the YAML node is an integer

Returns: bool — true if the node is an integer, false otherwise

isFloat¶

1

public f<bool> YamlValue.isFloat()

Check whether the YAML node is a float

Returns: bool — true if the node is a float, false otherwise

isBool¶

1

public f<bool> YamlValue.isBool()

Check whether the YAML node is a boolean

Returns: bool — true if the node is a boolean, false otherwise

isSequence¶

1

public f<bool> YamlValue.isSequence()

Check whether the YAML node is a sequence

Returns: bool — true if the node is a sequence, false otherwise

isMapping¶

1

public f<bool> YamlValue.isMapping()

Check whether the YAML node is a mapping

Returns: bool — true if the node is a mapping, false otherwise

getString¶

1

public f<const String&> YamlValue.getString()

Retrieve the string payload. Panics if the node is not a string.

Returns: const String& — String value

getInteger¶

1

public f<long> YamlValue.getInteger()

Retrieve the integer payload. Panics if the node is not an integer.

Returns: long — Integer value

getFloat¶

1

public f<double> YamlValue.getFloat()

Retrieve the float payload. Panics if the node is not a float.

Returns: double — Float value

getBool¶

1

public f<bool> YamlValue.getBool()

Retrieve the boolean payload. Panics if the node is not a boolean.

Returns: bool — Boolean value

getSequenceSize¶

1

public f<unsigned long> YamlValue.getSequenceSize()

Retrieve the number of items in the sequence. Panics if the node is not a sequence.

Returns: unsigned long — Number of sequence items

getSequenceItem¶

1

public f<YamlValue*> YamlValue.getSequenceItem(unsigned long idx)

Retrieve the sequence item at the given index. Panics if the node is not a sequence.

Parameters

Returns: YamlValue* — Pointer to the sequence item

getSequenceItem¶

1

public f<YamlValue*> YamlValue.getSequenceItem(unsigned int idx)

Retrieve the sequence item at the given index. Panics if the node is not a sequence.

Parameters

Returns: YamlValue* — Pointer to the sequence item

addSequenceItem¶

1

public p YamlValue.addSequenceItem(YamlValue* item)

Append an item to the sequence. Panics if the node is not a sequence. The sequence takes ownership of the heap-allocated item.

Parameters

getMappingSize¶

1

public f<unsigned long> YamlValue.getMappingSize()

Retrieve the number of entries in the mapping. Panics if the node is not a mapping.

Returns: unsigned long — Number of mapping entries

getMappingKey¶

1

public f<const String&> YamlValue.getMappingKey(unsigned long idx)

Retrieve the key of the mapping entry at the given index, in document order. Panics if the node is not a mapping.

Parameters

Returns: const String& — Entry key

getMappingValue¶

1

public f<YamlValue*> YamlValue.getMappingValue(unsigned long idx)

Retrieve the value of the mapping entry at the given index, in document order. Panics if the node is not a mapping.

Parameters

Returns: YamlValue* — Pointer to the entry value

hasField¶

1

public f<bool> YamlValue.hasField(const String& key)

Check whether the mapping contains an entry with the given key

Parameters

Returns: bool — true if the entry exists, false otherwise

hasField¶

1

public f<bool> YamlValue.hasField(string key)

Check whether the mapping contains an entry with the given key

Parameters

Returns: bool — true if the entry exists, false otherwise

getFieldOrNil¶

1

public f<YamlValue*> YamlValue.getFieldOrNil(const String& key)

Retrieve the value of the mapping entry with the given key, or nil if the node is not a mapping or the entry does not exist.

Parameters

Returns: YamlValue* — Pointer to the entry value, or nil

getFieldOrNil¶

1

public f<YamlValue*> YamlValue.getFieldOrNil(string key)

Retrieve the value of the mapping entry with the given key, or nil if the node is not a mapping or the entry does not exist.

Parameters

Returns: YamlValue* — Pointer to the entry value, or nil

getField¶

1

public f<YamlValue*> YamlValue.getField(const String& key)

Retrieve the value of the mapping entry with the given key. Panics if the node is not a mapping or the entry does not exist.

Parameters

Returns: YamlValue* — Pointer to the entry value

getField¶

1

public f<YamlValue*> YamlValue.getField(string key)

Retrieve the value of the mapping entry with the given key. Panics if the node is not a mapping or the entry does not exist.

Parameters

Returns: YamlValue* — Pointer to the entry value

addMappingField¶

1

public p YamlValue.addMappingField(const String& key, YamlValue* value)

Append an entry to the mapping. Panics if the node is not a mapping. The mapping takes ownership of the heap-allocated entry value.

Parameters

Functions¶

deleteYamlValue¶

1

public p deleteYamlValue(YamlValue*& value)

Destroys a heap-allocated YAML node together with everything it owns and sets the given handle to nil, so releasing a whole tree only takes one call on its root.

Note that this is what sDelete would normally be used for. It cannot be used here, because a node tree is destroyed recursively and the compiler does not emit an explicit dtor that is only reached through sDestruct.

Parameters

copyYamlValue¶

1

public f<YamlValue*> copyYamlValue(YamlValue* value)

Creates a deep copy of the given node, which the caller owns and releases again with deleteYamlValue. This is what the parser uses to resolve an alias against its anchor, so that the resulting tree stays free of shared nodes.

Parameters

Returns: YamlValue* — Pointer to the freshly allocated copy

yamlPlainScalarKind¶

1

public f<YamlValueKind> yamlPlainScalarKind(const String& text)

Determine which kind a plain scalar resolves to under the YAML 1.2 core schema. Both the parser and the serializer go through this, so that a string which would be read back as another kind can be quoted when it is written out again.

Parameters

Returns: YamlValueKind — Kind the scalar resolves to, never YAML_SEQUENCE or YAML_MAPPING

resolveYamlScalar¶

1

public f<YamlValue*> resolveYamlScalar(const String& text)

Build the node a plain scalar denotes under the YAML 1.2 core schema. The caller owns the returned node and releases it again with deleteYamlValue.

Parameters

Returns: YamlValue* — Pointer to the freshly allocated node

yamlInfinity¶

1

public f<double> yamlInfinity()

Retrieve positive infinity, which YAML spells .inf. Spice has no literal for it, so it is provided here for building and inspecting float values.

Returns: double — Positive infinity

yamlNaN¶

1

public f<double> yamlNaN()

Retrieve a quiet NaN, which YAML spells .nan. Spice has no literal for it, so it is provided here for building float values.

Returns: double — Not a number

yamlIsNaN¶

1

public f<bool> yamlIsNaN(double value)

Checks whether the given float is a NaN. The usual value != value trick does not work in Spice, since its float comparisons are ordered ones.

Parameters

Returns: bool — true if the value is a NaN, false otherwise

YamlValueKind enum¶

Tag for the variant stored inside a YamlValue.