woad.Rust
Minimal ANSI terminal colour codes, for Rust
Table of Contents
Introduction
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.
Developer Experience
woad.Rust builds with Cargo. The declared MSRV is 1.74, and the crate has no runtime dependencies.
The smallest useful call emits a sequence only when the writer supports colour:
use ;
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.
# The same program, piped: plain "ok".
|
# Force colour, including through the pipe.
WOAD_COLOUR=1 |
CLICOLOR_FORCE=1 |
# Inhibit colour, including on a terminal.
WOAD_COLOUR=never
NO_COLOR=1
# Automatic policy, dumb terminal: plain "ok".
TERM=dumb
Installation
Reference in Cargo.toml in the usual way:
= { = "0.1.0-alpha2" }
Components
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.
Fixed sequences
String constants: RESET, BOLD, BLINKING, FG_*, and BG_*, the colours each in normal and BRIGHT variants. They always emit.
Environment
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
Examples are provided in the examples directory. A catalogue is in EXAMPLES.md.
Stream-conditional sequences
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 = stdout;
println!;
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).
Colour policy
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
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).
Project Information
Where to get help
Contribution guidelines
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/woad.Rust.
Minimum Supported Rust Version (MSRV)
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.
Dependencies
Efferent (fan-out)
None. Windows virtual-terminal mode and mintty PTY recognition are not implemented, so this crate does not depend on windows-sys.
Development Dependencies
None.
Afferent (fan-in)
None (currently).
Related projects
- woad (C, C++)
- woad.Python
- woad.Ruby
License
woad.Rust is released under the 3-clause BSD license. See LICENSE for details.