Minimal ANSI terminal colour codes, for Rust
woad provides fixed ANSI SGR sequences, and stream-conditional counterparts that emit only when the destination warrants colour. It is not a console or TUI framework.
woad.Rust is the Rust implementation. The declared MSRV is 1.74. It has no dependencies on any other crate.
This alpha matches the portable colour contract of woad 0.3.0. Console-mode changes, Windows virtual-terminal gating, handle currencies, and mintty PTY recognition are not included. console_supports_ansi is always true.
woad.Rust builds with Cargo. The declared MSRV is 1.74, and the crate has no runtime dependencies.
cargo test --all-targets
cargo run --example colour
cargo run --example colour_forThe smallest useful call emits a sequence only when the writer supports colour:
use woad::{seq_for, FG_GREEN, RESET};
fn main() {
let out = std::io::stdout();
print!("{}ok{}", seq_for(FG_GREEN, &out), seq_for(RESET, &out));
}That is examples/colour/main.rs. examples/colour_for/main.rs prints stdout and stderr, including bold, blinking, and, on Unix, the descriptor form. Fixed sequences (BOLD, BLINKING, FG_*, BG_*) always contain the SGR bytes. colour_policy, supports_colour, and seq_for apply the cached environment policy. is_tty reports attachment only. refresh drops that cache.
The colour example prints green ok only when stdout supports colour. A pipe is not a terminal, so automatic policy drops the sequences. WOAD_COLOUR and NO_COLOR override that. The accepted forms are listed under Environment.
# Automatic policy, attached to a terminal: green "ok" when TERM is not dumb.
cargo run --example colour
# The same program, piped: plain "ok".
cargo run --example colour | cat
# Force colour, including through the pipe.
WOAD_COLOUR=1 cargo run --example colour | cat
CLICOLOR_FORCE=1 cargo run --example colour | cat
# Inhibit colour, including on a terminal.
WOAD_COLOUR=never cargo run --example colour
NO_COLOR=1 cargo run --example colour
# Automatic policy, dumb terminal: plain "ok".
TERM=dumb cargo run --example colourReference in Cargo.toml in the usual way:
woad = { version = "0.1.0-alpha2" }woad.Rust ships fixed SGR sequences (BLINKING, BOLD, RESET, FG_*, BG_*, including bright variants), VERSION, packed version() / version_string(), and the portable colour policy: colour_policy, refresh, is_tty, supports_colour, and seq_for. Attribute helpers (blinking_for, bold_for, reset_for) and the Unix descriptor forms sit beside those. On Unix a terminal supports colour when the policy is automatic and TERM is not dumb. Windows virtual-terminal mode, handle currencies, and mintty PTY recognition are not implemented.
String constants: RESET, BOLD, BLINKING, FG_*, and BG_*, the colours each in normal and BRIGHT variants. They always emit.
colour_policy() returns ColourPolicy: Auto (0), Force (1), or Inhibit (2). The result is cached until refresh is invoked.
A variable that is unset or empty is absent. Values are not trimmed. The first present variable in this order wins:
- Non-empty
WOAD_COLOUR, otherwise non-emptyWOAD_COLOR. Compared case-insensitively. Truey forces:1,always,force,on,true,yes. Falsey inhibits:0,false,never,no,none,off. Anything else, includingauto, selects auto and does not fall through; - Non-empty
NO_COLORinhibits, whatever its text is; - Non-empty
CLICOLOR_FORCEother than the exact bytes0forces. Exact0does not force and does not inhibit; - Non-empty
FORCE_COLORother than exact0orfalse(any capitalisation) forces. Exact0andfalsedo not force and do not inhibit; CLICOLORequal to the exact bytes0inhibits. Any other value is ignored;- Otherwise auto.
TERM equal to dumb, in any capitalisation, is cached beside the policy. It is not a policy value. It suppresses colour only when the policy is auto. force ignores the terminal and TERM. inhibit never emits colour.
On Unix, auto plus a terminal plus a TERM that is not dumb means colour. There is no console probe. WOAD_SET_CONSOLE_MODE is not read in this alpha.
Examples are provided in the examples directory. A catalogue is in EXAMPLES.md.
seq_for yields the sequence when the destination warrants colour, and "" when it does not. blinking_for, bold_for, and reset_for are the attribute forms. The destination is any std::io::IsTerminal value (Stdout, Stderr, Stdin, File, and on Unix a borrowed file descriptor).
let stdout = std::io::stdout();
println!(
"{}ok{}",
woad::seq_for(woad::FG_GREEN, &stdout),
woad::reset_for(&stdout),
);On Unix, fd_is_tty, fd_supports_colour, and seq_for_fd take AsFd. A missing destination is supports_colour_absent / seq_for_absent (the C null-stream case: the policy alone).
The environment is read once, on first need, until refresh():
| Variable | Value | Effect |
|---|---|---|
WOAD_COLOUR, or WOAD_COLOR |
1, always, force, on, true, yes |
Force colour |
WOAD_COLOUR, or WOAD_COLOR |
0, false, never, no, none, off |
Inhibit colour |
WOAD_COLOUR, or WOAD_COLOR |
auto, or anything unrecognised |
Defer to the destination |
NO_COLOR |
set and non-empty | Inhibit colour |
CLICOLOR_FORCE |
set, non-empty, and not 0 |
Force colour |
FORCE_COLOR |
set, non-empty, and not 0 or false |
Force colour |
CLICOLOR |
0 |
Inhibit colour |
WOAD_COLOUR / WOAD_COLOR are case-insensitive. In the deferring case, a TERM of dumb also suppresses colour. console_supports_ansi() is always true in this alpha.
VERSION and version_string() are the SemVer string, including the prerelease label (0.1.0-alpha2). version() is the packed woad WOAD_VER (0x00010042; low byte 0x42 is alpha 2).
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/woad.Rust.
The declared Minimum Supported Rust Version (MSRV) for woad.Rust is 1.74.
This MSRV guarantee applies to the library crate itself, its runtime dependencies ([dependencies]), and its build dependencies ([build-dependencies]). Downstream consumers compiling this crate as a dependency are guaranteed that it builds cleanly on the declared MSRV toolchain.
Development dependencies ([dev-dependencies], such as benchmarking frameworks like criterion) may require newer Rust toolchains for local development or performance testing. These dev-dependencies are never fetched or compiled by downstream consumers and do not affect the library's MSRV guarantee.
None. Windows virtual-terminal mode and mintty PTY recognition are not implemented, so this crate does not depend on windows-sys.
None.
None (currently).
- woad (C, C++)
- woad.Python
- woad.Ruby
woad.Rust is released under the 3-clause BSD license. See LICENSE for details.