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). No support for cursor movement or any other control codes.
5//!
6//! This crate provides constant bindings for text-styling ANSI control codes like `BOLD` (bound to the string `\x1b[1m`) and `GREEN` (bound to `\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//! It also provides functions to 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 functions that invoke truecolor functionality for terminals that support it:
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!("{}{}example text{RESET}", truecolor(127, 45, 68), truecolor_bg(0, 255, 255));
44//!
45//! ```
46//!
47//! The functions `color_256`, `color_256_bg`, `truecolor`, and `truecolor_bg` 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 describing what it wants (such as "make the following text bold" or "make the following text green") 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, all text that follows it is styled in the manner requested. If you want to go back to unstyled text, output the `RESET` code or one of the more specific style-resetting codes such as `NOT_UNDERLINED`.
52//!
53//! The list of control codes is taken from [the Wikipedia page on ANSI control codes](https://en.wikipedia.org/wiki/ANSI_escape_code). Codes which are not widely supported (as reported by Wikipedia) are marked as such below.
54
55// Styles: 0-29.
56
57/// Unset all styles and return to default text formatting.
58pub const RESET: &'static str = "\x1b[0m";
59/// Make the following text bold.
60pub const BOLD: &'static str = "\x1b[1m";
61/// Make the following text dim.
62pub const DIM: &'static str = "\x1b[2m";
63/// Make the following text italic.
64pub const ITALIC: &'static str = "\x1b[3m";
65/// Underline the following text.
66pub const UNDERLINE: &'static str = "\x1b[4m";
67/// Make the following text blink slowly.
68pub const SLOW_BLINK: &'static str = "\x1b[5m";
69/// Make the following text blink quickly. Not widely supported according to Wikipedia.
70pub const RAPID_BLINK: &'static str = "\x1b[6m";
71/// Swap the current foreground color and current background color for the following text.
72pub const INVERTED: &'static str = "\x1b[7m";
73/// Hide the following text. Not widely supported according to Wikipedia.
74pub const HIDDEN: &'static str = "\x1b[8m";
75/// Make the following text strikethrough. Not supported in Terminal.app according to Wikipedia.
76pub const STRIKETHROUGH: &'static str = "\x1b[9m";
77/// Switch to the default font.
78pub const DEFAULT_FONT: &'static str = "\x1b[10m";
79/// Switch to alternative font #1.
80pub const ALT_FONT_1: &'static str = "\x1b[11m";
81/// Switch to alternative font #2.
82pub const ALT_FONT_2: &'static str = "\x1b[12m";
83/// Switch to alternative font #3.
84pub const ALT_FONT_3: &'static str = "\x1b[13m";
85/// Switch to alternative font #4.
86pub const ALT_FONT_4: &'static str = "\x1b[14m";
87/// Switch to alternative font #5.
88pub const ALT_FONT_5: &'static str = "\x1b[15m";
89/// Switch to alternative font #6.
90pub const ALT_FONT_6: &'static str = "\x1b[16m";
91/// Switch to alternative font #7.
92pub const ALT_FONT_7: &'static str = "\x1b[17m";
93/// Switch to alternative font #8.
94pub const ALT_FONT_8: &'static str = "\x1b[18m";
95/// Switch to alternative font #9.
96pub const ALT_FONT_9: &'static str = "\x1b[19m";
97/// Switch to Fraktur font. Rarely supported according to Wikipedia.
98pub const FRAKTUR: &'static str = "\x1b[20m";
99/// Double-underline the following text. WARNING: this constant contains the exact same control
100/// code as the constant `NOT_BOLD`, because different terminals interpret the code to mean
101/// different things. If you use either constant, be aware that your text may be rendered
102/// differently by different terminals.
103pub const DOUBLE_UNDERLINE: &'static str = "\x1b[21m";
104/// Make the following text not bold. WARNING: this constant contains the exact same control
105/// code as the constant `DOUBLE_UNDERLINE`, because different terminals interpret the code to mean
106/// different things. If you use either constant, be aware that your text may be rendered
107/// differently by different terminals.
108pub const NOT_BOLD: &'static str = "\x1b[21m";
109/// Return to ordinary intensity (neither bold nor dim) for the following text.
110pub const NORMAL_INTENSITY: &'static str = "\x1b[22m";
111/// Make the following text neither bold nor italic.
112pub const NEITHER_BOLD_NOR_ITALIC: &'static str = "\x1b[23m";
113/// Make the following text not underlined.
114pub const NOT_UNDERLINED: &'static str = "\x1b[24m";
115/// Make the following text not blink.
116pub const NOT_BLINKING: &'static str = "\x1b[25m";
117/// Use a font with proportional spacing (i.e., a non-monospace font) for the following text.
118/// Rarely supported according to Wikipedia.
119pub const PROPORTIONAL_SPACING: &'static str = "\x1b[26m";
120/// Unswap the foreground and background colors for the following text.
121pub const NOT_INVERTED: &'static str = "\x1b[27m";
122/// Make the following text not hidden.
123pub const NOT_HIDDEN: &'static str = "\x1b[28m";
124/// Make the following text not strikethrough.
125pub const NOT_STRIKETHROUGH: &'static str = "\x1b[29m";
126
127/// Set forground color to black for the following text.
128pub const BLACK: &'static str = "\x1b[30m";
129/// Set foreground color to red for the following text.
130pub const RED: &'static str = "\x1b[31m";
131/// Set foreground color to green for the following text.
132pub const GREEN: &'static str = "\x1b[32m";
133/// Set foreground color to yellow for the following text.
134pub const YELLOW: &'static str = "\x1b[33m";
135/// Set foreground color to blue for the following text.
136pub const BLUE: &'static str = "\x1b[34m";
137/// Set foreground color to purple for the following text.
138pub const PURPLE: &'static str = "\x1b[35m";
139/// Set foreground color to cyan for the following text.
140pub const CYAN: &'static str = "\x1b[36m";
141/// Set foreground color to white for the following text.
142pub const WHITE: &'static str = "\x1b[37m";
143
144/// Set the foreground color for the following text to the *n*th color in the 256-color palette. Commonly, the set of 256 available colors consists of the 8 named foreground colors, the 8 bright versions of these colors, a 6×6×6 RGB cube (for a total of 216 colors distributed evenly across RGB-space), and then a scale of 24 shades of gray. Different terminals may differ in what colors they provide here.
145
146pub fn color_256(n: u8) -> String {
147 format!("\x1b[38;5;{n}m")
148}
149
150/// Set the foreground color to the RGB value (r, g, b). Not supported on all terminals. Terminals which do support this feature are called "truecolor terminals".
151
152pub fn truecolor(r: u8, g: u8, b: u8) -> String {
153 format!("\x1b[38;2;{r};{g};{b}m")
154}
155
156/// Return to the default foreground color for the following text.
157pub const DEFAULT: &'static str = "\x1b[39m";
158
159/// Set background color to black for the following text.
160pub const BLACK_BG: &'static str = "\x1b[40m";
161/// Set background color to red for the following text.
162pub const RED_BG: &'static str = "\x1b[41m";
163/// Set background color to green for the following text.
164pub const GREEN_BG: &'static str = "\x1b[42m";
165/// Set background color to yellow for the following text.
166pub const YELLOW_BG: &'static str = "\x1b[43m";
167/// Set background color to blue for the following text.
168pub const BLUE_BG: &'static str = "\x1b[44m";
169/// Set background color to purple for the following text.
170pub const PURPLE_BG: &'static str = "\x1b[45m";
171/// Set background color to cyan for the following text.
172pub const CYAN_BG: &'static str = "\x1b[46m";
173/// Set background color to white for the following text.
174pub const WHITE_BG: &'static str = "\x1b[47m";
175
176/// Set the background color for the following text to the *n*th color in the 256-color palette. Commonly, the set of 256 available colors consists of the 8 named background colors, the 8 bright versions of these colors, a 6×6×6 RGB cube (for a total of 216 colors distributed evenly across RGB-space), and then a scale of 24 shades of gray. Different terminals may differ in what colors they provide here.
177
178pub fn color_256_bg(n: u8) -> String {
179 format!("\x1b[48;5;{n}m")
180}
181
182/// Set the background color to the RGB value (r, g, b). Not supported on all terminals. Terminals which do support this feature are called "truecolor terminals".
183
184pub fn truecolor_bg(r: u8, g: u8, b: u8) -> String {
185 format!("\x1b[48;2;{r};{g};{b}m")
186}
187
188/// Return to the default background color for the following text.
189pub const DEFAULT_BG: &'static str = "\x1b[49m";
190
191/// Return to a non-proportionally spaced font for the following text. Rarely meaningful because
192/// the `PROPORTIONAL_SPACING` control code is rarely supported to begin with.
193pub const NO_PROPORTIONAL_SPACING: &'static str = "\x1b[50m";
194/// Frame the following text.
195pub const FRAMED: &'static str = "\x1b[51m";
196/// Encircle the following text.
197pub const ENCIRCLED: &'static str = "\x1b[52m";
198/// Add an overline to the following text.
199pub const OVERLINE: &'static str = "\x1b[53m";
200/// Make the following text neither framed nor encircled.
201pub const NEITHER_FRAMED_NOR_ENCIRCLED:
202 &'static str = "\x1b[54m";
203/// Make the following text not overlined.
204pub const NOT_OVERLINED: &'static str = "\x1b[55m";
205
206/// Set the foreground color to bright black for the following text.
207pub const BRIGHT_BLACK: &'static str = "\x1b[90m";
208/// Set the foreground color to bright red for the following text.
209pub const BRIGHT_RED: &'static str = "\x1b[91m";
210/// Set the foreground color to bright green for the following text.
211pub const BRIGHT_GREEN: &'static str = "\x1b[92m";
212/// Set the foreground color to bright yellow for the following text.
213pub const BRIGHT_YELLOW: &'static str = "\x1b[93m";
214/// Set the foreground color to bright blue for the following text.
215pub const BRIGHT_BLUE: &'static str = "\x1b[94m";
216/// Set the foreground color to bright purple for the following text.
217pub const BRIGHT_PURPLE: &'static str = "\x1b[95m";
218/// Set the foreground color to bright cyan for the following text.
219pub const BRIGHT_CYAN: &'static str = "\x1b[96m";
220/// Set the foreground color to bright white for the following text.
221pub const BRIGHT_WHITE: &'static str = "\x1b[97m";
222
223/// Set the background color to bright black for the following text.
224pub const BRIGHT_BLACK_BG: &'static str = "\x1b[100m";
225/// Set the background color to bright red for the following text.
226pub const BRIGHT_RED_BG: &'static str = "\x1b[101m";
227/// Set the background color to bright green for the following text.
228pub const BRIGHT_GREEN_BG: &'static str = "\x1b[102m";
229/// Set the background color to bright yellow for the following text.
230pub const BRIGHT_YELLOW_BG: &'static str = "\x1b[103m";
231/// Set the background color to bright blue for the following text.
232pub const BRIGHT_BLUE_BG: &'static str = "\x1b[104m";
233/// Set the background color to bright purple for the following text.
234pub const BRIGHT_PURPLE_BG: &'static str = "\x1b[105m";
235/// Set the background color to bright cyan for the following text.
236pub const BRIGHT_CYAN_BG: &'static str = "\x1b[106m";
237/// Set the background color to bright white for the following text.
238pub const BRIGHT_WHITE_BG: &'static str = "\x1b[107m";
239
240// Test (requires manual inspection of outputs).
241
242#[cfg(test)]
243mod tests {
244 use super::*;
245
246 #[test]
247 fn print_and_verify_visually() {
248 println!();
249 println!("{GREEN}green{RESET}");
250 println!("{BOLD}{RED}BOLD RED{RESET}");
251 println!("normal {WHITE}white {BRIGHT_WHITE}bright white{RESET}");
252 println!("{BLUE}blue {BRIGHT_BLUE}bright blue{RESET}");
253 println!("normal {ITALIC}italic {BOLD}and bold {UNDERLINE}and underline{RESET}");
254 println!("normal {DOUBLE_UNDERLINE}double underline{RESET}");
255 println!("normal {ENCIRCLED}encircled{RESET}");
256 println!("normal {FRAMED}framed{RESET}");
257 println!("normal {OVERLINE}overline{RESET}");
258
259 println!(
260 "{}g{}r{}e{}y{}s{}c{}a{}l{}e{} {}c{}o{}l{}o{}r{}s{}",
261 color_256(232),
262 color_256(235),
263 color_256(238),
264 color_256(241),
265 color_256(244),
266 color_256(247),
267 color_256(250),
268 color_256(253),
269 color_256(255),
270 RESET,
271 color_256_bg(255),
272 color_256_bg(251),
273 color_256_bg(247),
274 color_256_bg(243),
275 color_256_bg(239),
276 color_256_bg(235),
277 RESET,
278 );
279
280 println!(
281 "{}r{}a{}i{}n{}b{}o{}w{}i{}c{} {}c{}o{}l{}o{}r{}s{}",
282 color_256(132),
283 color_256(135),
284 color_256(138),
285 color_256(141),
286 color_256(144),
287 color_256(147),
288 color_256(150),
289 color_256(153),
290 color_256(155),
291 RESET,
292 color_256_bg(155),
293 color_256_bg(151),
294 color_256_bg(147),
295 color_256_bg(143),
296 color_256_bg(139),
297 color_256_bg(135),
298 RESET,
299 );
300
301 println!(
302 "{BOLD}{}t{}r{}u{}e{}c{}o{}l{}o{}r{} {BOLD}{}r{}a{}i{}n{}b{}o{}w{}",
303 truecolor(255, 0, 0),
304 truecolor(170, 0, 0),
305 truecolor(90, 0, 0),
306 truecolor(30, 0, 0),
307 truecolor(0, 30, 0),
308 truecolor(0, 90, 0),
309 truecolor(0, 170, 0),
310 truecolor(0, 200, 0),
311 truecolor(0, 255, 0),
312 RESET,
313 truecolor_bg(0, 255, 0),
314 truecolor_bg(0, 150, 0),
315 truecolor_bg(0, 50, 0),
316 truecolor_bg(0, 0, 50),
317 truecolor_bg(0, 0, 150),
318 truecolor_bg(0, 0, 170),
319 truecolor_bg(0, 0, 255),
320 RESET,
321 );
322
323 println!("hidden: {HIDDEN}hidden{NOT_HIDDEN} revealed");
324 println!("{}green fg {}reset fg", truecolor(0, 255, 0), DEFAULT);
325 println!("{}green bg {}reset bg", truecolor_bg(0, 255, 0), DEFAULT_BG);
326 println!();
327
328 println!("{GREEN}ok{RESET}"); // prints a green "ok"
329 println!("{BOLD}{RED}error!{RESET}"); // prints a bold, red "error!"
330 println!("{BLUE_BG}cloud{RESET}"); // prints
331 println!();
332
333 println!("{}{}example text{RESET}", color_256(237), color_256_bg(214));
334 println!("{}{}truecolor text{RESET}", truecolor(127, 45, 68), truecolor_bg(0, 255, 255));
335 println!();
336
337 println!("{SLOW_BLINK}slow blink{RESET}");
338 println!("{RAPID_BLINK}rapid blink{RESET}");
339 println!("{ALT_FONT_1}alt font 1{RESET}");
340 println!("{ALT_FONT_2}alt font 2{RESET}");
341 println!("{ALT_FONT_3}alt font 3{RESET}");
342 println!("{FRAKTUR}Fraktur font{RESET}");
343 println!("{DEFAULT_FONT}default font{RESET}");
344 println!("{INVERTED}{GREEN}green fg but it's bg{RESET}");
345 println!();
346 }
347}
348