module watt.toml.tree

Uses the event parser to parse TOML into a tree in memory.

Code Map

//! Uses the event parser to parse TOML into a tree in memory.
module watt.toml.tree;


//! A TOML Value.
class Value
{
public:
	//! Each TOML Value is typed with one of these types.
	enum Type
	{
		//! A series of characters.
		String,
		//! A 64 bit signed integer.
		Integer,
		//! A 64 bit floating point number.
		Float,
		//! A boolean value is true or false.
		Boolean,
		//! An array of Values of the same type.
		Array,
		//! A table of Values, indexed by string.
		Table,
	}


public:
	//! The type of this Value.
	type: Type;
	//! Any comments that appeared before this value.
	comment: string;
	//! If this is a table, was it inline? (Affects toString functions).
	inline: bool;
	//! If this is an array, should it appear before the table it's nested in?
	hoist: bool;


public:
	//! Construct a Value with no type.
	this() { }
	//! Construct a Value with a string type.
	this(v: string) { }
	//! Construct a Value with an integer type.
	this(v: i64) { }
	//! Construct a Value with an integer type.
	this(v: i32) { }
	//! Construct a Value with a floating point type.
	this(v: f64) { }
	//! Construct a Value with a boolean type.
	this(v: bool) { }
	//! Construct an array of Values.
	this(v: Value[]) { }
	//! Get the keys for this table.
	fn tableKeys() string[] { }
	//! Get the Values set for this table.
	fn tableValues() Value[] { }
	//! If this is a table, remove the given key, if it is set.
	fn removeKey(key: string) { }
	//! Get a string representation of the value.
	fn toString() string { }
	//! Add the string representation of this Value to the given sink.
	fn toString(sink: scope (sink.Sink), parent: string) { }
	//! Retrieve the string value.
	fn str() string { }
	//! Set the string value.
	fn str(val: string) { }
	//! Retrieve the integer value.
	fn integer() i64 { }
	fn integer(val: i64) { }
	//! Retrieve the floating value.
	fn floating() f64 { }
	//! Set the floating value.
	fn floating(val: f64) { }
	//! Retrieve the boolean value.
	fn boolean() bool { }
	//! Set the boolean value.
	fn boolean(val: bool) { }
	//! Retrieve the array value.
	fn array() Value[] { }
	//! Set a table entry.
	fn tableEntry(k: string, v: Value) { }
	//! Set the array value.
	fn array(vals: Value[]) { }
	//! How many keys does this table have set?
	fn countKeys() size_t { }
	//! Does this table have a key?
	fn hasKey(key: string) bool { }
	//! Retrieve a key from this table.
	fn opIndex(key: string) Value { }
}

//! Given a TOML document, return a Value that represents that document.
fn parse(src: string) Value { }
class Value

A TOML Value.

watt.toml treats tables as a value, and thus represents the entire document as a table.

enum Type

Each TOML Value is typed with one of these types.

The TOML spec also specifies a date type, but the watt TOML parser does not support and has no plans to support this type.

enum String

A series of characters.

enum Integer

A 64 bit signed integer.

enum Float

A 64 bit floating point number.

enum Boolean

A boolean value is true or false.

enum Array

An array of Values of the same type.

enum Table

A table of Values, indexed by string.

type: Type

The type of this Value.

comment: string

Any comments that appeared before this value.

inline: bool

If this is a table, was it inline? (Affects toString functions).

hoist: bool

If this is an array, should it appear before the table it's nested in?

this()

Construct a Value with no type.

this(v: string)

Construct a Value with a string type.

this(v: i64)

Construct a Value with an integer type.

this(v: i32)

Construct a Value with an integer type.

this(v: f64)

Construct a Value with a floating point type.

this(v: bool)

Construct a Value with a boolean type.

this(v: Value[])

Construct an array of Values.

Throws

  • TomlException if any of the given Values do not have the same type.

fn tableKeys() string[]

Get the keys for this table.

Corresponds to the array returned by tableValues.

Throws

  • TomlException if this Value is not a table.

fn tableValues() Value[]

Get the Values set for this table.

Corresponds to the array return by tableKeys.

Throws

  • TomlException if this Value is not a table.

fn removeKey(key: string)

If this is a table, remove the given key, if it is set.

No operation is performed if the key is not set.

Throws

  • TomlException if this Value is not a table.

fn toString() string

Get a string representation of the value.

This is intended for serialisation of the data. e.g. Reading in a document, modifying it, and then using the output of this function to write back to disk.

The string returned will be a valid TOML document.
Note that this does not get an individual string value. Use str for that.

Limitations

This will try to handle implicitly defined tables gracefully, and maintain the structure as given, but complicated cascading nested tables are likely to generate bugs.

In particular, a setup like this:

[a.b.c]
x = 1
[a.b]
y = 2
[a]
z = 3

Will cause problems. To work around this issue, declare tables in the regular order (parent -> child) instead:

[a]
z = 3
[a.b]
y = 2
[a.b.c]
x = 1
fn toString(sink: scope (sink.Sink), parent: string)

Add the string representation of this Value to the given sink.

The parent parameter is for setting what table a sub table belongs to, and in most user code should be left blank.

Use str to get the string value of a key.

fn str() string

Retrieve the string value.

To get a printable string of any value type, or entire table, use toString. This is for retrieving the string value of a String typed toml value.

Throws

  • TomlException if this Value isn't a string.

fn str(val: string)

Set the string value.

Throws

  • TomlException if this Value isn't a string.

fn integer() i64

Retrieve the integer value.

Throws

  • TomlException if this Value isn't an integer.

fn floating() f64

Retrieve the floating value.

Throws

  • TomlException if this Value isn't a float.

fn floating(val: f64)

Set the floating value.

Throws

  • TomlException if this Value isn't a float.

fn boolean() bool

Retrieve the boolean value.

Throws

  • TomlException if this Value isn't a boolean.

fn boolean(val: bool)

Set the boolean value.

Throws

  • TomlException if this Value isn't a boolean.

fn array() Value[]

Retrieve the array value.

Throws

  • TomlException if this Value isn't an array.

fn tableEntry(k: string, v: Value)

Set a table entry.

Throws

  • TomlException if this Value isn't an array.

fn array(vals: Value[])

Set the array value.

Throws

  • TomlException if this Value isn't an array, or if the array is mistyped.

fn countKeys() size_t

How many keys does this table have set?

Return

The number of keys that have been set.

Throws

  • TomlExeption if this Value isn't a table.

fn hasKey(key: string) bool

Does this table have a key?

Return

true if the key is set.

Throws

  • TomlException if this Value isn't a table.

fn opIndex(key: string) Value

Retrieve a key from this table.

Throws

  • TomlException if the key isn't set, or this isn't a table.

fn parse(src: string) Value

Given a TOML document, return a Value that represents that document.

The returned Value will be a table.