HewStandard Library

Module std::encoding::toml

TOML parsing and generation.

Parse TOML documents into values, build new tables programmatically, and serialize back to TOML text.

Examples

import std::encoding::toml;

fn main() {
    let doc = toml.parse("[package]\nname = \"hew\"");
    let pkg = doc.get_field("package");
    let name = pkg.get_field("name");
    println(name.get_string());  // "hew"
    name.free();
    pkg.free();
    doc.free();
}

Contents

Functions

Function parse

pub fn parse(s: string) -> Value

Parse a TOML string into a Value.

Preserves the legacy behavior: invalid TOML returns an invalid handle (type_of() == -1). Use try_parse for a structured error result.

Function try_parse

pub fn try_parse(s: string) -> Result<Value, ParseError>

Parse a TOML string into a Value.

Returns Err(ParseError::Invalid(message)) with the native parser message when parsing fails. Match on ParseError::Invalid(message) to recover the original parser message.

Function table

pub fn table() -> Value

Create a new empty TOML table.

Function array

pub fn array() -> Value

Create a new empty TOML array.

Function from_int

pub fn from_int(val: i64) -> Value

Create a TOML Value from an integer.

Function from_float

pub fn from_float(val: f64) -> Value

Create a TOML Value from a float.

Function from_string

pub fn from_string(val: string) -> Value

Create a TOML Value from a string.

Function from_bool

pub fn from_bool(val: bool) -> Value

Create a TOML Value from a boolean.

Types

Enum ParseError

Structured error type for TOML parsing failures.

Use Result<Value, ParseError> with try_parse for structured error handling. Import std::encoding::toml when matching on the returned error value so you can use the existing unqualified ParseError::Invalid(message) constructor/pattern style.

Variants

Invalid(string)

The input was not valid TOML. Carries the native parser message.

Struct Value

An opaque TOML value.

Represents any TOML type: string, integer, float, boolean, array, table, or datetime. The canonical shared wire tag prefix reserves 0 for null, even though TOML itself has no null value. Must be freed with free() when no longer needed.

Traits

Trait ValueMethods

Methods available on a TOML Value.

Extends the shared opaque-handle contract from std::encoding::wire::value_trait. Canonical methods are redeclared here with TOML-specific docstrings for documentation purposes.

Methods

fn type_of(self: Self) -> i32

Return the type tag (0=null reserved, 1=bool, 2=i64, 3=float, 4=string, 5=array, 6=table, 7=datetime).

fn get_string(self: Self) -> string

Extract the string value.

fn get_int(self: Self) -> i64

Extract the integer value.

fn get_float(self: Self) -> f64

Extract the floating-point value.

fn get_bool(self: Self) -> i32

Extract the boolean value (0 or 1).

fn get_field(self: Self, key: string) -> Value

Look up a field by key in a TOML table.

fn array_len(self: Self) -> i64

Return the number of elements in a TOML array.

fn array_get(self: Self, index: i64) -> Value

Return the element at the given index in a TOML array.

fn stringify(self: Self) -> string

Serialize the value back to a TOML string.

fn free(self: Self)

Release the value resources.

fn with_string(self: Self, key: string, val: string) -> Value

Set a string field on a table. Returns the table for chaining.

fn with_int(self: Self, key: string, val: i64) -> Value

Set an integer field. Returns the table for chaining.

fn with_float(self: Self, key: string, val: f64) -> Value

Set a float field. Returns the table for chaining.

fn with_bool(self: Self, key: string, val: bool) -> Value

Set a boolean field. Returns the table for chaining.

fn with(self: Self, key: string, child: Value) -> Value

Set a Value child on a table. The child is consumed. Returns the table.

fn push(self: Self, child: Value) -> Value

Push a Value onto an array. The child is consumed. Returns the array.

fn push_int(self: Self, val: i64) -> Value

Push an integer onto an array. Returns the array.

fn push_string(self: Self, val: string) -> Value

Push a string onto an array. Returns the array.

fn push_float(self: Self, val: f64) -> Value

Push a float onto an array. Returns the array.

fn push_bool(self: Self, val: bool) -> Value

Push a boolean onto an array. Returns the array.