bmx-site/docs/api/text/text_toml.md

---

id: text.toml title: Text.Toml

sidebar_label: Introduction

The text.toml is a module designed for parsing TOML (Tom's Obvious, Minimal Language) documents. TOML is a human-readable data serialization format used for configuration files and data interchange between languages with different data structures. It is similar to JSON, YAML, and INI files but aims to be more minimal and easier to read and write.

TOML documents consist of key-value pairs, which are organized into sections called tables. Each key-value pair is represented by a key followed by an equals sign (=) and a value. Tables can be nested, allowing for a hierarchical structure. TOML supports several data types, including strings, integers, floating-point numbers, booleans, dates, times, and arrays.

Key-Value Pairs

In TOML, key-value pairs are the basic building blocks of the document. Each key-value pair is represented by a key followed by an equals sign (=) and a value. Here's a simple example:

key = "value"

Tables

Tables are sections within a TOML document used to organize key-value pairs. They are defined by square brackets [ and ]. Here's an example of a table:

[table]
key = "value"

Nested Tables

TOML allows for nesting tables to create a hierarchical structure. Nested tables are defined using dot notation within the square brackets. Here's an example of nested tables:

[table]
key = "value"

[table.subtable]
nested_key = "nested_value"

Data Types

TOML supports several data types, including:

Strings

Enclosed in double quotes ". They can be single-line or multi-line (using triple quotes """).

string_key = "This is a string"
multiline_string_key = """
This is a
multiline string
"""

Integers

Whole numbers without a decimal point.

integer_key = 42

Floating-point numbers

Numbers with a decimal point.

float_key = 3.14

Booleans

Represented as true or false.

boolean_key = true

Dates

Represented in the format YYYY-MM-DD.

date_key = 2021-09-01

Times

Represented in the format hh:mm:ss (optionally with fractional seconds).

time_key = 12:34:56
time_with_fractional_key = 12:34:56.789

Date-times

Represented as a combination of date and time, separated by a T or a space.

datetime_key = 2021-09-01T12:34:56
datetime_with_space_key = 2021-09-01 12:34:56

Arrays

A collection of values enclosed in square brackets and separated by commas.

array_key = [1, 2, 3]

Here's a complete example of a TOML document using various data types and tables:

title = "TOML Example"

[author]
name = "John Doe"
age = 35
is_member = true

[book]
title = "The TOML Guide"
published_date = 2022-03-15
price = 19.99
keywords = ["TOML", "guide", "configuration"]

[book.publication_time]
hour = 15
minute = 30

Working with TOML documents

The module is composed of several types and interfaces, including:

TToml: The main class responsible for parsing TOML documents. It provides functions for loading and parsing TOML files or strings, returning a TTomlTable object.

TTomlTable: Represents a TOML table and implements the ITomlNode interface. It offers methods for adding and retrieving nodes with specified keys and enumerating the keys.

TTomlArray: Represents a TOML array and implements the ITomlNode interface.

TTomlString, TTomlInteger, TTomlFloatingPoint, TTomlBoolean, TTomlDate, TTomlTime, and TTomlDateTime: Each represents a specific TOML data type and implements the ITomlNode interface.

ITomlNode: An interface implemented by all TOML nodes. It includes methods for determining the type of the node and converting it to the desired data type.

Types

Type	Description
TTomlSourceRegion	Source region, provided with parsing errors.
TToml	TOML loader.
TTomlTable	A TOML table.
TTomlArray	A TOML array.
TTomlString	A TOML string.
TTomlInteger	A TOML integer number, represented as a Long.
TTomlFloatingPoint	A TOML floating point number, represented as a Double.
TTomlBoolean	A TOML boolean.
TTomlDate	A TOML date.
TTomlTime	A TOML time.
TTomlDateTime	A TOML date time.
TTomlParseError	A toml parse error.

Interfaces

Interface	Description
ITomlNode	A toml node.

Structs

Struct	Description
STomlDate	A toml date representation.
STomlTime	A toml time representation.
STomlDateTime	A toml date time representation, with optional offset.

Enums

Enum	Description
ETomlNodeType	Toml node type.