9 releases
Uses old Rust 2015
0.4.0 | Feb 26, 2024 |
---|---|
0.3.0 | Nov 16, 2020 |
0.2.4 | Aug 22, 2017 |
0.2.3 | Nov 23, 2016 |
0.1.1 | Apr 15, 2015 |
#187 in Command-line interface
2,059 downloads per month
Used in 252 crates
(18 directly)
41KB
320 lines
Coloring terminal output
term-painter
is a cross-platform (i.e. also non-ANSI terminals) Rust library for coloring and formatting terminal output.
It provides easy ways to format various things and uses the crate rust-lang/term
to do the actual formatting. Please read "When (not) to use this crate".
Note: I created another library for coloring terminal text: bunt
. I like it much better, so maybe consider using bunt
instead of term-painter
:-)
Example:
println!("{} | {} | {} | {} | {}",
Red.bg(Green).bold().paint("Red-Green-Bold"),
Blue.paint("Blue"),
Blue.bold().paint("BlueBold"),
Blue.bg(Magenta).paint("BlueMagentaBG"),
Plain.underline().paint("Underline")
);
Red.with(|| {
print!("JustRed");
Bold.with(|| {
print!(" BoldRed {} BoldRed ", Underline.paint("Underline"));
});
print!("JustRed ");
print!("{}", Blue.paint("Blue (overwrite) "));
Green.with(|| {
println!("Green (overwrite)");
});
});
It's easy to use and integrates well with println!
/print!
.
The main design goal was to make it simple.
This has one performance disadvantage: It will often reset the terminal style after each printing operation.
But performance isn't usually hugely important when printing on the terminal, so simplicity was more important for the design of this library.
More examples here (examples/main.rs
) or in the Documentation.
When (not) to use this crate
There are more terminal color crates than stars in the observable universe, therefore it's a valid question to ask "which one is best"? Unfortunately, there is no clear answer, I think.
Don't use this crate, if:
- you want full power of what happens (consider using
rust-lang/term
instead), or - you want to print from multiple threads (consider using
termcolor
orbunt
instead), or - you want to color/format text you print on something else than stdout (however,
term-painter
might add support for stderr in the future) - you want an actively developed crate (see "Status of this crate")
- you want to use a crate with a fancy name (
term-painter
is such a boring name 😒)
You probably shouldn't use this crate, if:
- you don't need to support non-ANSI terminals (Only supporting ANSI-formatting gives the author of the lib greater flexibility in designing the API, thus potentially making it easier and more powerful. See section "Cross Platform". Consider using
ansi-term
,colored
,yansi
, ... instead.), or - you expect a time-proven library
Use this crate, if:
- you need support for non-ANSI terminals, and
- you are developing a non-mission critical project
Cross Platform
This crate uses rust-lang/term
internally.
term
supports all (or rather: many) platforms, hence term-painter
does, too.
How does it work? In order to work, this crate depends on a specific way how println!
and friends evaluate their arguments (which is the common-sense way).
There are no guarantees about argument evaluation, but currently it works.
And honestly, it's unlikely that this way of evaluation ever changes.
But, for example, if println!()
would always call format!()
first and print the resulting String
, it wouldn't work.
To give a simplified explanation of the terminal-world: there are ANSI-terminal and non-ANSI Terminals. ANSI-formatting works by inserting special control characters into the string. Thus you can easily store the formatted string in a String
to print it later. Non-ANSI terminals work differently, and the most commonly used one is cmd
which is part of Windows 7/10. Formatting for cmd
works by calling methods of the winapi before and after printing. Thus you cannot easily store a formatted string. Apart from that, AFAIK there are not that many developers mainly using cmd
-- most Windows developer use IDEs alone or another terminal for Windows (there are plenty).
In summary: most terminals support ANSI-coloring, non-ANSI-terminals make the world more complicated.
Status of this crate
This crate is not actively developed anymore. The API is likely to stay as it is. I doubt this crate will reach its 1.0 milestone. This doesn't mean that this crate doesn't work! You can still use it, if it fits your needs.
Thanks
I've got some design ideas from rust-ansi-term
.
I decided to make my own crate though, since my goals were too different from ansi-term
(specifically: ansi-term
does not work everywhere).
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~155–610KB