| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Term::ANSIColor 3perl" |
| 58 |
.TH Term::ANSIColor 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Term::ANSIColor \- Color screen output using ANSI escape sequences |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 11 |
| 68 |
\& use Term::ANSIColor; |
| 69 |
\& print color(\*(Aqbold blue\*(Aq); |
| 70 |
\& print "This text is bold blue.\en"; |
| 71 |
\& print color(\*(Aqreset\*(Aq); |
| 72 |
\& print "This text is normal.\en"; |
| 73 |
\& print colored("Yellow on magenta.", \*(Aqyellow on_magenta\*(Aq), "\en"; |
| 74 |
\& print "This text is normal.\en"; |
| 75 |
\& print colored([\*(Aqyellow on_magenta\*(Aq], \*(AqYellow on magenta.\*(Aq, "\en"); |
| 76 |
\& print colored([\*(Aqred on_bright_yellow\*(Aq], \*(AqRed on bright yellow.\*(Aq, "\en"); |
| 77 |
\& print colored([\*(Aqbright_red on_black\*(Aq], \*(AqBright red on black.\*(Aq, "\en"); |
| 78 |
\& print "\en"; |
| 79 |
\& |
| 80 |
\& # Map escape sequences back to color names. |
| 81 |
\& use Term::ANSIColor 1.04 qw(uncolor); |
| 82 |
\& my @names = uncolor(\*(Aq01;31\*(Aq); |
| 83 |
\& print join(q{ }, @names), "\en"; |
| 84 |
\& |
| 85 |
\& # Strip all color escape sequences. |
| 86 |
\& use Term::ANSIColor 2.01 qw(colorstrip); |
| 87 |
\& print colorstrip("\ee[1mThis is bold\ee[0m"), "\en"; |
| 88 |
\& |
| 89 |
\& # Determine whether a color is valid. |
| 90 |
\& use Term::ANSIColor 2.02 qw(colorvalid); |
| 91 |
\& my $valid = colorvalid(\*(Aqblue bold\*(Aq, \*(Aqon_magenta\*(Aq); |
| 92 |
\& print "Color string is ", $valid ? "valid\en" : "invalid\en"; |
| 93 |
\& |
| 94 |
\& # Create new aliases for colors. |
| 95 |
\& use Term::ANSIColor 4.00 qw(coloralias); |
| 96 |
\& coloralias(\*(Aqalert\*(Aq, \*(Aqred\*(Aq); |
| 97 |
\& print "Alert is ", coloralias(\*(Aqalert\*(Aq), "\en"; |
| 98 |
\& print colored("This is in red.", \*(Aqalert\*(Aq), "\en"; |
| 99 |
\& |
| 100 |
\& use Term::ANSIColor qw(:constants); |
| 101 |
\& print BOLD, BLUE, "This text is in bold blue.\en", RESET; |
| 102 |
\& |
| 103 |
\& use Term::ANSIColor qw(:constants); |
| 104 |
\& { |
| 105 |
\& local $Term::ANSIColor::AUTORESET = 1; |
| 106 |
\& print BOLD BLUE "This text is in bold blue.\en"; |
| 107 |
\& print "This text is normal.\en"; |
| 108 |
\& } |
| 109 |
\& |
| 110 |
\& use Term::ANSIColor 2.00 qw(:pushpop); |
| 111 |
\& print PUSHCOLOR RED ON_GREEN "This text is red on green.\en"; |
| 112 |
\& print PUSHCOLOR BRIGHT_BLUE "This text is bright blue on green.\en"; |
| 113 |
\& print RESET BRIGHT_BLUE "This text is just bright blue.\en"; |
| 114 |
\& print POPCOLOR "Back to red on green.\en"; |
| 115 |
\& print LOCALCOLOR GREEN ON_BLUE "This text is green on blue.\en"; |
| 116 |
\& print "This text is red on green.\en"; |
| 117 |
\& { |
| 118 |
\& local $Term::ANSIColor::AUTOLOCAL = 1; |
| 119 |
\& print ON_BLUE "This text is red on blue.\en"; |
| 120 |
\& print "This text is red on green.\en"; |
| 121 |
\& } |
| 122 |
\& print POPCOLOR "Back to whatever we started as.\en"; |
| 123 |
.Ve |
| 124 |
.SH DESCRIPTION |
| 125 |
.IX Header "DESCRIPTION" |
| 126 |
This module has two interfaces, one through \fBcolor()\fR and \fBcolored()\fR and the |
| 127 |
other through constants. It also offers the utility functions \fBuncolor()\fR, |
| 128 |
\&\fBcolorstrip()\fR, \fBcolorvalid()\fR, and \fBcoloralias()\fR, which have to be explicitly |
| 129 |
imported to be used (see "SYNOPSIS"). |
| 130 |
.PP |
| 131 |
If you are using Term::ANSIColor in a console command, consider supporting the |
| 132 |
CLICOLOR standard. See "Supporting CLICOLOR" for more information. |
| 133 |
.PP |
| 134 |
See "COMPATIBILITY" for the versions of Term::ANSIColor that introduced |
| 135 |
particular features and the versions of Perl that included them. |
| 136 |
.SS "Supported Colors" |
| 137 |
.IX Subsection "Supported Colors" |
| 138 |
Terminal emulators that support color divide into four types: ones that |
| 139 |
support only eight colors, ones that support sixteen, ones that support 256, |
| 140 |
and ones that support 24\-bit color. This module provides the ANSI escape |
| 141 |
codes for all of them. These colors are referred to as ANSI colors 0 through |
| 142 |
7 (normal), 8 through 15 (16\-color), 16 through 255 (256\-color), and true |
| 143 |
color (called direct-color by \fBxterm\fR). |
| 144 |
.PP |
| 145 |
Unfortunately, interpretation of colors 0 through 7 often depends on |
| 146 |
whether the emulator supports eight colors or sixteen colors. Emulators |
| 147 |
that only support eight colors (such as the Linux console) will display |
| 148 |
colors 0 through 7 with normal brightness and ignore colors 8 through 15, |
| 149 |
treating them the same as white. Emulators that support 16 colors, such |
| 150 |
as gnome-terminal, normally display colors 0 through 7 as dim or darker |
| 151 |
versions and colors 8 through 15 as normal brightness. On such emulators, |
| 152 |
the "normal" white (color 7) usually is shown as pale grey, requiring |
| 153 |
bright white (15) to be used to get a real white color. Bright black |
| 154 |
usually is a dark grey color, although some terminals display it as pure |
| 155 |
black. Some sixteen-color terminal emulators also treat normal yellow |
| 156 |
(color 3) as orange or brown, and bright yellow (color 11) as yellow. |
| 157 |
.PP |
| 158 |
Following the normal convention of sixteen-color emulators, this module |
| 159 |
provides a pair of attributes for each color. For every normal color (0 |
| 160 |
through 7), the corresponding bright color (8 through 15) is obtained by |
| 161 |
prepending the string \f(CW\*(C`bright_\*(C'\fR to the normal color name. For example, |
| 162 |
\&\f(CW\*(C`red\*(C'\fR is color 1 and \f(CW\*(C`bright_red\*(C'\fR is color 9. The same applies for |
| 163 |
background colors: \f(CW\*(C`on_red\*(C'\fR is the normal color and \f(CW\*(C`on_bright_red\*(C'\fR is |
| 164 |
the bright color. Capitalize these strings for the constant interface. |
| 165 |
.PP |
| 166 |
There is unfortunately no way to know whether the current emulator |
| 167 |
supports more than eight colors, which makes the choice of colors |
| 168 |
difficult. The most conservative choice is to use only the regular |
| 169 |
colors, which are at least displayed on all emulators. However, they will |
| 170 |
appear dark in sixteen-color terminal emulators, including most common |
| 171 |
emulators in UNIX X environments. If you know the display is one of those |
| 172 |
emulators, you may wish to use the bright variants instead. Even better, |
| 173 |
offer the user a way to configure the colors for a given application to |
| 174 |
fit their terminal emulator. |
| 175 |
.PP |
| 176 |
For 256\-color emulators, this module additionally provides \f(CW\*(C`ansi0\*(C'\fR |
| 177 |
through \f(CW\*(C`ansi15\*(C'\fR, which are the same as colors 0 through 15 in |
| 178 |
sixteen-color emulators but use the 256\-color escape syntax, \f(CW\*(C`grey0\*(C'\fR |
| 179 |
through \f(CW\*(C`grey23\*(C'\fR ranging from nearly black to nearly white, and a set of |
| 180 |
RGB colors. The RGB colors are of the form \f(CW\*(C`rgb\fR\f(CIRGB\fR\f(CW\*(C'\fR where \fIR\fR, \fIG\fR, |
| 181 |
and \fIB\fR are numbers from 0 to 5 giving the intensity of red, green, and |
| 182 |
blue. The grey and RGB colors are also available as \f(CW\*(C`ansi16\*(C'\fR through |
| 183 |
\&\f(CW\*(C`ansi255\*(C'\fR if you want simple names for all 256 colors. \f(CW\*(C`on_\*(C'\fR variants |
| 184 |
of all of these colors are also provided. These colors may be ignored |
| 185 |
completely on non\-256\-color terminals or may be misinterpreted and produce |
| 186 |
random behavior. Additional attributes such as blink, italic, or bold may |
| 187 |
not work with the 256\-color palette. |
| 188 |
.PP |
| 189 |
For true color emulators, this module supports attributes of the form \f(CW\*(C`r\fR\f(CINNN\fR\f(CWg\fR\f(CINNN\fR\f(CWb\fR\f(CINNN\fR\f(CW\*(C'\fR and \f(CW\*(C`on_r\fR\f(CINNN\fR\f(CWg\fR\f(CINNN\fR\f(CWb\fR\f(CINNN\fR\f(CW\*(C'\fR for all values of |
| 190 |
\&\fINNN\fR between 0 and 255. These represent foreground and background colors, |
| 191 |
respectively, with the RGB values given by the \fINNN\fR numbers. These colors |
| 192 |
may be ignored completely on non-true-color terminals or may be misinterpreted |
| 193 |
and produce random behavior. |
| 194 |
.SS "Function Interface" |
| 195 |
.IX Subsection "Function Interface" |
| 196 |
The function interface uses attribute strings to describe the colors and |
| 197 |
text attributes to assign to text. The recognized non-color attributes |
| 198 |
are clear, reset, bold, dark, faint, italic, underline, underscore, blink, |
| 199 |
reverse, and concealed. Clear and reset (reset to default attributes), |
| 200 |
dark and faint (dim and saturated), and underline and underscore are |
| 201 |
equivalent, so use whichever is the most intuitive to you. |
| 202 |
.PP |
| 203 |
Note that not all attributes are supported by all terminal types, and some |
| 204 |
terminals may not support any of these sequences. Dark and faint, italic, |
| 205 |
blink, and concealed in particular are frequently not implemented. |
| 206 |
.PP |
| 207 |
The recognized normal foreground color attributes (colors 0 to 7) are: |
| 208 |
.PP |
| 209 |
.Vb 1 |
| 210 |
\& black red green yellow blue magenta cyan white |
| 211 |
.Ve |
| 212 |
.PP |
| 213 |
The corresponding bright foreground color attributes (colors 8 to 15) are: |
| 214 |
.PP |
| 215 |
.Vb 2 |
| 216 |
\& bright_black bright_red bright_green bright_yellow |
| 217 |
\& bright_blue bright_magenta bright_cyan bright_white |
| 218 |
.Ve |
| 219 |
.PP |
| 220 |
The recognized normal background color attributes (colors 0 to 7) are: |
| 221 |
.PP |
| 222 |
.Vb 2 |
| 223 |
\& on_black on_red on_green on yellow |
| 224 |
\& on_blue on_magenta on_cyan on_white |
| 225 |
.Ve |
| 226 |
.PP |
| 227 |
The recognized bright background color attributes (colors 8 to 15) are: |
| 228 |
.PP |
| 229 |
.Vb 2 |
| 230 |
\& on_bright_black on_bright_red on_bright_green on_bright_yellow |
| 231 |
\& on_bright_blue on_bright_magenta on_bright_cyan on_bright_white |
| 232 |
.Ve |
| 233 |
.PP |
| 234 |
For 256\-color terminals, the recognized foreground colors are: |
| 235 |
.PP |
| 236 |
.Vb 2 |
| 237 |
\& ansi0 .. ansi255 |
| 238 |
\& grey0 .. grey23 |
| 239 |
.Ve |
| 240 |
.PP |
| 241 |
plus \f(CW\*(C`rgb\fR\f(CIRGB\fR\f(CW\*(C'\fR for \fIR\fR, \fIG\fR, and \fIB\fR values from 0 to 5, such as |
| 242 |
\&\f(CW\*(C`rgb000\*(C'\fR or \f(CW\*(C`rgb515\*(C'\fR. Similarly, the recognized background colors are: |
| 243 |
.PP |
| 244 |
.Vb 2 |
| 245 |
\& on_ansi0 .. on_ansi255 |
| 246 |
\& on_grey0 .. on_grey23 |
| 247 |
.Ve |
| 248 |
.PP |
| 249 |
plus \f(CW\*(C`on_rgb\fR\f(CIRGB\fR\f(CW\*(C'\fR for \fIR\fR, \fIG\fR, and \fIB\fR values from 0 to 5. |
| 250 |
.PP |
| 251 |
For true color terminals, the recognized foreground colors are \f(CW\*(C`r\fR\f(CIRRR\fR\f(CWg\fR\f(CIGGG\fR\f(CWb\fR\f(CIBBB\fR\f(CW\*(C'\fR for \fIRRR\fR, \fIGGG\fR, and \fIBBB\fR values between 0 and |
| 252 |
255. Similarly, the recognized background colors are \f(CW\*(C`on_r\fR\f(CIRRR\fR\f(CWg\fR\f(CIGGG\fR\f(CWb\fR\f(CIBBB\fR\f(CW\*(C'\fR for \fIRRR\fR, \fIGGG\fR, and \fIBBB\fR values between 0 |
| 253 |
and 255. |
| 254 |
.PP |
| 255 |
For any of the above listed attributes, case is not significant. |
| 256 |
.PP |
| 257 |
Attributes, once set, last until they are unset (by printing the attribute |
| 258 |
\&\f(CW\*(C`clear\*(C'\fR or \f(CW\*(C`reset\*(C'\fR). Be careful to do this, or otherwise your attribute |
| 259 |
will last after your script is done running, and people get very annoyed |
| 260 |
at having their prompt and typing changed to weird colors. |
| 261 |
.IP "color(ATTR[, ATTR ...])" 4 |
| 262 |
.IX Item "color(ATTR[, ATTR ...])" |
| 263 |
\&\fBcolor()\fR takes any number of strings as arguments and considers them to be |
| 264 |
space-separated lists of attributes. It then forms and returns the escape |
| 265 |
sequence to set those attributes. It doesn't print it out, just returns |
| 266 |
it, so you'll have to print it yourself if you want to. This is so that |
| 267 |
you can save it as a string, pass it to something else, send it to a file |
| 268 |
handle, or do anything else with it that you might care to. \fBcolor()\fR |
| 269 |
throws an exception if given an invalid attribute. |
| 270 |
.IP "colored(STRING, ATTR[, ATTR ...])" 4 |
| 271 |
.IX Item "colored(STRING, ATTR[, ATTR ...])" |
| 272 |
.PD 0 |
| 273 |
.IP "colored(ATTR\-REF, STRING[, STRING...])" 4 |
| 274 |
.IX Item "colored(ATTR-REF, STRING[, STRING...])" |
| 275 |
.PD |
| 276 |
As an aid in resetting colors, \fBcolored()\fR takes a scalar as the first |
| 277 |
argument and any number of attribute strings as the second argument and |
| 278 |
returns the scalar wrapped in escape codes so that the attributes will be |
| 279 |
set as requested before the string and reset to normal after the string. |
| 280 |
Alternately, you can pass a reference to an array as the first argument, |
| 281 |
and then the contents of that array will be taken as attributes and color |
| 282 |
codes and the remainder of the arguments as text to colorize. |
| 283 |
.Sp |
| 284 |
Normally, \fBcolored()\fR just puts attribute codes at the beginning and end of |
| 285 |
the string, but if you set \f(CW$Term::ANSIColor::EACHLINE\fR to some string, that |
| 286 |
string will be considered the line delimiter and the attribute will be set |
| 287 |
at the beginning of each line of the passed string and reset at the end of |
| 288 |
each line. This is often desirable if the output contains newlines and |
| 289 |
you're using background colors, since a background color that persists |
| 290 |
across a newline is often interpreted by the terminal as providing the |
| 291 |
default background color for the next line. Programs like pagers can also |
| 292 |
be confused by attributes that span lines. Normally you'll want to set |
| 293 |
\&\f(CW$Term::ANSIColor::EACHLINE\fR to \f(CW"\en"\fR to use this feature. |
| 294 |
.Sp |
| 295 |
Particularly consider setting \f(CW$Term::ANSIColor::EACHLINE\fR if you are |
| 296 |
interleaving output to standard output and standard error and you aren't |
| 297 |
flushing standard output (via \fBautoflush()\fR or setting \f(CW$|\fR). If you don't, |
| 298 |
the code to reset the color may unexpectedly sit in the standard output buffer |
| 299 |
rather than going to the display, causing standard error output to appear in |
| 300 |
the wrong color. |
| 301 |
.IP uncolor(ESCAPE) 4 |
| 302 |
.IX Item "uncolor(ESCAPE)" |
| 303 |
\&\fBuncolor()\fR performs the opposite translation as \fBcolor()\fR, turning escape |
| 304 |
sequences into a list of strings corresponding to the attributes being set |
| 305 |
by those sequences. \fBuncolor()\fR will never return \f(CW\*(C`ansi16\*(C'\fR through |
| 306 |
\&\f(CW\*(C`ansi255\*(C'\fR, instead preferring the \f(CW\*(C`grey\*(C'\fR and \f(CW\*(C`rgb\*(C'\fR names (and likewise |
| 307 |
for \f(CW\*(C`on_ansi16\*(C'\fR through \f(CW\*(C`on_ansi255\*(C'\fR). |
| 308 |
.IP "colorstrip(STRING[, STRING ...])" 4 |
| 309 |
.IX Item "colorstrip(STRING[, STRING ...])" |
| 310 |
\&\fBcolorstrip()\fR removes all color escape sequences from the provided strings, |
| 311 |
returning the modified strings separately in array context or joined |
| 312 |
together in scalar context. Its arguments are not modified. |
| 313 |
.IP "colorvalid(ATTR[, ATTR ...])" 4 |
| 314 |
.IX Item "colorvalid(ATTR[, ATTR ...])" |
| 315 |
\&\fBcolorvalid()\fR takes attribute strings the same as \fBcolor()\fR and returns true |
| 316 |
if all attributes are known and false otherwise. |
| 317 |
.IP "coloralias(ALIAS[, ATTR ...])" 4 |
| 318 |
.IX Item "coloralias(ALIAS[, ATTR ...])" |
| 319 |
If ATTR is specified, it is interpreted as a list of space-separated strings |
| 320 |
naming attributes or existing aliases. In this case, \fBcoloralias()\fR sets up an |
| 321 |
alias of ALIAS for the set of attributes given by ATTR. From that point |
| 322 |
forward, ALIAS can be passed into \fBcolor()\fR, \fBcolored()\fR, and \fBcolorvalid()\fR and |
| 323 |
will have the same meaning as the sequence of attributes given in ATTR. One |
| 324 |
possible use of this facility is to give more meaningful names to the |
| 325 |
256\-color RGB colors. Only ASCII alphanumerics, \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`_\*(C'\fR, and \f(CW\*(C`\-\*(C'\fR are |
| 326 |
allowed in alias names. |
| 327 |
.Sp |
| 328 |
If ATTR includes aliases, those aliases will be expanded at definition time |
| 329 |
and their values will be used to define the new alias. This means that if you |
| 330 |
define an alias A in terms of another alias B, and then later redefine alias |
| 331 |
B, the value of alias A will not change. |
| 332 |
.Sp |
| 333 |
If ATTR is not specified, \fBcoloralias()\fR returns the standard attribute or |
| 334 |
attributes to which ALIAS is aliased, if any, or undef if ALIAS does not |
| 335 |
exist. If it is aliased to multiple attributes, the return value will be a |
| 336 |
single string and the attributes will be separated by spaces. |
| 337 |
.Sp |
| 338 |
This is the same facility used by the ANSI_COLORS_ALIASES environment |
| 339 |
variable (see "ENVIRONMENT" below) but can be used at runtime, not just |
| 340 |
when the module is loaded. |
| 341 |
.Sp |
| 342 |
Later invocations of \fBcoloralias()\fR with the same ALIAS will override |
| 343 |
earlier aliases. There is no way to remove an alias. |
| 344 |
.Sp |
| 345 |
Aliases have no effect on the return value of \fBuncolor()\fR. |
| 346 |
.Sp |
| 347 |
\&\fBWARNING\fR: Aliases are global and affect all callers in the same process. |
| 348 |
There is no way to set an alias limited to a particular block of code or a |
| 349 |
particular object. |
| 350 |
.SS "Constant Interface" |
| 351 |
.IX Subsection "Constant Interface" |
| 352 |
Alternately, if you import \f(CW\*(C`:constants\*(C'\fR, you can use the following |
| 353 |
constants directly: |
| 354 |
.PP |
| 355 |
.Vb 3 |
| 356 |
\& CLEAR RESET BOLD DARK |
| 357 |
\& FAINT ITALIC UNDERLINE UNDERSCORE |
| 358 |
\& BLINK REVERSE CONCEALED |
| 359 |
\& |
| 360 |
\& BLACK RED GREEN YELLOW |
| 361 |
\& BLUE MAGENTA CYAN WHITE |
| 362 |
\& BRIGHT_BLACK BRIGHT_RED BRIGHT_GREEN BRIGHT_YELLOW |
| 363 |
\& BRIGHT_BLUE BRIGHT_MAGENTA BRIGHT_CYAN BRIGHT_WHITE |
| 364 |
\& |
| 365 |
\& ON_BLACK ON_RED ON_GREEN ON_YELLOW |
| 366 |
\& ON_BLUE ON_MAGENTA ON_CYAN ON_WHITE |
| 367 |
\& ON_BRIGHT_BLACK ON_BRIGHT_RED ON_BRIGHT_GREEN ON_BRIGHT_YELLOW |
| 368 |
\& ON_BRIGHT_BLUE ON_BRIGHT_MAGENTA ON_BRIGHT_CYAN ON_BRIGHT_WHITE |
| 369 |
.Ve |
| 370 |
.PP |
| 371 |
These are the same as color('attribute') and can be used if you prefer |
| 372 |
typing: |
| 373 |
.PP |
| 374 |
.Vb 1 |
| 375 |
\& print BOLD BLUE ON_WHITE "Text", RESET, "\en"; |
| 376 |
.Ve |
| 377 |
.PP |
| 378 |
to |
| 379 |
.PP |
| 380 |
.Vb 1 |
| 381 |
\& print colored ("Text", \*(Aqbold blue on_white\*(Aq), "\en"; |
| 382 |
.Ve |
| 383 |
.PP |
| 384 |
(Note that the newline is kept separate to avoid confusing the terminal as |
| 385 |
described above since a background color is being used.) |
| 386 |
.PP |
| 387 |
If you import \f(CW\*(C`:constants256\*(C'\fR, you can use the following constants |
| 388 |
directly: |
| 389 |
.PP |
| 390 |
.Vb 2 |
| 391 |
\& ANSI0 .. ANSI255 |
| 392 |
\& GREY0 .. GREY23 |
| 393 |
\& |
| 394 |
\& RGBXYZ (for X, Y, and Z values from 0 to 5, like RGB000 or RGB515) |
| 395 |
\& |
| 396 |
\& ON_ANSI0 .. ON_ANSI255 |
| 397 |
\& ON_GREY0 .. ON_GREY23 |
| 398 |
\& |
| 399 |
\& ON_RGBXYZ (for X, Y, and Z values from 0 to 5) |
| 400 |
.Ve |
| 401 |
.PP |
| 402 |
Note that \f(CW\*(C`:constants256\*(C'\fR does not include the other constants, so if you |
| 403 |
want to mix both, you need to include \f(CW\*(C`:constants\*(C'\fR as well. You may want |
| 404 |
to explicitly import at least \f(CW\*(C`RESET\*(C'\fR, as in: |
| 405 |
.PP |
| 406 |
.Vb 1 |
| 407 |
\& use Term::ANSIColor 4.00 qw(RESET :constants256); |
| 408 |
.Ve |
| 409 |
.PP |
| 410 |
True color and aliases are not supported by the constant interface. |
| 411 |
.PP |
| 412 |
When using the constants, if you don't want to have to remember to add the |
| 413 |
\&\f(CW\*(C`, RESET\*(C'\fR at the end of each print line, you can set |
| 414 |
\&\f(CW$Term::ANSIColor::AUTORESET\fR to a true value. Then, the display mode will |
| 415 |
automatically be reset if there is no comma after the constant. In other |
| 416 |
words, with that variable set: |
| 417 |
.PP |
| 418 |
.Vb 1 |
| 419 |
\& print BOLD BLUE "Text\en"; |
| 420 |
.Ve |
| 421 |
.PP |
| 422 |
will reset the display mode afterward, whereas: |
| 423 |
.PP |
| 424 |
.Vb 1 |
| 425 |
\& print BOLD, BLUE, "Text\en"; |
| 426 |
.Ve |
| 427 |
.PP |
| 428 |
will not. If you are using background colors, you will probably want to |
| 429 |
either use \fBsay()\fR (in newer versions of Perl) or print the newline with a |
| 430 |
separate print statement to avoid confusing the terminal. |
| 431 |
.PP |
| 432 |
If \f(CW$Term::ANSIColor::AUTOLOCAL\fR is set (see below), it takes precedence |
| 433 |
over \f(CW$Term::ANSIColor::AUTORESET\fR, and the latter is ignored. |
| 434 |
.PP |
| 435 |
The subroutine interface has the advantage over the constants interface in |
| 436 |
that only two subroutines are exported into your namespace, versus |
| 437 |
thirty-eight in the constants interface, and aliases and true color attributes |
| 438 |
are supported. On the flip side, the constants interface has the advantage of |
| 439 |
better compile time error checking, since misspelled names of colors or |
| 440 |
attributes in calls to \fBcolor()\fR and \fBcolored()\fR won't be caught until runtime |
| 441 |
whereas misspelled names of constants will be caught at compile time. So, |
| 442 |
pollute your namespace with almost two dozen subroutines that you may not even |
| 443 |
use that often, or risk a silly bug by mistyping an attribute. Your choice, |
| 444 |
TMTOWTDI after all. |
| 445 |
.SS "The Color Stack" |
| 446 |
.IX Subsection "The Color Stack" |
| 447 |
You can import \f(CW\*(C`:pushpop\*(C'\fR and maintain a stack of colors using PUSHCOLOR, |
| 448 |
POPCOLOR, and LOCALCOLOR. PUSHCOLOR takes the attribute string that |
| 449 |
starts its argument and pushes it onto a stack of attributes. POPCOLOR |
| 450 |
removes the top of the stack and restores the previous attributes set by |
| 451 |
the argument of a prior PUSHCOLOR. LOCALCOLOR surrounds its argument in a |
| 452 |
PUSHCOLOR and POPCOLOR so that the color resets afterward. |
| 453 |
.PP |
| 454 |
If \f(CW$Term::ANSIColor::AUTOLOCAL\fR is set, each sequence of color constants |
| 455 |
will be implicitly preceded by LOCALCOLOR. In other words, the following: |
| 456 |
.PP |
| 457 |
.Vb 4 |
| 458 |
\& { |
| 459 |
\& local $Term::ANSIColor::AUTOLOCAL = 1; |
| 460 |
\& print BLUE "Text\en"; |
| 461 |
\& } |
| 462 |
.Ve |
| 463 |
.PP |
| 464 |
is equivalent to: |
| 465 |
.PP |
| 466 |
.Vb 1 |
| 467 |
\& print LOCALCOLOR BLUE "Text\en"; |
| 468 |
.Ve |
| 469 |
.PP |
| 470 |
If \f(CW$Term::ANSIColor::AUTOLOCAL\fR is set, it takes precedence over |
| 471 |
\&\f(CW$Term::ANSIColor::AUTORESET\fR, and the latter is ignored. |
| 472 |
.PP |
| 473 |
When using PUSHCOLOR, POPCOLOR, and LOCALCOLOR, it's particularly |
| 474 |
important to not put commas between the constants. |
| 475 |
.PP |
| 476 |
.Vb 1 |
| 477 |
\& print PUSHCOLOR BLUE "Text\en"; |
| 478 |
.Ve |
| 479 |
.PP |
| 480 |
will correctly push BLUE onto the top of the stack. |
| 481 |
.PP |
| 482 |
.Vb 1 |
| 483 |
\& print PUSHCOLOR, BLUE, "Text\en"; # wrong! |
| 484 |
.Ve |
| 485 |
.PP |
| 486 |
will not, and a subsequent pop won't restore the correct attributes. |
| 487 |
PUSHCOLOR pushes the attributes set by its argument, which is normally a |
| 488 |
string of color constants. It can't ask the terminal what the current |
| 489 |
attributes are. |
| 490 |
.SS "Supporting CLICOLOR" |
| 491 |
.IX Subsection "Supporting CLICOLOR" |
| 492 |
<https://bixense.com/clicolors/> proposes a standard for enabling and |
| 493 |
disabling color output from console commands using two environment variables, |
| 494 |
CLICOLOR and CLICOLOR_FORCE. Term::ANSIColor cannot automatically support |
| 495 |
this standard, since the correct action depends on where the output is going |
| 496 |
and Term::ANSIColor may be used in a context where colors should always be |
| 497 |
generated even if CLICOLOR is set in the environment. But you can use the |
| 498 |
supported environment variable ANSI_COLORS_DISABLED to implement CLICOLOR in |
| 499 |
your own programs with code like this: |
| 500 |
.PP |
| 501 |
.Vb 5 |
| 502 |
\& if (exists($ENV{CLICOLOR}) && $ENV{CLICOLOR} == 0) { |
| 503 |
\& if (!$ENV{CLICOLOR_FORCE}) { |
| 504 |
\& $ENV{ANSI_COLORS_DISABLED} = 1; |
| 505 |
\& } |
| 506 |
\& } |
| 507 |
.Ve |
| 508 |
.PP |
| 509 |
If you are using the constant interface, be sure to include this code before |
| 510 |
you use any color constants (such as at the very top of your script), since |
| 511 |
this environment variable is only honored the first time a color constant is |
| 512 |
seen. |
| 513 |
.PP |
| 514 |
Be aware that this will export ANSI_COLORS_DISABLED to any child processes of |
| 515 |
your program as well. |
| 516 |
.SH DIAGNOSTICS |
| 517 |
.IX Header "DIAGNOSTICS" |
| 518 |
.ie n .IP "Bad color mapping %s" 4 |
| 519 |
.el .IP "Bad color mapping \f(CW%s\fR" 4 |
| 520 |
.IX Item "Bad color mapping %s" |
| 521 |
(W) The specified color mapping from ANSI_COLORS_ALIASES is not valid and |
| 522 |
could not be parsed. It was ignored. |
| 523 |
.ie n .IP "Bad escape sequence %s" 4 |
| 524 |
.el .IP "Bad escape sequence \f(CW%s\fR" 4 |
| 525 |
.IX Item "Bad escape sequence %s" |
| 526 |
(F) You passed an invalid ANSI escape sequence to \fBuncolor()\fR. |
| 527 |
.IP "Bareword ""%s"" not allowed while ""strict subs"" in use" 4 |
| 528 |
.IX Item "Bareword ""%s"" not allowed while ""strict subs"" in use" |
| 529 |
(F) You probably mistyped a constant color name such as: |
| 530 |
.Sp |
| 531 |
.Vb 1 |
| 532 |
\& $Foobar = FOOBAR . "This line should be blue\en"; |
| 533 |
.Ve |
| 534 |
.Sp |
| 535 |
or: |
| 536 |
.Sp |
| 537 |
.Vb 1 |
| 538 |
\& @Foobar = FOOBAR, "This line should be blue\en"; |
| 539 |
.Ve |
| 540 |
.Sp |
| 541 |
This will only show up under use strict (another good reason to run under |
| 542 |
use strict). |
| 543 |
.ie n .IP "Cannot alias standard color %s" 4 |
| 544 |
.el .IP "Cannot alias standard color \f(CW%s\fR" 4 |
| 545 |
.IX Item "Cannot alias standard color %s" |
| 546 |
(F) The alias name passed to \fBcoloralias()\fR matches a standard color name. |
| 547 |
Standard color names cannot be aliased. |
| 548 |
.ie n .IP "Cannot alias standard color %s in %s" 4 |
| 549 |
.el .IP "Cannot alias standard color \f(CW%s\fR in \f(CW%s\fR" 4 |
| 550 |
.IX Item "Cannot alias standard color %s in %s" |
| 551 |
(W) The same, but in ANSI_COLORS_ALIASES. The color mapping was ignored. |
| 552 |
.ie n .IP "Invalid alias name %s" 4 |
| 553 |
.el .IP "Invalid alias name \f(CW%s\fR" 4 |
| 554 |
.IX Item "Invalid alias name %s" |
| 555 |
(F) You passed an invalid alias name to \fBcoloralias()\fR. Alias names must |
| 556 |
consist only of alphanumerics, \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`\-\*(C'\fR, and \f(CW\*(C`_\*(C'\fR. |
| 557 |
.ie n .IP "Invalid alias name %s in %s" 4 |
| 558 |
.el .IP "Invalid alias name \f(CW%s\fR in \f(CW%s\fR" 4 |
| 559 |
.IX Item "Invalid alias name %s in %s" |
| 560 |
(W) You specified an invalid alias name on the left hand of the equal sign |
| 561 |
in a color mapping in ANSI_COLORS_ALIASES. The color mapping was ignored. |
| 562 |
.ie n .IP "Invalid attribute name %s" 4 |
| 563 |
.el .IP "Invalid attribute name \f(CW%s\fR" 4 |
| 564 |
.IX Item "Invalid attribute name %s" |
| 565 |
(F) You passed an invalid attribute name to \fBcolor()\fR, \fBcolored()\fR, or |
| 566 |
\&\fBcoloralias()\fR. |
| 567 |
.ie n .IP "Invalid attribute name %s in %s" 4 |
| 568 |
.el .IP "Invalid attribute name \f(CW%s\fR in \f(CW%s\fR" 4 |
| 569 |
.IX Item "Invalid attribute name %s in %s" |
| 570 |
(W) You specified an invalid attribute name on the right hand of the equal |
| 571 |
sign in a color mapping in ANSI_COLORS_ALIASES. The color mapping was |
| 572 |
ignored. |
| 573 |
.IP "Name ""%s"" used only once: possible typo" 4 |
| 574 |
.IX Item "Name ""%s"" used only once: possible typo" |
| 575 |
(W) You probably mistyped a constant color name such as: |
| 576 |
.Sp |
| 577 |
.Vb 1 |
| 578 |
\& print FOOBAR "This text is color FOOBAR\en"; |
| 579 |
.Ve |
| 580 |
.Sp |
| 581 |
It's probably better to always use commas after constant names in order to |
| 582 |
force the next error. |
| 583 |
.IP "No comma allowed after filehandle" 4 |
| 584 |
.IX Item "No comma allowed after filehandle" |
| 585 |
(F) You probably mistyped a constant color name such as: |
| 586 |
.Sp |
| 587 |
.Vb 1 |
| 588 |
\& print FOOBAR, "This text is color FOOBAR\en"; |
| 589 |
.Ve |
| 590 |
.Sp |
| 591 |
Generating this fatal compile error is one of the main advantages of using |
| 592 |
the constants interface, since you'll immediately know if you mistype a |
| 593 |
color name. |
| 594 |
.ie n .IP "No name for escape sequence %s" 4 |
| 595 |
.el .IP "No name for escape sequence \f(CW%s\fR" 4 |
| 596 |
.IX Item "No name for escape sequence %s" |
| 597 |
(F) The ANSI escape sequence passed to \fBuncolor()\fR contains escapes which |
| 598 |
aren't recognized and can't be translated to names. |
| 599 |
.SH ENVIRONMENT |
| 600 |
.IX Header "ENVIRONMENT" |
| 601 |
.IP ANSI_COLORS_ALIASES 4 |
| 602 |
.IX Item "ANSI_COLORS_ALIASES" |
| 603 |
This environment variable allows the user to specify custom color aliases |
| 604 |
that will be understood by \fBcolor()\fR, \fBcolored()\fR, and \fBcolorvalid()\fR. None of |
| 605 |
the other functions will be affected, and no new color constants will be |
| 606 |
created. The custom colors are aliases for existing color names; no new |
| 607 |
escape sequences can be introduced. Only alphanumerics, \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`_\*(C'\fR, and |
| 608 |
\&\f(CW\*(C`\-\*(C'\fR are allowed in alias names. |
| 609 |
.Sp |
| 610 |
The format is: |
| 611 |
.Sp |
| 612 |
.Vb 1 |
| 613 |
\& ANSI_COLORS_ALIASES=\*(Aqnewcolor1=oldcolor1,newcolor2=oldcolor2\*(Aq |
| 614 |
.Ve |
| 615 |
.Sp |
| 616 |
Whitespace is ignored. The alias value can be a single attribute or a |
| 617 |
space-separated list of attributes. |
| 618 |
.Sp |
| 619 |
For example the Solarized <https://ethanschoonover.com/solarized> colors |
| 620 |
can be mapped with: |
| 621 |
.Sp |
| 622 |
.Vb 11 |
| 623 |
\& ANSI_COLORS_ALIASES=\*(Aq\e |
| 624 |
\& base00=bright_yellow, on_base00=on_bright_yellow,\e |
| 625 |
\& base01=bright_green, on_base01=on_bright_green, \e |
| 626 |
\& base02=black, on_base02=on_black, \e |
| 627 |
\& base03=bright_black, on_base03=on_bright_black, \e |
| 628 |
\& base0=bright_blue, on_base0=on_bright_blue, \e |
| 629 |
\& base1=bright_cyan, on_base1=on_bright_cyan, \e |
| 630 |
\& base2=white, on_base2=on_white, \e |
| 631 |
\& base3=bright_white, on_base3=on_bright_white, \e |
| 632 |
\& orange=bright_red, on_orange=on_bright_red, \e |
| 633 |
\& violet=bright_magenta,on_violet=on_bright_magenta\*(Aq |
| 634 |
.Ve |
| 635 |
.Sp |
| 636 |
This environment variable is read and applied when the Term::ANSIColor |
| 637 |
module is loaded and is then subsequently ignored. Changes to |
| 638 |
ANSI_COLORS_ALIASES after the module is loaded will have no effect. See |
| 639 |
\&\fBcoloralias()\fR for an equivalent facility that can be used at runtime. |
| 640 |
.IP ANSI_COLORS_DISABLED 4 |
| 641 |
.IX Item "ANSI_COLORS_DISABLED" |
| 642 |
If this environment variable is set to a true value, all of the functions |
| 643 |
defined by this module (\fBcolor()\fR, \fBcolored()\fR, and all of the constants) will not |
| 644 |
output any escape sequences and instead will just return the empty string or |
| 645 |
pass through the original text as appropriate. This is intended to support |
| 646 |
easy use of scripts using this module on platforms that don't support ANSI |
| 647 |
escape sequences. |
| 648 |
.IP NO_COLOR 4 |
| 649 |
.IX Item "NO_COLOR" |
| 650 |
If this environment variable is set to any value, it suppresses generation of |
| 651 |
escape sequences the same as if ANSI_COLORS_DISABLED is set to a true value. |
| 652 |
This implements the <https://no\-color.org/> informal standard. Programs that |
| 653 |
want to enable color despite NO_COLOR being set will need to unset that |
| 654 |
environment variable before any constant or function provided by this module |
| 655 |
is used. |
| 656 |
.SH COMPATIBILITY |
| 657 |
.IX Header "COMPATIBILITY" |
| 658 |
Term::ANSIColor was first included with Perl in Perl 5.6.0. |
| 659 |
.PP |
| 660 |
The \fBuncolor()\fR function and support for ANSI_COLORS_DISABLED were added in |
| 661 |
Term::ANSIColor 1.04, included in Perl 5.8.0. |
| 662 |
.PP |
| 663 |
Support for dark was added in Term::ANSIColor 1.08, included in Perl |
| 664 |
5.8.4. |
| 665 |
.PP |
| 666 |
The color stack, including the \f(CW\*(C`:pushpop\*(C'\fR import tag, PUSHCOLOR, |
| 667 |
POPCOLOR, LOCALCOLOR, and the \f(CW$Term::ANSIColor::AUTOLOCAL\fR variable, was |
| 668 |
added in Term::ANSIColor 2.00, included in Perl 5.10.1. |
| 669 |
.PP |
| 670 |
\&\fBcolorstrip()\fR was added in Term::ANSIColor 2.01 and \fBcolorvalid()\fR was added |
| 671 |
in Term::ANSIColor 2.02, both included in Perl 5.11.0. |
| 672 |
.PP |
| 673 |
Support for colors 8 through 15 (the \f(CW\*(C`bright_\*(C'\fR variants) was added in |
| 674 |
Term::ANSIColor 3.00, included in Perl 5.13.3. |
| 675 |
.PP |
| 676 |
Support for italic was added in Term::ANSIColor 3.02, included in Perl |
| 677 |
5.17.1. |
| 678 |
.PP |
| 679 |
Support for colors 16 through 256 (the \f(CW\*(C`ansi\*(C'\fR, \f(CW\*(C`rgb\*(C'\fR, and \f(CW\*(C`grey\*(C'\fR |
| 680 |
colors), the \f(CW\*(C`:constants256\*(C'\fR import tag, the \fBcoloralias()\fR function, and |
| 681 |
support for the ANSI_COLORS_ALIASES environment variable were added in |
| 682 |
Term::ANSIColor 4.00, included in Perl 5.17.8. |
| 683 |
.PP |
| 684 |
\&\f(CW$Term::ANSIColor::AUTOLOCAL\fR was changed to take precedence over |
| 685 |
\&\f(CW$Term::ANSIColor::AUTORESET\fR, rather than the other way around, in |
| 686 |
Term::ANSIColor 4.00, included in Perl 5.17.8. |
| 687 |
.PP |
| 688 |
\&\f(CW\*(C`ansi16\*(C'\fR through \f(CW\*(C`ansi255\*(C'\fR, as aliases for the \f(CW\*(C`rgb\*(C'\fR and \f(CW\*(C`grey\*(C'\fR colors, |
| 689 |
and the corresponding \f(CW\*(C`on_ansi\*(C'\fR names and \f(CW\*(C`ANSI\*(C'\fR and \f(CW\*(C`ON_ANSI\*(C'\fR constants |
| 690 |
were added in Term::ANSIColor 4.06, included in Perl 5.25.7. |
| 691 |
.PP |
| 692 |
Support for true color (the \f(CW\*(C`rNNNgNNNbNNN\*(C'\fR and \f(CW\*(C`on_rNNNgNNNbNNN\*(C'\fR |
| 693 |
attributes), defining aliases in terms of other aliases, and aliases mapping |
| 694 |
to multiple attributes instead of only a single attribute was added in |
| 695 |
Term::ANSIColor 5.00. |
| 696 |
.PP |
| 697 |
Support for NO_COLOR was added in Term::ANSIColor 5.01. |
| 698 |
.SH RESTRICTIONS |
| 699 |
.IX Header "RESTRICTIONS" |
| 700 |
Both \fBcolored()\fR and many uses of the color constants will add the reset escape |
| 701 |
sequence after a newline. If a program mixes colored output to standard |
| 702 |
output with output to standard error, this can result in the standard error |
| 703 |
text having the wrong color because the reset escape sequence hasn't yet been |
| 704 |
flushed to the display (since standard output to a terminal is line-buffered |
| 705 |
by default). To avoid this, either set \fBautoflush()\fR on STDOUT or set |
| 706 |
\&\f(CW$Term::ANSIColor::EACHLINE\fR to \f(CW"\en"\fR. |
| 707 |
.PP |
| 708 |
It would be nice if one could leave off the commas around the constants |
| 709 |
entirely and just say: |
| 710 |
.PP |
| 711 |
.Vb 1 |
| 712 |
\& print BOLD BLUE ON_WHITE "Text\en" RESET; |
| 713 |
.Ve |
| 714 |
.PP |
| 715 |
but the syntax of Perl doesn't allow this. You need a comma after the |
| 716 |
string. (Of course, you may consider it a bug that commas between all the |
| 717 |
constants aren't required, in which case you may feel free to insert |
| 718 |
commas unless you're using \f(CW$Term::ANSIColor::AUTORESET\fR or |
| 719 |
PUSHCOLOR/POPCOLOR.) |
| 720 |
.PP |
| 721 |
For easier debugging, you may prefer to always use the commas when not |
| 722 |
setting \f(CW$Term::ANSIColor::AUTORESET\fR or PUSHCOLOR/POPCOLOR so that you'll |
| 723 |
get a fatal compile error rather than a warning. |
| 724 |
.PP |
| 725 |
It's not possible to use this module to embed formatting and color |
| 726 |
attributes using Perl formats. They replace the escape character with a |
| 727 |
space (as documented in \fBperlform\fR\|(1)), resulting in garbled output from |
| 728 |
the unrecognized attribute. Even if there were a way around that problem, |
| 729 |
the format doesn't know that the non-printing escape sequence is |
| 730 |
zero-length and would incorrectly format the output. For formatted output |
| 731 |
using color or other attributes, either use \fBsprintf()\fR instead or use |
| 732 |
\&\fBformline()\fR and then add the color or other attributes after formatting and |
| 733 |
before output. |
| 734 |
.SH NOTES |
| 735 |
.IX Header "NOTES" |
| 736 |
The codes generated by this module are standard terminal control codes, |
| 737 |
complying with ECMA\-048 and ISO 6429 (generally referred to as "ANSI |
| 738 |
color" for the color codes). The non-color control codes (bold, dark, |
| 739 |
italic, underline, and reverse) are part of the earlier ANSI X3.64 |
| 740 |
standard for control sequences for video terminals and peripherals. |
| 741 |
.PP |
| 742 |
Note that not all displays are ISO 6429\-compliant, or even X3.64\-compliant |
| 743 |
(or are even attempting to be so). This module will not work as expected |
| 744 |
on displays that do not honor these escape sequences, such as cmd.exe, |
| 745 |
4nt.exe, and command.com under either Windows NT or Windows 2000. They |
| 746 |
may just be ignored, or they may display as an ESC character followed by |
| 747 |
some apparent garbage. |
| 748 |
.PP |
| 749 |
Jean Delvare provided the following table of different common terminal |
| 750 |
emulators and their support for the various attributes and others have |
| 751 |
helped me flesh it out: |
| 752 |
.PP |
| 753 |
.Vb 12 |
| 754 |
\& clear bold faint under blink reverse conceal |
| 755 |
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- |
| 756 |
\& xterm yes yes no yes yes yes yes |
| 757 |
\& linux yes yes yes bold yes yes no |
| 758 |
\& rxvt yes yes no yes bold/black yes no |
| 759 |
\& dtterm yes yes yes yes reverse yes yes |
| 760 |
\& teraterm yes reverse no yes rev/red yes no |
| 761 |
\& aixterm kinda normal no yes no yes yes |
| 762 |
\& PuTTY yes color no yes no yes no |
| 763 |
\& Windows yes no no no no yes no |
| 764 |
\& Cygwin SSH yes yes no color color color yes |
| 765 |
\& Terminal.app yes yes no yes yes yes yes |
| 766 |
.Ve |
| 767 |
.PP |
| 768 |
Windows is Windows telnet, Cygwin SSH is the OpenSSH implementation under |
| 769 |
Cygwin on Windows NT, and Mac Terminal is the Terminal application in Mac |
| 770 |
OS X. Where the entry is other than yes or no, that emulator displays the |
| 771 |
given attribute as something else instead. Note that on an aixterm, clear |
| 772 |
doesn't reset colors; you have to explicitly set the colors back to what |
| 773 |
you want. More entries in this table are welcome. |
| 774 |
.PP |
| 775 |
Support for code 3 (italic) is rare and therefore not mentioned in that |
| 776 |
table. It is not believed to be fully supported by any of the terminals |
| 777 |
listed, although it's displayed as green in the Linux console, but it is |
| 778 |
reportedly supported by urxvt. |
| 779 |
.PP |
| 780 |
Note that codes 6 (rapid blink) and 9 (strike-through) are specified in ANSI |
| 781 |
X3.64 and ECMA\-048 but are not commonly supported by most displays and |
| 782 |
emulators and therefore aren't supported by this module. ECMA\-048 also |
| 783 |
specifies a large number of other attributes, including a sequence of |
| 784 |
attributes for font changes, Fraktur characters, double-underlining, framing, |
| 785 |
circling, and overlining. As none of these attributes are widely supported or |
| 786 |
useful, they also aren't currently supported by this module. |
| 787 |
.PP |
| 788 |
Most modern X terminal emulators support 256 colors. Known to not support |
| 789 |
those colors are aterm, rxvt, Terminal.app, and TTY/VC. |
| 790 |
.PP |
| 791 |
For information on true color support in various terminal emulators, see |
| 792 |
True Colour support <https://gist.github.com/XVilka/8346728>. |
| 793 |
.SH AUTHORS |
| 794 |
.IX Header "AUTHORS" |
| 795 |
Original idea (using constants) by Zenin, reimplemented using subs by Russ |
| 796 |
Allbery <[email protected]>, and then combined with the original idea by |
| 797 |
Russ with input from Zenin. 256\-color support is based on work by Kurt |
| 798 |
Starsinic. Russ Allbery now maintains this module. |
| 799 |
.PP |
| 800 |
PUSHCOLOR, POPCOLOR, and LOCALCOLOR were contributed by openmethods.com |
| 801 |
voice solutions. |
| 802 |
.SH "COPYRIGHT AND LICENSE" |
| 803 |
.IX Header "COPYRIGHT AND LICENSE" |
| 804 |
Copyright 1996\-1998, 2000\-2002, 2005\-2006, 2008\-2018, 2020 Russ Allbery |
| 805 |
<[email protected]> |
| 806 |
.PP |
| 807 |
Copyright 1996 Zenin |
| 808 |
.PP |
| 809 |
Copyright 2012 Kurt Starsinic <[email protected]> |
| 810 |
.PP |
| 811 |
This program is free software; you may redistribute it and/or modify it |
| 812 |
under the same terms as Perl itself. |
| 813 |
.SH "SEE ALSO" |
| 814 |
.IX Header "SEE ALSO" |
| 815 |
The CPAN module Term::ExtendedColor provides a different and more |
| 816 |
comprehensive interface for 256\-color emulators that may be more |
| 817 |
convenient. The CPAN module Win32::Console::ANSI provides ANSI color |
| 818 |
(and other escape sequence) support in the Win32 Console environment. |
| 819 |
The CPAN module Term::Chrome provides a different interface using |
| 820 |
objects and operator overloading. |
| 821 |
.PP |
| 822 |
ECMA\-048 is available on-line (at least at the time of this writing) at |
| 823 |
<https://www.ecma\-international.org/publications/standards/Ecma\-048.htm>. |
| 824 |
.PP |
| 825 |
ISO 6429 is available from ISO for a charge; the author of this module |
| 826 |
does not own a copy of it. Since the source material for ISO 6429 was |
| 827 |
ECMA\-048 and the latter is available for free, there seems little reason |
| 828 |
to obtain the ISO standard. |
| 829 |
.PP |
| 830 |
The 256\-color control sequences are documented at |
| 831 |
<https://invisible\-island.net/xterm/ctlseqs/ctlseqs.html> (search for |
| 832 |
256\-color). |
| 833 |
.PP |
| 834 |
Information about true color support in various terminal emulators and test |
| 835 |
programs you can run to check the true color support in your terminal emulator |
| 836 |
are available at <https://gist.github.com/XVilka/8346728>. |
| 837 |
.PP |
| 838 |
CLICOLORS <https://bixense.com/clicolors/> and |
| 839 |
NO_COLOR <https://no-color.org/> are useful standards to be aware of, and |
| 840 |
ideally follow, for any application using color. Term::ANSIColor complies |
| 841 |
with the latter. |
| 842 |
.PP |
| 843 |
The current version of this module is always available from its web site |
| 844 |
at <https://www.eyrie.org/~eagle/software/ansicolor/>. It is also part |
| 845 |
of the Perl core distribution as of 5.6.0. |