1NAME
2 Color::ANSI::Util - Routines for dealing with ANSI colors
3
4VERSION
5 This document describes version 0.164 of Color::ANSI::Util (from Perl
6 distribution Color-ANSI-Util), released on 2020-06-09.
7
8SYNOPSIS
9 use Color::ANSI::Util qw(
10 ansifg
11 ansibg
12 );
13
14 say ansifg("f0c010"); # => "\e[33;1m" (on 16-color terminal)
15 # => "\e[38;5;11m" (on 256-color terminal)
16 # => "\e[38;2;240;192;16m" (on 24-bit-color terminal)
17
18 say ansibg("ff5f87"); # => "\e[47m" (on 16-color terminal)
19 # => "\e[48;5;7m" (on 256-color terminal)
20 # => "\e[48;2;255;95;135m" (on 24-bit-color terminal)
21
22 There are a bunch of other exportable functions too, mostly for
23 converting between RGB and ANSI color (16/256/24bit color depth).
24
25DESCRIPTION
26 This module provides routines for dealing with ANSI colors. The two main
27 functions are "ansifg" and "ansibg". With those functions, you can
28 specify colors in RGB and let it output the correct ANSI color escape
29 code according to the color depth support of the terminal (whether
30 16-color, 256-color, or 24bit). There are other functions to convert RGB
31 to ANSI in specific color depths, or reverse functions to convert from
32 ANSI to RGB codes.
33
34 Keywords: xterm, xterm-256color, terminal
35
36BUGS/NOTES
37 Algorithm for finding closest indexed color from RGB color currently not
38 very efficient. Probably can add some threshold square distance, below
39 which we can shortcut to the final answer.
40
41FUNCTIONS
42 ansi16_to_rgb
43 Usage:
44
45 ansi16_to_rgb($color) -> color::rgb24
46
47 Convert ANSI-16 color to RGB.
48
49 Returns 6-hexdigit, e.g. 'ff00cc'.
50
51 This function is not exported by default, but exportable.
52
53 Arguments ('*' denotes required arguments):
54
55 * $color* => *color::ansi16*
56
57 Return value: (color::rgb24)
58
59 ansi256_to_rgb
60 Usage:
61
62 ansi256_to_rgb($color) -> color::rgb24
63
64 Convert ANSI-256 color to RGB.
65
66 This function is not exported by default, but exportable.
67
68 Arguments ('*' denotes required arguments):
69
70 * $color* => *color::ansi256*
71
72 Return value: (color::rgb24)
73
74 rgb_to_ansi16
75 Usage:
76
77 rgb_to_ansi16($color) -> color::ansi16
78
79 Convert RGB to ANSI-16 color.
80
81 This function is not exported by default, but exportable.
82
83 Arguments ('*' denotes required arguments):
84
85 * $color* => *color::rgb24*
86
87 Return value: (color::ansi16)
88
89 rgb_to_ansi16_bg_code
90 Usage:
91
92 rgb_to_ansi16_bg_code($color) -> str
93
94 Convert RGB to ANSI-16 color escape sequence to change background color.
95
96 This function is not exported by default, but exportable.
97
98 Arguments ('*' denotes required arguments):
99
100 * $color* => *color::rgb24*
101
102 Return value: (str)
103
104 rgb_to_ansi16_fg_code
105 Usage:
106
107 rgb_to_ansi16_fg_code($color) -> str
108
109 Convert RGB to ANSI-16 color escape sequence to change foreground color.
110
111 This function is not exported by default, but exportable.
112
113 Arguments ('*' denotes required arguments):
114
115 * $color* => *color::rgb24*
116
117 Return value: (str)
118
119 rgb_to_ansi24b_bg_code
120 Usage:
121
122 rgb_to_ansi24b_bg_code($color) -> str
123
124 Convert RGB to ANSI 24bit-color escape sequence to change background
125 color.
126
127 This function is not exported by default, but exportable.
128
129 Arguments ('*' denotes required arguments):
130
131 * $color* => *color::rgb24*
132
133 Return value: (str)
134
135 rgb_to_ansi24b_fg_code
136 Usage:
137
138 rgb_to_ansi24b_fg_code($color) -> str
139
140 Convert RGB to ANSI 24bit-color escape sequence to change foreground
141 color.
142
143 This function is not exported by default, but exportable.
144
145 Arguments ('*' denotes required arguments):
146
147 * $color* => *color::rgb24*
148
149 Return value: (str)
150
151 rgb_to_ansi256
152 Usage:
153
154 rgb_to_ansi256($color) -> color::ansi256
155
156 Convert RGB to ANSI-256 color.
157
158 This function is not exported by default, but exportable.
159
160 Arguments ('*' denotes required arguments):
161
162 * $color* => *color::rgb24*
163
164 Return value: (color::ansi256)
165
166 rgb_to_ansi256_bg_code
167 Usage:
168
169 rgb_to_ansi256_bg_code($color) -> str
170
171 Convert RGB to ANSI-256 color escape sequence to change background
172 color.
173
174 This function is not exported by default, but exportable.
175
176 Arguments ('*' denotes required arguments):
177
178 * $color* => *color::rgb24*
179
180 Return value: (str)
181
182 rgb_to_ansi256_fg_code
183 Usage:
184
185 rgb_to_ansi256_fg_code($color) -> str
186
187 Convert RGB to ANSI-256 color escape sequence to change foreground
188 color.
189
190 This function is not exported by default, but exportable.
191
192 Arguments ('*' denotes required arguments):
193
194 * $color* => *color::rgb24*
195
196 Return value: (str)
197
198 rgb_to_ansi_bg_code
199 Usage:
200
201 rgb_to_ansi_bg_code($color) -> str
202
203 Convert RGB to ANSI color escape sequence to change background color.
204
205 Autodetect terminal capability and can return either empty string,
206 16-color, 256-color, or 24bit-code.
207
208 Which color depth used is determined by "COLOR_DEPTH" environment
209 setting or from Term::Detect::Software if that module is available). In
210 other words, this function automatically chooses
211 rgb_to_ansi{24b,256,16}*bg*code().
212
213 This function is not exported by default, but exportable.
214
215 Arguments ('*' denotes required arguments):
216
217 * $color* => *color::rgb24*
218
219 Return value: (str)
220
221 rgb_to_ansi_fg_code
222 Usage:
223
224 rgb_to_ansi_fg_code($color) -> str
225
226 Convert RGB to ANSI color escape sequence to change foreground color.
227
228 Autodetect terminal capability and can return either empty string,
229 16-color, 256-color, or 24bit-code.
230
231 Color depth used is determined by "COLOR_DEPTH" environment setting or
232 from Term::Detect::Software if that module is available. In other words,
233 this function automatically chooses rgb_to_ansi{24b,256,16}*fg*code().
234
235 This function is not exported by default, but exportable.
236
237 Arguments ('*' denotes required arguments):
238
239 * $color* => *color::rgb24*
240
241 Return value: (str)
242
243 ansi16fg($rgb) => STR
244 Alias for rgb_to_ansi16_fg_code().
245
246 ansi16bg($rgb) => STR
247 Alias for rgb_to_ansi16_bg_code().
248
249 ansi256fg($rgb) => STR
250 Alias for rgb_to_ansi256_fg_code().
251
252 ansi256bg($rgb) => STR
253 Alias for rgb_to_ansi256_bg_code().
254
255 ansi24bfg($rgb) => STR
256 Alias for rgb_to_ansi24b_fg_code().
257
258 ansi24bbg($rgb) => STR
259 Alias for rgb_to_ansi24b_bg_code().
260
261 rgb_to_ansi_fg_code($rgb) => STR
262 ansifg($rgb) => STR
263 Alias for rgb_to_ansi_fg_code().
264
265 ansibg($rgb) => STR
266 Alias for rgb_to_ansi_bg_code().
267
268 ansi_reset( [ $conditional ])
269 Returns "\e[0m", which is the ANSI escape sequence to reset color.
270 Normally you print this sequence after you print colored text.
271
272 If $conditional is set to true, then ansi_reset() will return "" if
273 color is disabled.
274
275ENVIRONMENT
276 NO_COLOR
277 Can be used to explicitly disable color. See <https://no-color.org> for
278 more details.
279
280 Observed by: ansi{fg,bg}.
281
282 COLOR => bool
283 Can be used to explicitly disable color by setting it to 0.
284
285 Observed by: ansi{fg,bg}.
286
287 COLOR_DEPTH => INT
288 Can be used to explicitly set color depth instead of trying to detect
289 appropriate color depth.
290
291 Observed by: ansi{fg,bg}.
292
293HOMEPAGE
294 Please visit the project's homepage at
295 <https://metacpan.org/release/Color-ANSI-Util>.
296
297SOURCE
298 Source repository is at
299 <https://github.com/perlancar/perl-Color-ANSI-Util>.
300
301BUGS
302 Please report any bugs or feature requests on the bugtracker website
303 <https://rt.cpan.org/Public/Dist/Display.html?Name=Color-ANSI-Util>
304
305 When submitting a bug or request, please include a test-file or a patch
306 to an existing test-file that illustrates the bug or desired feature.
307
308SEE ALSO
309 Term::ANSIColor
310
311 <http://en.wikipedia.org/wiki/ANSI_escape_code>
312
313AUTHOR
314 perlancar <perlancar@cpan.org>
315
316COPYRIGHT AND LICENSE
317 This software is copyright (c) 2020, 2019, 2018, 2017, 2016, 2015, 2014,
318 2013 by perlancar@cpan.org.
319
320 This is free software; you can redistribute it and/or modify it under
321 the same terms as the Perl 5 programming language system itself.
322
323