tom

A pure Gleam TOML parser!

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)
}

Types

GetError

</>

An error that can occur when retrieving a value from a TOML document dictionary with one of the get_* functions.

pub type GetError {
  NotFound(key: List(String))
  WrongType(key: List(String), expected: String, got: String)
}

Constructors

```
NotFound(key: List(String))
```
There was no value at the given key.

WrongType(key: List(String), expected: String, got: String)

The value at the given key was not of the expected type.

Number

</>

A number of any kind, returned by the get_number/number_decoder functions.

pub type Number {
  NumberInt(Int)
  NumberFloat(Float)
  NumberInfinity(Sign)
  NumberNan(Sign)
}

Constructors

```
NumberInt(Int)
```
```
NumberFloat(Float)
```
```
NumberInfinity(Sign)
```
```
NumberNan(Sign)
```

Offset

</>

pub type Offset {
  Local
  Offset(duration.Duration)
}

Constructors

```
Local
```
```
Offset(duration.Duration)
```

ParseError

</>

An error that can occur when parsing a TOML document.

pub type ParseError {
  Unexpected(got: String, expected: String)
  KeyAlreadyInUse(key: List(String))
}

Constructors

```
Unexpected(got: String, expected: String)
```
An unexpected character was encountered when parsing the document.
```
KeyAlreadyInUse(key: List(String))
```
More than one items have the same key in the document.

Toml

</>

A TOML document.

pub type Toml {
  Int(Int)
  Float(Float)
  Infinity(Sign)
  Nan(Sign)
  Bool(Bool)
  String(String)
  Date(calendar.Date)
  Time(calendar.TimeOfDay)
  DateTime(
    date: calendar.Date,
    time: calendar.TimeOfDay,
    offset: Offset,
  )
  Array(List(Toml))
  ArrayOfTables(List(dict.Dict(String, Toml)))
  Table(dict.Dict(String, Toml))
  InlineTable(dict.Dict(String, Toml))
}

Constructors

```
Int(Int)
```
```
Float(Float)
```
```
Infinity(Sign)
```
Infinity is a valid number in TOML but Gleam does not support it, so this variant represents the infinity values.
```
Nan(Sign)
```
NaN is a valid number in TOML but Gleam does not support it, so this variant represents the NaN values.
```
Bool(Bool)
```
```
String(String)
```
```
Date(calendar.Date)
```
```
Time(calendar.TimeOfDay)
```

DateTime(
  date: calendar.Date,
  time: calendar.TimeOfDay,
  offset: Offset,
)

```
Array(List(Toml))
```

ArrayOfTables(List(dict.Dict(String, Toml)))

```
Table(dict.Dict(String, Toml))
```
```
InlineTable(dict.Dict(String, Toml))
```

Values

Examples

as_array(Array([]))
// -> Ok([])

as_array(Int(1))
// -> Error(WrongType([], "Array", "Int"))

Examples

as_bool(Bool(true))
// -> Ok(true)

as_bool(Int(1))
// -> Error(WrongType([], "Bool", "Int"))

Examples

as_calendar_time(DateTime(datetime))
// -> Ok(datetime)

as_calendar_time(Int(1))
// -> Error(WrongType([], "DateTime", "Int"))

Examples

as_date(Date(date))
// -> Ok(date)

as_date(Int(1))
// -> Error(WrongType([], "Date", "Int"))

Examples

as_float(Float(1.5))
// -> Ok(1.5)

as_float(Int(1))
// -> Error(WrongType([], "Float", "Int"))

Examples

as_int(Int(1))
// -> Ok(1)

as_int(Float(1.4))
// -> Error(WrongType([], "Int", "Float"))

as_number

</>

pub fn as_number(toml: Toml) -> Result(Number, GetError)

Get a number (int or float) from a TOML document.

Examples

as_number(Int(1))
// -> Ok(NumberInt(1))

as_number(Float(1.5))
// -> Ok(NumberFloat(1.5))

as_number(Bool(true))
// -> Error(WrongType([], "Number", "Bool"))

Examples

as_string(String("hello"))
// -> Ok("hello")

as_string(Int(1))
// -> Error(WrongType([], "String", "Int"))

Examples

as_table(Table(dict.new()))
// -> Ok(dict.new())

as_table(Int(1))
// -> Error(WrongType([], "Table", "Int"))

Examples

as_time_of_day(Time(time))
// -> Ok(time)

as_time_of_day(Int(1))
// -> Error(WrongType([], "Time", "Int"))

as_timestamp

</>

pub fn as_timestamp(
  toml: Toml,
) -> Result(timestamp.Timestamp, GetError)

Get an unambiguous time from a TOML document.

Examples

as_timestamp(Int(1))
// -> Error(WrongType([], "DateTime with offset", "Int"))

calendar_date_time_of_day_decoder

</>

pub fn calendar_date_time_of_day_decoder() -> decode.Decoder(
  #(calendar.Date, calendar.TimeOfDay, Offset),
)

A decoder that decodes TOML date time into corresponding date, time, and offset parts.

Examples

let assert Ok(toml) = tom.parse_to_dynamic("datetime = 2015-10-21T07:28:00")
decode.run(toml, decode.dict(decode.string, tom.calendar_date_time_of_day_decoder()))
// -> Ok(
//    dict.from_list([
//      #("datetime", #(
//        calendar.Date(2015, calendar.October, 21),
//        calendar.TimeOfDay(7, 28, 0, 0),
//        tom.Local
//      ))
//    ])
//  )

date_decoder

</>

pub fn date_decoder() -> decode.Decoder(calendar.Date)

A decoder that decodes TOML date into a calendar.Date.

Examples

let assert Ok(toml) = tom.parse_to_dynamic("future = 2015-10-21")
decode.run(toml, decode.dict(decode.string, tom.date_decoder())))
// -> Ok(
//    dict.from_list([
//      #("future", calendar.Date(
//        year: 2015, month: calendar.October, day: 21
//      )),
//    ])
//  )

get

</>

pub fn get(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(Toml, GetError)

Get a value of any type from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = 1")
get(parsed, ["a", "b", "c"])
// -> Ok(Int(1))

get_array

</>

pub fn get_array(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(List(Toml), GetError)

Get an array from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = [1, 2]")
get_array(parsed, ["a", "b", "c"])
// -> Ok([Int(1), Int(2)])

get_bool

</>

pub fn get_bool(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(Bool, GetError)

Get a bool from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = true")
get_bool(parsed, ["a", "b", "c"])
// -> Ok(True)

get_calendar_time

</>

pub fn get_calendar_time(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(
  #(calendar.Date, calendar.TimeOfDay, Offset),
  GetError,
)

Get a date-time from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = 1979-05-27T07:32:00")
get_calendar_time(parsed, ["a", "b", "c"])
// -> Ok(#(Date(1979, May, 27), TimeOfDay(7, 32, 0, 0), Local))

get_date

</>

pub fn get_date(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(calendar.Date, GetError)

Get a date from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = 1979-05-27")
get_date(parsed, ["a", "b", "c"])
// -> Ok(Date(1979, May, 27))

get_float

</>

pub fn get_float(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(Float, GetError)

Get a float from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = 1.1")
get_float(parsed, ["a", "b", "c"])
// -> Ok(1.1)

get_int

</>

pub fn get_int(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(Int, GetError)

Get an int from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = 1")
get_int(parsed, ["a", "b", "c"])
// -> Ok(1)

get_number

</>

pub fn get_number(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(Number, GetError)

Get a number of any kind from a TOML document dictionary. This could be an int, a float, a NaN, or an infinity.

Examples

let assert Ok(parsed) = parse("a.b.c = { d = inf }")
get_number(parsed, ["a", "b", "c"])
// -> Ok(NumberInfinity(Positive)))

get_string

</>

pub fn get_string(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(String, GetError)

Get a string from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = \"ok\"")
get_string(parsed, ["a", "b", "c"])
// -> Ok("ok")

get_table

</>

pub fn get_table(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(dict.Dict(String, Toml), GetError)

Get a table from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = { d = 1 }")
get_table(parsed, ["a", "b", "c"])
// -> Ok(dict.from_list([#("d", Int(1))]))

get_time_of_day

</>

pub fn get_time_of_day(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(calendar.TimeOfDay, GetError)

Get a time from a TOML document dictionary.

Examples

let assert Ok(parsed) = parse("a.b.c = 07:32:00")
get_time_of_day(parsed, ["a", "b", "c"])
// -> Ok(TimeOfDay(7, 32, 0, 0))

get_timestamp

</>

pub fn get_timestamp(
  toml: dict.Dict(String, Toml),
  key: List(String),
) -> Result(timestamp.Timestamp, GetError)

Get an unambiguous time from a TOML document dictionary.

If a TOML date time has no offset it is ambiguous and cannot be converted into a timestamp. There’s no way to know what actual point in time it would be as it would be different in different time zones.

Examples

let assert Ok(parsed) = parse("a.b.c = 1970-00-00T00:00:00Z")
get_timestamp(parsed, ["a", "b", "c"])
// -> Ok(timestamp.from_unix_seconds(0))

number_decoder

</>

pub fn number_decoder() -> decode.Decoder(Number)

A decoder that decodes TOML numbers into a Number. This could be an int, a float, a NaN, or an infinity.

Examples

let assert Ok(toml) = tom.parse_to_dynamic("lucy = 1337")
decode.run(toml, decode.dict(decode.string, tom.number_decoder())))
// -> Ok(dict.from_list([#("lucy", tom.NumberInt(1337))]))

parse

</>

pub fn parse(
  input: String,
) -> Result(dict.Dict(String, Toml), ParseError)

parse_to_dynamic

</>

pub fn parse_to_dynamic(
  input: String,
) -> Result(dynamic.Dynamic, ParseError)

A convenience for parsing a TOML document and immediately converting it to a Dynamic. This can be used to build complex decoders based on TOML data, using gleam/dynamic/decode. Decoders are provided in this library for TOML-specific types.

Examples

let config = "name = \"Lucy\"\npoints = 5"
let assert Ok(dynamic) = parse_to_dynamic(config)

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

decode.run(dynamic, decoder)
// -> Ok(#("Lucy", 5))

time_of_day_decoder

</>

pub fn time_of_day_decoder() -> decode.Decoder(calendar.TimeOfDay)

A decoder that decodes TOML time into a calendar.TimeOfDay.

Examples

let assert Ok(toml) = tom.parse_to_dynamic("time = 07:28:00")
decode.run(toml, decode.dict(decode.string, tom.time_of_day_decoder())))
// -> Ok(
//    dict.from_list([
//      #("time", calendar.TimeOfDay(
//        hours: 7, minutes: 28, seconds: 0, nanoseconds: 0
//      ))
//    ])
//  )

timestamp_decoder

</>

pub fn timestamp_decoder() -> decode.Decoder(timestamp.Timestamp)

A decoder that decodes TOML date time into an unambiguous timestamp

Examples

let assert Ok(toml) = tom.parse_to_dynamic("datetime = 2015-10-21T14:28:00Z")
decode.run(toml, decode.dict(decode.string, tom.timestamp_decoder()))
// -> Ok(dict.from_list([#("datetime", timestamp.from_unix_seconds(1445437680))]))

to_dynamic

</>

pub fn to_dynamic(
  toml: dict.Dict(String, Toml),
) -> dynamic.Dynamic

Convert a parsed TOML document into a Dynamic. This can be used to build complex decoders based on TOML data, using gleam/dynamic/decode. Decoders are provided in this library for TOML-specific types.

Examples

let config = "name = \"Lucy\"\npoints = 5"
let assert Ok(parsed) = parse(config)
let dynamic = to_dynamic(parsed)

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

decode.run(dynamic, decoder)
// -> Ok(#("Lucy", 5))