Crate toml_spanner 

A high-performance TOML parser that preserves span information for every parsed value.

Strings are zero-copy where possible, borrowing directly from the input; escape sequences are allocated into a caller-supplied Arena.

Quick start

Call parse with a TOML string and an Arena to get a Table. Then extract values with Table::required and Table::optional, or index into nested structures with bracket operators that return MaybeItem (never panic on missing keys).

Examples

use toml_spanner::{Arena, Deserialize, Error, Item};

#[derive(Debug)]
struct Things {
    name: String,
    value: u32,
    color: Option<String>,
}

impl<'de> Deserialize<'de> for Things {
    fn deserialize(value: &mut Item<'de>) -> Result<Self, Error> {
        let table = value.expect_table()?;
        Ok(Things {
            name: table.required("name")?,
            value: table.required("value")?,
            color: table.optional("color")?,
        })
    }
}

let content = r#"
dev-mode = true

[[things]]
name = "hammer"
value = 43

[[things]]
name = "drill"
value = 300
color = "green"
"#;

let arena = Arena::new();
let mut table = toml_spanner::parse(content, &arena)?;

// Null-coalescing index operators — missing keys return a None-like
// MaybeItem instead of panicking.
assert_eq!(table["things"][0]["color"].as_str(), None);
assert_eq!(table["things"][1]["color"].as_str(), Some("green"));

// Deserialize typed values out of the table.
let things: Vec<Things> = table.required("things")?;
let dev_mode: bool = table.optional("dev-mode")?.unwrap_or(false);
// Error if unconsumed fields remain.
table.expect_empty()?;

assert_eq!(things.len(), 2);
assert_eq!(things[0].name, "hammer");
assert!(dev_mode);

Structs

Arena

A bump allocator used by the parser to store escaped strings.

Array

A growable array of TOML Items.

Error

An error from parsing or deserializing TOML.

Item

A parsed TOML value with span information.

Key

A TOML table key with its source span.

MaybeItem

A nullable reference to a parsed TOML value.

Span

A byte-offset range within a TOML document.

Spanned

Wraps a value T with its source Span.

Table

A TOML table with span information.

Enums

ErrorKind

The specific kind of parse or deserialization error.

Value

Borrowed view into an Item for pattern matching.

ValueMut

Mutable view into an Item for pattern matching.

Traits

Deserialize

Converts a parsed TOML Item into a typed Rust value.

DeserializeOwned

Object-safe version of Deserialize for types that do not borrow from the input.

Functions

parse

Parses a TOML string into a Table.