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