spaceship_toml

Package VersionHex Docs

A TOML parser, editor, and serializer for Gleam that preserves comments, formatting, and line numbers.

Parse a TOML config file, edit values programmatically, and serialize it back — all without losing your comments or indentation.

gleam add spaceship_toml

Quick Start

import spaceship_toml

import gleam/option.{None}



pub fn main() {

  let input = "

# App config

name = \"my-app\"



[server]

host = \"localhost\"

port = 8080

"



  // Parse

  let assert Ok(doc) = spaceship_toml.parse(input)



  // Get a value (with line number)

  let assert Ok(result) = spaceship_toml.get(doc, ["server", "port"])

  // result.value == TomlInteger(8080)

  // result.line_number == 7



  // Edit

  let assert Ok(doc) =

    spaceship_toml.set(doc, ["server", "port"], spaceship_toml.integer(9090), None)



  // Serialize (preserves comments and formatting)

  let output = spaceship_toml.to_string(doc)

  // "# App config\nname = \"my-app\"\n\n[server]\nhost = \"localhost\"\nport = 9090\n"

}

API

Parsing & Serialization

// Parse TOML string into a Document

spaceship_toml.parse(input: String) -> Result(Document, ParseError)



// Serialize a Document back to a TOML string

spaceship_toml.to_string(doc: Document) -> String

Reading Values

// Get a value by key path, returns key, value, and line number

spaceship_toml.get(doc, ["server", "host"])

// -> Ok(GetResult(key: "server.host", value: TomlString("localhost"), line_number: 5))

Typed Getters

Type-safe getters that return the value directly, avoiding manual pattern matching:

// Returns #(value, line_number)

let assert Ok(#(name, _line)) = spaceship_toml.get_string(doc, ["name"])

let assert Ok(#(count, _line)) = spaceship_toml.get_int(doc, ["count"])

let assert Ok(#(pi, _line)) = spaceship_toml.get_float(doc, ["pi"])

let assert Ok(#(debug, _line)) = spaceship_toml.get_bool(doc, ["debug"])

let assert Ok(#(items, _line)) = spaceship_toml.get_array(doc, ["items"])

let assert Ok(#(created, _line)) = spaceship_toml.get_date(doc, ["created"])

let assert Ok(#(time, _line)) = spaceship_toml.get_time(doc, ["time"])

let assert Ok(#(timestamp, _line)) = spaceship_toml.get_datetime(doc, ["timestamp"])

Returns Error(KeyNotFound(...)) if the key doesn't exist or the type doesn't match.

Editing Values

// Set a value (update existing or append)

spaceship_toml.set(doc, ["key"], spaceship_toml.string("value"), None)



// Set at a specific line number

spaceship_toml.set(doc, ["key"], spaceship_toml.string("value"), Some(10))



// Delete a key

spaceship_toml.delete(doc, ["key"])



// Rename a key

spaceship_toml.rename_key(doc, ["old_name"], ["new_name"])

Table Operations

// Get all entries in a table

spaceship_toml.get_table(doc, ["server"])

// -> Ok([#("server.host", TomlString("localhost")), #("server.port", TomlInteger(8080))])



// Add a new table header

spaceship_toml.add_table(doc, ["database"], None)

Value Constructors

spaceship_toml.string("hello")       // -> TomlString("hello")

spaceship_toml.integer(42)           // -> TomlInteger(42)

spaceship_toml.float(3.14)           // -> TomlFloat(3.14)

spaceship_toml.boolean(True)         // -> TomlBoolean(True)

spaceship_toml.array([a, b, c])      // -> TomlArray([...])

spaceship_toml.table(entries)        // -> TomlTable(...)

spaceship_toml.inline_table(entries) // -> TomlInlineTable(...)

spaceship_toml.date(2025, 1, 15)     // -> TomlDate(...)

spaceship_toml.time(14, 30, 0)       // -> TomlTime(...)

spaceship_toml.datetime(2025, 1, 15, 14, 30, 0) // -> TomlDateTime(...)

Supported TOML Features

Types

pub type Document   // The parsed TOML document

pub type TomlValue  // All TOML value types

pub type GetResult  // Result of get(): key, value, and line_number

pub type ParseError // Parse error with line information

pub type EditError  // Edit error (key not found, etc.)

Development

gleam run   # Run the project

gleam test  # Run the tests

gleam format  # Format the code

License

Apache-2.0