#ansi-colors #ansi #terminal-colors #color #terminal #cli #linux-macos

r3bl_ansi_color

Rust crate to generate formatted ANSI 256 (8-bit) and truecolor (24-bit) color output to stdout

14 releases (4 breaking)

0.6.9 Oct 22, 2023
0.6.7 Sep 12, 2023

#153 in Command-line interface

Download history 5159/week @ 2024-02-26 4653/week @ 2024-03-04 4215/week @ 2024-03-11 3412/week @ 2024-03-18 3114/week @ 2024-03-25 3322/week @ 2024-04-01 3366/week @ 2024-04-08 3565/week @ 2024-04-15 3614/week @ 2024-04-22 4684/week @ 2024-04-29 4092/week @ 2024-05-06 3200/week @ 2024-05-13 3350/week @ 2024-05-20 3706/week @ 2024-05-27 2769/week @ 2024-06-03 2813/week @ 2024-06-10

13,045 downloads per month
Used in 12 crates (5 directly)

Apache-2.0

5MB
1K SLoC

Rust 1K SLoC // 0.1% comments Nushell 145 SLoC // 0.2% comments

r3bl_ansi_color crate

What does it do?

Rust crate to generate formatted ANSI 256 (8-bit) and truecolor (24-bit) color output to stdout. On macOS, the default Terminal.app does not support truecolor, so ANSI 256 colors are used instead.

This crate performs its own detection of terminal color capability heuristically. And does not use other crates to perform this function.

Here's a screenshot of running the main example on various operating systems:

Linux screenshot
Running on Linux Tilix
Windows screenshot
Running on Windows Terminal
macOS screenshot Terminal app
Running on macOS Terminal app (note ANSI 256 runtime detection)
macOS screenshot iTerm app
Running on macOS iTerm app (note Truecolor runtime detection)

How to use it?

The main struct that we have to consider is AnsiStyledText. It has two fields:

  • text - the text to print.
  • style - a list of styles to apply to the text.

Here's an example.

AnsiStyledText {
    text: "Print a formatted (bold, italic, underline) string w/ ANSI color codes.",
    style: &[
        Style::Bold,
        Style::Italic,
        Style::Underline,
        Style::Foreground(Color::Rgb(50, 50, 50)),
        Style::Background(Color::Rgb(100, 200, 1)),
    ],
}
.println();

Please a look at the main example to get a better idea of how to use this crate.

Build, run, test tasks

Prerequisites

🌠 In order for these to work you have to install the Rust toolchain and the following crates cargo-cache, cargo-watch, flamegraph, and nu using these instructions:

  1. Install the Rust toolchain using rustup by following the instructions here.
  2. Install cargo-cache using cargo install cargo-cache.
  3. Install cargo-watch using cargo install cargo-watch.
  4. Install flamegraph using cargo install flamegraph.
  5. Install nu using cargo install nu.

Commands to run

The script to run is run.nu. It works on Linux, macOS, and Windows. Please make sure that the pre-requisites are installed.

  • Build: nu run.nu build
  • Clean: nu run.nu clean
  • Run examples: nu run.nu run
  • Run examples with release flag: nu run.nu run-release
  • Run examples with flamegraph profiling: nu run.nu run-flamegraph
  • Run tests: nu run.nu test
  • Run clippy: nu run.nu clippy
  • Build docs: nu run.nu docs
  • Serve docs: nu run.nu serve-docs. This is only useful if you SSH into a remote machine via VSCode (where you build and serve the docs) and want to view the docs in a browser on your local machine.
  • Upgrade deps: nu run.nu upgrade-deps
  • Run rustfmt: nu run.nu rustfmt

The following commands will watch for changes in the source folder and re-run:

  • Watch run: nu run.nu watch-run
  • Watch all test: nu run.nu watch-all-tests
  • Watch one test: nu run.nu watch-one-test <test_name>
  • Watch clippy: nu run.nu watch-clippy
  • Watch macro expansion for one test: nu run.nu watch-macro-expansion-one-test <test_name>

References

Why make a new crate for this?

  • There are a few crates on crates.io that do similar things but they don't amenable licenses.
  • Other crates simply ignore ANSI 256 colors and only support truecolor, even when they claim that they support it.
  • And there are other crates which don't correctly report that macOS Terminal.app does not support truecolor and only supports ANSI 256 color.

Here are some links:

  1. https://github.com/rust-cli/concolor/issues/47
  2. https://docs.rs/anstream/latest/anstream/
  3. https://docs.rs/colorchoice/latest/colorchoice/
  4. https://docs.rs/colorchoice-clap/latest/colorchoice_clap/
  5. https://docs.rs/anstyle-query/latest/anstyle_query/fn.term_supports_ansi_color.html
  6. https://crates.io/crates/anstyle-query
  7. https://docs.rs/supports-color/2.0.0/supports_color/
  8. https://crates.io/crates/r3bl_ansi_color (the source in ansi_color folder is this crate)
  9. https://crates.io/crates/colored

Dependencies