termosaic 0.2.0

Semantic, structured output for human, machine-text, and opaque-byte destinations
Documentation

Termosaic

Semantic terminal output, composed.

Termosaic is a reusable Rust library for structured CLI presentation. It keeps human output, machine-readable text, and opaque bytes as distinct capabilities; renders semantic tokens through application-owned themes; lays out documents and tables without splitting Unicode graphemes; and coordinates human diagnostics with stderr progress.

The library owns no process-global stdout, stderr, color, theme, or progress state. Each Console instance receives explicit destination capabilities and output classes, so mixed human and machine streams cannot silently contaminate each other.

Features

Feature Default Capability
serde via json Validated serialization for names and tokens
json yes Semantic pretty JSON and compact/pretty machine JSON
progress yes Coordinated stderr progress handles
adaptive-tables no Width-aware borderless tables

The core library, including human and machine-text writers, opaque bytes, semantic tokens, themes, document layout, and fixed tables, builds with default features disabled. Termosaic 0.2 supports Rust 1.88 and newer.

Example

use termosaic::{
    ColorChoice, ColorDepth, Console, ConsoleOptions, DestinationOptions,
    OutputClass, Span, Stream, TerminalCapabilities, themes, tokens,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let destination = DestinationOptions {
        output_class: OutputClass::Human,
        color: ColorChoice::Never,
        terminal: TerminalCapabilities {
            is_terminal: false,
            color_depth: ColorDepth::Ansi16,
            width: None,
            interactive_cursor: false,
        },
    };
    let console = Console::with_writers(
        std::io::stdout(),
        std::io::stderr(),
        ConsoleOptions {
            stdout: destination,
            stderr: destination,
            theme: themes::default(),
        },
    )?;

    console
        .human(Stream::Stdout)?
        .line(&[Span::new(tokens::STATUS_SUCCESS, "composed")])?;
    Ok(())
}

See examples/basic.rs for a compilable example.

Common formatters

Termosaic includes ready-made human document constructors for wrapped prose, fixed-width text, lines, words, lists, key/value pairs, diagnostics, and tables. They return ordinary semantic Doc values and remain fully themeable:

use std::num::NonZeroU8;
use termosaic::formatters;

let prose = formatters::word_wrapped("A long explanation that may wrap.");
let fixed = formatters::fixed_width_with_tab_width(
    "name\tstatus",
    NonZeroU8::new(4).unwrap(),
);

With the json feature, human JSON is adaptive and semantically tokenized, while NDJSON remains validated machine text:

# fn example() -> Result<(), termosaic::JsonFormatError> {
let value = serde_json::json!({"status": "ready", "count": 2});
let human: termosaic::Doc = termosaic::formatters::json::pretty(&value)?;
let machine: termosaic::MachineText = termosaic::formatters::json::ndjson(&value)?;
assert!(machine.as_str().ends_with('\n'));
# Ok(()) }

MachineTextWriter::write_ndjson writes one compact record and one line feed. Machine JsonStyle::Pretty is intentionally fixed serialized JSON; it never uses terminal width, themes, or ANSI styling.

Prepared documents and strict rendering

Human documents use Laidout internally, but every public document, option, capacity, and error type is owned by Termosaic. Laidout remains usable on its own and never depends on or names Termosaic.

For repeated output, retain one HumanWriter, prepare the document once, and warm the width/strategy before entering a latency-sensitive path:

use termosaic::{Doc, HumanLayoutOptions, Stream};
# fn example(console: &termosaic::Console) -> Result<(), Box<dyn std::error::Error>> {
let doc = Doc::group(Doc::concat([
    Doc::text("status"), Doc::line(), Doc::text("ready"),
]));
let prepared = doc.prepare()?;
let mut human = console.human(Stream::Stdout)?;
let capacity = human.warm_rendering(&prepared, HumanLayoutOptions::fast())?;
human.reserve_rendering(capacity)?;
human.doc_strict(&prepared, HumanLayoutOptions::fast())?;
# Ok(()) }

Preparation and warming may allocate. Once adequately reserved, doc_strict performs layout, ANSI generation, terminal-newline handling, and the complete no-progress write through a preinitialized nonallocating sink with zero allocator calls. Insufficient storage is a typed error and writes no document bytes. doc_prepared is the Growable alternative; release_rendering_capacity drops a retained high-water mark.

See the 0.2 migration guide for constructor, error, Fast-layout, and dependency changes.

Verification

./scripts/verify.sh

This checks formatting, every feature lane, core/default/all-feature tests, the example, and Clippy with warnings denied.

License

MIT