Struct TableHelper 

pub struct TableHelper<'ctx, 'table, 'de> {
    pub ctx: &'ctx mut Context<'de>,
    pub table: &'table Table<'de>,
    /* private fields */
}

Available on crate feature from-toml only.

Guides extraction from a Table by tracking which fields have been consumed.

Create via Document::table_helper for the root table, or Item::table_helper / TableHelper::new for nested tables. Extract fields with required and optional, then call require_empty to reject unknown keys.

Errors accumulate in the shared Context rather than failing on the first problem, so a single pass can report multiple issues.

Examples

use toml_spanner::{Arena, FromToml, Item, Context, Failed, TableHelper};

struct Config {
    name: String,
    port: u16,
    debug: bool,
}

impl<'de> FromToml<'de> for Config {
    fn from_toml(ctx: &mut Context<'de>, item: &Item<'de>) -> Result<Self, Failed> {
        let mut th = item.table_helper(ctx)?;
        let name = th.required("name")?;
        let port = th.required("port")?;
        let debug = th.optional("debug").unwrap_or(false);
        th.require_empty()?;
        Ok(Config { name, port, debug })
    }
}

Fields

ctx: &'ctx mut Context<'de>

table: &'table Table<'de>

Implementations

impl<'ctx, 't, 'de> TableHelper<'ctx, 't, 'de>

pub fn new(ctx: &'ctx mut Context<'de>, table: &'t Table<'de>) -> Self

Creates a new helper for the given table.

Prefer Item::table_helper inside FromToml implementations, or Document::table_helper for the root table.

pub fn get_entry(&self, key: &str) -> Option<&'t (Key<'de>, Item<'de>)>

Looks up a key-value entry without marking it as consumed.

Useful for peeking at a field before deciding how to convert it. The entry will still be flagged as unexpected by require_empty unless later consumed by required or optional.

pub fn required_mapped<T>( &mut self, name: &'static str, func: fn(&Item<'de>) -> Result<T, Error>, ) -> Result<T, Failed>

Extracts a required field and transforms it with func.

Looks up name, marks it as consumed, and passes the Item to func. Useful for parsing string values via Item::parse or applying custom validation without implementing FromToml.

Errors

Returns Failed if the key is absent or if func returns an error. In both cases the error is pushed onto the shared Context.

pub fn optional_mapped<T>( &mut self, name: &'static str, func: fn(&Item<'de>) -> Result<T, Error>, ) -> Option<T>

Extracts an optional field and transforms it with func.

Returns None if the key is missing (no error recorded) or if func returns an error (the error is pushed onto the Context). The field is marked as consumed so require_empty will not flag it as unexpected.

pub fn required_item( &mut self, name: &'static str, ) -> Result<&'t Item<'de>, Failed>

Returns the raw Item for a required field.

Like required but skips conversion, giving direct access to the parsed value. The field is marked as consumed.

Errors

Returns Failed and records a MissingField error if the key is absent.

pub fn optional_item(&mut self, name: &'static str) -> Option<&'t Item<'de>>

Returns the raw Item for an optional field.

Like optional but skips conversion, giving direct access to the parsed value. Returns None when the key is missing (no error recorded). The field is marked as consumed.

pub fn required_entry( &mut self, name: &'static str, ) -> Result<&'t (Key<'de>, Item<'de>), Failed>

Returns the (Key, Item) pair for a required field.

Useful when the key’s Span is needed in addition to the value. The field is marked as consumed.

Errors

Returns Failed and records a MissingField error if the key is absent.

pub fn optional_entry(&mut self, key: &str) -> Option<&'t (Key<'de>, Item<'de>)>

Returns the (Key, Item) pair for an optional field.

Returns None when the key is missing (no error recorded). Useful when the key’s Span is needed in addition to the value. The field is marked as consumed.

pub fn required<T: FromToml<'de>>( &mut self, name: &'static str, ) -> Result<T, Failed>

Extracts and converts a required field via FromToml.

The field is marked as consumed so require_empty will not flag it as unexpected.

Errors

Returns Failed if the key is absent or if conversion fails. In both cases the error is pushed onto the shared Context.

pub fn optional<T: FromToml<'de>>(&mut self, name: &str) -> Option<T>

Extracts and converts an optional field via FromToml, returning None if the key is missing or conversion fails (recording the error in the Context).

The field is marked as consumed so require_empty will not flag it as unexpected.

pub fn remaining_count(&self) -> usize

Returns the number of unused entries remaining in the table.

pub fn into_remaining(self) -> RemainingEntriesIter<'t, 'de>

Iterate over unused &(Key<'de>, Item<'de>) entries in the table.

pub fn require_empty(self) -> Result<(), Failed>

Finishes field extraction, recording an error for any fields not consumed by required or optional.

Call as the last step in a FromToml implementation to reject unknown keys.

Errors

Returns Failed and pushes an ErrorKind::UnexpectedKey error if unconsumed fields remain.