1Term::ANSIColor(3)    User Contributed Perl Documentation   Term::ANSIColor(3)
2
3
4

NAME

6       Term::ANSIColor - Color screen output using ANSI escape sequences
7

SYNOPSIS

9           use Term::ANSIColor;
10           print color('bold blue');
11           print "This text is bold blue.\n";
12           print color('reset');
13           print "This text is normal.\n";
14           print colored("Yellow on magenta.", 'yellow on_magenta'), "\n";
15           print "This text is normal.\n";
16           print colored(['yellow on_magenta'], 'Yellow on magenta.', "\n");
17           print colored(['red on_bright_yellow'], 'Red on bright yellow.', "\n");
18           print colored(['bright_red on_black'], 'Bright red on black.', "\n");
19           print "\n";
20
21           # Map escape sequences back to color names.
22           use Term::ANSIColor 1.04 qw(uncolor);
23           my @names = uncolor('01;31');
24           print join(q{ }, @names), "\n";
25
26           # Strip all color escape sequences.
27           use Term::ANSIColor 2.01 qw(colorstrip);
28           print colorstrip("\e[1mThis is bold\e[0m"), "\n";
29
30           # Determine whether a color is valid.
31           use Term::ANSIColor 2.02 qw(colorvalid);
32           my $valid = colorvalid('blue bold', 'on_magenta');
33           print "Color string is ", $valid ? "valid\n" : "invalid\n";
34
35           # Create new aliases for colors.
36           use Term::ANSIColor 4.00 qw(coloralias);
37           coloralias('alert', 'red');
38           print "Alert is ", coloralias('alert'), "\n";
39           print colored("This is in red.", 'alert'), "\n";
40
41           use Term::ANSIColor qw(:constants);
42           print BOLD, BLUE, "This text is in bold blue.\n", RESET;
43
44           use Term::ANSIColor qw(:constants);
45           {
46               local $Term::ANSIColor::AUTORESET = 1;
47               print BOLD BLUE "This text is in bold blue.\n";
48               print "This text is normal.\n";
49           }
50
51           use Term::ANSIColor 2.00 qw(:pushpop);
52           print PUSHCOLOR RED ON_GREEN "This text is red on green.\n";
53           print PUSHCOLOR BRIGHT_BLUE "This text is bright blue on green.\n";
54           print RESET BRIGHT_BLUE "This text is just bright blue.\n";
55           print POPCOLOR "Back to red on green.\n";
56           print LOCALCOLOR GREEN ON_BLUE "This text is green on blue.\n";
57           print "This text is red on green.\n";
58           {
59               local $Term::ANSIColor::AUTOLOCAL = 1;
60               print ON_BLUE "This text is red on blue.\n";
61               print "This text is red on green.\n";
62           }
63           print POPCOLOR "Back to whatever we started as.\n";
64

DESCRIPTION

66       This module has two interfaces, one through color() and colored() and
67       the other through constants.  It also offers the utility functions
68       uncolor(), colorstrip(), colorvalid(), and coloralias(), which have to
69       be explicitly imported to be used (see "SYNOPSIS").
70
71       If you are using Term::ANSIColor in a console command, consider
72       supporting the CLICOLOR standard.  See "Supporting CLICOLOR" for more
73       information.
74
75       See "COMPATIBILITY" for the versions of Term::ANSIColor that introduced
76       particular features and the versions of Perl that included them.
77
78   Supported Colors
79       Terminal emulators that support color divide into four types: ones that
80       support only eight colors, ones that support sixteen, ones that support
81       256, and ones that support 24-bit color.  This module provides the ANSI
82       escape codes for all of them.  These colors are referred to as ANSI
83       colors 0 through 7 (normal), 8 through 15 (16-color), 16 through 255
84       (256-color), and true color (called direct-color by xterm).
85
86       Unfortunately, interpretation of colors 0 through 7 often depends on
87       whether the emulator supports eight colors or sixteen colors.
88       Emulators that only support eight colors (such as the Linux console)
89       will display colors 0 through 7 with normal brightness and ignore
90       colors 8 through 15, treating them the same as white.  Emulators that
91       support 16 colors, such as gnome-terminal, normally display colors 0
92       through 7 as dim or darker versions and colors 8 through 15 as normal
93       brightness.  On such emulators, the "normal" white (color 7) usually is
94       shown as pale grey, requiring bright white (15) to be used to get a
95       real white color.  Bright black usually is a dark grey color, although
96       some terminals display it as pure black.  Some sixteen-color terminal
97       emulators also treat normal yellow (color 3) as orange or brown, and
98       bright yellow (color 11) as yellow.
99
100       Following the normal convention of sixteen-color emulators, this module
101       provides a pair of attributes for each color.  For every normal color
102       (0 through 7), the corresponding bright color (8 through 15) is
103       obtained by prepending the string "bright_" to the normal color name.
104       For example, "red" is color 1 and "bright_red" is color 9.  The same
105       applies for background colors: "on_red" is the normal color and
106       "on_bright_red" is the bright color.  Capitalize these strings for the
107       constant interface.
108
109       There is unfortunately no way to know whether the current emulator
110       supports more than eight colors, which makes the choice of colors
111       difficult.  The most conservative choice is to use only the regular
112       colors, which are at least displayed on all emulators.  However, they
113       will appear dark in sixteen-color terminal emulators, including most
114       common emulators in UNIX X environments.  If you know the display is
115       one of those emulators, you may wish to use the bright variants
116       instead.  Even better, offer the user a way to configure the colors for
117       a given application to fit their terminal emulator.
118
119       For 256-color emulators, this module additionally provides "ansi0"
120       through "ansi15", which are the same as colors 0 through 15 in sixteen-
121       color emulators but use the 256-color escape syntax, "grey0" through
122       "grey23" ranging from nearly black to nearly white, and a set of RGB
123       colors.  The RGB colors are of the form "rgbRGB" where R, G, and B are
124       numbers from 0 to 5 giving the intensity of red, green, and blue.  The
125       grey and RGB colors are also available as "ansi16" through "ansi255" if
126       you want simple names for all 256 colors.  "on_" variants of all of
127       these colors are also provided.  These colors may be ignored completely
128       on non-256-color terminals or may be misinterpreted and produce random
129       behavior.  Additional attributes such as blink, italic, or bold may not
130       work with the 256-color palette.
131
132       For true color emulators, this module supports attributes of the form
133       "rNNNgNNNbNNN" and "on_rNNNgNNNbNNN" for all values of NNN between 0
134       and 255.  These represent foreground and background colors,
135       respectively, with the RGB values given by the NNN numbers.  These
136       colors may be ignored completely on non-true-color terminals or may be
137       misinterpreted and produce random behavior.
138
139   Function Interface
140       The function interface uses attribute strings to describe the colors
141       and text attributes to assign to text.  The recognized non-color
142       attributes are clear, reset, bold, dark, faint, italic, underline,
143       underscore, blink, reverse, and concealed.  Clear and reset (reset to
144       default attributes), dark and faint (dim and saturated), and underline
145       and underscore are equivalent, so use whichever is the most intuitive
146       to you.
147
148       Note that not all attributes are supported by all terminal types, and
149       some terminals may not support any of these sequences.  Dark and faint,
150       italic, blink, and concealed in particular are frequently not
151       implemented.
152
153       The recognized normal foreground color attributes (colors 0 to 7) are:
154
155         black  red  green  yellow  blue  magenta  cyan  white
156
157       The corresponding bright foreground color attributes (colors 8 to 15)
158       are:
159
160         bright_black  bright_red      bright_green  bright_yellow
161         bright_blue   bright_magenta  bright_cyan   bright_white
162
163       The recognized normal background color attributes (colors 0 to 7) are:
164
165         on_black  on_red      on_green  on yellow
166         on_blue   on_magenta  on_cyan   on_white
167
168       The recognized bright background color attributes (colors 8 to 15) are:
169
170         on_bright_black  on_bright_red      on_bright_green  on_bright_yellow
171         on_bright_blue   on_bright_magenta  on_bright_cyan   on_bright_white
172
173       For 256-color terminals, the recognized foreground colors are:
174
175         ansi0 .. ansi255
176         grey0 .. grey23
177
178       plus "rgbRGB" for R, G, and B values from 0 to 5, such as "rgb000" or
179       "rgb515".  Similarly, the recognized background colors are:
180
181         on_ansi0 .. on_ansi255
182         on_grey0 .. on_grey23
183
184       plus "on_rgbRGB" for R, G, and B values from 0 to 5.
185
186       For true color terminals, the recognized foreground colors are
187       "rRRRgGGGbBBB" for RRR, GGG, and BBB values between 0 and 255.
188       Similarly, the recognized background colors are "on_rRRRgGGGbBBB" for
189       RRR, GGG, and BBB values between 0 and 255.
190
191       For any of the above listed attributes, case is not significant.
192
193       Attributes, once set, last until they are unset (by printing the
194       attribute "clear" or "reset").  Be careful to do this, or otherwise
195       your attribute will last after your script is done running, and people
196       get very annoyed at having their prompt and typing changed to weird
197       colors.
198
199       color(ATTR[, ATTR ...])
200           color() takes any number of strings as arguments and considers them
201           to be space-separated lists of attributes.  It then forms and
202           returns the escape sequence to set those attributes.  It doesn't
203           print it out, just returns it, so you'll have to print it yourself
204           if you want to.  This is so that you can save it as a string, pass
205           it to something else, send it to a file handle, or do anything else
206           with it that you might care to.  color() throws an exception if
207           given an invalid attribute.
208
209       colored(STRING, ATTR[, ATTR ...])
210       colored(ATTR-REF, STRING[, STRING...])
211           As an aid in resetting colors, colored() takes a scalar as the
212           first argument and any number of attribute strings as the second
213           argument and returns the scalar wrapped in escape codes so that the
214           attributes will be set as requested before the string and reset to
215           normal after the string.  Alternately, you can pass a reference to
216           an array as the first argument, and then the contents of that array
217           will be taken as attributes and color codes and the remainder of
218           the arguments as text to colorize.
219
220           Normally, colored() just puts attribute codes at the beginning and
221           end of the string, but if you set $Term::ANSIColor::EACHLINE to
222           some string, that string will be considered the line delimiter and
223           the attribute will be set at the beginning of each line of the
224           passed string and reset at the end of each line.  This is often
225           desirable if the output contains newlines and you're using
226           background colors, since a background color that persists across a
227           newline is often interpreted by the terminal as providing the
228           default background color for the next line.  Programs like pagers
229           can also be confused by attributes that span lines.  Normally
230           you'll want to set $Term::ANSIColor::EACHLINE to "\n" to use this
231           feature.
232
233           Particularly consider setting $Term::ANSIColor::EACHLINE if you are
234           interleaving output to standard output and standard error and you
235           aren't flushing standard output (via autoflush() or setting $|).
236           If you don't, the code to reset the color may unexpectedly sit in
237           the standard output buffer rather than going to the display,
238           causing standard error output to appear in the wrong color.
239
240       uncolor(ESCAPE)
241           uncolor() performs the opposite translation as color(), turning
242           escape sequences into a list of strings corresponding to the
243           attributes being set by those sequences.  uncolor() will never
244           return "ansi16" through "ansi255", instead preferring the "grey"
245           and "rgb" names (and likewise for "on_ansi16" through
246           "on_ansi255").
247
248       colorstrip(STRING[, STRING ...])
249           colorstrip() removes all color escape sequences from the provided
250           strings, returning the modified strings separately in array context
251           or joined together in scalar context.  Its arguments are not
252           modified.
253
254       colorvalid(ATTR[, ATTR ...])
255           colorvalid() takes attribute strings the same as color() and
256           returns true if all attributes are known and false otherwise.
257
258       coloralias(ALIAS[, ATTR ...])
259           If ATTR is specified, it is interpreted as a list of space-
260           separated strings naming attributes or existing aliases.  In this
261           case, coloralias() sets up an alias of ALIAS for the set of
262           attributes given by ATTR.  From that point forward, ALIAS can be
263           passed into color(), colored(), and colorvalid() and will have the
264           same meaning as the sequence of attributes given in ATTR.  One
265           possible use of this facility is to give more meaningful names to
266           the 256-color RGB colors.  Only ASCII alphanumerics, ".", "_", and
267           "-" are allowed in alias names.
268
269           If ATTR includes aliases, those aliases will be expanded at
270           definition time and their values will be used to define the new
271           alias.  This means that if you define an alias A in terms of
272           another alias B, and then later redefine alias B, the value of
273           alias A will not change.
274
275           If ATTR is not specified, coloralias() returns the standard
276           attribute or attributes to which ALIAS is aliased, if any, or undef
277           if ALIAS does not exist.  If it is aliased to multiple attributes,
278           the return value will be a single string and the attributes will be
279           separated by spaces.
280
281           This is the same facility used by the ANSI_COLORS_ALIASES
282           environment variable (see "ENVIRONMENT" below) but can be used at
283           runtime, not just when the module is loaded.
284
285           Later invocations of coloralias() with the same ALIAS will override
286           earlier aliases.  There is no way to remove an alias.
287
288           Aliases have no effect on the return value of uncolor().
289
290           WARNING: Aliases are global and affect all callers in the same
291           process.  There is no way to set an alias limited to a particular
292           block of code or a particular object.
293
294   Constant Interface
295       Alternately, if you import ":constants", you can use the following
296       constants directly:
297
298         CLEAR           RESET             BOLD            DARK
299         FAINT           ITALIC            UNDERLINE       UNDERSCORE
300         BLINK           REVERSE           CONCEALED
301
302         BLACK           RED               GREEN           YELLOW
303         BLUE            MAGENTA           CYAN            WHITE
304         BRIGHT_BLACK    BRIGHT_RED        BRIGHT_GREEN    BRIGHT_YELLOW
305         BRIGHT_BLUE     BRIGHT_MAGENTA    BRIGHT_CYAN     BRIGHT_WHITE
306
307         ON_BLACK        ON_RED            ON_GREEN        ON_YELLOW
308         ON_BLUE         ON_MAGENTA        ON_CYAN         ON_WHITE
309         ON_BRIGHT_BLACK ON_BRIGHT_RED     ON_BRIGHT_GREEN ON_BRIGHT_YELLOW
310         ON_BRIGHT_BLUE  ON_BRIGHT_MAGENTA ON_BRIGHT_CYAN  ON_BRIGHT_WHITE
311
312       These are the same as color('attribute') and can be used if you prefer
313       typing:
314
315           print BOLD BLUE ON_WHITE "Text", RESET, "\n";
316
317       to
318
319           print colored ("Text", 'bold blue on_white'), "\n";
320
321       (Note that the newline is kept separate to avoid confusing the terminal
322       as described above since a background color is being used.)
323
324       If you import ":constants256", you can use the following constants
325       directly:
326
327         ANSI0 .. ANSI255
328         GREY0 .. GREY23
329
330         RGBXYZ (for X, Y, and Z values from 0 to 5, like RGB000 or RGB515)
331
332         ON_ANSI0 .. ON_ANSI255
333         ON_GREY0 .. ON_GREY23
334
335         ON_RGBXYZ (for X, Y, and Z values from 0 to 5)
336
337       Note that ":constants256" does not include the other constants, so if
338       you want to mix both, you need to include ":constants" as well.  You
339       may want to explicitly import at least "RESET", as in:
340
341           use Term::ANSIColor 4.00 qw(RESET :constants256);
342
343       True color and aliases are not supported by the constant interface.
344
345       When using the constants, if you don't want to have to remember to add
346       the ", RESET" at the end of each print line, you can set
347       $Term::ANSIColor::AUTORESET to a true value.  Then, the display mode
348       will automatically be reset if there is no comma after the constant.
349       In other words, with that variable set:
350
351           print BOLD BLUE "Text\n";
352
353       will reset the display mode afterward, whereas:
354
355           print BOLD, BLUE, "Text\n";
356
357       will not.  If you are using background colors, you will probably want
358       to either use say() (in newer versions of Perl) or print the newline
359       with a separate print statement to avoid confusing the terminal.
360
361       If $Term::ANSIColor::AUTOLOCAL is set (see below), it takes precedence
362       over $Term::ANSIColor::AUTORESET, and the latter is ignored.
363
364       The subroutine interface has the advantage over the constants interface
365       in that only two subroutines are exported into your namespace, versus
366       thirty-eight in the constants interface, and aliases and true color
367       attributes are supported.  On the flip side, the constants interface
368       has the advantage of better compile time error checking, since
369       misspelled names of colors or attributes in calls to color() and
370       colored() won't be caught until runtime whereas misspelled names of
371       constants will be caught at compile time.  So, pollute your namespace
372       with almost two dozen subroutines that you may not even use that often,
373       or risk a silly bug by mistyping an attribute.  Your choice, TMTOWTDI
374       after all.
375
376   The Color Stack
377       You can import ":pushpop" and maintain a stack of colors using
378       PUSHCOLOR, POPCOLOR, and LOCALCOLOR.  PUSHCOLOR takes the attribute
379       string that starts its argument and pushes it onto a stack of
380       attributes.  POPCOLOR removes the top of the stack and restores the
381       previous attributes set by the argument of a prior PUSHCOLOR.
382       LOCALCOLOR surrounds its argument in a PUSHCOLOR and POPCOLOR so that
383       the color resets afterward.
384
385       If $Term::ANSIColor::AUTOLOCAL is set, each sequence of color constants
386       will be implicitly preceded by LOCALCOLOR.  In other words, the
387       following:
388
389           {
390               local $Term::ANSIColor::AUTOLOCAL = 1;
391               print BLUE "Text\n";
392           }
393
394       is equivalent to:
395
396           print LOCALCOLOR BLUE "Text\n";
397
398       If $Term::ANSIColor::AUTOLOCAL is set, it takes precedence over
399       $Term::ANSIColor::AUTORESET, and the latter is ignored.
400
401       When using PUSHCOLOR, POPCOLOR, and LOCALCOLOR, it's particularly
402       important to not put commas between the constants.
403
404           print PUSHCOLOR BLUE "Text\n";
405
406       will correctly push BLUE onto the top of the stack.
407
408           print PUSHCOLOR, BLUE, "Text\n";    # wrong!
409
410       will not, and a subsequent pop won't restore the correct attributes.
411       PUSHCOLOR pushes the attributes set by its argument, which is normally
412       a string of color constants.  It can't ask the terminal what the
413       current attributes are.
414
415   Supporting CLICOLOR
416       <https://bixense.com/clicolors/> proposes a standard for enabling and
417       disabling color output from console commands using two environment
418       variables, CLICOLOR and CLICOLOR_FORCE.  Term::ANSIColor cannot
419       automatically support this standard, since the correct action depends
420       on where the output is going and Term::ANSIColor may be used in a
421       context where colors should always be generated even if CLICOLOR is set
422       in the environment.  But you can use the supported environment variable
423       ANSI_COLORS_DISABLED to implement CLICOLOR in your own programs with
424       code like this:
425
426           if (exists($ENV{CLICOLOR}) && $ENV{CLICOLOR} == 0) {
427               if (!$ENV{CLICOLOR_FORCE}) {
428                   $ENV{ANSI_COLORS_DISABLED} = 1;
429               }
430           }
431
432       If you are using the constant interface, be sure to include this code
433       before you use any color constants (such as at the very top of your
434       script), since this environment variable is only honored the first time
435       a color constant is seen.
436
437       Be aware that this will export ANSI_COLORS_DISABLED to any child
438       processes of your program as well.
439

DIAGNOSTICS

441       Bad color mapping %s
442           (W) The specified color mapping from ANSI_COLORS_ALIASES is not
443           valid and could not be parsed.  It was ignored.
444
445       Bad escape sequence %s
446           (F) You passed an invalid ANSI escape sequence to uncolor().
447
448       Bareword "%s" not allowed while "strict subs" in use
449           (F) You probably mistyped a constant color name such as:
450
451               $Foobar = FOOBAR . "This line should be blue\n";
452
453           or:
454
455               @Foobar = FOOBAR, "This line should be blue\n";
456
457           This will only show up under use strict (another good reason to run
458           under use strict).
459
460       Cannot alias standard color %s
461           (F) The alias name passed to coloralias() matches a standard color
462           name.  Standard color names cannot be aliased.
463
464       Cannot alias standard color %s in %s
465           (W) The same, but in ANSI_COLORS_ALIASES.  The color mapping was
466           ignored.
467
468       Invalid alias name %s
469           (F) You passed an invalid alias name to coloralias().  Alias names
470           must consist only of alphanumerics, ".", "-", and "_".
471
472       Invalid alias name %s in %s
473           (W) You specified an invalid alias name on the left hand of the
474           equal sign in a color mapping in ANSI_COLORS_ALIASES.  The color
475           mapping was ignored.
476
477       Invalid attribute name %s
478           (F) You passed an invalid attribute name to color(), colored(), or
479           coloralias().
480
481       Invalid attribute name %s in %s
482           (W) You specified an invalid attribute name on the right hand of
483           the equal sign in a color mapping in ANSI_COLORS_ALIASES.  The
484           color mapping was ignored.
485
486       Name "%s" used only once: possible typo
487           (W) You probably mistyped a constant color name such as:
488
489               print FOOBAR "This text is color FOOBAR\n";
490
491           It's probably better to always use commas after constant names in
492           order to force the next error.
493
494       No comma allowed after filehandle
495           (F) You probably mistyped a constant color name such as:
496
497               print FOOBAR, "This text is color FOOBAR\n";
498
499           Generating this fatal compile error is one of the main advantages
500           of using the constants interface, since you'll immediately know if
501           you mistype a color name.
502
503       No name for escape sequence %s
504           (F) The ANSI escape sequence passed to uncolor() contains escapes
505           which aren't recognized and can't be translated to names.
506

ENVIRONMENT

508       ANSI_COLORS_ALIASES
509           This environment variable allows the user to specify custom color
510           aliases that will be understood by color(), colored(), and
511           colorvalid().  None of the other functions will be affected, and no
512           new color constants will be created.  The custom colors are aliases
513           for existing color names; no new escape sequences can be
514           introduced.  Only alphanumerics, ".", "_", and "-" are allowed in
515           alias names.
516
517           The format is:
518
519               ANSI_COLORS_ALIASES='newcolor1=oldcolor1,newcolor2=oldcolor2'
520
521           Whitespace is ignored.  The alias value can be a single attribute
522           or a space-separated list of attributes.
523
524           For example the Solarized <https://ethanschoonover.com/solarized>
525           colors can be mapped with:
526
527               ANSI_COLORS_ALIASES='\
528                   base00=bright_yellow, on_base00=on_bright_yellow,\
529                   base01=bright_green,  on_base01=on_bright_green, \
530                   base02=black,         on_base02=on_black,        \
531                   base03=bright_black,  on_base03=on_bright_black, \
532                   base0=bright_blue,    on_base0=on_bright_blue,   \
533                   base1=bright_cyan,    on_base1=on_bright_cyan,   \
534                   base2=white,          on_base2=on_white,         \
535                   base3=bright_white,   on_base3=on_bright_white,  \
536                   orange=bright_red,    on_orange=on_bright_red,   \
537                   violet=bright_magenta,on_violet=on_bright_magenta'
538
539           This environment variable is read and applied when the
540           Term::ANSIColor module is loaded and is then subsequently ignored.
541           Changes to ANSI_COLORS_ALIASES after the module is loaded will have
542           no effect.  See coloralias() for an equivalent facility that can be
543           used at runtime.
544
545       ANSI_COLORS_DISABLED
546           If this environment variable is set to a true value, all of the
547           functions defined by this module (color(), colored(), and all of
548           the constants) will not output any escape sequences and instead
549           will just return the empty string or pass through the original text
550           as appropriate.  This is intended to support easy use of scripts
551           using this module on platforms that don't support ANSI escape
552           sequences.
553
554       NO_COLOR
555           If this environment variable is set to any value, it suppresses
556           generation of escape sequences the same as if ANSI_COLORS_DISABLED
557           is set to a true value.  This implements the
558           <https://no-color.org/> informal standard.  Programs that want to
559           enable color despite NO_COLOR being set will need to unset that
560           environment variable before any constant or function provided by
561           this module is used.
562

COMPATIBILITY

564       Term::ANSIColor was first included with Perl in Perl 5.6.0.
565
566       The uncolor() function and support for ANSI_COLORS_DISABLED were added
567       in Term::ANSIColor 1.04, included in Perl 5.8.0.
568
569       Support for dark was added in Term::ANSIColor 1.08, included in Perl
570       5.8.4.
571
572       The color stack, including the ":pushpop" import tag, PUSHCOLOR,
573       POPCOLOR, LOCALCOLOR, and the $Term::ANSIColor::AUTOLOCAL variable, was
574       added in Term::ANSIColor 2.00, included in Perl 5.10.1.
575
576       colorstrip() was added in Term::ANSIColor 2.01 and colorvalid() was
577       added in Term::ANSIColor 2.02, both included in Perl 5.11.0.
578
579       Support for colors 8 through 15 (the "bright_" variants) was added in
580       Term::ANSIColor 3.00, included in Perl 5.13.3.
581
582       Support for italic was added in Term::ANSIColor 3.02, included in Perl
583       5.17.1.
584
585       Support for colors 16 through 256 (the "ansi", "rgb", and "grey"
586       colors), the ":constants256" import tag, the coloralias() function, and
587       support for the ANSI_COLORS_ALIASES environment variable were added in
588       Term::ANSIColor 4.00, included in Perl 5.17.8.
589
590       $Term::ANSIColor::AUTOLOCAL was changed to take precedence over
591       $Term::ANSIColor::AUTORESET, rather than the other way around, in
592       Term::ANSIColor 4.00, included in Perl 5.17.8.
593
594       "ansi16" through "ansi255", as aliases for the "rgb" and "grey" colors,
595       and the corresponding "on_ansi" names and "ANSI" and "ON_ANSI"
596       constants were added in Term::ANSIColor 4.06, included in Perl 5.25.7.
597
598       Support for true color (the "rNNNgNNNbNNN" and "on_rNNNgNNNbNNN"
599       attributes), defining aliases in terms of other aliases, and aliases
600       mapping to multiple attributes instead of only a single attribute was
601       added in Term::ANSIColor 5.00.
602
603       Support for NO_COLOR was added in Term::ANSIColor 5.01.
604

RESTRICTIONS

606       Both colored() and many uses of the color constants will add the reset
607       escape sequence after a newline.  If a program mixes colored output to
608       standard output with output to standard error, this can result in the
609       standard error text having the wrong color because the reset escape
610       sequence hasn't yet been flushed to the display (since standard output
611       to a terminal is line-buffered by default).  To avoid this, either set
612       autoflush() on STDOUT or set $Term::ANSIColor::EACHLINE to "\n".
613
614       It would be nice if one could leave off the commas around the constants
615       entirely and just say:
616
617           print BOLD BLUE ON_WHITE "Text\n" RESET;
618
619       but the syntax of Perl doesn't allow this.  You need a comma after the
620       string.  (Of course, you may consider it a bug that commas between all
621       the constants aren't required, in which case you may feel free to
622       insert commas unless you're using $Term::ANSIColor::AUTORESET or
623       PUSHCOLOR/POPCOLOR.)
624
625       For easier debugging, you may prefer to always use the commas when not
626       setting $Term::ANSIColor::AUTORESET or PUSHCOLOR/POPCOLOR so that
627       you'll get a fatal compile error rather than a warning.
628
629       It's not possible to use this module to embed formatting and color
630       attributes using Perl formats.  They replace the escape character with
631       a space (as documented in perlform(1)), resulting in garbled output
632       from the unrecognized attribute.  Even if there were a way around that
633       problem, the format doesn't know that the non-printing escape sequence
634       is zero-length and would incorrectly format the output.  For formatted
635       output using color or other attributes, either use sprintf() instead or
636       use formline() and then add the color or other attributes after
637       formatting and before output.
638

NOTES

640       The codes generated by this module are standard terminal control codes,
641       complying with ECMA-048 and ISO 6429 (generally referred to as "ANSI
642       color" for the color codes).  The non-color control codes (bold, dark,
643       italic, underline, and reverse) are part of the earlier ANSI X3.64
644       standard for control sequences for video terminals and peripherals.
645
646       Note that not all displays are ISO 6429-compliant, or even
647       X3.64-compliant (or are even attempting to be so).  This module will
648       not work as expected on displays that do not honor these escape
649       sequences, such as cmd.exe, 4nt.exe, and command.com under either
650       Windows NT or Windows 2000.  They may just be ignored, or they may
651       display as an ESC character followed by some apparent garbage.
652
653       Jean Delvare provided the following table of different common terminal
654       emulators and their support for the various attributes and others have
655       helped me flesh it out:
656
657                     clear    bold     faint   under    blink   reverse  conceal
658        ------------------------------------------------------------------------
659        xterm         yes      yes      no      yes      yes      yes      yes
660        linux         yes      yes      yes    bold      yes      yes      no
661        rxvt          yes      yes      no      yes  bold/black   yes      no
662        dtterm        yes      yes      yes     yes    reverse    yes      yes
663        teraterm      yes    reverse    no      yes    rev/red    yes      no
664        aixterm      kinda   normal     no      yes      no       yes      yes
665        PuTTY         yes     color     no      yes      no       yes      no
666        Windows       yes      no       no      no       no       yes      no
667        Cygwin SSH    yes      yes      no     color    color    color     yes
668        Terminal.app  yes      yes      no      yes      yes      yes      yes
669
670       Windows is Windows telnet, Cygwin SSH is the OpenSSH implementation
671       under Cygwin on Windows NT, and Mac Terminal is the Terminal
672       application in Mac OS X.  Where the entry is other than yes or no, that
673       emulator displays the given attribute as something else instead.  Note
674       that on an aixterm, clear doesn't reset colors; you have to explicitly
675       set the colors back to what you want.  More entries in this table are
676       welcome.
677
678       Support for code 3 (italic) is rare and therefore not mentioned in that
679       table.  It is not believed to be fully supported by any of the
680       terminals listed, although it's displayed as green in the Linux
681       console, but it is reportedly supported by urxvt.
682
683       Note that codes 6 (rapid blink) and 9 (strike-through) are specified in
684       ANSI X3.64 and ECMA-048 but are not commonly supported by most displays
685       and emulators and therefore aren't supported by this module.  ECMA-048
686       also specifies a large number of other attributes, including a sequence
687       of attributes for font changes, Fraktur characters, double-underlining,
688       framing, circling, and overlining.  As none of these attributes are
689       widely supported or useful, they also aren't currently supported by
690       this module.
691
692       Most modern X terminal emulators support 256 colors.  Known to not
693       support those colors are aterm, rxvt, Terminal.app, and TTY/VC.
694
695       For information on true color support in various terminal emulators,
696       see True Colour support <https://gist.github.com/XVilka/8346728>.
697

AUTHORS

699       Original idea (using constants) by Zenin, reimplemented using subs by
700       Russ Allbery <rra@cpan.org>, and then combined with the original idea
701       by Russ with input from Zenin.  256-color support is based on work by
702       Kurt Starsinic.  Russ Allbery now maintains this module.
703
704       PUSHCOLOR, POPCOLOR, and LOCALCOLOR were contributed by openmethods.com
705       voice solutions.
706
708       Copyright 1996-1998, 2000-2002, 2005-2006, 2008-2018, 2020 Russ Allbery
709       <rra@cpan.org>
710
711       Copyright 1996 Zenin
712
713       Copyright 2012 Kurt Starsinic <kstarsinic@gmail.com>
714
715       This program is free software; you may redistribute it and/or modify it
716       under the same terms as Perl itself.
717

SEE ALSO

719       The CPAN module Term::ExtendedColor provides a different and more
720       comprehensive interface for 256-color emulators that may be more
721       convenient.  The CPAN module Win32::Console::ANSI provides ANSI color
722       (and other escape sequence) support in the Win32 Console environment.
723       The CPAN module Term::Chrome provides a different interface using
724       objects and operator overloading.
725
726       ECMA-048 is available on-line (at least at the time of this writing) at
727       <https://www.ecma-international.org/publications/standards/Ecma-048.htm>.
728
729       ISO 6429 is available from ISO for a charge; the author of this module
730       does not own a copy of it.  Since the source material for ISO 6429 was
731       ECMA-048 and the latter is available for free, there seems little
732       reason to obtain the ISO standard.
733
734       The 256-color control sequences are documented at
735       <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html> (search for
736       256-color).
737
738       Information about true color support in various terminal emulators and
739       test programs you can run to check the true color support in your
740       terminal emulator are available at
741       <https://gist.github.com/XVilka/8346728>.
742
743       CLICOLORS <https://bixense.com/clicolors/> and NO_COLOR <https://no-
744       color.org/> are useful standards to be aware of, and ideally follow,
745       for any application using color.  Term::ANSIColor complies with the
746       latter.
747
748       The current version of this module is always available from its web
749       site at <https://www.eyrie.org/~eagle/software/ansicolor/>.  It is also
750       part of the Perl core distribution as of 5.6.0.
751
752
753
754perl v5.30.1                      2020-01-30                Term::ANSIColor(3)
Impressum