Skip to main content

Module tabular

standout_render

Module tabular 

Source
Expand description

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:

ApproachUse When
Template filters (col, pad_left)Simple tables, column widths known at template time
TabularFormatterDynamic 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 %}
FilterUsage
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_render::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

§Sub-Columns

Columns can contain inner sub-columns for per-row layout within a parent column. Exactly one sub-column is Width::Fill (the grower); the rest are Fixed or Bounded. Widths are resolved per-row from actual content.

use standout_render::tabular::{
    TabularSpec, Col, SubCol, SubColumns, TabularFormatter, CellValue,
};

let spec = TabularSpec::builder()
    .column(Col::fixed(4))
    .column(Col::fill().sub_columns(
        SubColumns::new(
            vec![SubCol::fill(), SubCol::bounded(0, 30).right()],
            " ",
        ).unwrap(),
    ))
    .separator("  ")
    .build();

let formatter = TabularFormatter::new(&spec, 60);
let row = formatter.format_row_cells(&[
    CellValue::Single("1."),
    CellValue::Sub(vec!["Title", "[tag]"]),
]);

§Utility Functions

use standout_render::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

§Template Filters

FilterUsage
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.
SubCol
Shorthand constructors for creating sub-columns.
SubColumn
A sub-column within a parent column for per-row width distribution.
SubColumns
Configuration for sub-columns within a parent column.
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.
CellValue
A cell value that may be a single string or a list of sub-values.
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.
visible_width
Returns the visible display width of a string, stripping both BBCode tags and ANSI escape codes before measurement.
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.