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 = match toml.parse("[package]\nname = \"hew\"") {
        .Ok(value) => value,
        .Err(_) => panic("invalid TOML"),
    };
    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) -> 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 stringify

pub fn stringify(val: Value) -> Result<string, string>

Serialize val back to a TOML string without panicking.

A TOML document root must be a table. An integer, string, or array root serializes to no text at all, which is exactly what an empty table serializes to, so the two are only distinguishable through this result.

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.

Function encode

pub fn encode(value: T) -> string

Encode any data value as a TOML document. Records encode as objects keyed by field name in declaration order.

Function decode

pub fn decode(text: string) -> Result<T, wire.DecodeError>

Decode a TOML document as T. A failure names the path of the value that did not fit, for example Type: .tags[1]: expected string, found integer.

Types

Enum ParseError

Structured error type for TOML parsing failures.

Use Result<Value, ParseError> with 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. TOML has no null value. Values close automatically at the end of their ownership scope; close() performs the same release explicitly.

Traits

Trait ValueMethods

Methods available on a TOML Value. This module retains an independent resource carrier.

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.

Panics if the value cannot be a TOML document root. Only a table can: an integer, string, or array root serializes to no text at all, which is exactly what an empty table serializes to. Use stringify() when that failure should be returned as an error.

fn free(self: Self)

Consuming compatibility alias for the inherent close().

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

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

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

Set an integer field. Returns the table for chaining.

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

Set a float field. Returns the table for chaining.

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

Set a boolean field. Returns the table for chaining.

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

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

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

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

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

Push an integer onto an array. Returns the array.

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

Push a string onto an array. Returns the array.

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

Push a float onto an array. Returns the array.

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

Push a boolean onto an array. Returns the array.