Commit | Line | Data |
---|---|---|
e3e5e1ea | 1 | # Term::ANSIColor -- Color screen output using ANSI escape sequences. |
e3e5e1ea | 2 | # |
c23d8173 RGS |
3 | # Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2008, 2009 |
4 | # Russ Allbery <rra@stanford.edu> and Zenin | |
5 | # PUSH/POP support submitted 2007 by openmethods.com voice solutions | |
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 | ||
cdab9eb9 | 20 | $VERSION = '2.02'; |
c23d8173 | 21 | |
e3e5e1ea | 22 | use strict; |
c23d8173 RGS |
23 | use vars qw($AUTOLOAD $AUTOLOCAL $AUTORESET @COLORLIST @COLORSTACK $EACHLINE |
24 | @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $VERSION %ATTRIBUTES | |
25 | %ATTRIBUTES_R); | |
e3e5e1ea GS |
26 | |
27 | use Exporter (); | |
c23d8173 | 28 | BEGIN { |
cdab9eb9 S |
29 | @COLORLIST = qw(CLEAR RESET BOLD DARK FAINT UNDERLINE UNDERSCORE BLINK |
30 | REVERSE CONCEALED BLACK RED GREEN YELLOW BLUE MAGENTA | |
31 | CYAN WHITE ON_BLACK ON_RED ON_GREEN ON_YELLOW ON_BLUE | |
32 | ON_MAGENTA ON_CYAN ON_WHITE); | |
c23d8173 RGS |
33 | @ISA = qw(Exporter); |
34 | @EXPORT = qw(color colored); | |
cdab9eb9 | 35 | @EXPORT_OK = qw(uncolor colorstrip colorvalid); |
c23d8173 RGS |
36 | %EXPORT_TAGS = (constants => \@COLORLIST, |
37 | pushpop => [ @COLORLIST, | |
38 | qw(PUSHCOLOR POPCOLOR LOCALCOLOR) ]); | |
39 | Exporter::export_ok_tags ('pushpop'); | |
40 | } | |
e3e5e1ea | 41 | |
135dda52 | 42 | ############################################################################## |
e3e5e1ea | 43 | # Internal data structures |
135dda52 | 44 | ############################################################################## |
e3e5e1ea | 45 | |
c23d8173 | 46 | %ATTRIBUTES = ('clear' => 0, |
e3e5e1ea GS |
47 | 'reset' => 0, |
48 | 'bold' => 1, | |
f63addff | 49 | 'dark' => 2, |
c23d8173 | 50 | 'faint' => 2, |
e3e5e1ea GS |
51 | 'underline' => 4, |
52 | 'underscore' => 4, | |
53 | 'blink' => 5, | |
54 | 'reverse' => 7, | |
55 | 'concealed' => 8, | |
56 | ||
110e9fb0 JH |
57 | 'black' => 30, 'on_black' => 40, |
58 | 'red' => 31, 'on_red' => 41, | |
59 | 'green' => 32, 'on_green' => 42, | |
60 | 'yellow' => 33, 'on_yellow' => 43, | |
61 | 'blue' => 34, 'on_blue' => 44, | |
62 | 'magenta' => 35, 'on_magenta' => 45, | |
63 | 'cyan' => 36, 'on_cyan' => 46, | |
e3e5e1ea GS |
64 | 'white' => 37, 'on_white' => 47); |
65 | ||
110e9fb0 | 66 | # Reverse lookup. Alphabetically first name for a sequence is preferred. |
c23d8173 RGS |
67 | for (reverse sort keys %ATTRIBUTES) { |
68 | $ATTRIBUTES_R{$ATTRIBUTES{$_}} = $_; | |
110e9fb0 JH |
69 | } |
70 | ||
135dda52 | 71 | ############################################################################## |
e3e5e1ea | 72 | # Implementation (constant form) |
135dda52 | 73 | ############################################################################## |
e3e5e1ea | 74 | |
135dda52 JH |
75 | # Time to have fun! We now want to define the constant subs, which are named |
76 | # the same as the attributes above but in all caps. Each constant sub needs | |
77 | # to act differently depending on whether $AUTORESET is set. Without | |
e3e5e1ea GS |
78 | # autoreset: |
79 | # | |
135dda52 | 80 | # BLUE "text\n" ==> "\e[34mtext\n" |
e3e5e1ea GS |
81 | # |
82 | # If $AUTORESET is set, we should instead get: | |
83 | # | |
135dda52 | 84 | # BLUE "text\n" ==> "\e[34mtext\n\e[0m" |
e3e5e1ea GS |
85 | # |
86 | # The sub also needs to handle the case where it has no arguments correctly. | |
135dda52 | 87 | # Maintaining all of this as separate subs would be a major nightmare, as well |
c23d8173 | 88 | # as duplicate the %ATTRIBUTES hash, so instead we define an AUTOLOAD sub to |
135dda52 JH |
89 | # define the constant subs on demand. To do that, we check the name of the |
90 | # called sub against the list of attributes, and if it's an all-caps version | |
91 | # of one of them, we define the sub on the fly and then run it. | |
110e9fb0 | 92 | # |
c23d8173 RGS |
93 | # If the environment variable ANSI_COLORS_DISABLED is set, just return the |
94 | # arguments without adding any escape sequences. This is to make it easier to | |
95 | # write scripts that also work on systems without any ANSI support, like | |
96 | # Windows consoles. | |
e3e5e1ea | 97 | sub AUTOLOAD { |
c23d8173 RGS |
98 | if (defined $ENV{ANSI_COLORS_DISABLED}) { |
99 | return join ('', @_); | |
100 | } | |
b5b25974 RGS |
101 | if ($AUTOLOAD =~ /^([\w:]*::([A-Z_]+))$/ and defined $ATTRIBUTES{lc $2}) { |
102 | $AUTOLOAD = $1; | |
103 | my $attr = "\e[" . $ATTRIBUTES{lc $2} . 'm'; | |
e3e5e1ea GS |
104 | eval qq { |
105 | sub $AUTOLOAD { | |
106 | if (\$AUTORESET && \@_) { | |
c23d8173 RGS |
107 | return '$attr' . join ('', \@_) . "\e[0m"; |
108 | } elsif (\$AUTOLOCAL && \@_) { | |
109 | return PUSHCOLOR ('$attr') . join ('', \@_) . POPCOLOR; | |
e3e5e1ea | 110 | } else { |
c23d8173 | 111 | return '$attr' . join ('', \@_); |
e3e5e1ea GS |
112 | } |
113 | } | |
114 | }; | |
115 | goto &$AUTOLOAD; | |
116 | } else { | |
f63addff JH |
117 | require Carp; |
118 | Carp::croak ("undefined subroutine &$AUTOLOAD called"); | |
e3e5e1ea GS |
119 | } |
120 | } | |
121 | ||
c23d8173 RGS |
122 | # Append a new color to the top of the color stack and return the top of |
123 | # the stack. | |
124 | sub PUSHCOLOR { | |
125 | my ($text) = @_; | |
126 | my ($color) = ($text =~ m/^((?:\e\[[\d;]+m)+)/); | |
127 | if (@COLORSTACK) { | |
128 | $color = $COLORSTACK[-1] . $color; | |
129 | } | |
130 | push (@COLORSTACK, $color); | |
131 | return $text; | |
132 | } | |
133 | ||
134 | # Pop the color stack and return the new top of the stack (or reset, if | |
135 | # the stack is empty). | |
136 | sub POPCOLOR { | |
137 | pop @COLORSTACK; | |
138 | if (@COLORSTACK) { | |
139 | return $COLORSTACK[-1] . join ('', @_); | |
140 | } else { | |
141 | return RESET (@_); | |
142 | } | |
143 | } | |
144 | ||
145 | # Surround arguments with a push and a pop. | |
146 | sub LOCALCOLOR { | |
147 | return PUSHCOLOR (join ('', @_)) . POPCOLOR (); | |
148 | } | |
149 | ||
135dda52 | 150 | ############################################################################## |
e3e5e1ea | 151 | # Implementation (attribute string form) |
135dda52 | 152 | ############################################################################## |
e3e5e1ea GS |
153 | |
154 | # Return the escape code for a given set of color attributes. | |
155 | sub color { | |
110e9fb0 | 156 | return '' if defined $ENV{ANSI_COLORS_DISABLED}; |
e3e5e1ea GS |
157 | my @codes = map { split } @_; |
158 | my $attribute = ''; | |
159 | foreach (@codes) { | |
160 | $_ = lc $_; | |
c23d8173 | 161 | unless (defined $ATTRIBUTES{$_}) { |
e3e5e1ea GS |
162 | require Carp; |
163 | Carp::croak ("Invalid attribute name $_"); | |
164 | } | |
c23d8173 | 165 | $attribute .= $ATTRIBUTES{$_} . ';'; |
e3e5e1ea GS |
166 | } |
167 | chop $attribute; | |
c23d8173 | 168 | return ($attribute ne '') ? "\e[${attribute}m" : undef; |
e3e5e1ea GS |
169 | } |
170 | ||
110e9fb0 | 171 | # Return a list of named color attributes for a given set of escape codes. |
135dda52 JH |
172 | # Escape sequences can be given with or without enclosing "\e[" and "m". The |
173 | # empty escape sequence '' or "\e[m" gives an empty list of attrs. | |
110e9fb0 JH |
174 | sub uncolor { |
175 | my (@nums, @result); | |
176 | for (@_) { | |
177 | my $escape = $_; | |
178 | $escape =~ s/^\e\[//; | |
179 | $escape =~ s/m$//; | |
180 | unless ($escape =~ /^((?:\d+;)*\d*)$/) { | |
181 | require Carp; | |
b5b25974 | 182 | Carp::croak ("Bad escape sequence $escape"); |
110e9fb0 JH |
183 | } |
184 | push (@nums, split (/;/, $1)); | |
185 | } | |
186 | for (@nums) { | |
187 | $_ += 0; # Strip leading zeroes | |
c23d8173 | 188 | my $name = $ATTRIBUTES_R{$_}; |
110e9fb0 JH |
189 | if (!defined $name) { |
190 | require Carp; | |
191 | Carp::croak ("No name for escape sequence $_" ); | |
192 | } | |
193 | push (@result, $name); | |
194 | } | |
c23d8173 | 195 | return @result; |
110e9fb0 JH |
196 | } |
197 | ||
e3e5e1ea GS |
198 | # Given a string and a set of attributes, returns the string surrounded by |
199 | # escape codes to set those attributes and then clear them at the end of the | |
f63addff | 200 | # string. The attributes can be given either as an array ref as the first |
135dda52 JH |
201 | # argument or as a list as the second and subsequent arguments. If $EACHLINE |
202 | # is set, insert a reset before each occurrence of the string $EACHLINE and | |
203 | # the starting attribute code after the string $EACHLINE, so that no attribute | |
204 | # crosses line delimiters (this is often desirable if the output is to be | |
205 | # piped to a pager or some other program). | |
e3e5e1ea | 206 | sub colored { |
f63addff JH |
207 | my ($string, @codes); |
208 | if (ref $_[0]) { | |
209 | @codes = @{+shift}; | |
210 | $string = join ('', @_); | |
211 | } else { | |
212 | $string = shift; | |
213 | @codes = @_; | |
214 | } | |
110e9fb0 | 215 | return $string if defined $ENV{ANSI_COLORS_DISABLED}; |
e3e5e1ea | 216 | if (defined $EACHLINE) { |
f63addff | 217 | my $attr = color (@codes); |
c23d8173 RGS |
218 | return join '', |
219 | map { ($_ ne $EACHLINE) ? $attr . $_ . "\e[0m" : $_ } | |
51da1d85 RGS |
220 | grep { length ($_) > 0 } |
221 | split (/(\Q$EACHLINE\E)/, $string); | |
e3e5e1ea | 222 | } else { |
c23d8173 | 223 | return color (@codes) . $string . "\e[0m"; |
e3e5e1ea GS |
224 | } |
225 | } | |
226 | ||
b5b25974 RGS |
227 | # Given a string, strip the ANSI color codes out of that string and return the |
228 | # result. This removes only ANSI color codes, not movement codes and other | |
229 | # escape sequences. | |
230 | sub colorstrip { | |
231 | my (@string) = @_; | |
232 | for my $string (@string) { | |
233 | $string =~ s/\e\[[\d;]*m//g; | |
234 | } | |
235 | return wantarray ? @string : join ('', @string); | |
236 | } | |
237 | ||
cdab9eb9 S |
238 | # Given a list of color attributes (arguments for color, for instance), return |
239 | # true if they're all valid or false if any of them are invalid. | |
240 | sub colorvalid { | |
241 | my @codes = map { split } @_; | |
242 | for (@codes) { | |
243 | unless (defined $ATTRIBUTES{lc $_}) { | |
244 | return; | |
245 | } | |
246 | } | |
247 | return 1; | |
248 | } | |
249 | ||
135dda52 | 250 | ############################################################################## |
e3e5e1ea | 251 | # Module return value and documentation |
135dda52 | 252 | ############################################################################## |
e3e5e1ea GS |
253 | |
254 | # Ensure we evaluate to true. | |
255 | 1; | |
256 | __END__ | |
257 | ||
258 | =head1 NAME | |
259 | ||
260 | Term::ANSIColor - Color screen output using ANSI escape sequences | |
261 | ||
c23d8173 RGS |
262 | =for stopwords |
263 | cyan colorize namespace runtime TMTOWTDI cmd.exe 4nt.exe command.com NT | |
264 | ESC Delvare SSH OpenSSH aixterm ECMA-048 Fraktur overlining Zenin | |
265 | reimplemented Allbery PUSHCOLOR POPCOLOR LOCALCOLOR openmethods.com | |
266 | ||
e3e5e1ea GS |
267 | =head1 SYNOPSIS |
268 | ||
269 | use Term::ANSIColor; | |
270 | print color 'bold blue'; | |
271 | print "This text is bold blue.\n"; | |
272 | print color 'reset'; | |
273 | print "This text is normal.\n"; | |
cd07961b | 274 | print colored ("Yellow on magenta.", 'yellow on_magenta'), "\n"; |
e3e5e1ea | 275 | print "This text is normal.\n"; |
cd07961b SP |
276 | print colored ['yellow on_magenta'], 'Yellow on magenta.'; |
277 | print "\n"; | |
e3e5e1ea | 278 | |
110e9fb0 | 279 | use Term::ANSIColor qw(uncolor); |
b5b25974 RGS |
280 | print uncolor ('01;31'), "\n"; |
281 | ||
282 | use Term::ANSIColor qw(colorstrip); | |
283 | print colorstrip '\e[1mThis is bold\e[0m', "\n"; | |
110e9fb0 | 284 | |
cdab9eb9 S |
285 | use Term::ANSIColor qw(colorvalid); |
286 | my $valid = colorvalid ('blue bold', 'on_magenta'); | |
287 | print "Color string is ", $valid ? "valid\n" : "invalid\n"; | |
288 | ||
e3e5e1ea GS |
289 | use Term::ANSIColor qw(:constants); |
290 | print BOLD, BLUE, "This text is in bold blue.\n", RESET; | |
291 | ||
292 | use Term::ANSIColor qw(:constants); | |
c23d8173 RGS |
293 | { |
294 | local $Term::ANSIColor::AUTORESET = 1; | |
295 | print BOLD BLUE "This text is in bold blue.\n"; | |
296 | print "This text is normal.\n"; | |
297 | } | |
298 | ||
299 | use Term::ANSIColor qw(:pushpop); | |
300 | print PUSHCOLOR RED ON_GREEN "This text is red on green.\n"; | |
301 | print PUSHCOLOR BLUE "This text is blue on green.\n"; | |
302 | print RESET BLUE "This text is just blue.\n"; | |
303 | print POPCOLOR "Back to red on green.\n"; | |
304 | print LOCALCOLOR GREEN ON_BLUE "This text is green on blue.\n"; | |
305 | print "This text is red on green.\n"; | |
306 | { | |
307 | local $Term::ANSIColor::AUTOLOCAL = 1; | |
308 | print ON_BLUE "This text is red on blue.\n"; | |
309 | print "This text is red on green.\n"; | |
310 | } | |
311 | print POPCOLOR "Back to whatever we started as.\n"; | |
e3e5e1ea GS |
312 | |
313 | =head1 DESCRIPTION | |
314 | ||
315 | This module has two interfaces, one through color() and colored() and the | |
cdab9eb9 S |
316 | other through constants. It also offers the utility functions uncolor(), |
317 | colorstrip(), and colorvalid(), which have to be explicitly imported to be | |
318 | used (see L</SYNOPSIS>). | |
b5b25974 RGS |
319 | |
320 | =head2 Function Interface | |
bbc7dcd2 | 321 | |
e3e5e1ea GS |
322 | color() takes any number of strings as arguments and considers them to be |
323 | space-separated lists of attributes. It then forms and returns the escape | |
c23d8173 RGS |
324 | sequence to set those attributes. It doesn't print it out, just returns |
325 | it, so you'll have to print it yourself if you want to (this is so that | |
326 | you can save it as a string, pass it to something else, send it to a file | |
cdab9eb9 S |
327 | handle, or do anything else with it that you might care to). color() |
328 | throws an exception if given an invalid attribute, so you can also use it | |
329 | to check attribute names for validity (see L</EXAMPLES>). | |
110e9fb0 JH |
330 | |
331 | uncolor() performs the opposite translation, turning escape sequences | |
332 | into a list of strings. | |
e3e5e1ea | 333 | |
b5b25974 RGS |
334 | colorstrip() removes all color escape sequences from the provided strings, |
335 | returning the modified strings separately in array context or joined | |
336 | together in scalar context. Its arguments are not modified. | |
337 | ||
cdab9eb9 S |
338 | colorvalid() takes attribute strings the same as color() and returns true |
339 | if all attributes are known and false otherwise. | |
340 | ||
c23d8173 RGS |
341 | The recognized non-color attributes are clear, reset, bold, dark, faint, |
342 | underline, underscore, blink, reverse, and concealed. Clear and reset | |
343 | (reset to default attributes), dark and faint (dim and saturated), and | |
344 | underline and underscore are equivalent, so use whichever is the most | |
345 | intuitive to you. The recognized foreground color attributes are black, | |
346 | red, green, yellow, blue, magenta, cyan, and white. The recognized | |
347 | background color attributes are on_black, on_red, on_green, on_yellow, | |
348 | on_blue, on_magenta, on_cyan, and on_white. Case is not significant. | |
e3e5e1ea | 349 | |
f63addff | 350 | Note that not all attributes are supported by all terminal types, and some |
c23d8173 RGS |
351 | terminals may not support any of these sequences. Dark and faint, blink, |
352 | and concealed in particular are frequently not implemented. | |
f63addff JH |
353 | |
354 | Attributes, once set, last until they are unset (by sending the attribute | |
c23d8173 RGS |
355 | C<clear> or C<reset>). Be careful to do this, or otherwise your attribute |
356 | will last after your script is done running, and people get very annoyed | |
357 | at having their prompt and typing changed to weird colors. | |
358 | ||
359 | As an aid to help with this, colored() takes a scalar as the first | |
360 | argument and any number of attribute strings as the second argument and | |
361 | returns the scalar wrapped in escape codes so that the attributes will be | |
362 | set as requested before the string and reset to normal after the string. | |
363 | Alternately, you can pass a reference to an array as the first argument, | |
364 | and then the contents of that array will be taken as attributes and color | |
365 | codes and the remainder of the arguments as text to colorize. | |
f63addff | 366 | |
e3e5e1ea | 367 | Normally, colored() just puts attribute codes at the beginning and end of |
110e9fb0 JH |
368 | the string, but if you set $Term::ANSIColor::EACHLINE to some string, that |
369 | string will be considered the line delimiter and the attribute will be set | |
370 | at the beginning of each line of the passed string and reset at the end of | |
cd07961b SP |
371 | each line. This is often desirable if the output contains newlines and |
372 | you're using background colors, since a background color that persists | |
373 | across a newline is often interpreted by the terminal as providing the | |
374 | default background color for the next line. Programs like pagers can also | |
375 | be confused by attributes that span lines. Normally you'll want to set | |
376 | $Term::ANSIColor::EACHLINE to C<"\n"> to use this feature. | |
e3e5e1ea | 377 | |
b5b25974 RGS |
378 | =head2 Constant Interface |
379 | ||
e3e5e1ea | 380 | Alternately, if you import C<:constants>, you can use the constants CLEAR, |
cdab9eb9 S |
381 | RESET, BOLD, DARK, FAINT, UNDERLINE, UNDERSCORE, BLINK, REVERSE, |
382 | CONCEALED, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, | |
383 | ON_BLACK, ON_RED, ON_GREEN, ON_YELLOW, ON_BLUE, ON_MAGENTA, ON_CYAN, and | |
384 | ON_WHITE directly. These are the same as color('attribute') and can be | |
385 | used if you prefer typing: | |
e3e5e1ea | 386 | |
cd07961b | 387 | print BOLD BLUE ON_WHITE "Text", RESET, "\n"; |
e3e5e1ea GS |
388 | |
389 | to | |
390 | ||
cd07961b SP |
391 | print colored ("Text", 'bold blue on_white'), "\n"; |
392 | ||
393 | (Note that the newline is kept separate to avoid confusing the terminal as | |
394 | described above since a background color is being used.) | |
e3e5e1ea GS |
395 | |
396 | When using the constants, if you don't want to have to remember to add the | |
397 | C<, RESET> at the end of each print line, you can set | |
398 | $Term::ANSIColor::AUTORESET to a true value. Then, the display mode will | |
399 | automatically be reset if there is no comma after the constant. In other | |
400 | words, with that variable set: | |
401 | ||
402 | print BOLD BLUE "Text\n"; | |
403 | ||
c23d8173 | 404 | will reset the display mode afterward, whereas: |
e3e5e1ea GS |
405 | |
406 | print BOLD, BLUE, "Text\n"; | |
407 | ||
cd07961b SP |
408 | will not. If you are using background colors, you will probably want to |
409 | print the newline with a separate print statement to avoid confusing the | |
410 | terminal. | |
e3e5e1ea GS |
411 | |
412 | The subroutine interface has the advantage over the constants interface in | |
f63addff JH |
413 | that only two subroutines are exported into your namespace, versus |
414 | twenty-two in the constants interface. On the flip side, the constants | |
415 | interface has the advantage of better compile time error checking, since | |
416 | misspelled names of colors or attributes in calls to color() and colored() | |
c23d8173 RGS |
417 | won't be caught until runtime whereas misspelled names of constants will |
418 | be caught at compile time. So, pollute your namespace with almost two | |
419 | dozen subroutines that you may not even use that often, or risk a silly | |
420 | bug by mistyping an attribute. Your choice, TMTOWTDI after all. | |
421 | ||
b5b25974 RGS |
422 | =head2 The Color Stack |
423 | ||
c23d8173 RGS |
424 | As of Term::ANSIColor 2.0, you can import C<:pushpop> and maintain a stack |
425 | of colors using PUSHCOLOR, POPCOLOR, and LOCALCOLOR. PUSHCOLOR takes the | |
426 | attribute string that starts its argument and pushes it onto a stack of | |
427 | attributes. POPCOLOR removes the top of the stack and restores the | |
428 | previous attributes set by the argument of a prior PUSHCOLOR. LOCALCOLOR | |
429 | surrounds its argument in a PUSHCOLOR and POPCOLOR so that the color | |
430 | resets afterward. | |
431 | ||
432 | When using PUSHCOLOR, POPCOLOR, and LOCALCOLOR, it's particularly | |
433 | important to not put commas between the constants. | |
434 | ||
435 | print PUSHCOLOR BLUE "Text\n"; | |
436 | ||
437 | will correctly push BLUE onto the top of the stack. | |
438 | ||
439 | print PUSHCOLOR, BLUE, "Text\n"; # wrong! | |
440 | ||
441 | will not, and a subsequent pop won't restore the correct attributes. | |
442 | PUSHCOLOR pushes the attributes set by its argument, which is normally a | |
443 | string of color constants. It can't ask the terminal what the current | |
444 | attributes are. | |
e3e5e1ea GS |
445 | |
446 | =head1 DIAGNOSTICS | |
447 | ||
448 | =over 4 | |
449 | ||
110e9fb0 JH |
450 | =item Bad escape sequence %s |
451 | ||
452 | (F) You passed an invalid ANSI escape sequence to uncolor(). | |
453 | ||
454 | =item Bareword "%s" not allowed while "strict subs" in use | |
455 | ||
456 | (F) You probably mistyped a constant color name such as: | |
457 | ||
458 | $Foobar = FOOBAR . "This line should be blue\n"; | |
459 | ||
460 | or: | |
461 | ||
462 | @Foobar = FOOBAR, "This line should be blue\n"; | |
463 | ||
464 | This will only show up under use strict (another good reason to run under | |
465 | use strict). | |
466 | ||
e3e5e1ea GS |
467 | =item Invalid attribute name %s |
468 | ||
f63addff | 469 | (F) You passed an invalid attribute name to either color() or colored(). |
e3e5e1ea | 470 | |
f63addff | 471 | =item Name "%s" used only once: possible typo |
e3e5e1ea | 472 | |
f63addff | 473 | (W) You probably mistyped a constant color name such as: |
e3e5e1ea GS |
474 | |
475 | print FOOBAR "This text is color FOOBAR\n"; | |
476 | ||
477 | It's probably better to always use commas after constant names in order to | |
478 | force the next error. | |
479 | ||
480 | =item No comma allowed after filehandle | |
481 | ||
f63addff | 482 | (F) You probably mistyped a constant color name such as: |
e3e5e1ea GS |
483 | |
484 | print FOOBAR, "This text is color FOOBAR\n"; | |
485 | ||
486 | Generating this fatal compile error is one of the main advantages of using | |
487 | the constants interface, since you'll immediately know if you mistype a | |
488 | color name. | |
489 | ||
110e9fb0 | 490 | =item No name for escape sequence %s |
e3e5e1ea | 491 | |
110e9fb0 JH |
492 | (F) The ANSI escape sequence passed to uncolor() contains escapes which |
493 | aren't recognized and can't be translated to names. | |
e3e5e1ea | 494 | |
110e9fb0 | 495 | =back |
e3e5e1ea | 496 | |
110e9fb0 | 497 | =head1 ENVIRONMENT |
e3e5e1ea | 498 | |
110e9fb0 | 499 | =over 4 |
e3e5e1ea | 500 | |
110e9fb0 JH |
501 | =item ANSI_COLORS_DISABLED |
502 | ||
503 | If this environment variable is set, all of the functions defined by this | |
c23d8173 RGS |
504 | module (color(), colored(), and all of the constants not previously used |
505 | in the program) will not output any escape sequences and instead will just | |
110e9fb0 JH |
506 | return the empty string or pass through the original text as appropriate. |
507 | This is intended to support easy use of scripts using this module on | |
508 | platforms that don't support ANSI escape sequences. | |
509 | ||
510 | For it to have its proper effect, this environment variable must be set | |
511 | before any color constants are used in the program. | |
e3e5e1ea GS |
512 | |
513 | =back | |
514 | ||
515 | =head1 RESTRICTIONS | |
516 | ||
517 | It would be nice if one could leave off the commas around the constants | |
518 | entirely and just say: | |
519 | ||
520 | print BOLD BLUE ON_WHITE "Text\n" RESET; | |
521 | ||
522 | but the syntax of Perl doesn't allow this. You need a comma after the | |
523 | string. (Of course, you may consider it a bug that commas between all the | |
c23d8173 RGS |
524 | constants aren't required, in which case you may feel free to insert |
525 | commas unless you're using $Term::ANSIColor::AUTORESET or | |
526 | PUSHCOLOR/POPCOLOR.) | |
e3e5e1ea | 527 | |
3c4b39be | 528 | For easier debugging, you may prefer to always use the commas when not |
c23d8173 RGS |
529 | setting $Term::ANSIColor::AUTORESET or PUSHCOLOR/POPCOLOR so that you'll |
530 | get a fatal compile error rather than a warning. | |
e3e5e1ea | 531 | |
f63addff JH |
532 | =head1 NOTES |
533 | ||
110e9fb0 | 534 | The codes generated by this module are standard terminal control codes, |
c23d8173 RGS |
535 | complying with ECMA-048 and ISO 6429 (generally referred to as "ANSI |
536 | color" for the color codes). The non-color control codes (bold, dark, | |
537 | italic, underline, and reverse) are part of the earlier ANSI X3.64 | |
538 | standard for control sequences for video terminals and peripherals. | |
110e9fb0 JH |
539 | |
540 | Note that not all displays are ISO 6429-compliant, or even X3.64-compliant | |
c23d8173 RGS |
541 | (or are even attempting to be so). This module will not work as expected |
542 | on displays that do not honor these escape sequences, such as cmd.exe, | |
543 | 4nt.exe, and command.com under either Windows NT or Windows 2000. They | |
544 | may just be ignored, or they may display as an ESC character followed by | |
545 | some apparent garbage. | |
110e9fb0 | 546 | |
f63addff | 547 | Jean Delvare provided the following table of different common terminal |
c23d8173 RGS |
548 | emulators and their support for the various attributes and others have |
549 | helped me flesh it out: | |
f63addff | 550 | |
c23d8173 | 551 | clear bold faint under blink reverse conceal |
f63addff | 552 | ------------------------------------------------------------------------ |
cdab9eb9 | 553 | xterm yes yes no yes yes yes yes |
f63addff JH |
554 | linux yes yes yes bold yes yes no |
555 | rxvt yes yes no yes bold/black yes no | |
556 | dtterm yes yes yes yes reverse yes yes | |
557 | teraterm yes reverse no yes rev/red yes no | |
558 | aixterm kinda normal no yes no yes yes | |
2d1e314f JH |
559 | PuTTY yes color no yes no yes no |
560 | Windows yes no no no no yes no | |
561 | Cygwin SSH yes yes no color color color yes | |
92c7d2a2 RGS |
562 | Mac Terminal yes yes no yes yes yes yes |
563 | ||
564 | Windows is Windows telnet, Cygwin SSH is the OpenSSH implementation under | |
c23d8173 RGS |
565 | Cygwin on Windows NT, and Mac Terminal is the Terminal application in Mac |
566 | OS X. Where the entry is other than yes or no, that emulator displays the | |
92c7d2a2 | 567 | given attribute as something else instead. Note that on an aixterm, clear |
c23d8173 RGS |
568 | doesn't reset colors; you have to explicitly set the colors back to what |
569 | you want. More entries in this table are welcome. | |
570 | ||
571 | Note that codes 3 (italic), 6 (rapid blink), and 9 (strike-through) are | |
572 | specified in ANSI X3.64 and ECMA-048 but are not commonly supported by | |
573 | most displays and emulators and therefore aren't supported by this module | |
574 | at the present time. ECMA-048 also specifies a large number of other | |
575 | attributes, including a sequence of attributes for font changes, Fraktur | |
576 | characters, double-underlining, framing, circling, and overlining. As | |
577 | none of these attributes are widely supported or useful, they also aren't | |
578 | currently supported by this module. | |
110e9fb0 JH |
579 | |
580 | =head1 SEE ALSO | |
581 | ||
582 | ECMA-048 is available on-line (at least at the time of this writing) at | |
2d1e314f | 583 | L<http://www.ecma-international.org/publications/standards/ECMA-048.HTM>. |
110e9fb0 | 584 | |
c23d8173 RGS |
585 | ISO 6429 is available from ISO for a charge; the author of this module |
586 | does not own a copy of it. Since the source material for ISO 6429 was | |
587 | ECMA-048 and the latter is available for free, there seems little reason | |
588 | to obtain the ISO standard. | |
f63addff | 589 | |
c23d8173 RGS |
590 | The current version of this module is always available from its web site |
591 | at L<http://www.eyrie.org/~eagle/software/ansicolor/>. It is also part of | |
592 | the Perl core distribution as of 5.6.0. | |
135dda52 | 593 | |
e3e5e1ea GS |
594 | =head1 AUTHORS |
595 | ||
110e9fb0 | 596 | Original idea (using constants) by Zenin, reimplemented using subs by Russ |
c23d8173 RGS |
597 | Allbery <rra@stanford.edu>, and then combined with the original idea by |
598 | Russ with input from Zenin. Russ Allbery now maintains this module. | |
110e9fb0 | 599 | |
135dda52 | 600 | =head1 COPYRIGHT AND LICENSE |
110e9fb0 | 601 | |
c23d8173 RGS |
602 | Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2008, 2009 Russ |
603 | Allbery <rra@stanford.edu> and Zenin. This program is free software; you | |
604 | may redistribute it and/or modify it under the same terms as Perl itself. | |
605 | ||
606 | PUSHCOLOR, POPCOLOR, and LOCALCOLOR were contributed by openmethods.com | |
607 | voice solutions. | |
e3e5e1ea GS |
608 | |
609 | =cut |