#terminal-colors #ansi-colors #ansi-term #color #terminal #rgb #escaping

ansistream

Write blazingly fast, free allocation ansi escape codes to a buffer, and flushes them all to any output

6 releases

0.2.0 Jan 21, 2024
0.1.6 Jan 11, 2024

#804 in Development tools

MIT license

210KB
527 lines

AnsiStream

Crates.io Crates.io Downloads Rust Stable License GitHub Actions Workflow Status

Write blazingly fast, free allocation ansi escape codes to a buffer, and flushes them all to any output stream. Supports 8/16 colors, 256 colors, RGB color rendering output.

ANSI Escape Codes for Terminal Graphics

The ANSI escape code standard, formally adopted as ISO/IEC 6429, defines a series of control sequences. Each control sequence begins with a Control Sequence Introducer (CSI), defined as a scape character followed immediately by a bracket: ESC[. In particular, a CSI followed by a certain number of "parameter bytes" (ASCII 0-9:; <=>?) then the letter m forms a control sequence known as Select Graphic Rendition (SGR). If no parameter bytes are explicitly given, then it is assumed to be 0. SGR parameters can be chained together with a semicolon ; as delimiter.

Some common SGR parameters are shown below.

Parameter Effect
0 reset all SGR effects to their default
1 bold or increased intensity
2 faint or decreased insensity
4 singly underlined
5 slow blink
30-37 foreground color (3/4 bit)
38;5;x foreground color (256 colors, non-standard)
38;2;r;g;b foreground color (RGB, non-standard)
40-47 background color (8 colors)
48;5;x background color (256 colors, non-standard)
48;2;r;g;b background color (RGB, non-standard)
90-97 bright foreground color (non-standard)
100-107 bright background color (non-standard)
  • Below example will print a red underlined text.

sgi

Usage

  • Add the AnsiStream crate to your Cargo.toml
$ cargo add ansistream
  • Initialize a buffer and write a simple string in it
// initialize a ansi stream
let output = Cursor::new(Vec::<u8>::new());
let mut astream = ansistream::AnsiScapeStream::new(output);
// write a simple string in buffer
astream.write_string("the quick brown fox jumps over the lazy dog")?;
// data will be flushed when astream drop or gets flushed
  • Write the stream in stdout
let stdout = io::stdout().lock();

let mut astream = ansistream::AnsiScapeStream::new(stdout);
astream.write_string("simple text")?;

astream.flush()?;
  • Writing a green foreground text to stream
let mut astream = AnsiEscapeStream::new(writer);
astream.write_text_fc_fmt(FCGREEN, format_args!("123")).unwrap();
// asserts that fcgreen was writed and also reseted with fcdefault
assert_eq!(
    &[0x1b, 0x5b, 0x33, 0x32, 0x6d, 0x31, 0x32, 0x33, 0x1b, 0x5b, 0x33, 0x39, 0x6d],
    astream.buffer()
);
  • Write formatted color output
let mut astream = AnsiEscapeStream::new(writer);

  for i in 100..=107 {
      astream.write_text_color_fmt(FC_LIGHT_GRAY, i, format_args!("{i:>5} "))?;
  }

Examples

  • 16color example

256color

$ hyperfine --warmup 100 '16color'
Benchmark 1: 16color
  Time (mean ± σ):      10.9 ms ±   0.4 ms    [User: 5.7 ms, System: 9.3 ms]
  Range (min … max):    10.3 ms …  12.2 ms    133 runs
  • 256color example

256color

$ hyperfine --warmup 100 '256color'
Benchmark 1: 256color
  Time (mean ± σ):      11.3 ms ±   0.4 ms    [User: 4.9 ms, System: 9.3 ms]
  Range (min … max):    10.7 ms …  12.7 ms    130 runs
  • truecolor example

truecolor

$ hyperfine --warmup 100 'truecolor'
Benchmark 1: truecolor
  Time (mean ± σ):      11.2 ms ±   0.5 ms    [User: 5.4 ms, System: 9.2 ms]
  Range (min … max):    10.4 ms …  13.0 ms    131 runs

Status

Escape codes available

Finnished Type
x Color and Style Escape Codes
Screen and Cursor Escape Codes

References

Ansi Escape Codes

No runtime deps