# orca.toml

> A module of morca's API.

The TOML that `orca.toml` is written in (`orca.config`): a parser and a writer for the subset a configuration file needs.

var doc = parse_toml(text)          # raises "<line>: <why>" on bad input
    doc.get(["pipelines", "gharchive", "workers"])   # Optional[TomlValue]
    doc.tables(["pipelines"])           # the tables directly under it

Supported, as TOML 1.0 has them: comments, `[table]` headers with bare,
quoted and dotted keys, `key = value` with dotted keys, basic strings (with
every escape) and literal strings, integers (decimal, with `_` between
digits), floats, booleans, arrays of those (over several lines, with
comments and a trailing comma), inline tables, nested, and arrays of inline
tables, inline (`machines = [{ type = "cax31", wait = 600 }, ...]`) or as
`[[x]]` headers, nested too (`[[version.step]]` adds to the last
`[[version]]`). A key or table
defined twice, a dotted key extending a table a header defined, and a header
reopening an inline table are refused, as TOML refuses them. Not supported,
each refused with a message saying so: multi-line strings, dates and times, hexadecimal, octal and binary integers,
`inf` and `nan`, arrays of arrays, arrays mixing tables with other values,
and keys holding control characters.

The document is flat: an entry per table and per value, in the order the
file has them, each with its whole key path, so a reader looks values up by
path and a new key needs no new type. An array of tables is an `ARRAY`
entry whose items are its elements' indices, of kind `TABLE`, and each
element a table at the array's path and its index: `machines.0.type`. mojoshelf's `mojo-toml` is built for
Mojo before 1.0, which is why orca has its own.

## Structs

### `TomlValue`

```mojo
struct TomlValue
```

One value: its kind (`STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `ARRAY` or `TABLE`) and its text: a string's contents, a number as written without its `_`s, `true` or `false`; an array's elements are `items`, each scalar, with their kinds in `item_kinds`.

Implements: `Copyable`, `Movable`, `Writable`

Fields:

- `kind: String`
- `text: String`
- `items: List[String]`
- `item_kinds: List[String]`
- `line: Int`: The line it was defined on, from 1.

#### `as_int`

```mojo
def as_int(self) -> Int
```

#### `write_to`

```mojo
def write_to(self, mut writer: T)
```

The value as TOML.

### `TomlEntry`

```mojo
struct TomlEntry
```

Implements: `Copyable`, `Movable`

Fields:

- `path: List[String]`
- `value: TomlValue`
- `how: Int`: For a table, how it was made (`_HEADER` and the rest).

### `TomlDoc`

```mojo
struct TomlDoc
```

A parsed document: its tables and values, in the file's order.

Implements: `Movable`

Fields:

- `entries: List[TomlEntry]`

#### `__init__`

```mojo
def __init__(out self)
```

#### `find`

```mojo
def find(self, path: List[String]) -> Int
```

The entry at `path`'s index, or -1.

#### `get`

```mojo
def get(self, path: List[String]) -> Optional[TomlValue]
```

#### `has_table`

```mojo
def has_table(self, path: List[String]) -> Bool
```

#### `keys`

```mojo
def keys(self, table: List[String]) -> List[String]
```

The keys directly under `table` (`[]` for the root), tables and values, in the order they were first defined.

#### `tables`

```mojo
def tables(self, table: List[String]) -> List[String]
```

The tables directly under `table`, in order.

#### `dump`

```mojo
def dump(self) -> String
```

The document as TOML, every value under its whole dotted key and every table with nothing in it as `{}`: what `parse_toml` reads back to the same entries (`fuzz/fuzz_toml.mojo` checks it).

#### `is_table_array`

```mojo
def is_table_array(self, v: TomlValue) -> Bool
```

Whether `v` is an array of tables (`machines.0`, ...).

## Functions

### `toml_key`

```mojo
def toml_key(k: String) -> String
```

`k` as a TOML key: bare if it can be, else a basic string.

### `toml_string`

```mojo
def toml_string(s: String) -> String
```

`s` as a TOML basic string, quotes included.

### `parse_toml`

```mojo
def parse_toml(text: String) -> TomlDoc
```

`text` as a document; raises `<line>: <why>` if it isn't one this subset reads.

## Aliases

### `STRING`

```mojo
comptime STRING = "string"
```

### `INTEGER`

```mojo
comptime INTEGER = "integer"
```

### `FLOAT`

```mojo
comptime FLOAT = "float"
```

### `BOOLEAN`

```mojo
comptime BOOLEAN = "boolean"
```

### `ARRAY`

```mojo
comptime ARRAY = "array"
```

### `TABLE`

```mojo
comptime TABLE = "table"
```