Struct TabularFormatter 

pub struct TabularFormatter { /* private fields */ }

Formats table rows according to a specification.

The formatter holds resolved column widths and produces formatted rows. It supports row-by-row formatting for interleaved output patterns.

Example

use standout_render::tabular::{FlatDataSpec, Column, Width, TabularFormatter};

let spec = FlatDataSpec::builder()
    .column(Column::new(Width::Fixed(8)))
    .column(Column::new(Width::Fill))
    .column(Column::new(Width::Fixed(10)))
    .separator("  ")
    .build();

let formatter = TabularFormatter::new(&spec, 80);

// Format rows one at a time (enables interleaved output)
let row1 = formatter.format_row(&["abc123", "path/to/file.rs", "pending"]);
println!("{}", row1);
println!("  └─ Note: needs review");  // Interleaved content
let row2 = formatter.format_row(&["def456", "src/lib.rs", "done"]);
println!("{}", row2);

Implementations

impl TabularFormatter

pub fn new(spec: &FlatDataSpec, total_width: usize) -> Self

Create a new formatter by resolving widths from the spec.

Arguments

• spec - Table specification
• total_width - Total available width including decorations

pub fn from_resolved(spec: &FlatDataSpec, resolved: ResolvedWidths) -> Self

Create a formatter with pre-resolved widths.

Use this when you’ve already calculated widths (e.g., from data).

pub fn from_resolved_with_width( spec: &FlatDataSpec, resolved: ResolvedWidths, total_width: usize, ) -> Self

Create a formatter with pre-resolved widths and explicit total width.

pub fn with_widths(columns: Vec<Column>, widths: Vec<usize>) -> Self

Create a formatter from explicit widths and columns.

This is useful for direct construction without a full FlatDataSpec.

pub fn from_type<T: Tabular>(total_width: usize) -> Self

Create a formatter from a type that implements Tabular.

This constructor uses the TabularSpec generated by the #[derive(Tabular)] macro to configure the formatter.

Example

use standout_render::tabular::{Tabular, TabularFormatter};
use serde::Serialize;

#[derive(Serialize, Tabular)]
struct Task {
    #[col(width = 8)]
    id: String,
    #[col(width = "fill")]
    title: String,
}

let formatter = TabularFormatter::from_type::<Task>(80);

pub fn total_width(self, width: usize) -> Self

Set the total target width (for anchor gap calculations).

pub fn separator(self, sep: impl Into<String>) -> Self

Set the column separator.

pub fn prefix(self, prefix: impl Into<String>) -> Self

Set the row prefix.

pub fn suffix(self, suffix: impl Into<String>) -> Self

Set the row suffix.

pub fn format_row<S: AsRef<str>>(&self, values: &[S]) -> String

Format a single row of values.

Values are truncated/padded according to the column specifications. Missing values use the column’s null representation.

Arguments

• values - Slice of cell values (strings)

Example

use standout_render::tabular::{FlatDataSpec, Column, Width, TabularFormatter};

let spec = FlatDataSpec::builder()
    .column(Column::new(Width::Fixed(10)))
    .column(Column::new(Width::Fixed(8)))
    .separator(" | ")
    .build();

let formatter = TabularFormatter::new(&spec, 80);
let output = formatter.format_row(&["Hello", "World"]);
assert_eq!(output, "Hello      | World   ");

pub fn format_rows<S: AsRef<str>>(&self, rows: &[Vec<S>]) -> Vec<String>

Format multiple rows.

Returns a vector of formatted row strings.

pub fn format_row_lines<S: AsRef<str>>(&self, values: &[S]) -> Vec<String>

Format a row that may produce multiple output lines (due to wrapping).

If any cell wraps to multiple lines, the output contains multiple lines with proper vertical alignment. Cells are top-aligned.

Example

use standout_render::tabular::{FlatDataSpec, Column, Width, Overflow, TabularFormatter};

let spec = FlatDataSpec::builder()
    .column(Column::new(Width::Fixed(10)).wrap())
    .column(Column::new(Width::Fixed(8)))
    .separator("  ")
    .build();

let formatter = TabularFormatter::new(&spec, 80);
let lines = formatter.format_row_lines(&["This is a long text", "Short"]);
// Returns multiple lines if the first column wraps

pub fn column_width(&self, index: usize) -> Option<usize>

Get the resolved width for a column by index.

pub fn widths(&self) -> &[usize]

Get all resolved column widths.

pub fn num_columns(&self) -> usize

Get the number of columns.

pub fn extract_headers(&self) -> Vec<String>

Extract headers from column specifications.

For each column, uses (in order of preference):

1. The header field if set
2. The key field if set
3. The name field if set
4. Empty string

This is useful for Table::header_from_columns().

pub fn row_from<T: Serialize>(&self, value: &T) -> String

Format a row by extracting values from a serializable struct.

This method extracts field values from the struct based on each column’s key or name field. Supports dot notation for nested field access (e.g., “user.email”).

Arguments

• value - Any serializable value to extract fields from

Example

use standout_render::tabular::{FlatDataSpec, Column, Width, TabularFormatter};
use serde::Serialize;

#[derive(Serialize)]
struct Record {
    name: String,
    status: String,
    count: u32,
}

let spec = FlatDataSpec::builder()
    .column(Column::new(Width::Fixed(20)).key("name"))
    .column(Column::new(Width::Fixed(10)).key("status"))
    .column(Column::new(Width::Fixed(5)).key("count"))
    .separator("  ")
    .build();

let formatter = TabularFormatter::new(&spec, 80);
let record = Record {
    name: "example".to_string(),
    status: "active".to_string(),
    count: 42,
};

let row = formatter.row_from(&record);
assert!(row.contains("example"));
assert!(row.contains("active"));
assert!(row.contains("42"));

pub fn row_lines_from<T: Serialize>(&self, value: &T) -> Vec<String>

Format a row with potential multi-line output from a serializable struct.

Same as row_from but handles word-wrap columns that may produce multiple output lines.

pub fn row_from_trait<T: TabularRow>(&self, value: &T) -> String

Format a row using the TabularRow trait.

This method uses the optimized to_row() implementation generated by #[derive(TabularRow)], avoiding JSON serialization overhead.

Example

use standout_render::tabular::{TabularRow, TabularFormatter};

#[derive(TabularRow)]
struct Task {
    id: String,
    title: String,
}

let task = Task {
    id: "TSK-001".to_string(),
    title: "Implement feature".to_string(),
};

let formatter = TabularFormatter::from_type::<Task>(80);
let row = formatter.row_from_trait(&task);

pub fn row_lines_from_trait<T: TabularRow>(&self, value: &T) -> Vec<String>

Format a row with potential multi-line output using the TabularRow trait.

Same as row_from_trait but handles word-wrap columns that may produce multiple output lines.

Trait Implementations

impl Clone for TabularFormatter

fn clone(&self) -> TabularFormatter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TabularFormatter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Object for TabularFormatter

fn get_value(self: &Arc<Self>, key: &Value) -> Option<Value>

Given a key, looks up the associated value.

fn enumerate(self: &Arc<Self>) -> Enumerator

Enumerates the object.

fn call_method( self: &Arc<Self>, _state: &State<'_, '_>, name: &str, args: &[Value], ) -> Result<Value, Error>

The engine calls this to invoke a method on the object.

fn repr(self: &Arc<Self>) -> ObjectRepr

Indicates the natural representation of an object.

fn enumerator_len(self: &Arc<Self>) -> Option<usize>

Returns the length of the enumerator.

fn is_true(self: &Arc<Self>) -> bool

Returns true if this object is considered true for if conditions.

fn call( self: &Arc<Self>, state: &State<'_, '_>, args: &[Value], ) -> Result<Value, Error>

The engine calls this to invoke the object itself.

fn custom_cmp(self: &Arc<Self>, other: &DynObject) -> Option<Ordering>

Custom comparison of this object against another object of the same type.

fn render(self: &Arc<Self>, f: &mut Formatter<'_>) -> Result<(), Error>

where Self: Sized + 'static,

Formats the object for stringification.