Tom

https://github.com/lpil/tom
Admin
Tom is a TOML parser library for Gleam, enabling parsing of TOML strings and convenient retrieval of...
Tokens:37,570
Snippets:226
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### as_string success example

Source: https://github.com/lpil/tom

Example usage of tom.as_string with a String value, asserting the result is Ok("hello").

```gleam
import tom

pub fn main() {
  let assert Ok("hello") = tom.as_string(tom.String("hello"))
}
```

--------------------------------

### as_int success example

Source: https://github.com/lpil/tom

Example of as_int returning Ok(1) when given tom.Int(1). Uses an assert pattern to unwrap the result.

```gleam
import tom

pub fn main() {
  let assert Ok(1) = tom.as_int(tom.Int(1))
}
```

--------------------------------

### as_bool success example

Source: https://github.com/lpil/tom

Example usage of tom.as_bool with a Bool value, asserting the result is Ok(True).

```gleam
import tom

pub fn main() {
  let assert Ok(True) = tom.as_bool(tom.Bool(True))
}
```

--------------------------------

### Basic call to tom.get

Source: https://github.com/lpil/tom

Example of calling tom.get with a parsed document and a key path. Uses assert to unwrap the result.

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("a.b.c = 1")
  let assert Ok(tom.Int(1)) = tom.get(parsed, ["a", "b", "c"])
}
```

--------------------------------

### as_float success example

Source: https://github.com/lpil/tom

Example usage of tom.as_float with a Float value, asserting the result is Ok(1.5).

```gleam
import tom

pub fn main() {
  let assert Ok(1.5) = tom.as_float(tom.Float(1.5))
}
```

--------------------------------

### Basic TOML parse example

Source: https://github.com/lpil/tom

Parses a TOML string and accesses the nested 'person' table. Uses an assert to unwrap the Ok result.

```gleam
import tom
import gleam/dict

pub fn main() {
  let config = "
    [person]
    name = \"Lucy\"
    is_cool = true
    scores = [10, 20, 30]
  "

  let assert Ok(parsed) = tom.parse(config)

  // parsed is a Dict(String, Toml): the [person] table is tom.Table(...)
  let assert Some(tom.Table(person)) = dict.get(parsed, "person")
}
```

--------------------------------

### Handling WrongType error from tom.get

Source: https://github.com/lpil/tom

Example showing how to handle a key that exists but at the wrong level, using case to match on Error variants.

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("a = 1") // "a" is an Int, not a table

  case tom.get(parsed, ["a", "b"]) {
    Ok(value) -> { /* use value */ }
    Error(tom.NotFound(path)) -> { /* no value at this path */ }
    Error(tom.WrongType(path, expected, got)) -> {
      // Here: WrongType(["a"], "Table", "Int")
    }
  }
}
```

--------------------------------

### as_table usage example

Source: https://github.com/lpil/tom

Shows how to call `as_table` with a `Table` or `InlineTable` value. Uses `let assert` to unwrap the result, and includes a commented alternative for `InlineTable`.

```gleam
import gleam/dict
import tom

pub fn main() {
  let assert Ok(table) = tom.as_table(tom.Table(dict.new()))
  // or: tom.as_table(tom.InlineTable(dict.from_list([#("a", tom.Int(1))])))
}
```

--------------------------------

### as_array usage example

Source: https://github.com/lpil/tom

Example showing successful extraction of an Array value into a list of Toml values using as_array. Constructs a tom.Array with two Int items and asserts the returned list matches.

```gleam
import tom

pub fn main() {
  let assert Ok([tom.Int(1), tom.Int(2)]) =
    tom.as_array(tom.Array([tom.Int(1), tom.Int(2)]))
}
```

--------------------------------

### as_date successful unwrap example

Source: https://github.com/lpil/tom

Shows how to call tom.as_date on a tom.Date value and assert the resulting calendar.Date. Requires importing gleam/time/calendar and tom.

```gleam
import gleam/time/calendar
import tom

pub fn main() {
  let assert Ok(calendar.Date(1979, calendar.May, 27)) =
    tom.as_date(tom.Date(calendar.Date(1979, calendar.May, 27)))
}
```

--------------------------------

### as_calendar_time usage example

Source: https://github.com/lpil/tom

Example showing successful extraction of a DateTime value into its three parts using as_calendar_time. Constructs a tom.DateTime with a Local offset and asserts the returned tuple matches the expected values.

```gleam
import gleam/time/calendar
import tom

pub fn main() {
  let value =
    tom.DateTime(
      date: calendar.Date(1979, calendar.May, 27),
      time: calendar.TimeOfDay(7, 32, 0, 0),
      offset: tom.Local,
    )
  let assert Ok(#(
    calendar.Date(1979, calendar.May, 27),
    calendar.TimeOfDay(7, 32, 0, 0),
    tom.Local,
  )) = tom.as_calendar_time(value)
}
```

--------------------------------

### get_string usage example

Source: https://github.com/lpil/tom

Example of using tom.get_string to parse a TOML string with a string value and assert the result. Requires the tom package and a parsed document.

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("name = \"Joe\"")
  let assert Ok("Joe") = tom.get_string(parsed, ["name"])
}
```

--------------------------------

### as_number usage example

Source: https://github.com/lpil/tom

Shows how to call `as_number` with `Int`, `Float`, and `Infinity` values, expecting the corresponding `Number` variants. Uses `let assert` to unwrap results.

```gleam
import tom

pub fn main() {
  let assert Ok(tom.NumberInt(1337)) = tom.as_number(tom.Int(1337))
  let assert Ok(tom.NumberFloat(1.5)) = tom.as_number(tom.Float(1.5))
  let assert Ok(tom.NumberInfinity(tom.Positive)) =
    tom.as_number(tom.Infinity(tom.Positive))
}
```

--------------------------------

### as_time_of_day successful unwrap example

Source: https://github.com/lpil/tom

Shows how to call tom.as_time_of_day on a tom.Time value and assert the resulting calendar.TimeOfDay. Requires importing gleam/time/calendar and tom.

```gleam
import gleam/time/calendar
import tom

pub fn main() {
  let assert Ok(calendar.TimeOfDay(7, 32, 0, 0)) =
    tom.as_time_of_day(tom.Time(calendar.TimeOfDay(7, 32, 0, 0)))
}
```

--------------------------------

### as_string failure example

Source: https://github.com/lpil/tom

Example showing tom.as_string returning Error(tom.WrongType([], "String", "Int")) when given an Int value.

```gleam
let assert Error(tom.WrongType([], "String", "Int")) =
  tom.as_string(tom.Int(1))
```

--------------------------------

### Add tom dependency with gleam add

Source: https://github.com/lpil/tom/blob/main/README.md

Install the tom package using the Gleam package manager.

```sh
gleam add tom
```

--------------------------------

### get_bool usage example

Source: https://github.com/lpil/tom

Example of using tom.get_bool to parse a TOML string with a boolean literal and assert the result. Requires the tom package and a parsed document.

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("is_cool = true")
  let assert Ok(True) = tom.get_bool(parsed, ["is_cool"])
}
```

--------------------------------

### as_int failure example

Source: https://github.com/lpil/tom

Example of as_int returning Error(WrongType([], "Int", "Float")) when given tom.Float(1.4). The key path is empty list [].

```gleam
let assert Error(tom.WrongType([], "Int", "Float")) =
  tom.as_int(tom.Float(1.4))
```

--------------------------------

### as_float failure example

Source: https://github.com/lpil/tom

Example showing tom.as_float returning Error(tom.WrongType([], "Float", "Int")) when given an Int value.

```gleam
let assert Error(tom.WrongType([], "Float", "Int")) =
  tom.as_float(tom.Int(1))
```

--------------------------------

### parse_to_dynamic basic use with a decoder

Source: https://github.com/lpil/tom

Example showing how to parse a TOML string and decode it using gleam/dynamic/decode. The decoder extracts the 'name' and 'points' fields and returns a tuple.

```gleam
import gleam/dynamic/decode
import tom

pub fn main() {
  let config = "name = \"Lucy\"\npoints = 5"
  let assert Ok(dynamic) = tom.parse_to_dynamic(config)

  let decoder = {
    use name <- decode.field("name", decode.string)
    use points <- decode.field("points", decode.int)
    decode.success(#(name, points))
  }

  let assert Ok(#("Lucy", 5)) = decode.run(dynamic, decoder)
}
```

--------------------------------

### as_bool failure example

Source: https://github.com/lpil/tom

Example showing tom.as_bool returning Error(tom.WrongType([], "Bool", "Int")) when given an Int value.

```gleam
let assert Error(tom.WrongType([], "Bool", "Int")) =
  tom.as_bool(tom.Int(1))
```

--------------------------------

### as_timestamp successful unwrap example

Source: https://github.com/lpil/tom

Shows how to call tom.as_timestamp on a tom.DateTime with an explicit offset. Requires importing gleam/time/calendar, gleam/time/duration, gleam/time/timestamp, and tom.

```gleam
import gleam/time/calendar
import gleam/time/duration
import gleam/time/timestamp
import tom

pub fn main() {
  let value =
    tom.DateTime(
      date: calendar.Date(1979, calendar.May, 27),
      time: calendar.TimeOfDay(7, 32, 0, 0),
      offset: tom.Offset(duration.hours(2)),
    )
  let assert Ok(ts) = tom.as_timestamp(value)
}
```

--------------------------------

### get_float usage example

Source: https://github.com/lpil/tom

Example of using tom.get_float to parse a TOML string with a float value and assert the result. Requires the tom package and a parsed document.

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("ratio = 1.5")
  let assert Ok(1.5) = tom.get_float(parsed, ["ratio"])
}
```

--------------------------------

### parse_to_dynamic propagating the parse error

Source: https://github.com/lpil/tom

Example showing that a parse failure returns Error(ParseError) and can be matched with the Unexpected variant. It composes with result.try for subsequent decoding steps.

```gleam
import tom

pub fn main() {
  // A parse failure is returned as Error(ParseError); combined with
  // result.try it composes with subsequent decoding steps.
  let assert Error(tom.Unexpected(_, _)) = tom.parse_to_dynamic("nope")
}
```

--------------------------------

### get(toml, key)

Source: https://github.com/lpil/tom

Retrieves a value of any type from a parsed TOML document by dotted key path. Returns the raw Toml value; use the get_* family for typed retrieval.

```APIDOC
## `get`

### Description
Retrieves a value of any type from a parsed document by dotted key path.

### Signature
```gleam
pub fn get(
  toml: Dict(String, Toml),
  key: List(String),
) -> Result(Toml, GetError)
```

### Parameters
- **toml** (`Dict(String, Toml)`) - Required - The parsed document (result of `parse`).
- **key** (`List(String)`) - Required - Key path segments, e.g. `["person", "name"]` for `person.name`.

### Return
`Result(Toml, GetError)`. Returns the raw `Toml` value; use the `get_*` family (see [get-functions.md](get-functions.md)) for typed retrieval.

### Behavior
- `key == []` → `Error(NotFound([]))`.
- Single segment: dictionary lookup; missing key → `Error(NotFound([key]))`.
- Multi segment: intermediate segments must resolve to `Table` or `InlineTable`; an intermediate value of any other type → `Error(WrongType([k], "Table", ...))`; a missing intermediate → `Error(NotFound([k]))`. Traversed keys are prepended to error paths via `push_key`, so returned paths are the full prefix path from the document root.

### Request Example
```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("a.b.c = 1")
  let assert Ok(tom.Int(1)) = tom.get(parsed, ["a", "b", "c"])
}
```

### Request Example
```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("a = 1") // "a" is an Int, not a table

  case tom.get(parsed, ["a", "b"]) {
    Ok(value) -> { /* use value */ }
    Error(tom.NotFound(path)) -> { /* no value at this path */ }
    Error(tom.WrongType(path, expected, got)) -> {
      // Here: WrongType(["a"], "Table", "Int")
    }
  }
}
```
```

--------------------------------

### as_array ArrayOfTables error example

Source: https://github.com/lpil/tom

Example showing the error returned when as_array is called on an ArrayOfTables value. The function returns a WrongType error with expected name "Array" and actual name "Array" because classify names both variants "Array". Arrays of tables must first be turned into Table values.

```gleam
// Arrays of tables must first be turned into Table values
let assert Error(tom.WrongType([], "Array", "Array")) =
  tom.as_array(tom.ArrayOfTables([]))
```

--------------------------------

### as_calendar_time WrongType error example

Source: https://github.com/lpil/tom

Example showing the error returned when as_calendar_time is called on a Date value. The function returns a WrongType error with expected name "DateTime" and actual name "Date".

```gleam
let assert Error(tom.WrongType([], "DateTime", "Date")) =
  tom.as_calendar_time(tom.Date(calendar.Date(2015, calendar.October, 21)))
```

--------------------------------

### get_int usage example

Source: https://github.com/lpil/tom

Parses a TOML string and retrieves an integer value using a dotted key path. Uses assert to unwrap the Ok result.

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("a.b.c = 1")
  let assert Ok(1) = tom.get_int(parsed, ["a", "b", "c"])
}
```

--------------------------------

### Parse TOML and retrieve values with tom.parse, tom.get_string, tom.get_bool

Source: https://github.com/lpil/tom/blob/main/README.md

Parses a TOML string and retrieves values using the get_* functions. The example asserts the parse succeeds and shows expected results for get_string and get_bool.

```gleam
import tom

const config = "
  [person]
  name = \"Lucy\"
  is_cool = true
"

pub fn main() {
  // Parse a string of TOML
  let assert Ok(parsed) = tom.parse(config)

  // Now you can work with the data directly, or you can use the `get_*`
  // functions to retrieve values.

  tom.get_string(parsed, ["person", "name"])
  // -> Ok("Lucy")

  let is_cool = tom.get_bool(parsed, ["person", "is_cool"])
  // -> Ok(True)
}
```

--------------------------------

### as_table error example

Source: https://github.com/lpil/tom

Demonstrates that `as_table` returns a `WrongType` error when given a non-table value, such as `tom.Int(1)`. The expected name is `"Table"`.

```gleam
let assert Error(tom.WrongType([], "Table", "Int")) =
  tom.as_table(tom.Int(1))
```

--------------------------------

### get_date usage example

Source: https://github.com/lpil/tom

Parses a TOML document with a bare date and retrieves it using get_date. Uses assert to unwrap the result and match the expected calendar.Date value.

```gleam
import gleam/time/calendar
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("born = 1979-05-27")
  let assert Ok(calendar.Date(1979, calendar.May, 27)) =
    tom.get_date(parsed, ["born"])
}
```

--------------------------------

### get_time_of_day usage example

Source: https://github.com/lpil/tom

Parses a TOML document with a local time and retrieves it using get_time_of_day. Uses assert to unwrap the result and match the expected calendar.TimeOfDay value.

```gleam
import gleam/time/calendar
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("wake = 07:32:00")
  let assert Ok(calendar.TimeOfDay(7, 32, 0, 0)) =
    tom.get_time_of_day(parsed, ["wake"])
}
```

--------------------------------

### as_time_of_day WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned when as_time_of_day receives a non-Time value, such as tom.Int(1). The expected-name is "Time".

```gleam
let assert Error(tom.WrongType([], "Time", "Int")) =
  tom.as_time_of_day(tom.Int(1))
```

--------------------------------

### get_number with infinity value

Source: https://github.com/lpil/tom

Example of using tom.get_number to handle an infinity value. The case expression matches on the result, covering NumberInfinity, other Number variants, and errors.

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("x = inf")
  case tom.get_number(parsed, ["x"]) {
    Ok(tom.NumberInfinity(tom.Positive)) -> { /* positive infinity */ }
    Ok(number) -> { /* NumberInt | NumberFloat | NumberNan */ }
    Error(e) -> { /* NotFound or WrongType */ }
  }
}
```

--------------------------------

### as_number error example

Source: https://github.com/lpil/tom

Demonstrates that `as_number` returns a `WrongType` error when given a non-numeric value, such as `tom.Bool(True)`. The expected name is `"Number"`.

```gleam
let assert Error(tom.WrongType([], "Number", "Bool")) =
  tom.as_number(tom.Bool(True))
```

--------------------------------

### get_array with array of tables

Source: https://github.com/lpil/tom

Retrieves an array of tables, where each element is wrapped in tom.Table. The example parses a TOML document with [[fruit]] entries and asserts the result contains two Table values.

```gleam
import tom

pub fn main() {
  // Arrays of tables are returned with each element wrapped in Table
  let document = "
    [[fruit]]
    name = \"apple\"
    [[fruit]]
    name = \"banana\"
  "
  let assert Ok(parsed) = tom.parse(document)
  let assert Ok([tom.Table(_), tom.Table(_)]) =
    tom.get_array(parsed, ["fruit"])
}
```

--------------------------------

### to_dynamic decode a TOML-specific value

Source: https://github.com/lpil/tom

Example showing how to convert a parsed TOML document to Dynamic and decode a timestamp field using the library's timestamp_decoder. The DateTime dynamic carries { "date", "time", "offset" } properties.

```gleam
import gleam/dynamic/decode
import gleam/time/timestamp
import tom

pub fn main() {
  let config = "at = 1970-01-01T00:00:00Z"
  let assert Ok(parsed) = tom.parse(config)
  let dynamic = tom.to_dynamic(parsed)

  // DateTime dynamics carry { "date", "time", "offset" } properties,
  // which the timestamp decoder understands
  let assert Ok(ts) =
    decode.run(dynamic, decode.field("at", tom.timestamp_decoder()))
  let assert ts == timestamp.from_unix_seconds(0)
}
```

--------------------------------

### get_table WrongType error example

Source: https://github.com/lpil/tom

Shows the expected error when get_table is called on a value that is not a table, such as an integer. The error is tom.WrongType with expected name "Table".

```gleam
let assert Error(tom.WrongType(_, "Table", "Int")) =
  tom.get_table(parsed, ["person"]) // when the value is 42
```

--------------------------------

### as_date WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned when as_date receives a non-Date value, such as tom.Int(1). The expected-name is "Date".

```gleam
let assert Error(tom.WrongType([], "Date", "Int")) =
  tom.as_date(tom.Int(1))
```

--------------------------------

### get_int WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned when the value at the key path is a Float instead of an Int. The WrongType error includes the expected type "Int" and the actual type "Float".

```gleam
let assert Error(tom.WrongType(_, "Int", "Float")) =
  tom.get_int(parsed, ["a", "b", "c"]) // when the value is 1.0
```

--------------------------------

### get_string WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned by tom.get_string when the value is not a String (here, a Table). The WrongType error includes the expected type name "String" and the actual type "Table".

```gleam
let assert Error(tom.WrongType(_, "String", "Table")) =
  tom.get_string(parsed, ["name"]) // when the value is a table
```

--------------------------------

### get_date WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned when the value at the key is a string instead of a bare date. The WrongType error carries expected name "Date" and actual type "String".

```gleam
let assert Error(tom.WrongType(_, "Date", "String")) =
  tom.get_date(parsed, ["born"]) // when the value is "1979-05-27"
```

--------------------------------

### get_time_of_day WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned when the value is a date-time instead of a bare time. The WrongType error carries expected name "Time" and actual type "DateTime".

```gleam
// a date-time is not a bare time
let assert Error(tom.WrongType(_, "Time", "DateTime")) =
  tom.get_time_of_day(parsed, ["wake"]) // when the value is 1979-05-27T07:32:00
```

--------------------------------

### get_calendar_time basic usage

Source: https://github.com/lpil/tom

Parses a TOML string containing a DateTime value and retrieves its calendar date, time, and offset using tom.get_calendar_time. The example asserts the result matches the expected tuple.

```gleam
import gleam/time/calendar
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("at = 1979-05-27T07:32:00")
  let assert Ok(#(calendar.Date(1979, calendar.May, 27),
    calendar.TimeOfDay(7, 32, 0, 0), tom.Local)) =
    tom.get_calendar_time(parsed, ["at"])
}
```

--------------------------------

### get_bool WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned by tom.get_bool when the value is not a Bool (here, an Int). The WrongType error includes the expected type name "Bool" and the actual type "Int".

```gleam
let assert Error(tom.WrongType(_, "Bool", "Int")) =
  tom.get_bool(parsed, ["is_cool"]) // when the value is 1
```

--------------------------------

### Import the tom module

Source: https://github.com/lpil/tom

Import the public `tom` module from the `tom` package.

```gleam
import tom
```

--------------------------------

### get/2

Source: https://github.com/lpil/tom

Retrieves a value from a parsed TOML document using a key path. Returns a Result with the value or a GetError.

```APIDOC
## get/2

### Description
Retrieves a value from a parsed TOML document using a key path. Returns a Result with the value or a GetError.

### Function Signature
`get(key: List(String), toml: Toml) -> Result(Dynamic, GetError)`

### Parameters
- `key` (List(String)) - Required - The key path to the value.
- `toml` (Toml) - Required - The parsed TOML document.

### Returns
- `Result(Dynamic, GetError)` - The value at the key path or a GetError.
```

--------------------------------

### parse/1

Source: https://github.com/lpil/tom

Parses a TOML string into a Toml document. This is the main entry point for parsing TOML content.

```APIDOC
## parse/1

### Description
Parses a TOML string into a Toml document. This is the main entry point for parsing TOML content.

### Function Signature
`parse(input: String) -> Result(Toml, ParseError)`

### Parameters
- `input` (String) - Required - The TOML string to parse.

### Returns
- `Result(Toml, ParseError)` - The parsed TOML document or a ParseError.
```

--------------------------------

### tom.parse function signature

Source: https://github.com/lpil/tom

Declares the public API for parsing TOML strings. Returns a Result with a Dict of Toml values or a ParseError.

```gleam
pub fn parse(input: String) -> Result(Dict(String, Toml), ParseError) {
```

--------------------------------

### Error handling on malformed TOML parse

Source: https://github.com/lpil/tom

Handles both Unexpected and KeyAlreadyInUse errors from tom.parse. Shows pattern matching on the Result type.

```gleam
import tom

pub fn main() {
  let result = tom.parse("name = [1, 2") // unterminated array
  case result {
    Ok(document) -> {
      // use the parsed document
    }
    Error(tom.Unexpected(got, expected)) -> {
      // e.g. Unexpected("EOF", "]") — the lexer hit the end of input
      // while expecting "]"
      io.println("expected " <> expected <> " but got " <> got)
    }
    Error(tom.KeyAlreadyInUse(key)) -> {
      // a key was defined more than once; `key` is the dotted path
    }
  }
}
```

--------------------------------

### to_dynamic

Source: https://github.com/lpil/tom

Converts an already-parsed TOML document dictionary into a Dynamic. Never fails, as every Toml variant has a Dynamic representation.

```APIDOC
## `to_dynamic`

### Description
Converts an already-parsed TOML document dictionary into a `Dynamic`.

### Signature
```gleam
pub fn to_dynamic(toml: Dict(String, Toml)) -> Dynamic
```

### Parameters
- **toml** (`Dict(String, Toml)`) - Required - A parsed TOML document (the `Ok` value of `parse`).

### Return
`Dynamic`. Never fails — every `Toml` variant has a `Dynamic` representation (implementation `table_to_dynamic(toml)`, line 152).

Dynamic shape produced by the internal converters (`value_to_dynamic`, `table_to_dynamic`, `date_to_dynamic`, `time_to_dynamic`, `datetime_to_dynamic`, `offset_to_dynamic`, `duration_to_dynamic`, lines 1917–2005):

- `Int(x)` → `dynamic.int(x)`
- `Float(x)` → `dynamic.float(x)`
- `Bool(x)` → `dynamic.bool(x)`
- `String(x)` → `dynamic.string(x)`
- `Nan(Positive)` / `Nan(Negative)` → platform-specific sentinel (`positive_nan` / `negative_nan` atoms on Erlang; `Symbol("+NaN")` / `Symbol("-NaN")` on JavaScript) via FFI `nan_to_dynamic`
- `Infinity(Positive)` / `Infinity(Negative)` → `Infinity` / `-Infinity` on JavaScript, `positive_infinity` / `negative_infinity` atoms on Erlang, via FFI `infinity_to_dynamic`
- `Date(date)` → properties `{ "day": Int, "month": "January".."December", "year": Int }`
- `Time(time)` → properties `{ "hours", "minutes", "seconds", "nanoseconds" }` (all `Int`)
- `DateTime(date, time, offset)` → properties `{ "date": …, "time": …, "offset": … }`
- `Table(dict)` / `InlineTable(dict)` → `dynamic.properties` (string-keyed)
- `Array(elems)` → `dynamic.list` of converted elements
- `ArrayOfTables(tables)` → `dynamic.list` of converted tables
- `Offset` representations: `Local` → `{ "type": "Local" }`; `Offset(duration)` → `{ "type": "Offset", "duration": { "seconds": Int, "nanoseconds": Int } }` (via `duration.to_seconds_and_nanoseconds`)

### Request Example
```gleam
import gleam/dynamic/decode
import gleam/time/timestamp
import tom

pub fn main() {
  let config = "at = 1970-01-01T00:00:00Z"
  let assert Ok(parsed) = tom.parse(config)
  let dynamic = tom.to_dynamic(parsed)

  // DateTime dynamics carry { "date", "time", "offset" } properties,
  // which the timestamp decoder understands
  let assert Ok(ts) =
    decode.run(dynamic, decode.field("at", tom.timestamp_decoder()))
  let assert ts == timestamp.from_unix_seconds(0)
}
```
```

--------------------------------

### get_number with integer value

Source: https://github.com/lpil/tom

Example of using tom.get_number to extract an integer value from a parsed TOML document. The result is asserted to be NumberInt(1337).

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("a = 1337")
  let assert Ok(tom.NumberInt(1337)) = tom.get_number(parsed, ["a"])
}
```

--------------------------------

### parse_to_dynamic/1

Source: https://github.com/lpil/tom

Parses a TOML string and returns a Dynamic value. Combines parsing and conversion in one step.

```APIDOC
## parse_to_dynamic/1

### Description
Parses a TOML string and returns a Dynamic value. Combines parsing and conversion in one step.

### Function Signature
`parse_to_dynamic(input: String) -> Result(Dynamic, ParseError)`

### Parameters
- `input` (String) - Required - The TOML string to parse.

### Returns
- `Result(Dynamic, ParseError)` - The parsed TOML as a Dynamic value or a ParseError.
```

--------------------------------

### to_dynamic/1

Source: https://github.com/lpil/tom

Converts a parsed TOML document into a Dynamic value. Useful for working with dynamic data structures.

```APIDOC
## to_dynamic/1

### Description
Converts a parsed TOML document into a Dynamic value. Useful for working with dynamic data structures.

### Function Signature
`to_dynamic(toml: Toml) -> Dynamic`

### Parameters
- `toml` (Toml) - Required - The parsed TOML document.

### Returns
- `Dynamic` - The TOML document as a Dynamic value.
```

--------------------------------

### Basic call to timestamp_decoder

Source: https://github.com/lpil/tom

Parses a TOML string with an offset date-time and decodes it into a timestamp. The example shows the expected result as a tuple with the key and the timestamp value.

```gleam
import gleam/dynamic/decode
import gleam/time/timestamp
import tom

pub fn main() {
  let assert Ok(dynamic) = tom.parse_to_dynamic("at = 2015-10-21T14:28:00Z")
  let assert Ok(dict) =
    decode.run(dynamic, decode.dict(decode.string, tom.timestamp_decoder()))
  // #("at", timestamp.from_unix_seconds(1445437680))
}
```

--------------------------------

### tom.get function signature

Source: https://github.com/lpil/tom

Function signature for retrieving a value from a parsed TOML document by dotted key path. Returns Result(Toml, GetError).

```gleam
pub fn get(
  toml: Dict(String, Toml),
  key: List(String),
) -> Result(Toml, GetError) {
```

--------------------------------

### as_int/1 … as_number/1

Source: https://github.com/lpil/tom

Conversion functions that convert a Dynamic value to a specific type. Useful for working with dynamic values from parsed TOML.

```APIDOC
## as_int/1 … as_number/1

### Description
Conversion functions that convert a Dynamic value to a specific type. Useful for working with dynamic values from parsed TOML.

### Function Signatures
- `as_int(dynamic: Dynamic) -> Result(Int, String)`
- `as_float(dynamic: Dynamic) -> Result(Float, String)`
- `as_bool(dynamic: Dynamic) -> Result(Bool, String)`
- `as_string(dynamic: Dynamic) -> Result(String, String)`
- `as_number(dynamic: Dynamic) -> Result(Number, String)`

### Parameters
- `dynamic` (Dynamic) - Required - The dynamic value to convert.

### Returns
- `Result(Int, String)` - The integer value or an error message.
- `Result(Float, String)` - The float value or an error message.
- `Result(Bool, String)` - The boolean value or an error message.
- `Result(String, String)` - The string value or an error message.
- `Result(Number, String)` - The number value or an error message.
```

--------------------------------

### parse

Source: https://github.com/lpil/tom

Parses a string of TOML into a nested dictionary of Toml values. Returns a Result that is either Ok with the parsed document or Error with a ParseError.

```APIDOC
## parse

### Description
Parses a string of TOML into a nested dictionary of `Toml` values. Returns a `Result` that is either `Ok` with the parsed document or `Error` with a `ParseError`.

### Method
parse

### Parameters
- **input** (String) - Required - The TOML document text to parse.

### Return
`Result(Dict(String, Toml), ParseError)` - On success the top-level document is a `Dict` keyed by the top-level keys of the document. Nested tables are represented by the `Table`/`InlineTable` variants, arrays of tables by `ArrayOfTables`, and every scalar by its corresponding `Toml` variant. On failure it returns `Error(ParseError)` — either `Unexpected(got, expected)` or `KeyAlreadyInUse(key)`; a `ParseError` is never thrown, only returned.

### Request Example
```gleam
import tom
import gleam/dict

pub fn main() {
  let config = "
    [person]
    name = \"Lucy\"
    is_cool = true
    scores = [10, 20, 30]
  "

  let assert Ok(parsed) = tom.parse(config)

  // parsed is a Dict(String, Toml): the [person] table is tom.Table(...)
  let assert Some(tom.Table(person)) = dict.get(parsed, "person")
}
```

### Response Example
```gleam
import tom

pub fn main() {
  let result = tom.parse("name = [1, 2") // unterminated array
  case result {
    Ok(document) -> {
      // use the parsed document
    }
    Error(tom.Unexpected(got, expected)) -> {
      // e.g. Unexpected("EOF", "]") — the lexer hit the end of input
      // while expecting "]"
      io.println("expected " <> expected <> " but got " <> got)
    }
    Error(tom.KeyAlreadyInUse(key)) -> {
      // a key was defined more than once; `key` is the dotted path
    }
  }
}
```
```

--------------------------------

### parse_to_dynamic

Source: https://github.com/lpil/tom

Parses a TOML string and immediately converts the result to a Dynamic, suitable for use with gleam/dynamic/decode decoders. Returns a Result containing either the Dynamic value or a ParseError.

```APIDOC
## `parse_to_dynamic`

### Description
Convenience function that parses a TOML string and immediately converts the result to a `Dynamic`, suitable for use with `gleam/dynamic/decode` decoders (including this library's TOML-specific decoders).

### Signature
```gleam
pub fn parse_to_dynamic(input: String) -> Result(Dynamic, ParseError)
```

### Parameters
- **input** (`String`) - Required - The TOML document text to parse.

### Return
`Result(Dynamic, ParseError)`. Implemented as `parse(input) |> result.map(to_dynamic)` (line 178). The dynamic shape produced is documented under [`to_dynamic`](#todynamic) below.

### Request Example
```gleam
import gleam/dynamic/decode
import tom

pub fn main() {
  let config = "name = \"Lucy\"\npoints = 5"
  let assert Ok(dynamic) = tom.parse_to_dynamic(config)

  let decoder = {
    use name <- decode.field("name", decode.string)
    use points <- decode.field("points", decode.int)
    decode.success(#(name, points))
  }

  let assert Ok(#("Lucy", 5)) = decode.run(dynamic, decoder)
}
```

### Response Example
```gleam
import tom

pub fn main() {
  // A parse failure is returned as Error(ParseError); combined with
  // result.try it composes with subsequent decoding steps.
  let assert Error(tom.Unexpected(_, _)) = tom.parse_to_dynamic("nope")
}
```
```

--------------------------------

### to_dynamic function signature

Source: https://github.com/lpil/tom

Signature of the to_dynamic function. It converts a parsed TOML document dictionary into a Dynamic. Never fails because every Toml variant has a Dynamic representation.

```gleam
pub fn to_dynamic(toml: Dict(String, Toml)) -> Dynamic {
```

--------------------------------

### get_calendar_time WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned when the value is a Date instead of a DateTime. The expected-name is "DateTime" and the actual type is "Date".

```gleam
let assert Error(tom.WrongType(_, "DateTime", "Date")) =
  tom.get_calendar_time(parsed, ["at"]) // when the value is 1979-05-27
```

--------------------------------

### parse_to_dynamic function signature

Source: https://github.com/lpil/tom

Signature of the parse_to_dynamic function. It parses a TOML string and converts the result to a Dynamic for use with gleam/dynamic/decode decoders.

```gleam
pub fn parse_to_dynamic(input: String) -> Result(Dynamic, ParseError) {
```

--------------------------------

### GetError

Source: https://github.com/lpil/tom

An error type returned by `get`, all `get_*` functions, and all `as_*` functions when retrieving a value from a parsed TOML document fails. It has two variants: `NotFound` for missing keys and `WrongType` for type mismatches.

```APIDOC
## GetError

### Description
An error that can occur when retrieving a value from a parsed document with a `get_*` function or an `as_*` function. Returned (never thrown) by `get`, all `get_*` functions, and all `as_*` functions.

### Variants

#### NotFound(key)
- `key` (List(String)) - Required - The path where no value exists. Returns `NotFound([])` when the key list is empty.

#### WrongType(key, expected, got)
- `key` (List(String)) - Required - The path of the value.
- `expected` (String) - Required - The expected type.
- `got` (String) - Required - The actual type, one of: `"Int"`, `"Float"`, `"NaN"`, `"Negative NaN"`, `"Infinity"`, `"Negative Infinity"`, `"Bool"`, `"String"`, `"Date"`, `"Time"`, `"DateTime"`, `"Array"`, `"Table"`.

### Usage
Returned by `get`, all `get_*` functions, and all `as_*` functions.
```

--------------------------------

### number_decoder/0 … timestamp_decoder/0

Source: https://github.com/lpil/tom

Decoder functions that return decoders for TOML types. These can be used with dynamic decoding libraries.

```APIDOC
## number_decoder/0 … timestamp_decoder/0

### Description
Decoder functions that return decoders for TOML types. These can be used with dynamic decoding libraries.

### Function Signatures
- `number_decoder() -> Decoder(Number)`
- `timestamp_decoder() -> Decoder(Timestamp)`

### Returns
- `Decoder(Number)` - A decoder for TOML numbers.
- `Decoder(Timestamp)` - A decoder for TOML timestamps.
```

--------------------------------

### get_float WrongType error example

Source: https://github.com/lpil/tom

Shows the error returned by tom.get_float when the value is not a Float (here, an Int). The WrongType error includes the expected type name "Float" and the actual type "Int".

```gleam
let assert Error(tom.WrongType(_, "Float", "Int")) =
  tom.get_float(parsed, ["ratio"]) // when the value is 1
```

--------------------------------

### get_int/2 … get_number/2

Source: https://github.com/lpil/tom

A family of typed getter functions that retrieve and convert values from a parsed TOML document. Each function targets a specific type (int, float, bool, string, etc.).

```APIDOC
## get_int/2 … get_number/2

### Description
A family of typed getter functions that retrieve and convert values from a parsed TOML document. Each function targets a specific type (int, float, bool, string, etc.).

### Function Signatures
- `get_int(key: List(String), toml: Toml) -> Result(Int, GetError)`
- `get_float(key: List(String), toml: Toml) -> Result(Float, GetError)`
- `get_bool(key: List(String), toml: Toml) -> Result(Bool, GetError)`
- `get_string(key: List(String), toml: Toml) -> Result(String, GetError)`
- `get_number(key: List(String), toml: Toml) -> Result(Number, GetError)`

### Parameters
- `key` (List(String)) - Required - The key path to the value.
- `toml` (Toml) - Required - The parsed TOML document.

### Returns
- `Result(Int, GetError)` - The integer value or a GetError.
- `Result(Float, GetError)` - The float value or a GetError.
- `Result(Bool, GetError)` - The boolean value or a GetError.
- `Result(String, GetError)` - The string value or a GetError.
- `Result(Number, GetError)` - The number value or a GetError.
```

--------------------------------

### get_timestamp ambiguous datetime without offset

Source: https://github.com/lpil/tom

Handles a DateTime value without an offset, which is ambiguous and produces WrongType with expected-name "DateTime with offset". The example shows a case expression matching Ok, WrongType, and NotFound outcomes.

```gleam
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("at = 1979-05-27T07:32:00") // no offset
  case tom.get_timestamp(parsed, ["at"]) {
    Ok(ts) -> { /* use the timestamp */ }
    Error(tom.WrongType(path, expected, got)) -> {
      // WrongType(["at"], "DateTime with offset", "DateTime")
    }
    Error(tom.NotFound(_)) -> { /* key absent */ }
  }
}
```

--------------------------------

### as_calendar_time function signature

Source: https://github.com/lpil/tom

Public function signature for as_calendar_time. Returns a Result containing a tuple of calendar.Date, calendar.TimeOfDay, and Offset, or a GetError. Unlike as_timestamp, Local offsets are accepted. WrongType expected-name is "DateTime".

```gleam
pub fn as_calendar_time(
  toml: Toml,
) -> Result(#(calendar.Date, calendar.TimeOfDay, Offset), GetError) {
```

--------------------------------

### as_time_of_day function signature

Source: https://github.com/lpil/tom

Declares the public API for as_time_of_day, which unwraps a Toml value into a calendar.TimeOfDay. Returns Result(calendar.TimeOfDay, GetError).

```gleam
pub fn as_time_of_day(toml: Toml) -> Result(calendar.TimeOfDay, GetError) {
```

--------------------------------

### as_table function signature

Source: https://github.com/lpil/tom

Defines the public function `as_table` that takes a `Toml` value and returns a `Result` with a dictionary of strings to `Toml` values or a `GetError`. Accepts both `Table` and `InlineTable` variants.

```gleam
pub fn as_table(toml: Toml) -> Result(Dict(String, Toml), GetError) {
```

--------------------------------

### as_date function signature

Source: https://github.com/lpil/tom

Declares the public API for as_date, which unwraps a Toml value into a calendar.Date. Returns Result(calendar.Date, GetError).

```gleam
pub fn as_date(toml: Toml) -> Result(calendar.Date, GetError) {
```

--------------------------------

### as_timestamp WrongType error for local datetime

Source: https://github.com/lpil/tom

Shows the error returned when as_timestamp receives a DateTime with a Local offset, which is ambiguous and cannot be converted. The expected-name is "DateTime with offset".

```gleam
// A local (offset-less) datetime is ambiguous and cannot be a timestamp
let assert Error(tom.WrongType([], "DateTime with offset", "DateTime")) =
  tom.as_timestamp(tom.DateTime(
    date: calendar.Date(1979, calendar.May, 27),
    time: calendar.TimeOfDay(7, 32, 0, 0),
    offset: tom.Local,
  ))
```

--------------------------------

### get_table with inline table

Source: https://github.com/lpil/tom

Parses a TOML document with an inline table and retrieves it using get_table, then accesses a value from the returned dictionary.

```gleam
import gleam/dict
import tom

pub fn main() {
  let assert Ok(parsed) = tom.parse("person = { name = \"Lucy\" }")
  let assert Ok(table) = tom.get_table(parsed, ["person"])
  let assert Some(tom.String("Lucy")) = dict.get(table, "name")
}
```
Tokens:
Raw