Crates.io | color-print |
lib.rs | color-print |
version | 0.3.6 |
source | src |
created_at | 2021-08-25 20:18:56.914857 |
updated_at | 2024-04-23 15:54:58.548284 |
description | Colorize and stylize strings for terminal at compile-time, by using an HTML-like syntax |
homepage | |
repository | https://gitlab.com/dajoha/color-print |
max_upload_size | |
id | 442315 |
size | 48,045 |
Colorize and stylize strings for terminal at compile-time, by using an HTML-like syntax.
This library provides the following macros:
cformat!(<FORMAT_STRING> [, ARGS...])
cprint!(<FORMAT_STRING> [, ARGS...])
cprintln!(<FORMAT_STRING> [, ARGS...])
cstr!(<FORMAT_STRING>)
untagged!(<FORMAT_STRING>)
cformat!()
, cprint!()
, and cprintln!()
have the same syntax as format!()
,
print!()
and println!()
respectively, but they accept an additional syntax inside the
format string: HTML-like tags which add ANSI colors/styles at compile-time.
cstr!()
only transforms the given string literal into another string literal, without
formatting anything else than the colors tag.
untagged!()
removes all the tags found in the given string literal.
By default, the provided macros will replace the tags found in the format string by ANSI hexadecimal escape codes. E.g.:
cprintln!("HELLO <green>WORLD</green>")
cprintln!("HELLO <green>WORLD</>"); // Alternative, shorter syntax
will be replaced by:
println!("HELLO \u{1b}[31mWORLD\u{1b}[39m")
Note: it is possible to change this behaviour by activating the feature terminfo
. Then it
will question the terminfo
database at runtime in order to know which sequence to write for
each kind of styling/colorizing (see below for more detail).
terminfo
is activated);"<green>...<blue>...</blue>...</green>"
;"my <b>blue</> word"
;format!
-like
macros; e.g., positional arguments and named arguments can be used as usual;use color_print::cprintln;
cprintln!("Hello <green>world</green>!");
</>
tagBasically, tags must be closed by giving exactly the same colors/styles as their matching
open tag (with a slash /
at the beginning), e.g: <blue,bold>...</blue,bold>
. But it can be
tedious!
So, it is also possible to close the last open tag simply with </>
:
cprintln!("Hello <green>world</>!");
Multiple styles and colors can be combined into a single tag by separating them with the ,
comma character:
cprintln!("This a <green,bold>green and bold text</green,bold>.");
// The same, but closing with the </> tag:
cprintln!("This a <green,bold>green and bold text</>.");
Any tag can be nested with any other.
Note: The closing tags must match correctly (following the basic rules of nesting for HTML
tags), but it can always be simplified by using the tag </>
.
Example of nested tags:
cprintln!("<green>This is green, <bold>then green and bold</bold>, then green again</green>");
cprintln!("<green>This is green, <bold>then green and bold</>, then green again</>");
// Colors can be nested as well:
cprintln!("<green>This is green, <blue>then blue</blue>, then green again</green>");
cprintln!("<green>This is green, <blue>then blue</>, then green again</>");
Tags which have not been closed manually will be closed automatically, which means that the ANSI sequences needed to go back to the original state will be added:
// The two following lines are strictly equivalent:
cprintln!("<green><bold>Hello");
cprintln!("<green><bold>Hello</></>");
<
and >
verbatimAs for {
and }
in standard format strings, the chars <
and >
have to be doubled in
order to display them verbatim:
cprintln!("This is an angle bracket character: <<, and here is another one: >>");
The expanded format string will only contain the needed ANSI codes. This is done by making a diff of the different style attributes, each time a tag is encountered, instead of mechanically adding the ANSI codes.
E.g., several nested <bold>
tags will only produce one bold ANSI sequence:
cprintln!("<bold><bold> A <bold,blue> B </> C </></>")
will be replaced by:
println!("\u{1b}[1m A \u{1b}[34m B \u{1b}[39m C \u{1b}[22m")
// ^-------^ ^--------^ ^--------^ ^--------^
// bold blue color bold
// reset reset
terminfo
Instead of inserting ANSI sequences directly into the format string, it is possible to activate
the feature terminfo
: this will add the format sequences at runtime, by consulting the
terminfo
database.
This has one pro and several cons:
lazy_static
and terminfo
;<strike>
and <conceal>
are not handled;terminfo
, many styles are not resettable individually, which implies longer format
sequences for the same result;lazy_static
: https://crates.io/crates/lazy_static
terminfo
: https://crates.io/crates/terminfo
Each tag has at least a long name, like <magenta>
or <underline>
.
The tags directly relative to colors (like <red>
, <bg:blue>
, <bg:bright-green>
..., as
opposed to style tags like <bold>
, <italics>
...) have some common naming rules:
<mycolor>
: the normal, foreground color;<bright-mycolor>
or <mycolor!>
: the bright, foreground color;<bg:mycolor>
, <MYCOLOR>
: the normal, background color;<bg:bright-mycolor>
, <bg:mycolor!>
, <BRIGHT-MYCOLOR>
or <MYCOLOR!>
: the bright,
background color;x
letter:
<x>
: the normal, foreground color;<x!>
: the bright, foreground color;<bg:x>
, <X>
: the normal, background color;<bg:x!>
, <X!>
: the bright, background color;<k>
which is the shortcut for <black>
), e.g. <y>
is the shortcut for <yellow>
;!
is a bright color;The two first columns show which styles are supported, respectively with the default crate
features (ANSI column), and with the feature terminfo
being activated.
ANSI | Terminfo | Shortcuts | Long names | Aliases |
---|---|---|---|---|
X | X | <s> |
<strong> |
<em> <bold> |
X | X | <dim> |
||
X | X | <u> |
<underline> |
|
X | <strike> |
|||
X | X | <reverse> |
<rev> |
|
X | <conceal> |
<hide> |
||
X | X | <i> |
<italics> |
<italic> |
X | X | <blink> |
||
X | X | <k> |
<black> |
|
X | X | <r> |
<red> |
|
X | X | <g> |
<green> |
|
X | X | <y> |
<yellow> |
|
X | X | <b> |
<blue> |
|
X | X | <m> |
<magenta> |
|
X | X | <c> |
<cyan> |
|
X | X | <w> |
<white> |
|
X | X | <k!> |
<bright-black> |
<black!> |
X | X | <r!> |
<bright-red> |
<red!> |
X | X | <g!> |
<bright-green> |
<green!> |
X | X | <y!> |
<bright-yellow> |
<yellow!> |
X | X | <b!> |
<bright-blue> |
<blue!> |
X | X | <m!> |
<bright-magenta> |
<magenta!> |
X | X | <c!> |
<bright-cyan> |
<cyan!> |
X | X | <w!> |
<bright-white> |
<white!> |
X | X | <K> |
<bg:black> |
<BLACK> |
X | X | <R> |
<bg:red> |
<RED> |
X | X | <G> |
<bg:green> |
<GREEN> |
X | X | <Y> |
<bg:yellow> |
<YELLOW> |
X | X | <B> |
<bg:blue> |
<BLUE> |
X | X | <M> |
<bg:magenta> |
<MAGENTA> |
X | X | <C> |
<bg:cyan> |
<CYAN> |
X | X | <W> |
<bg:white> |
<WHITE> |
X | X | <K!> |
<bg:bright-black> |
<BLACK!> <bg:black!> <BRIGHT-BLACK> |
X | X | <R!> |
<bg:bright-red> |
<RED!> <bg:red!> <BRIGHT-RED> |
X | X | <G!> |
<bg:bright-green> |
<GREEN!> <bg:green!> <BRIGHT-GREEN> |
X | X | <Y!> |
<bg:bright-yellow> |
<YELLOW!> <bg:yellow!> <BRIGHT-YELLOW> |
X | X | <B!> |
<bg:bright-blue> |
<BLUE!> <bg:blue!> <BRIGHT-BLUE> |
X | X | <M!> |
<bg:bright-magenta> |
<MAGENTA!> <bg:magenta!> <BRIGHT-MAGENTA> |
X | X | <C!> |
<bg:bright-cyan> |
<CYAN!> <bg:cyan!> <BRIGHT-CYAN> |
X | X | <W!> |
<bg:bright-white> |
<WHITE!> <bg:white!> <BRIGHT-WHITE> |
X | <rgb(r,g,b)> |
<#RRGGBB> |
||
X | <bg:rgb(r,g,b)> |
<bg:#RRGGBB> <RGB(r,g,b)> |
||
X | <0> ...<255> |
<palette(...)> |
<p(...)> <pal(...)> |
|
X | <P(...)> |
<bg:palette(...)> |
<PALETTE(...)> <PAL(...)> <bg:p(...)> <bg:pal(...)> |
License: MIT OR Apache-2.0