Color::ANSI::Util(3pm)

1Color::ANSI::Util(3)  User Contributed Perl Documentation Color::ANSI::Util(3)
2
3
4

NAME

6       Color::ANSI::Util - Routines for dealing with ANSI colors
7

VERSION

9       This document describes version 0.164 of Color::ANSI::Util (from Perl
10       distribution Color-ANSI-Util), released on 2020-06-09.
11

SYNOPSIS

13        use Color::ANSI::Util qw(
14            ansifg
15            ansibg
16        );
17
18        say ansifg("f0c010"); # => "\e[33;1m" (on 16-color terminal)
19                              # => "\e[38;5;11m" (on 256-color terminal)
20                              # => "\e[38;2;240;192;16m" (on 24-bit-color terminal)
21
22        say ansibg("ff5f87"); # => "\e[47m" (on 16-color terminal)
23                              # => "\e[48;5;7m" (on 256-color terminal)
24                              # => "\e[48;2;255;95;135m" (on 24-bit-color terminal)
25
26       There are a bunch of other exportable functions too, mostly for
27       converting between RGB and ANSI color (16/256/24bit color depth).
28

DESCRIPTION

30       This module provides routines for dealing with ANSI colors. The two
31       main functions are "ansifg" and "ansibg". With those functions, you can
32       specify colors in RGB and let it output the correct ANSI color escape
33       code according to the color depth support of the terminal (whether
34       16-color, 256-color, or 24bit).  There are other functions to convert
35       RGB to ANSI in specific color depths, or reverse functions to convert
36       from ANSI to RGB codes.
37
38       Keywords: xterm, xterm-256color, terminal
39

BUGS/NOTES

41       Algorithm for finding closest indexed color from RGB color currently
42       not very efficient. Probably can add some threshold square distance,
43       below which we can shortcut to the final answer.
44

FUNCTIONS

46   ansi16_to_rgb
47       Usage:
48
49        ansi16_to_rgb($color) -> color::rgb24
50
51       Convert ANSI-16 color to RGB.
52
53       Returns 6-hexdigit, e.g. 'ff00cc'.
54
55       This function is not exported by default, but exportable.
56
57       Arguments ('*' denotes required arguments):
58
59       •   $color* => color::ansi16
60
61       Return value:  (color::rgb24)
62
63   ansi256_to_rgb
64       Usage:
65
66        ansi256_to_rgb($color) -> color::rgb24
67
68       Convert ANSI-256 color to RGB.
69
70       This function is not exported by default, but exportable.
71
72       Arguments ('*' denotes required arguments):
73
74       •   $color* => color::ansi256
75
76       Return value:  (color::rgb24)
77
78   rgb_to_ansi16
79       Usage:
80
81        rgb_to_ansi16($color) -> color::ansi16
82
83       Convert RGB to ANSI-16 color.
84
85       This function is not exported by default, but exportable.
86
87       Arguments ('*' denotes required arguments):
88
89       •   $color* => color::rgb24
90
91       Return value:  (color::ansi16)
92
93   rgb_to_ansi16_bg_code
94       Usage:
95
96        rgb_to_ansi16_bg_code($color) -> str
97
98       Convert RGB to ANSI-16 color escape sequence to change background
99       color.
100
101       This function is not exported by default, but exportable.
102
103       Arguments ('*' denotes required arguments):
104
105       •   $color* => color::rgb24
106
107       Return value:  (str)
108
109   rgb_to_ansi16_fg_code
110       Usage:
111
112        rgb_to_ansi16_fg_code($color) -> str
113
114       Convert RGB to ANSI-16 color escape sequence to change foreground
115       color.
116
117       This function is not exported by default, but exportable.
118
119       Arguments ('*' denotes required arguments):
120
121       •   $color* => color::rgb24
122
123       Return value:  (str)
124
125   rgb_to_ansi24b_bg_code
126       Usage:
127
128        rgb_to_ansi24b_bg_code($color) -> str
129
130       Convert RGB to ANSI 24bit-color escape sequence to change background
131       color.
132
133       This function is not exported by default, but exportable.
134
135       Arguments ('*' denotes required arguments):
136
137       •   $color* => color::rgb24
138
139       Return value:  (str)
140
141   rgb_to_ansi24b_fg_code
142       Usage:
143
144        rgb_to_ansi24b_fg_code($color) -> str
145
146       Convert RGB to ANSI 24bit-color escape sequence to change foreground
147       color.
148
149       This function is not exported by default, but exportable.
150
151       Arguments ('*' denotes required arguments):
152
153       •   $color* => color::rgb24
154
155       Return value:  (str)
156
157   rgb_to_ansi256
158       Usage:
159
160        rgb_to_ansi256($color) -> color::ansi256
161
162       Convert RGB to ANSI-256 color.
163
164       This function is not exported by default, but exportable.
165
166       Arguments ('*' denotes required arguments):
167
168       •   $color* => color::rgb24
169
170       Return value:  (color::ansi256)
171
172   rgb_to_ansi256_bg_code
173       Usage:
174
175        rgb_to_ansi256_bg_code($color) -> str
176
177       Convert RGB to ANSI-256 color escape sequence to change background
178       color.
179
180       This function is not exported by default, but exportable.
181
182       Arguments ('*' denotes required arguments):
183
184       •   $color* => color::rgb24
185
186       Return value:  (str)
187
188   rgb_to_ansi256_fg_code
189       Usage:
190
191        rgb_to_ansi256_fg_code($color) -> str
192
193       Convert RGB to ANSI-256 color escape sequence to change foreground
194       color.
195
196       This function is not exported by default, but exportable.
197
198       Arguments ('*' denotes required arguments):
199
200       •   $color* => color::rgb24
201
202       Return value:  (str)
203
204   rgb_to_ansi_bg_code
205       Usage:
206
207        rgb_to_ansi_bg_code($color) -> str
208
209       Convert RGB to ANSI color escape sequence to change background color.
210
211       Autodetect terminal capability and can return either empty string,
212       16-color, 256-color, or 24bit-code.
213
214       Which color depth used is determined by "COLOR_DEPTH" environment
215       setting or from Term::Detect::Software if that module is available). In
216       other words, this function automatically chooses
217       rgb_to_ansi{24b,256,16}bgcode().
218
219       This function is not exported by default, but exportable.
220
221       Arguments ('*' denotes required arguments):
222
223       •   $color* => color::rgb24
224
225       Return value:  (str)
226
227   rgb_to_ansi_fg_code
228       Usage:
229
230        rgb_to_ansi_fg_code($color) -> str
231
232       Convert RGB to ANSI color escape sequence to change foreground color.
233
234       Autodetect terminal capability and can return either empty string,
235       16-color, 256-color, or 24bit-code.
236
237       Color depth used is determined by "COLOR_DEPTH" environment setting or
238       from Term::Detect::Software if that module is available. In other
239       words, this function automatically chooses
240       rgb_to_ansi{24b,256,16}fgcode().
241
242       This function is not exported by default, but exportable.
243
244       Arguments ('*' denotes required arguments):
245
246       •   $color* => color::rgb24
247
248       Return value:  (str)
249
250   ansi16fg($rgb) => STR
251       Alias for rgb_to_ansi16_fg_code().
252
253   ansi16bg($rgb) => STR
254       Alias for rgb_to_ansi16_bg_code().
255
256   ansi256fg($rgb) => STR
257       Alias for rgb_to_ansi256_fg_code().
258
259   ansi256bg($rgb) => STR
260       Alias for rgb_to_ansi256_bg_code().
261
262   ansi24bfg($rgb) => STR
263       Alias for rgb_to_ansi24b_fg_code().
264
265   ansi24bbg($rgb) => STR
266       Alias for rgb_to_ansi24b_bg_code().
267
268   rgb_to_ansi_fg_code($rgb) => STR
269   ansifg($rgb) => STR
270       Alias for rgb_to_ansi_fg_code().
271
272   ansibg($rgb) => STR
273       Alias for rgb_to_ansi_bg_code().
274
275   ansi_reset( [ $conditional ])
276       Returns "\e[0m", which is the ANSI escape sequence to reset color.
277       Normally you print this sequence after you print colored text.
278
279       If $conditional is set to true, then ansi_reset() will return "" if
280       color is disabled.
281

ENVIRONMENT

283   NO_COLOR
284       Can be used to explicitly disable color. See <https://no-color.org> for
285       more details.
286
287       Observed by: ansi{fg,bg}.
288
289   COLOR => bool
290       Can be used to explicitly disable color by setting it to 0.
291
292       Observed by: ansi{fg,bg}.
293
294   COLOR_DEPTH => INT
295       Can be used to explicitly set color depth instead of trying to detect
296       appropriate color depth.
297
298       Observed by: ansi{fg,bg}.
299

HOMEPAGE

301       Please visit the project's homepage at
302       <https://metacpan.org/release/Color-ANSI-Util>.
303

SOURCE

305       Source repository is at
306       <https://github.com/perlancar/perl-Color-ANSI-Util>.
307

BUGS

309       Please report any bugs or feature requests on the bugtracker website
310       <https://rt.cpan.org/Public/Dist/Display.html?Name=Color-ANSI-Util>
311
312       When submitting a bug or request, please include a test-file or a patch
313       to an existing test-file that illustrates the bug or desired feature.
314

AUTHOR

321       perlancar <perlancar@cpan.org>
322

COPYRIGHT AND LICENSE

324       This software is copyright (c) 2020, 2019, 2018, 2017, 2016, 2015,
325       2014, 2013 by perlancar@cpan.org.
326
327       This is free software; you can redistribute it and/or modify it under
328       the same terms as the Perl 5 programming language system itself.
329
330
331
332perl v5.38.0                      2023-07-20              Color::ANSI::Util(3)