Module tabular 

Unicode-aware column formatting for terminal tables.

This module provides utilities for aligned, column-based terminal output that correctly handles Unicode (CJK characters count as 2 columns) and preserves ANSI escape codes without counting them toward width.

TabularFormatter vs Template Filters

Two approaches, choose based on your needs:

Approach	Use When
Template filters (col, pad_left)	Simple tables, column widths known at template time
TabularFormatter	Dynamic widths, CSV export, complex specs with data extraction

Template filters are simpler for most cases. Use TabularFormatter when you need width resolution from actual data or structured CSV export.

Template Filters (Declarative)

Filters are available in all Standout templates:

{% for entry in entries %}
{{ entry.hash | col(7) }}  {{ entry.author | col(12) }}  {{ entry.message | col(50) }}
{% endfor %}

Filter	Usage
col	{{ value | col(10) }} or {{ value | col(10, align='right', truncate='middle') }}
pad_left	{{ value | pad_left(10) }}
pad_right	{{ value | pad_right(10) }}
pad_center	{{ value | pad_center(10) }}
truncate_at	{{ value | truncate_at(10, 'middle', '...') }}
display_width	{{ value | display_width }}

TabularFormatter (Imperative)

For programmatic control and CSV export:

use standout::tabular::{FlatDataSpec, Column, Width, Align, TabularFormatter};

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

let formatter = TabularFormatter::new(&spec, 80);
let row = formatter.format_row(&["abc123", "path/to/file.rs", "pending"]);

Width Strategies

• [Width::Fixed(n)] - Exactly n display columns
• [Width::Bounded { min, max }] - Auto-size within bounds based on content
• Width::Fill - Expand to fill remaining space

Truncation Modes

• TruncateAt::End - Keep start: “Hello W…”
• TruncateAt::Start - Keep end: “…o World”
• TruncateAt::Middle - Keep both: “Hel…orld” (useful for paths)

Utility Functions

use standout::tabular::{display_width, truncate_end, pad_right, wrap};

let text = "Hello World";
let truncated = truncate_end(text, 8, "…");  // "Hello W…"
let padded = pad_right(&truncated, 10);      // "Hello W…  "
assert_eq!(display_width(&padded), 10);

// Word-wrap long text
let lines = wrap("hello world foo bar", 11);
assert_eq!(lines, vec!["hello world", "foo bar"]);

Column Width Strategies

• [Width::Fixed(n)] - Exactly n display columns
• [Width::Bounded { min, max }] - Auto-calculate from content within bounds
• Width::Fill - Expand to fill remaining space (one per table)

Truncation Modes

• TruncateAt::End - Keep start, truncate end: “Hello W…”
• TruncateAt::Start - Keep end, truncate start: “…o World”
• TruncateAt::Middle - Keep both ends: “Hel…orld”

Template Filters

Filter	Usage
col	{{ value | col(10) }} or {{ value | col(10, align='right', truncate='middle') }}
pad_left	{{ value | pad_left(10) }}
pad_right	{{ value | pad_right(10) }}
pad_center	{{ value | pad_center(10) }}
truncate_at	{{ value | truncate_at(10, 'middle', '...') }}
display_width	{{ value | display_width }}

Modules

filters

MiniJinja filters and functions for tabular output.

Structs

Col

Shorthand constructors for creating columns.

Column

Configuration for a single column in a table.

ColumnBuilder

Builder for constructing Column instances.

Decorations

Decorations for table rows (separators, prefixes, suffixes).

FlatDataSpec

Complete specification for a flat data layout (Table or CSV).

FlatDataSpecBuilder

Builder for constructing FlatDataSpec instances.

ResolvedWidths

Resolved widths for all columns in a table.

Table

A decorated table with borders, headers, and separators.

TabularFormatter

Formats table rows according to a specification.

Enums

Align

Text alignment within a column.

Anchor

Column position anchor on the row.

BorderStyle

Border style for table decoration.

CellOutput

Result of formatting a cell, which may be single or multi-line.

Overflow

How a column handles content that exceeds its width.

TruncateAt

Position where truncation occurs when content exceeds max width.

Width

Specifies how a column determines its width.

Traits

Tabular

Trait for types that can generate a TabularSpec.

TabularFieldDisplay

Trait for types that implement Display.

TabularFieldOption

Trait for Option types.

TabularRow

Trait for types that can be converted to a row of strings.

Functions

display_width

Returns the display width of a string, ignoring ANSI escape codes.

pad_center

Pads a string on both sides (centers) to reach the target width.

pad_left

Pads a string on the left (right-aligns) to reach the target width.

pad_right

Pads a string on the right (left-aligns) to reach the target width.

truncate_end

Truncates a string from the end to fit within a maximum display width.

truncate_middle

Truncates a string from the middle to fit within a maximum display width.

truncate_start

Truncates a string from the start to fit within a maximum display width.

wrap

Wraps text to fit within a maximum display width, breaking at word boundaries.

wrap_indent

Wraps text with a continuation indent on subsequent lines.

Type Aliases

TabularSpec

Type alias: TabularSpec is the preferred name for FlatDataSpec.

TabularSpecBuilder

Type alias for the builder.