Commit | Line | Data |
---|---|---|
e3e5e1ea | 1 | # Term::ANSIColor -- Color screen output using ANSI escape sequences. |
135dda52 | 2 | # $Id: ANSIColor.pm,v 1.5 2002/06/28 22:49:01 eagle Exp $ |
e3e5e1ea | 3 | # |
135dda52 | 4 | # Copyright 1996, 1997, 1998, 2000, 2001, 2002 |
110e9fb0 | 5 | # by Russ Allbery <rra@stanford.edu> and Zenin <zenin@bawdycaste.com> |
e3e5e1ea | 6 | # |
110e9fb0 | 7 | # This program is free software; you may redistribute it and/or modify it |
e3e5e1ea | 8 | # under the same terms as Perl itself. |
f63addff JH |
9 | # |
10 | # Ah, September, when the sysadmins turn colors and fall off the trees.... | |
11 | # -- Dave Van Domelen | |
e3e5e1ea | 12 | |
135dda52 | 13 | ############################################################################## |
e3e5e1ea | 14 | # Modules and declarations |
135dda52 | 15 | ############################################################################## |
e3e5e1ea GS |
16 | |
17 | package Term::ANSIColor; | |
18 | require 5.001; | |
19 | ||
20 | use strict; | |
110e9fb0 JH |
21 | use vars qw($AUTOLOAD $AUTORESET $EACHLINE @ISA @EXPORT @EXPORT_OK |
22 | %EXPORT_TAGS $VERSION %attributes %attributes_r); | |
e3e5e1ea GS |
23 | |
24 | use Exporter (); | |
25 | @ISA = qw(Exporter); | |
26 | @EXPORT = qw(color colored); | |
110e9fb0 | 27 | @EXPORT_OK = qw(uncolor); |
e3e5e1ea GS |
28 | %EXPORT_TAGS = (constants => [qw(CLEAR RESET BOLD UNDERLINE UNDERSCORE BLINK |
29 | REVERSE CONCEALED BLACK RED GREEN YELLOW | |
30 | BLUE MAGENTA CYAN WHITE ON_BLACK ON_RED | |
31 | ON_GREEN ON_YELLOW ON_BLUE ON_MAGENTA | |
32 | ON_CYAN ON_WHITE)]); | |
33 | Exporter::export_ok_tags ('constants'); | |
f63addff | 34 | |
135dda52 JH |
35 | # Don't use the CVS revision as the version, since this module is also in Perl |
36 | # core and too many things could munge CVS magic revision strings. | |
05b46583 | 37 | $VERSION = 1.06; |
e3e5e1ea | 38 | |
135dda52 | 39 | ############################################################################## |
e3e5e1ea | 40 | # Internal data structures |
135dda52 | 41 | ############################################################################## |
e3e5e1ea GS |
42 | |
43 | %attributes = ('clear' => 0, | |
44 | 'reset' => 0, | |
45 | 'bold' => 1, | |
f63addff | 46 | 'dark' => 2, |
e3e5e1ea GS |
47 | 'underline' => 4, |
48 | 'underscore' => 4, | |
49 | 'blink' => 5, | |
50 | 'reverse' => 7, | |
51 | 'concealed' => 8, | |
52 | ||
110e9fb0 JH |
53 | 'black' => 30, 'on_black' => 40, |
54 | 'red' => 31, 'on_red' => 41, | |
55 | 'green' => 32, 'on_green' => 42, | |
56 | 'yellow' => 33, 'on_yellow' => 43, | |
57 | 'blue' => 34, 'on_blue' => 44, | |
58 | 'magenta' => 35, 'on_magenta' => 45, | |
59 | 'cyan' => 36, 'on_cyan' => 46, | |
e3e5e1ea GS |
60 | 'white' => 37, 'on_white' => 47); |
61 | ||
110e9fb0 JH |
62 | # Reverse lookup. Alphabetically first name for a sequence is preferred. |
63 | for (reverse sort keys %attributes) { | |
64 | $attributes_r{$attributes{$_}} = $_; | |
65 | } | |
66 | ||
135dda52 | 67 | ############################################################################## |
e3e5e1ea | 68 | # Implementation (constant form) |
135dda52 | 69 | ############################################################################## |
e3e5e1ea | 70 | |
135dda52 JH |
71 | # Time to have fun! We now want to define the constant subs, which are named |
72 | # the same as the attributes above but in all caps. Each constant sub needs | |
73 | # to act differently depending on whether $AUTORESET is set. Without | |
e3e5e1ea GS |
74 | # autoreset: |
75 | # | |
135dda52 | 76 | # BLUE "text\n" ==> "\e[34mtext\n" |
e3e5e1ea GS |
77 | # |
78 | # If $AUTORESET is set, we should instead get: | |
79 | # | |
135dda52 | 80 | # BLUE "text\n" ==> "\e[34mtext\n\e[0m" |
e3e5e1ea GS |
81 | # |
82 | # The sub also needs to handle the case where it has no arguments correctly. | |
135dda52 JH |
83 | # Maintaining all of this as separate subs would be a major nightmare, as well |
84 | # as duplicate the %attributes hash, so instead we define an AUTOLOAD sub to | |
85 | # define the constant subs on demand. To do that, we check the name of the | |
86 | # called sub against the list of attributes, and if it's an all-caps version | |
87 | # of one of them, we define the sub on the fly and then run it. | |
110e9fb0 JH |
88 | # |
89 | # If the environment variable ANSI_COLORS_DISABLED is set, turn all of the | |
90 | # generated subs into pass-through functions that don't add any escape | |
91 | # sequences. This is to make it easier to write scripts that also work on | |
92 | # systems without any ANSI support, like Windows consoles. | |
e3e5e1ea | 93 | sub AUTOLOAD { |
110e9fb0 | 94 | my $enable_colors = !defined $ENV{ANSI_COLORS_DISABLED}; |
e3e5e1ea GS |
95 | my $sub; |
96 | ($sub = $AUTOLOAD) =~ s/^.*:://; | |
97 | my $attr = $attributes{lc $sub}; | |
98 | if ($sub =~ /^[A-Z_]+$/ && defined $attr) { | |
110e9fb0 | 99 | $attr = $enable_colors ? "\e[" . $attr . 'm' : ''; |
e3e5e1ea GS |
100 | eval qq { |
101 | sub $AUTOLOAD { | |
102 | if (\$AUTORESET && \@_) { | |
103 | '$attr' . "\@_" . "\e[0m"; | |
104 | } else { | |
105 | ('$attr' . "\@_"); | |
106 | } | |
107 | } | |
108 | }; | |
109 | goto &$AUTOLOAD; | |
110 | } else { | |
f63addff JH |
111 | require Carp; |
112 | Carp::croak ("undefined subroutine &$AUTOLOAD called"); | |
e3e5e1ea GS |
113 | } |
114 | } | |
115 | ||
135dda52 | 116 | ############################################################################## |
e3e5e1ea | 117 | # Implementation (attribute string form) |
135dda52 | 118 | ############################################################################## |
e3e5e1ea GS |
119 | |
120 | # Return the escape code for a given set of color attributes. | |
121 | sub color { | |
110e9fb0 | 122 | return '' if defined $ENV{ANSI_COLORS_DISABLED}; |
e3e5e1ea GS |
123 | my @codes = map { split } @_; |
124 | my $attribute = ''; | |
125 | foreach (@codes) { | |
126 | $_ = lc $_; | |
127 | unless (defined $attributes{$_}) { | |
128 | require Carp; | |
129 | Carp::croak ("Invalid attribute name $_"); | |
130 | } | |
131 | $attribute .= $attributes{$_} . ';'; | |
132 | } | |
133 | chop $attribute; | |
134 | ($attribute ne '') ? "\e[${attribute}m" : undef; | |
135 | } | |
136 | ||
110e9fb0 | 137 | # Return a list of named color attributes for a given set of escape codes. |
135dda52 JH |
138 | # Escape sequences can be given with or without enclosing "\e[" and "m". The |
139 | # empty escape sequence '' or "\e[m" gives an empty list of attrs. | |
110e9fb0 JH |
140 | sub uncolor { |
141 | my (@nums, @result); | |
142 | for (@_) { | |
143 | my $escape = $_; | |
144 | $escape =~ s/^\e\[//; | |
145 | $escape =~ s/m$//; | |
146 | unless ($escape =~ /^((?:\d+;)*\d*)$/) { | |
147 | require Carp; | |
148 | Carp::croak ("Bad escape sequence $_"); | |
149 | } | |
150 | push (@nums, split (/;/, $1)); | |
151 | } | |
152 | for (@nums) { | |
153 | $_ += 0; # Strip leading zeroes | |
154 | my $name = $attributes_r{$_}; | |
155 | if (!defined $name) { | |
156 | require Carp; | |
157 | Carp::croak ("No name for escape sequence $_" ); | |
158 | } | |
159 | push (@result, $name); | |
160 | } | |
161 | @result; | |
162 | } | |
163 | ||
e3e5e1ea GS |
164 | # Given a string and a set of attributes, returns the string surrounded by |
165 | # escape codes to set those attributes and then clear them at the end of the | |
f63addff | 166 | # string. The attributes can be given either as an array ref as the first |
135dda52 JH |
167 | # argument or as a list as the second and subsequent arguments. If $EACHLINE |
168 | # is set, insert a reset before each occurrence of the string $EACHLINE and | |
169 | # the starting attribute code after the string $EACHLINE, so that no attribute | |
170 | # crosses line delimiters (this is often desirable if the output is to be | |
171 | # piped to a pager or some other program). | |
e3e5e1ea | 172 | sub colored { |
f63addff JH |
173 | my ($string, @codes); |
174 | if (ref $_[0]) { | |
175 | @codes = @{+shift}; | |
176 | $string = join ('', @_); | |
177 | } else { | |
178 | $string = shift; | |
179 | @codes = @_; | |
180 | } | |
110e9fb0 | 181 | return $string if defined $ENV{ANSI_COLORS_DISABLED}; |
e3e5e1ea | 182 | if (defined $EACHLINE) { |
f63addff | 183 | my $attr = color (@codes); |
110e9fb0 | 184 | join '', |
e3e5e1ea GS |
185 | map { $_ && $_ ne $EACHLINE ? $attr . $_ . "\e[0m" : $_ } |
186 | split (/(\Q$EACHLINE\E)/, $string); | |
187 | } else { | |
f63addff | 188 | color (@codes) . $string . "\e[0m"; |
e3e5e1ea GS |
189 | } |
190 | } | |
191 | ||
135dda52 | 192 | ############################################################################## |
e3e5e1ea | 193 | # Module return value and documentation |
135dda52 | 194 | ############################################################################## |
e3e5e1ea GS |
195 | |
196 | # Ensure we evaluate to true. | |
197 | 1; | |
198 | __END__ | |
199 | ||
200 | =head1 NAME | |
201 | ||
202 | Term::ANSIColor - Color screen output using ANSI escape sequences | |
203 | ||
204 | =head1 SYNOPSIS | |
205 | ||
206 | use Term::ANSIColor; | |
207 | print color 'bold blue'; | |
208 | print "This text is bold blue.\n"; | |
209 | print color 'reset'; | |
210 | print "This text is normal.\n"; | |
211 | print colored ("Yellow on magenta.\n", 'yellow on_magenta'); | |
212 | print "This text is normal.\n"; | |
f63addff | 213 | print colored ['yellow on_magenta'], "Yellow on magenta.\n"; |
e3e5e1ea | 214 | |
110e9fb0 JH |
215 | use Term::ANSIColor qw(uncolor); |
216 | print uncolor '01;31', "\n"; | |
217 | ||
e3e5e1ea GS |
218 | use Term::ANSIColor qw(:constants); |
219 | print BOLD, BLUE, "This text is in bold blue.\n", RESET; | |
220 | ||
221 | use Term::ANSIColor qw(:constants); | |
222 | $Term::ANSIColor::AUTORESET = 1; | |
223 | print BOLD BLUE "This text is in bold blue.\n"; | |
224 | print "This text is normal.\n"; | |
225 | ||
226 | =head1 DESCRIPTION | |
227 | ||
228 | This module has two interfaces, one through color() and colored() and the | |
110e9fb0 | 229 | other through constants. It also offers the utility function uncolor(), |
96cbc021 | 230 | which has to be explicitly imported to be used (see L<SYNOPSIS>). |
bbc7dcd2 | 231 | |
e3e5e1ea GS |
232 | color() takes any number of strings as arguments and considers them to be |
233 | space-separated lists of attributes. It then forms and returns the escape | |
110e9fb0 JH |
234 | sequence to set those attributes. It doesn't print it out, just returns it, |
235 | so you'll have to print it yourself if you want to (this is so that you can | |
236 | save it as a string, pass it to something else, send it to a file handle, or | |
237 | do anything else with it that you might care to). | |
238 | ||
239 | uncolor() performs the opposite translation, turning escape sequences | |
240 | into a list of strings. | |
e3e5e1ea GS |
241 | |
242 | The recognized attributes (all of which should be fairly intuitive) are | |
110e9fb0 JH |
243 | clear, reset, dark, bold, underline, underscore, blink, reverse, concealed, |
244 | black, red, green, yellow, blue, magenta, on_black, on_red, on_green, | |
245 | on_yellow, on_blue, on_magenta, on_cyan, and on_white. Case is not | |
246 | significant. Underline and underscore are equivalent, as are clear and | |
247 | reset, so use whichever is the most intuitive to you. The color alone sets | |
248 | the foreground color, and on_color sets the background color. | |
e3e5e1ea | 249 | |
f63addff JH |
250 | Note that not all attributes are supported by all terminal types, and some |
251 | terminals may not support any of these sequences. Dark, blink, and | |
252 | concealed in particular are frequently not implemented. | |
253 | ||
254 | Attributes, once set, last until they are unset (by sending the attribute | |
255 | "reset"). Be careful to do this, or otherwise your attribute will last | |
256 | after your script is done running, and people get very annoyed at having | |
257 | their prompt and typing changed to weird colors. | |
e3e5e1ea | 258 | |
110e9fb0 JH |
259 | As an aid to help with this, colored() takes a scalar as the first argument |
260 | and any number of attribute strings as the second argument and returns the | |
261 | scalar wrapped in escape codes so that the attributes will be set as | |
262 | requested before the string and reset to normal after the string. | |
263 | Alternately, you can pass a reference to an array as the first argument, and | |
264 | then the contents of that array will be taken as attributes and color codes | |
265 | and the remainder of the arguments as text to colorize. | |
f63addff | 266 | |
e3e5e1ea | 267 | Normally, colored() just puts attribute codes at the beginning and end of |
110e9fb0 JH |
268 | the string, but if you set $Term::ANSIColor::EACHLINE to some string, that |
269 | string will be considered the line delimiter and the attribute will be set | |
270 | at the beginning of each line of the passed string and reset at the end of | |
271 | each line. This is often desirable if the output is being sent to a program | |
272 | like a pager that can be confused by attributes that span lines. Normally | |
273 | you'll want to set $Term::ANSIColor::EACHLINE to C<"\n"> to use this | |
274 | feature. | |
e3e5e1ea GS |
275 | |
276 | Alternately, if you import C<:constants>, you can use the constants CLEAR, | |
110e9fb0 JH |
277 | RESET, BOLD, DARK, UNDERLINE, UNDERSCORE, BLINK, REVERSE, CONCEALED, BLACK, |
278 | RED, GREEN, YELLOW, BLUE, MAGENTA, ON_BLACK, ON_RED, ON_GREEN, ON_YELLOW, | |
279 | ON_BLUE, ON_MAGENTA, ON_CYAN, and ON_WHITE directly. These are the same as | |
280 | color('attribute') and can be used if you prefer typing: | |
e3e5e1ea GS |
281 | |
282 | print BOLD BLUE ON_WHITE "Text\n", RESET; | |
283 | ||
284 | to | |
285 | ||
286 | print colored ("Text\n", 'bold blue on_white'); | |
287 | ||
288 | When using the constants, if you don't want to have to remember to add the | |
289 | C<, RESET> at the end of each print line, you can set | |
290 | $Term::ANSIColor::AUTORESET to a true value. Then, the display mode will | |
291 | automatically be reset if there is no comma after the constant. In other | |
292 | words, with that variable set: | |
293 | ||
294 | print BOLD BLUE "Text\n"; | |
295 | ||
296 | will reset the display mode afterwards, whereas: | |
297 | ||
298 | print BOLD, BLUE, "Text\n"; | |
299 | ||
300 | will not. | |
301 | ||
302 | The subroutine interface has the advantage over the constants interface in | |
f63addff JH |
303 | that only two subroutines are exported into your namespace, versus |
304 | twenty-two in the constants interface. On the flip side, the constants | |
305 | interface has the advantage of better compile time error checking, since | |
306 | misspelled names of colors or attributes in calls to color() and colored() | |
110e9fb0 JH |
307 | won't be caught until runtime whereas misspelled names of constants will be |
308 | caught at compile time. So, polute your namespace with almost two dozen | |
309 | subroutines that you may not even use that often, or risk a silly bug by | |
310 | mistyping an attribute. Your choice, TMTOWTDI after all. | |
e3e5e1ea GS |
311 | |
312 | =head1 DIAGNOSTICS | |
313 | ||
314 | =over 4 | |
315 | ||
110e9fb0 JH |
316 | =item Bad escape sequence %s |
317 | ||
318 | (F) You passed an invalid ANSI escape sequence to uncolor(). | |
319 | ||
320 | =item Bareword "%s" not allowed while "strict subs" in use | |
321 | ||
322 | (F) You probably mistyped a constant color name such as: | |
323 | ||
324 | $Foobar = FOOBAR . "This line should be blue\n"; | |
325 | ||
326 | or: | |
327 | ||
328 | @Foobar = FOOBAR, "This line should be blue\n"; | |
329 | ||
330 | This will only show up under use strict (another good reason to run under | |
331 | use strict). | |
332 | ||
e3e5e1ea GS |
333 | =item Invalid attribute name %s |
334 | ||
f63addff | 335 | (F) You passed an invalid attribute name to either color() or colored(). |
e3e5e1ea | 336 | |
f63addff | 337 | =item Name "%s" used only once: possible typo |
e3e5e1ea | 338 | |
f63addff | 339 | (W) You probably mistyped a constant color name such as: |
e3e5e1ea GS |
340 | |
341 | print FOOBAR "This text is color FOOBAR\n"; | |
342 | ||
343 | It's probably better to always use commas after constant names in order to | |
344 | force the next error. | |
345 | ||
346 | =item No comma allowed after filehandle | |
347 | ||
f63addff | 348 | (F) You probably mistyped a constant color name such as: |
e3e5e1ea GS |
349 | |
350 | print FOOBAR, "This text is color FOOBAR\n"; | |
351 | ||
352 | Generating this fatal compile error is one of the main advantages of using | |
353 | the constants interface, since you'll immediately know if you mistype a | |
354 | color name. | |
355 | ||
110e9fb0 | 356 | =item No name for escape sequence %s |
e3e5e1ea | 357 | |
110e9fb0 JH |
358 | (F) The ANSI escape sequence passed to uncolor() contains escapes which |
359 | aren't recognized and can't be translated to names. | |
e3e5e1ea | 360 | |
110e9fb0 | 361 | =back |
e3e5e1ea | 362 | |
110e9fb0 | 363 | =head1 ENVIRONMENT |
e3e5e1ea | 364 | |
110e9fb0 | 365 | =over 4 |
e3e5e1ea | 366 | |
110e9fb0 JH |
367 | =item ANSI_COLORS_DISABLED |
368 | ||
369 | If this environment variable is set, all of the functions defined by this | |
370 | module (color(), colored(), and all of the constants not previously used in | |
371 | the program) will not output any escape sequences and instead will just | |
372 | return the empty string or pass through the original text as appropriate. | |
373 | This is intended to support easy use of scripts using this module on | |
374 | platforms that don't support ANSI escape sequences. | |
375 | ||
376 | For it to have its proper effect, this environment variable must be set | |
377 | before any color constants are used in the program. | |
e3e5e1ea GS |
378 | |
379 | =back | |
380 | ||
381 | =head1 RESTRICTIONS | |
382 | ||
383 | It would be nice if one could leave off the commas around the constants | |
384 | entirely and just say: | |
385 | ||
386 | print BOLD BLUE ON_WHITE "Text\n" RESET; | |
387 | ||
388 | but the syntax of Perl doesn't allow this. You need a comma after the | |
389 | string. (Of course, you may consider it a bug that commas between all the | |
110e9fb0 JH |
390 | constants aren't required, in which case you may feel free to insert commas |
391 | unless you're using $Term::ANSIColor::AUTORESET.) | |
e3e5e1ea GS |
392 | |
393 | For easier debuging, you may prefer to always use the commas when not | |
110e9fb0 JH |
394 | setting $Term::ANSIColor::AUTORESET so that you'll get a fatal compile error |
395 | rather than a warning. | |
e3e5e1ea | 396 | |
f63addff JH |
397 | =head1 NOTES |
398 | ||
110e9fb0 JH |
399 | The codes generated by this module are standard terminal control codes, |
400 | complying with ECMA-48 and ISO 6429 (generally referred to as "ANSI color" | |
401 | for the color codes). The non-color control codes (bold, dark, italic, | |
402 | underline, and reverse) are part of the earlier ANSI X3.64 standard for | |
403 | control sequences for video terminals and peripherals. | |
404 | ||
405 | Note that not all displays are ISO 6429-compliant, or even X3.64-compliant | |
406 | (or are even attempting to be so). This module will not work as expected on | |
135dda52 JH |
407 | displays that do not honor these escape sequences, such as cmd.exe, 4nt.exe, |
408 | and command.com under either Windows NT or Windows 2000. They may just be | |
409 | ignored, or they may display as an ESC character followed by some apparent | |
410 | garbage. | |
110e9fb0 | 411 | |
f63addff JH |
412 | Jean Delvare provided the following table of different common terminal |
413 | emulators and their support for the various attributes: | |
414 | ||
415 | clear bold dark under blink reverse conceal | |
416 | ------------------------------------------------------------------------ | |
417 | xterm yes yes no yes bold yes yes | |
418 | linux yes yes yes bold yes yes no | |
419 | rxvt yes yes no yes bold/black yes no | |
420 | dtterm yes yes yes yes reverse yes yes | |
421 | teraterm yes reverse no yes rev/red yes no | |
422 | aixterm kinda normal no yes no yes yes | |
423 | ||
424 | Where the entry is other than yes or no, that emulator interpret the given | |
110e9fb0 JH |
425 | attribute as something else instead. Note that on an aixterm, clear doesn't |
426 | reset colors; you have to explicitly set the colors back to what you want. | |
427 | More entries in this table are welcome. | |
428 | ||
429 | Note that codes 3 (italic), 6 (rapid blink), and 9 (strikethrough) are | |
430 | specified in ANSI X3.64 and ECMA-048 but are not commonly supported by most | |
431 | displays and emulators and therefore aren't supported by this module at the | |
432 | present time. ECMA-048 also specifies a large number of other attributes, | |
433 | including a sequence of attributes for font changes, Fraktur characters, | |
434 | double-underlining, framing, circling, and overlining. As none of these | |
435 | attributes are widely supported or useful, they also aren't currently | |
436 | supported by this module. | |
437 | ||
438 | =head1 SEE ALSO | |
439 | ||
440 | ECMA-048 is available on-line (at least at the time of this writing) at | |
135dda52 | 441 | L<http://www.ecma.ch/ecma1/STAND/ECMA-048.HTM>. |
110e9fb0 JH |
442 | |
443 | ISO 6429 is available from ISO for a charge; the author of this module does | |
444 | not own a copy of it. Since the source material for ISO 6429 was ECMA-048 | |
445 | and the latter is available for free, there seems little reason to obtain | |
446 | the ISO standard. | |
f63addff | 447 | |
135dda52 JH |
448 | The current version of this module is always available from its web site at |
449 | L<http://www.eyrie.org/~eagle/software/ansicolor/>. It is also part of the | |
450 | Perl core distribution as of 5.6.0. | |
451 | ||
e3e5e1ea GS |
452 | =head1 AUTHORS |
453 | ||
110e9fb0 | 454 | Original idea (using constants) by Zenin, reimplemented using subs by Russ |
135dda52 JH |
455 | Allbery <rra@stanford.edu>, and then combined with the original idea by Russ |
456 | with input from Zenin. Russ Allbery now maintains this module. | |
110e9fb0 | 457 | |
135dda52 | 458 | =head1 COPYRIGHT AND LICENSE |
110e9fb0 | 459 | |
135dda52 JH |
460 | Copyright 1996, 1997, 1998, 2000, 2001, 2002 Russ Allbery <rra@stanford.edu> |
461 | and Zenin <zenin@bawdycaste.org>. This program is free software; you may | |
110e9fb0 | 462 | redistribute it and/or modify it under the same terms as Perl itself. |
e3e5e1ea GS |
463 | |
464 | =cut |