flower_pot/
lib.rs

1
2#![warn(missing_docs)]
3
4//! Constants and simple functions for invoking ANSI control codes used for text-styling in terminals (including color codes). Does not support cursor movement or any other control codes.
5//!
6//! Provides constant bindings for text-styling control codes like `BOLD` (= `"\x1b[1m"`) and `GREEN` (= `"\x1b[32m"`):
7//!
8//! ```
9//! use flower_pot::*;
10//!
11//! println!("{GREEN}ok{RESET}");           // prints a green "ok"
12//! println!("{BOLD}{RED}error!{RESET}");   // prints a bold, red "error!"
13//! println!("{BLUE_BG}cloud{RESET}");      // prints white text on a blue background
14//!
15//! // Note that you must print the RESET code after the end of
16//! // the text you want styled, or else all text printed to the
17//! // terminal after that point will also be styled that way,
18//! // including text outputted by other programs.
19//!
20//! ```
21//!
22//! ...functions to succinctly invoke the 8-bit color palette:
23//!
24//! ```
25//! use flower_pot::*;
26//!
27//! // prints text in "palette-color #237" (often a shade of grey)
28//! // with a background color of "palette-color #214" (often a
29//! // shade of orange)
30//!
31//! println!("{}{}example text{RESET}", color_256(237), color_256_bg(214));
32//!
33//! ```
34//!
35//! ...and ones that invoke truecolor functionality:
36//!
37//! ```
38//! use flower_pot::*;
39//!
40//! // prints text in RGB color [127, 45, 68] with a background
41//! // color of RGB color [0, 255, 255]
42//!
43//! println!("{}{}truecolor text{RESET}", truecolor(127, 45, 68), truecolor_bg(0, 255, 255));
44//!
45//! ```
46//!
47//! The `color_256`, `color_256_bg`, `truecolor`, and `truecolor_bg` functions all return Strings.
48//!
49//! Note that not all terminals support all of the codes defined in this library. The basic workflow of ANSI control codes is that a program outputs sequences of special characters defining what it wants (such as "make the following text bold" or "make the following text green" or "make the following text be the RGB color [127, 45, 68]") to stdout, and then the terminal that the program is running in decides what to do with those characters. The codes themselves are reasonably well-standardized, but not every terminal understands all of them. Some terminals might ignore some codes, or might do weird things when you use them (such as displaying the text following the code incorrectly). This is a feature of the ANSI control code ecosystem, and not something a library can fix.
50//!
51//! Once you've outputted a control code the terminal understands, all text that follows it is styled in the manner requested. If you want to go back to unstyled text, output the `RESET` code (`\x1b[0m`) or one of the more specific style-resetting codes such as `NOT_UNDERLINED` (`\x1b[24m`).
52//!
53//! Poorly-supported codes (as reported by Wikipedia) are marked as such below.
54
55// Styles: 0-29.
56
57pub const RESET:                    &'static str = "\x1b[0m";
58pub const BOLD:                     &'static str = "\x1b[1m";
59pub const DIM:                      &'static str = "\x1b[2m";
60pub const ITALIC:                   &'static str = "\x1b[3m";
61pub const UNDERLINE:                &'static str = "\x1b[4m";
62pub const SLOW_BLINK:               &'static str = "\x1b[5m";
63pub const RAPID_BLINK:              &'static str = "\x1b[6m";
64pub const INVERTED:                 &'static str = "\x1b[7m";
65pub const HIDDEN:                   &'static str = "\x1b[8m";
66pub const STRIKETHROUGH:            &'static str = "\x1b[9m";
67pub const PRIMARY_FONT:             &'static str = "\x1b[10m";
68pub const ALT_FONT_1:               &'static str = "\x1b[11m";
69pub const ALT_FONT_2:               &'static str = "\x1b[12m";
70pub const ALT_FONT_3:               &'static str = "\x1b[13m";
71pub const ALT_FONT_4:               &'static str = "\x1b[14m";
72pub const ALT_FONT_5:               &'static str = "\x1b[15m";
73pub const ALT_FONT_6:               &'static str = "\x1b[16m";
74pub const ALT_FONT_7:               &'static str = "\x1b[17m";
75pub const ALT_FONT_8:               &'static str = "\x1b[18m";
76pub const ALT_FONT_9:               &'static str = "\x1b[19m";
77pub const FRAKTUR_FONT:             &'static str = "\x1b[20m";
78pub const DOUBLE_UNDERLINE:         &'static str = "\x1b[21m"; // identical because of competing standards
79pub const NOT_BOLD:                 &'static str = "\x1b[21m"; // identical because of competing standards
80pub const NORMAL_INTENSITY:         &'static str = "\x1b[22m";
81pub const NOT_ITALIC_NOT_BOLD:      &'static str = "\x1b[23m";
82pub const NOT_UNDERLINED:           &'static str = "\x1b[24m";
83pub const NOT_BLINKING:             &'static str = "\x1b[25m";
84pub const PROPORTIONAL_SPACING:     &'static str = "\x1b[26m";
85pub const NOT_INVERTED:             &'static str = "\x1b[27m";
86pub const NOT_HIDDEN:               &'static str = "\x1b[28m";
87pub const NOT_STRIKETHROUGH:        &'static str = "\x1b[29m";
88
89// Standard foreground colors: 30-37.
90
91pub const BLACK:                    &'static str = "\x1b[30m";
92pub const RED:                      &'static str = "\x1b[31m";
93pub const GREEN:                    &'static str = "\x1b[32m";
94pub const YELLOW:                   &'static str = "\x1b[33m";
95pub const BLUE:                     &'static str = "\x1b[34m";
96pub const PURPLE:                   &'static str = "\x1b[35m";
97pub const CYAN:                     &'static str = "\x1b[36m";
98pub const WHITE:                    &'static str = "\x1b[37m";
99
100// Fine-control foreground colors: 38.
101
102pub fn color_256(n: u8) -> String {
103    format!("\x1b[38;5;{n}m")
104}
105
106pub fn truecolor(r: u8, g: u8, b: u8) -> String {
107    format!("\x1b[38;2;{r};{g};{b}m")
108}
109
110// Reset foreground color: 39.
111
112pub const DEFAULT:                  &'static str = "\x1b[39m";
113
114// Standard background colors: 40-47.
115
116pub const BLACK_BG:                 &'static str = "\x1b[40m";
117pub const RED_BG:                   &'static str = "\x1b[41m";
118pub const GREEN_BG:                 &'static str = "\x1b[42m";
119pub const YELLOW_BG:                &'static str = "\x1b[43m";
120pub const BLUE_BG:                  &'static str = "\x1b[44m";
121pub const PURPLE_BG:                &'static str = "\x1b[45m";
122pub const CYAN_BG:                  &'static str = "\x1b[46m";
123pub const WHITE_BG:                 &'static str = "\x1b[47m";
124
125// Fine-control background colors: 48.
126
127pub fn color_256_bg(n: u8) -> String {
128    format!("\x1b[48;5;{n}m")
129}
130
131pub fn truecolor_bg(r: u8, g: u8, b: u8) -> String {
132    format!("\x1b[48;2;{r};{g};{b}m")
133}
134
135// Reset background color: 49.
136
137pub const DEFAULT_BG:               &'static str = "\x1b[49m";
138
139// Additional styles: 50-55.
140
141pub const NO_PROPORTIONAL_SPACING:  &'static str = "\x1b[50m";
142pub const FRAMED:                   &'static str = "\x1b[51m";
143pub const ENCIRCLED:                &'static str = "\x1b[52m";
144pub const OVERLINE:                 &'static str = "\x1b[53m";
145pub const NOT_FRAMED_NOT_ENCIRCLED: &'static str = "\x1b[54m";
146pub const NOT_OVERLINED:            &'static str = "\x1b[55m";
147
148// Bright foreground colors: 90-97 (discontinuous range).
149
150pub const BRIGHT_BLACK:             &'static str = "\x1b[90m";
151pub const BRIGHT_RED:               &'static str = "\x1b[91m";
152pub const BRIGHT_GREEN:             &'static str = "\x1b[92m";
153pub const BRIGHT_YELLOW:            &'static str = "\x1b[93m";
154pub const BRIGHT_BLUE:              &'static str = "\x1b[94m";
155pub const BRIGHT_PURPLE:            &'static str = "\x1b[95m";
156pub const BRIGHT_CYAN:              &'static str = "\x1b[96m";
157pub const BRIGHT_WHITE:             &'static str = "\x1b[97m";
158
159// Bright background colors: 100-107 (discontinuous range).
160
161pub const BRIGHT_BLACK_BG:          &'static str = "\x1b[100m";
162pub const BRIGHT_RED_BG:            &'static str = "\x1b[101m";
163pub const BRIGHT_GREEN_BG:          &'static str = "\x1b[102m";
164pub const BRIGHT_YELLOW_BG:         &'static str = "\x1b[103m";
165pub const BRIGHT_BLUE_BG:           &'static str = "\x1b[104m";
166pub const BRIGHT_PURPLE_BG:         &'static str = "\x1b[105m";
167pub const BRIGHT_CYAN_BG:           &'static str = "\x1b[106m";
168pub const BRIGHT_WHITE_BG:          &'static str = "\x1b[107m";
169
170// Test (requires manual inspection of outputs).
171
172#[cfg(test)]
173mod tests {
174    use super::*;
175
176    #[test]
177    fn print_and_verify_visually() {
178        println!();
179        println!("{GREEN}green{RESET}");
180        println!("{BOLD}{RED}BOLD RED{RESET}");
181        println!("normal {WHITE}white {BRIGHT_WHITE}bright white{RESET}");
182        println!("{BLUE}blue {BRIGHT_BLUE}bright blue{RESET}");
183        println!("normal {ITALIC}italic {BOLD}and bold {UNDERLINE}and underline{RESET}");
184        println!("normal {DOUBLE_UNDERLINE}double underline{RESET}");
185        println!("normal normal");
186        println!("normal {OVERLINE}overline{RESET}");
187        println!("normal {ENCIRCLED}encircled{RESET}");
188        println!("normal {FRAMED}framed{RESET}");
189        println!(
190            "{}g{}r{}e{}y{}s{}c{}a{}l{}e{} {}c{}o{}l{}o{}r{}s{}",
191            color_256(232),
192            color_256(235),
193            color_256(238),
194            color_256(241),
195            color_256(244),
196            color_256(247),
197            color_256(250),
198            color_256(253),
199            color_256(255),
200            RESET,
201            color_256_bg(255),
202            color_256_bg(251),
203            color_256_bg(247),
204            color_256_bg(243),
205            color_256_bg(239),
206            color_256_bg(235),
207            RESET,
208        );
209        println!(
210            "{}r{}a{}i{}n{}b{}o{}w{}i{}c{} {}c{}o{}l{}o{}r{}s{}",
211            color_256(132),
212            color_256(135),
213            color_256(138),
214            color_256(141),
215            color_256(144),
216            color_256(147),
217            color_256(150),
218            color_256(153),
219            color_256(155),
220            RESET,
221            color_256_bg(155),
222            color_256_bg(151),
223            color_256_bg(147),
224            color_256_bg(143),
225            color_256_bg(139),
226            color_256_bg(135),
227            RESET,
228        );
229
230        println!(
231            "{BOLD}{}t{}r{}u{}e{}c{}o{}l{}o{}r{} {BOLD}{}r{}a{}i{}n{}b{}o{}w{}",
232            truecolor(255, 0, 0),
233            truecolor(170, 0, 0),
234            truecolor(90, 0, 0),
235            truecolor(30, 0, 0),
236            truecolor(0, 30, 0),
237            truecolor(0, 90, 0),
238            truecolor(0, 170, 0),
239            truecolor(0, 200, 0),
240            truecolor(0, 255, 0),
241            RESET,
242            truecolor_bg(0, 255, 0),
243            truecolor_bg(0, 150, 0),
244            truecolor_bg(0, 50, 0),
245            truecolor_bg(0, 0, 50),
246            truecolor_bg(0, 0, 150),
247            truecolor_bg(0, 0, 170),
248            truecolor_bg(0, 0, 255),
249            RESET,
250        );
251        println!("hidden: {HIDDEN}hidden{NOT_HIDDEN} revealed");
252        println!("{}green fg {}reset fg", truecolor(0, 255, 0),    DEFAULT);
253        println!("{}green bg {}reset bg", truecolor_bg(0, 255, 0), DEFAULT_BG);
254        println!();
255
256        println!("{GREEN}ok{RESET}");           // prints a green "ok"
257        println!("{BOLD}{RED}error!{RESET}");   // prints a bold, red "error!"
258        println!("{BLUE_BG}cloud{RESET}");      // prints
259        println!();
260
261        println!("{}{}example text{RESET}", color_256(237), color_256_bg(214));
262        println!("{}{}truecolor text{RESET}", truecolor(127, 45, 68), truecolor_bg(0, 255, 255));
263        println!();
264    }
265}
266
flower_pot/lib.rs

flower_pot/
lib.rs
