Crate gilt

Expand description

§gilt — Beautiful Terminal Formatting for Rust

Beautiful terminal output for Rust: styles, tables, trees, syntax highlighting, progress bars, and more, all rendered as ANSI escape sequences.

§Quick Start

Add gilt to your Cargo.toml:

[dependencies]
gilt = "1.10"

Then use the prelude for convenient access to common types:

use gilt::prelude::*;

let mut console = Console::builder().width(80).build();
console.begin_capture();
console.print_text("Hello, [bold magenta]gilt[/bold magenta]!");
let output = console.end_capture();
assert!(output.contains("Hello"));

For quick one-off output, use the global console functions:

gilt::print_text("Hello, [bold]world[/bold]!");
gilt::inspect(&vec![1, 2, 3]);

§The Console

Console is the central type in gilt. It manages terminal capabilities, drives the rendering pipeline, and handles output buffering, capture, and export.

§Creating a Console

use gilt::console::Console;

// Defaults: auto-detect terminal size, TrueColor, markup on
let console = Console::new();

// Builder pattern for full control
let console = Console::builder()
    .width(120)
    .color_system("truecolor")
    .record(true)       // enable export_html / export_svg
    .no_color(false)
    .build();

§Printing

let mut console = Console::builder().width(80).build();

// Print with rich markup
console.print_text("[bold red]Error:[/bold red] something went wrong");

// Print any Renderable (Panel, Table, Tree, ...)
let panel = Panel::new(Text::new("inside a box", Style::null()));
console.print(&panel);

§Capture and Export

Capture lets you collect console output as a plain string instead of writing to the terminal:

let mut console = Console::builder().width(60).build();
console.begin_capture();
console.print_text("[bold]Captured![/bold]");
let plain = console.end_capture();
assert!(plain.contains("Captured!"));

For rich export, enable record(true) on the builder, then call export_text, export_html, or export_svg:

let mut console = Console::builder().width(60).force_terminal(true).record(true).build();
console.print_text("[green]Recorded[/green]");
let html = console.export_html(None, true, true);
assert!(html.contains("<span"));

§Text and Styling

§Style

Style represents a combination of foreground/background color, text attributes (bold, italic, underline, …), extended underline styles, and hyperlinks.

use gilt::style::Style;

// Parse from a human-readable definition
let style = Style::parse("bold red on white");
let subtle = Style::parse("dim italic #808080");

// Combine styles with the + operator (right side wins on conflicts)
let combined = style + subtle;

§Markup

gilt supports inline markup tags in strings, similar to BBCode:

let mut c = Console::builder().width(60).build();
c.begin_capture();
c.print_text("[bold]Bold[/bold], [italic green]green italic[/italic green]");
let out = c.end_capture();
assert!(out.contains("Bold"));

Closing tags match their opening tag, or use [/] to close the most recent: "[bold red]error[/] normal text".

§Text

Text is the fundamental rich-text type, storing a plain string plus styled spans.

use gilt::text::Text;
use gilt::style::Style;

// Plain text
let text = Text::new("Hello, world!", Style::null());

// Styled text (entire string has one style)
let bold = Text::styled("Important", "bold");

// From markup (parses [tags])
let rich = Text::from_markup("[red]Error:[/red] file not found").unwrap();
assert!(rich.plain().contains("Error:"));

§Stylize Trait

The Stylize trait provides a fluent, Rust-idiomatic API for building styled text directly from string literals:

use gilt::styled_str::Stylize;

let styled = "Hello".bold().red().on_blue();
assert_eq!(styled.text, "Hello");

StyledStr implements Renderable, so it can be passed directly to Console::print.

§Widgets

§Panel

Panel wraps content in a bordered box with optional title and subtitle.

use gilt::prelude::*;
use gilt::box_chars::DOUBLE;

// Expanding panel (fills available width)
let panel = Panel::new(Text::new("content", Style::null()))
    .with_title("My Panel")
    .with_box_chars(&DOUBLE)
    .with_border_style(Style::parse("blue"));

// Fit-to-content panel
let compact = Panel::fit(Text::new("snug", Style::null()));

§Table

Table renders data in Unicode box-drawing tables with column alignment, row striping, headers, footers, and style control.

use gilt::table::Table;

let mut table = Table::new(&["Name", "Age", "City"]);
table.add_row(&["Alice", "30", "Paris"]);
table.add_row(&["Bob", "25", "London"]);

let output = format!("{}", table);
assert!(output.contains("Alice"));

Builder methods customise every aspect of the table:

use gilt::table::Table;
use gilt::box_chars::ROUNDED;

let table = Table::new(&["Key", "Value"])
    .with_title("Config")
    .with_box_chars(Some(&ROUNDED))
    .with_border_style("cyan")
    .with_row_styles(vec!["".into(), "dim".into()])
    .with_expand(true);

Use Table::grid for borderless side-by-side layout:

use gilt::table::Table;

let mut grid = Table::grid(&["A", "B"]);
grid.add_row(&["left", "right"]);

§Tree

Tree renders hierarchical data with Unicode guide lines.

use gilt::prelude::*;

let mut tree = Tree::new(Text::new("root", Style::null()));
let child = tree.add(Text::new("child 1", Style::null()));
child.add(Text::new("grandchild", Style::null()));
tree.add(Text::new("child 2", Style::null()));

Guide style affects line weight: default is thin lines, bold gives thick lines, and underline2 selects double lines.

§Rule

Rule draws a horizontal line, optionally with a centered title.

use gilt::rule::Rule;

let rule = Rule::new();                           // plain line
let titled = Rule::with_title("Section Header");  // line with title

§Columns

Columns lays out items in an auto-fitting multi-column grid.

use gilt::columns::Columns;

let mut cols = Columns::new();
cols.add_renderable("one");
cols.add_renderable("two");
cols.add_renderable("three");

§Layout

Layout splits the terminal into rows and columns with flexible or fixed sizing, like a split-pane window manager.

use gilt::layout::Layout;

let mut root = Layout::new(None, Some("root".into()), None, None, Some(1), None);
root.split_row(vec![
    Layout::new(Some("Left pane".into()), Some("left".into()), None, None, Some(1), None),
    Layout::new(Some("Right pane".into()), Some("right".into()), None, None, Some(2), None),
]);

§Terminal Features

§Syntax Highlighting

Syntax highlights source code using syntect with 150+ language grammars. (Requires the syntax feature, enabled by default.)

use gilt::syntax::Syntax;

let code = r#"fn main() { println!("hello"); }"#;
let syntax = Syntax::new(code, "rust")
    .with_line_numbers(true)
    .with_theme("base16-ocean.dark");

§Markdown

Markdown renders Markdown to the terminal with headings, lists, code blocks, and emphasis. (Requires the markdown feature, enabled by default.)

use gilt::markdown::Markdown;

let md = Markdown::new("# Hello\n\nThis is **bold** and *italic*.");

§JSON Pretty-Printing

Json parses and syntax-highlights JSON data. (Requires the json feature, enabled by default.)

use gilt::json::{Json, JsonOptions};

let json = Json::new(r#"{"name": "gilt", "version": "0.6.0"}"#, JsonOptions::default()).unwrap();

The global convenience function makes it even simpler:

gilt::print_json(r#"{"key": "value"}"#);

§Progress Bars

Progress provides a multi-task progress display with customisable columns (text, bar, spinner, time, speed) and live terminal updates.

use gilt::progress::Progress;

let mut progress = Progress::new(vec![]);
let task = progress.add_task("Downloading", Some(100.0));
progress.start();
for _ in 0..100 {
    progress.advance(task, 1.0);
}
progress.stop();

§Iterator Progress

The ProgressIteratorExt trait adds .progress() to any iterator:

use gilt::progress::ProgressIteratorExt;

let items: Vec<i32> = (0..100).progress("Processing").collect();

§Live Display

Live renders content that updates in-place using cursor control codes.

use gilt::live::Live;
use gilt::text::Text;
use gilt::style::Style;

let mut live = Live::new(Text::new("Loading...", Style::null()));
live.start();
// ... update content ...
live.update_renderable(Text::new("Done!", Style::null()), true);
live.stop();

§Status Spinner

Status displays a spinner animation with a status message.

use gilt::status::Status;

let mut status = Status::new("Loading...");
status.start();
status.set("Processing...");
status.stop();

§Rust-Native Features

These features go beyond what the upstream library provides, taking advantage of Rust’s type system and ecosystem.

§Gradients

Gradient renders text with smoothly interpolated true-color gradients.

use gilt::gradient::Gradient;
use gilt::color::Color;

let g = Gradient::two_color("Hello!", Color::from_rgb(255, 0, 0), Color::from_rgb(0, 0, 255));
let rainbow = Gradient::rainbow("All the colors!");

§Sparkline

Sparkline renders numeric data as compact inline Unicode bar charts.

use gilt::sparkline::Sparkline;

let spark = Sparkline::new(&[1.0, 3.0, 5.0, 7.0, 5.0, 3.0, 1.0]);
let output = format!("{}", spark);
assert!(!output.is_empty());

§Canvas

Canvas provides a Braille dot-matrix for high-resolution terminal graphics. Each character cell encodes a 2x4 pixel grid, giving sub-character resolution.

use gilt::canvas::Canvas;

let mut c = Canvas::new(10, 5);
c.line(0, 0, 19, 19);   // diagonal line
c.rect(2, 2, 10, 10);   // rectangle
c.circle(10, 10, 8);    // circle

§Diff

Diff computes and renders colored line-level diffs in unified or side-by-side format.

use gilt::diff::{Diff, DiffStyle};

let old = "line 1\nline 2\nline 3\n";
let new = "line 1\nline 2 modified\nline 3\nline 4\n";
let diff = Diff::new(old, new).with_labels("before", "after");
let sbs = Diff::side_by_side(old, new);

§Figlet

Figlet renders large ASCII art text using a built-in 5x7 block font.

use gilt::figlet::Figlet;

let banner = Figlet::new("HI");
let output = format!("{}", banner);
assert!(!output.is_empty());

§Inspect

Inspect displays structured information about any Debug value in a styled panel, showing the type name and formatted representation.

use gilt::inspect::Inspect;
use gilt::console::Console;

let data = vec![1, 2, 3];
let widget = Inspect::new(&data)
    .with_title("My Data")
    .with_label("numbers");

let mut c = Console::builder().width(80).force_terminal(true).build();
c.begin_capture();
c.print(&widget);
let output = c.end_capture();
assert!(output.contains("Vec"));

Or use the global shorthand:

gilt::inspect(&vec![1, 2, 3]);

§CsvTable

CsvTable converts CSV data into a rich Table.

use gilt::csv_table::CsvTable;

let csv = CsvTable::from_csv_str("name,age\nAlice,30\nBob,25").unwrap();
let table = csv.to_table();

§Derive Macros

With the derive feature enabled, gilt provides seven proc-macro derives that automatically generate widget conversions from struct definitions:

Derive	Generates	Method
`Table`	Table from a slice of structs	`Type::to_table(&items)`
`Panel`	Panel from a single struct	`value.to_panel()`
`Tree`	Tree from a struct	`value.to_tree()`
`Columns`	Columns from a struct	`value.to_columns()`
`Rule`	Rule from a struct	`value.to_rule()`
`Inspect`	Inspect panel from a struct	`value.to_inspect()`
`Renderable`	`Renderable` trait impl	`console.print(&value)`

use gilt::Table;

#[derive(Table)]
#[table(title = "Employees", box_style = "ROUNDED")]
struct Employee {
    #[column(header = "Full Name", style = "bold")]
    name: String,
    #[column(justify = "right")]
    age: u32,
    #[column(skip)]
    internal_id: u64,
    #[column(header = "Dept", style = "green")]
    department: String,
}

let employees = vec![
    Employee { name: "Alice".into(), age: 30, internal_id: 1, department: "Eng".into() },
];
let table = Employee::to_table(&employees);

Enable in Cargo.toml:

gilt = { version = "1.10", features = ["derive"] }

§`gilt::derives` namespace

All seven derives are also re-exported under gilt::derives for cases where the macro names collide with widget types (Columns, Inspect, Rule overlap with the runtime widgets):

use gilt::derives::{Columns, Inspect, Panel, Renderable, Rule, Table, Tree};

§Feature Gates

Feature	Default	Crate Dependencies	Description
`json`	Yes	`serde`, `serde_json`	JSON pretty-printing via `Json`
`markdown`	Yes	`pulldown-cmark`	Terminal Markdown via `Markdown`
`syntax`	Yes	`syntect`	Syntax highlighting via `Syntax`
`syntax-theme-file`	No	`syntect/plist-load`	`Syntax::load_theme_from_file` (.tmTheme; native; pulls `plist`/`time`)
`interactive`	Yes	`rpassword`	Password prompts and selection menus
`logging`	Yes	`log`	Logging handler
`terminal-size`	Yes	`terminal_size`	Real terminal width/height via `ioctl` (native only; excluded from wasm/no-default builds)
`tracing`	No	`tracing`, `tracing-subscriber`	`GiltLayer` subscriber
`derive`	No	`gilt-derive`	7 proc-macro derives
`miette`	No	`miette`	`GiltMietteHandler`
`eyre`	No	`eyre`	`GiltEyreHandler`
`anstyle`	No	`anstyle`	Bidirectional `From` conversions
`csv`	No	`csv`	CSV file reading (built-in parser always available)
`readline`	No	`rustyline`	Readline-based prompt completions
`asciinema`	No	(json)	`Console::export_asciinema` — asciinema v2 `.cast` export
`windows-vt`	No	`windows-sys`	Enable VT processing at `Console::new()` (native Windows)
`inline-images`	No	`image`	Decode PNG/JPEG for `Image` (halfblock works without it)
`tty-select`	No	`crossterm`	Interactive `FuzzySelect` (the core `FuzzySelectState` is dep-free)
`terminal-query`	No	`crossterm`	OSC 11 background probe → `auto_theme` (parsing core is dep-free)

For a minimal build with no heavy dependencies:

gilt = { version = "1.10", default-features = false }

§Integrations

§miette – Diagnostic Reporting

Install gilt as the miette report handler for beautifully styled diagnostic output. (Requires the miette feature.)

gilt::miette_handler::install();

§eyre – Error Reporting

Install gilt as the eyre report handler. (Requires the eyre feature.)

gilt::eyre_handler::install().unwrap();

§tracing – Structured Logging

Use GiltLayer as a tracing subscriber layer for colored, formatted log output. (Requires the tracing feature.)

use gilt::tracing_layer::GiltLayer;
use tracing_subscriber::prelude::*;

tracing_subscriber::registry()
    .with(GiltLayer::new())
    .init();

§anstyle – Type Conversions

With the anstyle feature, gilt Color and Style types gain bidirectional From conversions with their anstyle counterparts, enabling interop with clap, owo-colors, and the anstyle ecosystem.

§Advanced

§Theme System

gilt’s Theme maps style names (like "table.header" or "bold red") to Style instances. The default theme provides sensible styling for all built-in widgets. Push custom themes onto the console’s theme stack:

use gilt::console::Console;
use gilt::theme::Theme;
use gilt::style::Style;
use std::collections::HashMap;

let mut styles = HashMap::new();
styles.insert("info".to_string(), Style::parse("bold cyan"));

let mut console = Console::new();
console.push_theme(Theme::new(Some(styles), true));
// All rendering now uses the custom "info" style
console.pop_theme();

§Custom Renderables

Implement the Renderable trait to create your own widgets:

use gilt::console::{Console, ConsoleOptions, Renderable};
use gilt::segment::Segment;

struct Greeting { name: String }

impl Renderable for Greeting {
    fn gilt_console(&self, _console: &Console, _options: &ConsoleOptions) -> Vec<Segment> {
        vec![
            Segment::text(&format!("Hello, {}!", self.name)),
            Segment::line(),
        ]
    }
}

§Accessibility (WCAG Contrast)

The accessibility module provides WCAG 2.1 contrast ratio calculations:

use gilt::accessibility::{contrast_ratio, meets_aa, meets_aaa};
use gilt::color_triplet::ColorTriplet;

let black = ColorTriplet::new(0, 0, 0);
let white = ColorTriplet::new(255, 255, 255);
assert!((contrast_ratio(&black, &white) - 21.0).abs() < 0.1);
assert!(meets_aa(&black, &white));
assert!(meets_aaa(&black, &white));

§Environment Variables

gilt respects standard terminal environment variables with a 5-tier priority system:

Variable	Effect
`NO_COLOR`	Disables all color output (no-color.org)
`FORCE_COLOR`	Forces color output even when not a TTY
`CLICOLOR_FORCE`	Same as `FORCE_COLOR`
`CLICOLOR=0`	Disables color
`COLUMNS` / `LINES`	Overrides terminal size detection
`GILT_THEME`	Path to a JSON theme file loaded at console construction time (native + `json` feature only; see `ConsoleBuilder::theme_from_path`)

Programmatic settings (via ConsoleBuilder) always take priority over environment variables.

§Console Export (HTML, SVG, Text)

When recording is enabled, the console can export its output in multiple formats:

let mut c = Console::builder().width(60).record(true).build();
c.print_text("[bold green]Success![/bold green]");

let text = c.export_text(true, false);             // plain text
let html = c.export_html(None, true, true);         // HTML with inline styles
let svg  = c.export_svg("Title", None, true, None, 0.61); // SVG image

Files can be written directly with save_text, save_html, and save_svg.

§Module Index

Module	Description
`console`	Console engine: rendering, capture, export
`style`	Text styles: colors, attributes, hyperlinks
`text`	Text with markup parsing and word wrapping
`table`	Unicode box-drawing tables
`panel`	Bordered content panels
`tree`	Hierarchical tree display
`rule`	Horizontal rules with titles
`columns`	Auto-fitting multi-column layout
`layout`	Split-pane terminal layouts
`progress`	Multi-task progress bars with live display
`live`	Live-updating terminal display
`status`	Spinner with status message
`gradient`	True-color gradient text
`sparkline`	Inline Unicode sparkline charts
`canvas`	Braille dot-matrix graphics
`diff`	Colored unified and side-by-side diffs
`figlet`	Large ASCII art text
`csv_table`	CSV-to-Table conversion
`styled_str`	Stylize trait for `"text".bold().red()` chaining
`inspect`	Debug any value with rich formatting
`markup`	Markup tag parser
`color`	Color types and parsing
`segment`	Low-level rendering segments
`theme`	Named style collections
`accessibility`	WCAG 2.1 contrast checking
`highlighter`	Regex-based and repr syntax highlighters
`emoji`	Emoji shortcode replacement
`box_chars`	19 box-drawing character sets
`prelude`	Convenience re-exports

Re-exports§

pub use utils::group;
pub use utils::styled;
pub use utils::styled_str;
pub use color::accessibility;
pub use color::color_env;
pub use color::color_triplet;
pub use color::palette;
pub use color::terminal_theme;
pub use color::theme;
pub use error::logging_handler;
pub use error::traceback;
pub use live::live_render;
pub use live::screen;
pub use status::spinner;
pub use status::spinners;
pub use status::toast;
pub use utils::align_widget;
pub use utils::ansi;
pub use utils::bar;
pub use utils::box_chars;
pub use utils::cells;
pub use utils::constrain;
pub use utils::containers;
pub use utils::control;
pub use utils::default_styles;
pub use utils::diagnose;
pub use utils::emoji;
pub use utils::emoji_codes;
pub use utils::emoji_replace;
pub use utils::filesize;
pub use utils::highlighter;
pub use utils::inspect;
pub use utils::padding;
pub use utils::pretty;
pub use utils::protocol;
pub use utils::ratio;
pub use utils::scope;
pub use widgets::table;
pub use color::clear_color_cache;
pub use color::color_cache_size;
pub use style::clear_style_cache;
pub use style::style_cache_size;

Modules§

accordion: Accordion widget – collapsible content panels for organizing complex output.
badge: Badge/Tag widget for displaying status indicators.
breadcrumbs: Breadcrumbs widget for showing navigation path/location.
canvas: Canvas – dot-matrix terminal graphics with multiple blitter modes.
color: Terminal color representation and manipulation.
columns: Columns module – displays renderables in neat auto-fitted columns.
console: Console engine — the central orchestrator of gilt rendering output.
console_caps: ConsoleCapabilities — detected terminal capability flags.
csv_table: CSV to Table — load CSV data directly into a gilt Table.
diff: Colored diff rendering widget.
error: Error types used throughout the gilt library.
export_format: Export format templates for Console HTML and SVG output.
figlet: Large ASCII art text using Unicode block characters.
form: Form builder (huh pattern) — multi-step chained prompts with validation and an accessibility fallback.
fuzzy_select: Fuzzy/substring select — opt-in interactive single-select with filter.
gradient: True color gradient rendering across text.
image: Inline terminal image rendering.
json: Pretty-printed, syntax-highlighted JSON display.
layout: Layout module — a recursive screen-splitting layout system.
live: Live display module – a terminal display that refreshes at regular intervals.
markdown: Markdown rendering module – parses CommonMark and produces styled terminal output.
markup: gilt markup parser — parses [bold red]text[/] syntax into styled Text.
measure: Measurement module for tracking minimum and maximum rendering widths.
pager: Pager module for displaying content through a system pager.
panel: Panel widget – a bordered box around content with optional title/subtitle.
prelude: Convenience re-exports for common gilt types.
progress: Progress tracking system – configurable progress bars with live display.
progress_bar: Progress bar renderable – a styled progress bar with pulse animation.
prompt: Interactive prompt module for styled user input with validation, choices, and defaults.
region: Region type for rectangular screen areas.
rule: Rule widget – a horizontal line with optional title.
segment: Segment - the atomic unit of terminal rendering.
sparkline: Sparkline – inline Unicode sparkline charts.
status: Status indicator with a spinner animation.
style: Style representation and manipulation for terminal text.
style_interner: Per-Console style interner. Dormant in v0.11.0-alpha.1.
syntax: Syntax highlighting module for terminal display.
terminal_bg: OSC 11 terminal background detection — auto dark/light theme selection.
text: Text module - the core text manipulation type.
tree: Tree widget for rendering hierarchical structures with guide characters.
utils: Utility modules for gilt.
widgets: Widget modules for gilt.
windows_vt: Windows Virtual Terminal (VT) processing enablement.
wrap: Word wrapping utilities for terminal text.

Macros§

derive_gilt_cast: Macro to derive GiltCast implementation (placeholder for future derive macro).
gilt_cast_impl: Macro to implement GiltCast using a closure-like syntax.

Functions§

inspect: Inspect a value in the default console.
print: Print a renderable to the default console.
print_json: Pretty-print JSON to the default console.
print_text: Print a text string to the default console, processing markup.
with_console: Access the global default console.

Crate gilt

Crate gilt Copy item path

§gilt — Beautiful Terminal Formatting for Rust

§Quick Start

§The Console

§Creating a Console

§Printing

§Capture and Export

§Text and Styling

§Style

§Markup

§Text

§Stylize Trait

§Widgets

§Panel

§Table

§Tree

§Rule

§Columns

§Layout

§Terminal Features

§Syntax Highlighting

§Markdown

§JSON Pretty-Printing

§Progress Bars

§Iterator Progress

§Live Display

§Status Spinner

§Rust-Native Features

§Gradients

§Sparkline

§Canvas

§Diff

§Figlet

§Inspect

§CsvTable

§Derive Macros

§gilt::derives namespace

§Feature Gates

§Integrations

§miette – Diagnostic Reporting

§eyre – Error Reporting

§tracing – Structured Logging

§anstyle – Type Conversions

§Advanced

§Theme System

§Custom Renderables

§Accessibility (WCAG Contrast)

§Environment Variables

§Console Export (HTML, SVG, Text)

§Module Index

Re-exports§

Modules§

Macros§

Functions§

Crate gilt

§`gilt::derives` namespace