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 ;
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 NonZeroU8;
use formatters;
let prose = word_wrapped;
let fixed = fixed_width_with_tab_width;
With the json feature, human JSON is adaptive and semantically tokenized,
while NDJSON remains validated machine text:
#
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 ;
#
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
This checks formatting, every feature lane, core/default/all-feature tests, the example, and Clippy with warnings denied.
License
MIT