spaceship_toml - v0.1.1

spaceship_toml

Package Version Hex 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

✨ Search Document