Struct Formatting 

pub struct Formatting<'a> { /* private fields */ }

Available on crate feature to-toml only.

Controls how TOML output is formatted when serializing.

Formatting::preserved_from preserves formatting from a previously parsed document, use Formatting::default() for standard formatting.

Examples

use toml_spanner::{Arena, Formatting};
use std::collections::BTreeMap;

let arena = Arena::new();
let source = "key = \"value\"\n";
let doc = toml_spanner::parse(source, &arena).unwrap();

let mut map = BTreeMap::new();
map.insert("key", "updated");

let output = Formatting::preserved_from(&doc).format(&map).unwrap();
assert!(output.contains("key = \"updated\""));

Implementations

impl<'a> Formatting<'a>

pub fn preserved_from(doc: &'a Document<'a>) -> Self

Creates a formatting template from a parsed document.

Indent style is auto-detected from the source text, defaulting to 4 spaces when no indentation is found.

pub fn with_indentation(self, indent: Indent) -> Self

Sets the indentation style for expanded inline arrays. Overrides auto-detection.

pub fn format(&self, value: &dyn ToToml) -> Result<String, ToTomlError>

Serializes a ToToml value into a TOML string.

The value must serialize to a table at the top level.

Errors

Returns ToTomlError if serialization fails or the top-level value is not a table.

pub fn format_table_to_bytes(&self, table: Table<'_>, arena: &Arena) -> Vec<u8>

Formats a Table directly into bytes.

Low-level primitive that normalizes and (when a source document is set) reprojects the table before emission. The provided arena is used for temporary allocations during emission.

pub fn with_span_projection_identity(self) -> Self

Matches dest items to the formatting reference by span identity.

By default, Formatting pairs dest items with reference items by content equality. Content matching cannot distinguish items carrying identical values, so mutations that swap, remove, or reorder such items can silently reattach comments and numeric formatting to the wrong items.

With span identity enabled, each candidate pair’s spans are compared. When the spans match, the reference item’s formatting is projected onto the dest item. When they differ, the dest item is treated as if Item::set_ignore_source_formatting_recursively had been called on it: its subtree is emitted from scratch rather than pulling bytes from the reference text.

Intended for the lower-level Table mutation APIs where the dest tree was produced by cloning a parsed document. Not suitable for round-trips through FromToml and ToToml, which do not preserve spans.

The caller must ensure that every dest item carrying a non-empty span points into the reference document. Items replaced with fresh values, or otherwise stripped of their original spans, are not projected even when their content matches the reference.

Examples

use toml_spanner::{Arena, Formatting};

let arena = Arena::new();
let source = "\
a = 1 # first
b = 1 # second
";
let doc = toml_spanner::parse(source, &arena).unwrap();

// Swap the two entries while keeping each item's original span.
let mut table = doc.table().clone_in(&arena);
let entries = table.entries_mut();
let (left, right) = entries.split_at_mut(1);
std::mem::swap(&mut left[0].1, &mut right[0].1);

// Span identity catches the swap: content matching would leave
// each comment stuck to its original key, misattributing them.
let bytes = Formatting::preserved_from(&doc)
    .with_span_projection_identity()
    .format_table_to_bytes(table, &arena);
let output = String::from_utf8(bytes).unwrap();
assert!(!output.contains("# first"));
assert!(!output.contains("# second"));

Trait Implementations

impl<'a> Default for Formatting<'a>

fn default() -> Formatting<'a>

Returns the “default value” for a type.