1Term::ANSIColor(3pm) Perl Programmers Reference Guide Term::ANSIColor(3pm)
2
6 Term::ANSIColor - Color screen output using ANSI escape sequences
7
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.\n", 'yellow on_magenta');
15 print "This text is normal.\n";
16 print colored ['yellow on_magenta'], "Yellow on magenta.\n";
17 use Term::ANSIColor qw(uncolor);
19 print uncolor '01;31', "\n";
20 use Term::ANSIColor qw(:constants);
22 print BOLD, BLUE, "This text is in bold blue.\n", RESET;
23 use Term::ANSIColor qw(:constants);
25 $Term::ANSIColor::AUTORESET = 1;
26 print BOLD BLUE "This text is in bold blue.\n";
27 print "This text is normal.\n";
28
30 This module has two interfaces, one through color() and colored() and
31 the other through constants. It also offers the utility function
32 uncolor(), which has to be explicitly imported to be used (see SYNOP‐
33 SIS).
34 color() takes any number of strings as arguments and considers them to
36 be space-separated lists of attributes. It then forms and returns the
37 escape sequence to set those attributes. It doesn't print it out, just
38 returns it, so you'll have to print it yourself if you want to (this is
39 so that you can save it as a string, pass it to something else, send it
40 to a file handle, or do anything else with it that you might care to).
41 uncolor() performs the opposite translation, turning escape sequences
43 into a list of strings.
44 The recognized attributes (all of which should be fairly intuitive) are
46 clear, reset, dark, bold, underline, underscore, blink, reverse, con‐
47 cealed, black, red, green, yellow, blue, magenta, on_black, on_red,
48 on_green, on_yellow, on_blue, on_magenta, on_cyan, and on_white. Case
49 is not significant. Underline and underscore are equivalent, as are
50 clear and reset, so use whichever is the most intuitive to you. The
51 color alone sets the foreground color, and on_color sets the background
52 color.
53 Note that not all attributes are supported by all terminal types, and
55 some terminals may not support any of these sequences. Dark, blink,
56 and concealed in particular are frequently not implemented.
57 Attributes, once set, last until they are unset (by sending the
59 attribute "reset"). Be careful to do this, or otherwise your attribute
60 will last after your script is done running, and people get very
61 annoyed at having their prompt and typing changed to weird colors.
62 As an aid to help with this, colored() takes a scalar as the first
64 argument and any number of attribute strings as the second argument and
65 returns the scalar wrapped in escape codes so that the attributes will
66 be set as requested before the string and reset to normal after the
67 string. Alternately, you can pass a reference to an array as the first
68 argument, and then the contents of that array will be taken as
69 attributes and color codes and the remainder of the arguments as text
70 to colorize.
71 Normally, colored() just puts attribute codes at the beginning and end
73 of the string, but if you set $Term::ANSIColor::EACHLINE to some
74 string, that string will be considered the line delimiter and the
75 attribute will be set at the beginning of each line of the passed
76 string and reset at the end of each line. This is often desirable if
77 the output is being sent to a program like a pager that can be confused
78 by attributes that span lines. Normally you'll want to set
79 $Term::ANSIColor::EACHLINE to "\n" to use this feature.
80 Alternately, if you import ":constants", you can use the constants
82 CLEAR, RESET, BOLD, DARK, UNDERLINE, UNDERSCORE, BLINK, REVERSE, CON‐
83 CEALED, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE,
84 ON_BLACK, ON_RED, ON_GREEN, ON_YELLOW, ON_BLUE, ON_MAGENTA, ON_CYAN,
85 and ON_WHITE directly. These are the same as color('attribute') and
86 can be used if you prefer typing:
87 print BOLD BLUE ON_WHITE "Text\n", RESET;
89 to
91 print colored ("Text\n", 'bold blue on_white');
93 When using the constants, if you don't want to have to remember to add
95 the ", RESET" at the end of each print line, you can set $Term::ANSI‐
96 Color::AUTORESET to a true value. Then, the display mode will automat‐
97 ically be reset if there is no comma after the constant. In other
98 words, with that variable set:
99 print BOLD BLUE "Text\n";
101 will reset the display mode afterwards, whereas:
103 print BOLD, BLUE, "Text\n";
105 will not.
107 The subroutine interface has the advantage over the constants interface
109 in that only two subroutines are exported into your namespace, versus
110 twenty-two in the constants interface. On the flip side, the constants
111 interface has the advantage of better compile time error checking,
112 since misspelled names of colors or attributes in calls to color() and
113 colored() won't be caught until runtime whereas misspelled names of
114 constants will be caught at compile time. So, polute your namespace
115 with almost two dozen subroutines that you may not even use that often,
116 or risk a silly bug by mistyping an attribute. Your choice, TMTOWTDI
117 after all.
118
120 Bad escape sequence %s
121 (F) You passed an invalid ANSI escape sequence to uncolor().
122 Bareword "%s" not allowed while "strict subs" in use
124 (F) You probably mistyped a constant color name such as:
125 $Foobar = FOOBAR . "This line should be blue\n";
127 or:
129 @Foobar = FOOBAR, "This line should be blue\n";
131 This will only show up under use strict (another good reason to run
133 under use strict).
134 Invalid attribute name %s
136 (F) You passed an invalid attribute name to either color() or col‐
137 ored().
138 Name "%s" used only once: possible typo
140 (W) You probably mistyped a constant color name such as:
141 print FOOBAR "This text is color FOOBAR\n";
143 It's probably better to always use commas after constant names in
145 order to force the next error.
146 No comma allowed after filehandle
148 (F) You probably mistyped a constant color name such as:
149 print FOOBAR, "This text is color FOOBAR\n";
151 Generating this fatal compile error is one of the main advantages
153 of using the constants interface, since you'll immediately know if
154 you mistype a color name.
155 No name for escape sequence %s
157 (F) The ANSI escape sequence passed to uncolor() contains escapes
158 which aren't recognized and can't be translated to names.
159
161 ANSI_COLORS_DISABLED
162 If this environment variable is set, all of the functions defined
163 by this module (color(), colored(), and all of the constants not
164 previously used in the program) will not output any escape
165 sequences and instead will just return the empty string or pass
166 through the original text as appropriate. This is intended to sup‐
167 port easy use of scripts using this module on platforms that don't
168 support ANSI escape sequences.
169 For it to have its proper effect, this environment variable must be
171 set before any color constants are used in the program.
172
174 It would be nice if one could leave off the commas around the constants
175 entirely and just say:
176 print BOLD BLUE ON_WHITE "Text\n" RESET;
178 but the syntax of Perl doesn't allow this. You need a comma after the
180 string. (Of course, you may consider it a bug that commas between all
181 the constants aren't required, in which case you may feel free to
182 insert commas unless you're using $Term::ANSIColor::AUTORESET.)
183 For easier debuging, you may prefer to always use the commas when not
185 setting $Term::ANSIColor::AUTORESET so that you'll get a fatal compile
186 error rather than a warning.
187
189 The codes generated by this module are standard terminal control codes,
190 complying with ECMA-48 and ISO 6429 (generally referred to as "ANSI
191 color" for the color codes). The non-color control codes (bold, dark,
192 italic, underline, and reverse) are part of the earlier ANSI X3.64
193 standard for control sequences for video terminals and peripherals.
194 Note that not all displays are ISO 6429-compliant, or even X3.64-com‐
196 pliant (or are even attempting to be so). This module will not work as
197 expected on displays that do not honor these escape sequences, such as
198 cmd.exe, 4nt.exe, and command.com under either Windows NT or Windows
199 2000. They may just be ignored, or they may display as an ESC charac‐
200 ter followed by some apparent garbage.
201 Jean Delvare provided the following table of different common terminal
203 emulators and their support for the various attributes and others have
204 helped me flesh it out:
205 clear bold dark under blink reverse conceal
207 ------------------------------------------------------------------------
208 xterm yes yes no yes bold yes yes
209 linux yes yes yes bold yes yes no
210 rxvt yes yes no yes bold/black yes no
211 dtterm yes yes yes yes reverse yes yes
212 teraterm yes reverse no yes rev/red yes no
213 aixterm kinda normal no yes no yes yes
214 PuTTY yes color no yes no yes no
215 Windows yes no no no no yes no
216 Cygwin SSH yes yes no color color color yes
217 Mac Terminal yes yes no yes yes yes yes
218 Windows is Windows telnet, Cygwin SSH is the OpenSSH implementation
220 under Cygwin on Windows NT, and Mac Terminal is the Terminal applica‐
221 tion in Mac OS X. Where the entry is other than yes or no, that emula‐
222 tor displays the given attribute as something else instead. Note that
223 on an aixterm, clear doesn't reset colors; you have to explicitly set
224 the colors back to what you want. More entries in this table are wel‐
225 come.
226 Note that codes 3 (italic), 6 (rapid blink), and 9 (strikethrough) are
228 specified in ANSI X3.64 and ECMA-048 but are not commonly supported by
229 most displays and emulators and therefore aren't supported by this mod‐
230 ule at the present time. ECMA-048 also specifies a large number of
231 other attributes, including a sequence of attributes for font changes,
232 Fraktur characters, double-underlining, framing, circling, and overlin‐
233 ing. As none of these attributes are widely supported or useful, they
234 also aren't currently supported by this module.
235
237 ECMA-048 is available on-line (at least at the time of this writing) at
238 <http://www.ecma-international.org/publications/stan‐
239 dards/ECMA-048.HTM>.
240 ISO 6429 is available from ISO for a charge; the author of this module
242 does not own a copy of it. Since the source material for ISO 6429 was
243 ECMA-048 and the latter is available for free, there seems little rea‐
244 son to obtain the ISO standard.
245 The current version of this module is always available from its web
247 site at <http://www.eyrie.org/~eagle/software/ansicolor/>. It is also
248 part of the Perl core distribution as of 5.6.0.
249
251 Original idea (using constants) by Zenin, reimplemented using subs by
252 Russ Allbery <rra@stanford.edu>, and then combined with the original
253 idea by Russ with input from Zenin. Russ Allbery now maintains this
254 module.
255
257 Copyright 1996, 1997, 1998, 2000, 2001, 2002 Russ Allbery <rra@stan‐
258 ford.edu> and Zenin. This program is free software; you may redis‐
259 tribute it and/or modify it under the same terms as Perl itself.
260perl v5.8.8 2001-09-21 Term::ANSIColor(3pm)