This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
ace4d4716765afefa1b00ab5a53fe830f570e432
[perl5.git] / cpan / Term-ANSIColor / lib / Term / ANSIColor.pm
1 # Term::ANSIColor -- Color screen output using ANSI escape sequences.
2 #
3 # Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2008, 2009, 2010,
4 #     2011, 2012, 2013, 2014, 2015 Russ Allbery <rra@cpan.org>
5 # Copyright 1996 Zenin
6 # Copyright 2012 Kurt Starsinic <kstarsinic@gmail.com>
7 #
8 # This program is free software; you may redistribute it and/or modify it
9 # under the same terms as Perl itself.
10 #
11 # PUSH/POP support submitted 2007 by openmethods.com voice solutions
12 #
13 # Ah, September, when the sysadmins turn colors and fall off the trees....
14 #                               -- Dave Van Domelen
15
16 ##############################################################################
17 # Modules and declarations
18 ##############################################################################
19
20 package Term::ANSIColor;
21
22 use 5.006;
23 use strict;
24 use warnings;
25
26 use Carp qw(croak);
27 use Exporter ();
28
29 # use Exporter plus @ISA instead of use base for 5.6 compatibility.
30 ## no critic (ClassHierarchies::ProhibitExplicitISA)
31
32 # Declare variables that should be set in BEGIN for robustness.
33 ## no critic (Modules::ProhibitAutomaticExportation)
34 our (@EXPORT, @EXPORT_OK, %EXPORT_TAGS, @ISA, $VERSION);
35
36 # We use autoloading, which sets this variable to the name of the called sub.
37 our $AUTOLOAD;
38
39 # Set $VERSION and everything export-related in a BEGIN block for robustness
40 # against circular module loading (not that we load any modules, but
41 # consistency is good).
42 BEGIN {
43     $VERSION = '4.04';
44
45     # All of the basic supported constants, used in %EXPORT_TAGS.
46     my @colorlist = qw(
47       CLEAR           RESET             BOLD            DARK
48       FAINT           ITALIC            UNDERLINE       UNDERSCORE
49       BLINK           REVERSE           CONCEALED
50
51       BLACK           RED               GREEN           YELLOW
52       BLUE            MAGENTA           CYAN            WHITE
53       ON_BLACK        ON_RED            ON_GREEN        ON_YELLOW
54       ON_BLUE         ON_MAGENTA        ON_CYAN         ON_WHITE
55
56       BRIGHT_BLACK    BRIGHT_RED        BRIGHT_GREEN    BRIGHT_YELLOW
57       BRIGHT_BLUE     BRIGHT_MAGENTA    BRIGHT_CYAN     BRIGHT_WHITE
58       ON_BRIGHT_BLACK ON_BRIGHT_RED     ON_BRIGHT_GREEN ON_BRIGHT_YELLOW
59       ON_BRIGHT_BLUE  ON_BRIGHT_MAGENTA ON_BRIGHT_CYAN  ON_BRIGHT_WHITE
60     );
61
62     # 256-color constants, used in %EXPORT_TAGS.
63     my @colorlist256 = (
64         (map { ("ANSI$_", "ON_ANSI$_") } 0 .. 15),
65         (map { ("GREY$_", "ON_GREY$_") } 0 .. 23),
66     );
67     for my $r (0 .. 5) {
68         for my $g (0 .. 5) {
69             push(@colorlist256, map { ("RGB$r$g$_", "ON_RGB$r$g$_") } 0 .. 5);
70         }
71     }
72
73     # Exported symbol configuration.
74     @ISA         = qw(Exporter);
75     @EXPORT      = qw(color colored);
76     @EXPORT_OK   = qw(uncolor colorstrip colorvalid coloralias);
77     %EXPORT_TAGS = (
78         constants    => \@colorlist,
79         constants256 => \@colorlist256,
80         pushpop      => [@colorlist, qw(PUSHCOLOR POPCOLOR LOCALCOLOR)],
81     );
82     Exporter::export_ok_tags('pushpop', 'constants256');
83 }
84
85 ##############################################################################
86 # Package variables
87 ##############################################################################
88
89 # If this is set, any color changes will implicitly push the current color
90 # onto the stack and then pop it at the end of the constant sequence, just as
91 # if LOCALCOLOR were used.
92 our $AUTOLOCAL;
93
94 # Caller sets this to force a reset at the end of each constant sequence.
95 our $AUTORESET;
96
97 # Caller sets this to force colors to be reset at the end of each line.
98 our $EACHLINE;
99
100 ##############################################################################
101 # Internal data structures
102 ##############################################################################
103
104 # This module does quite a bit of initialization at the time it is first
105 # loaded, primarily to set up the package-global %ATTRIBUTES hash.  The
106 # entries for 256-color names are easier to handle programmatically, and
107 # custom colors are also imported from the environment if any are set.
108
109 # All basic supported attributes, including aliases.
110 #<<<
111 our %ATTRIBUTES = (
112     'clear'          => 0,
113     'reset'          => 0,
114     'bold'           => 1,
115     'dark'           => 2,
116     'faint'          => 2,
117     'italic'         => 3,
118     'underline'      => 4,
119     'underscore'     => 4,
120     'blink'          => 5,
121     'reverse'        => 7,
122     'concealed'      => 8,
123
124     'black'          => 30,   'on_black'          => 40,
125     'red'            => 31,   'on_red'            => 41,
126     'green'          => 32,   'on_green'          => 42,
127     'yellow'         => 33,   'on_yellow'         => 43,
128     'blue'           => 34,   'on_blue'           => 44,
129     'magenta'        => 35,   'on_magenta'        => 45,
130     'cyan'           => 36,   'on_cyan'           => 46,
131     'white'          => 37,   'on_white'          => 47,
132
133     'bright_black'   => 90,   'on_bright_black'   => 100,
134     'bright_red'     => 91,   'on_bright_red'     => 101,
135     'bright_green'   => 92,   'on_bright_green'   => 102,
136     'bright_yellow'  => 93,   'on_bright_yellow'  => 103,
137     'bright_blue'    => 94,   'on_bright_blue'    => 104,
138     'bright_magenta' => 95,   'on_bright_magenta' => 105,
139     'bright_cyan'    => 96,   'on_bright_cyan'    => 106,
140     'bright_white'   => 97,   'on_bright_white'   => 107,
141 );
142 #>>>
143
144 # Generating the 256-color codes involves a lot of codes and offsets that are
145 # not helped by turning them into constants.
146
147 # The first 16 256-color codes are duplicates of the 16 ANSI colors,
148 # included for completeness.
149 for my $code (0 .. 15) {
150     $ATTRIBUTES{"ansi$code"}    = "38;5;$code";
151     $ATTRIBUTES{"on_ansi$code"} = "48;5;$code";
152 }
153
154 # 256-color RGB colors.  Red, green, and blue can each be values 0 through 5,
155 # and the resulting 216 colors start with color 16.
156 for my $r (0 .. 5) {
157     for my $g (0 .. 5) {
158         for my $b (0 .. 5) {
159             my $code = 16 + (6 * 6 * $r) + (6 * $g) + $b;
160             $ATTRIBUTES{"rgb$r$g$b"}    = "38;5;$code";
161             $ATTRIBUTES{"on_rgb$r$g$b"} = "48;5;$code";
162         }
163     }
164 }
165
166 # The last 256-color codes are 24 shades of grey.
167 for my $n (0 .. 23) {
168     my $code = $n + 232;
169     $ATTRIBUTES{"grey$n"}    = "38;5;$code";
170     $ATTRIBUTES{"on_grey$n"} = "48;5;$code";
171 }
172
173 # Reverse lookup.  Alphabetically first name for a sequence is preferred.
174 our %ATTRIBUTES_R;
175 for my $attr (reverse sort keys %ATTRIBUTES) {
176     $ATTRIBUTES_R{ $ATTRIBUTES{$attr} } = $attr;
177 }
178
179 # Import any custom colors set in the environment.
180 our %ALIASES;
181 if (exists $ENV{ANSI_COLORS_ALIASES}) {
182     my $spec = $ENV{ANSI_COLORS_ALIASES};
183     $spec =~ s{\s+}{}xmsg;
184
185     # Error reporting here is an interesting question.  Use warn rather than
186     # carp because carp would report the line of the use or require, which
187     # doesn't help anyone understand what's going on, whereas seeing this code
188     # will be more helpful.
189     ## no critic (ErrorHandling::RequireCarping)
190     for my $definition (split m{,}xms, $spec) {
191         my ($new, $old) = split m{=}xms, $definition, 2;
192         if (!$new || !$old) {
193             warn qq{Bad color mapping "$definition"};
194         } else {
195             my $result = eval { coloralias($new, $old) };
196             if (!$result) {
197                 my $error = $@;
198                 $error =~ s{ [ ] at [ ] .* }{}xms;
199                 warn qq{$error in "$definition"};
200             }
201         }
202     }
203 }
204
205 # Stores the current color stack maintained by PUSHCOLOR and POPCOLOR.  This
206 # is global and therefore not threadsafe.
207 our @COLORSTACK;
208
209 ##############################################################################
210 # Implementation (constant form)
211 ##############################################################################
212
213 # Time to have fun!  We now want to define the constant subs, which are named
214 # the same as the attributes above but in all caps.  Each constant sub needs
215 # to act differently depending on whether $AUTORESET is set.  Without
216 # autoreset:
217 #
218 #     BLUE "text\n"  ==>  "\e[34mtext\n"
219 #
220 # If $AUTORESET is set, we should instead get:
221 #
222 #     BLUE "text\n"  ==>  "\e[34mtext\n\e[0m"
223 #
224 # The sub also needs to handle the case where it has no arguments correctly.
225 # Maintaining all of this as separate subs would be a major nightmare, as well
226 # as duplicate the %ATTRIBUTES hash, so instead we define an AUTOLOAD sub to
227 # define the constant subs on demand.  To do that, we check the name of the
228 # called sub against the list of attributes, and if it's an all-caps version
229 # of one of them, we define the sub on the fly and then run it.
230 #
231 # If the environment variable ANSI_COLORS_DISABLED is set to a true value,
232 # just return the arguments without adding any escape sequences.  This is to
233 # make it easier to write scripts that also work on systems without any ANSI
234 # support, like Windows consoles.
235 #
236 ## no critic (ClassHierarchies::ProhibitAutoloading)
237 ## no critic (Subroutines::RequireArgUnpacking)
238 sub AUTOLOAD {
239     my ($sub, $attr) = $AUTOLOAD =~ m{ \A ([\w:]*::([[:upper:]\d_]+)) \z }xms;
240
241     # Check if we were called with something that doesn't look like an
242     # attribute.
243     if (!($attr && defined($ATTRIBUTES{ lc $attr }))) {
244         croak("undefined subroutine &$AUTOLOAD called");
245     }
246
247     # If colors are disabled, just return the input.  Do this without
248     # installing a sub for (marginal, unbenchmarked) speed.
249     if ($ENV{ANSI_COLORS_DISABLED}) {
250         return join(q{}, @_);
251     }
252
253     # We've untainted the name of the sub.
254     $AUTOLOAD = $sub;
255
256     # Figure out the ANSI string to set the desired attribute.
257     my $escape = "\e[" . $ATTRIBUTES{ lc $attr } . 'm';
258
259     # Save the current value of $@.  We can't just use local since we want to
260     # restore it before dispatching to the newly-created sub.  (The caller may
261     # be colorizing output that includes $@.)
262     my $eval_err = $@;
263
264     # Generate the constant sub, which should still recognize some of our
265     # package variables.  Use string eval to avoid a dependency on
266     # Sub::Install, even though it makes it somewhat less readable.
267     ## no critic (BuiltinFunctions::ProhibitStringyEval)
268     ## no critic (ValuesAndExpressions::ProhibitImplicitNewlines)
269     my $eval_result = eval qq{
270         sub $AUTOLOAD {
271             if (\$ENV{ANSI_COLORS_DISABLED}) {
272                 return join(q{}, \@_);
273             } elsif (\$AUTOLOCAL && \@_) {
274                 return PUSHCOLOR('$escape') . join(q{}, \@_) . POPCOLOR;
275             } elsif (\$AUTORESET && \@_) {
276                 return '$escape' . join(q{}, \@_) . "\e[0m";
277             } else {
278                 return '$escape' . join(q{}, \@_);
279             }
280         }
281         1;
282     };
283
284     # Failure is an internal error, not a problem with the caller.
285     ## no critic (ErrorHandling::RequireCarping)
286     if (!$eval_result) {
287         die "failed to generate constant $attr: $@";
288     }
289
290     # Restore $@.
291     ## no critic (Variables::RequireLocalizedPunctuationVars)
292     $@ = $eval_err;
293
294     # Dispatch to the newly-created sub.
295     ## no critic (References::ProhibitDoubleSigils)
296     goto &$AUTOLOAD;
297 }
298 ## use critic (Subroutines::RequireArgUnpacking)
299
300 # Append a new color to the top of the color stack and return the top of
301 # the stack.
302 #
303 # $text - Any text we're applying colors to, with color escapes prepended
304 #
305 # Returns: The text passed in
306 sub PUSHCOLOR {
307     my (@text) = @_;
308     my $text = join(q{}, @text);
309
310     # Extract any number of color-setting escape sequences from the start of
311     # the string.
312     my ($color) = $text =~ m{ \A ( (?:\e\[ [\d;]+ m)+ ) }xms;
313
314     # If we already have a stack, append these escapes to the set from the top
315     # of the stack.  This way, each position in the stack stores the complete
316     # enabled colors for that stage, at the cost of some potential
317     # inefficiency.
318     if (@COLORSTACK) {
319         $color = $COLORSTACK[-1] . $color;
320     }
321
322     # Push the color onto the stack.
323     push(@COLORSTACK, $color);
324     return $text;
325 }
326
327 # Pop the color stack and return the new top of the stack (or reset, if
328 # the stack is empty).
329 #
330 # @text - Any text we're applying colors to
331 #
332 # Returns: The concatenation of @text prepended with the new stack color
333 sub POPCOLOR {
334     my (@text) = @_;
335     pop(@COLORSTACK);
336     if (@COLORSTACK) {
337         return $COLORSTACK[-1] . join(q{}, @text);
338     } else {
339         return RESET(@text);
340     }
341 }
342
343 # Surround arguments with a push and a pop.  The effect will be to reset the
344 # colors to whatever was on the color stack before this sequence of colors was
345 # applied.
346 #
347 # @text - Any text we're applying colors to
348 #
349 # Returns: The concatenation of the text and the proper color reset sequence.
350 sub LOCALCOLOR {
351     my (@text) = @_;
352     return PUSHCOLOR(join(q{}, @text)) . POPCOLOR();
353 }
354
355 ##############################################################################
356 # Implementation (attribute string form)
357 ##############################################################################
358
359 # Return the escape code for a given set of color attributes.
360 #
361 # @codes - A list of possibly space-separated color attributes
362 #
363 # Returns: The escape sequence setting those color attributes
364 #          undef if no escape sequences were given
365 #  Throws: Text exception for any invalid attribute
366 sub color {
367     my (@codes) = @_;
368     @codes = map { split } @codes;
369
370     # Return the empty string if colors are disabled.
371     if ($ENV{ANSI_COLORS_DISABLED}) {
372         return q{};
373     }
374
375     # Build the attribute string from semicolon-separated numbers.
376     my $attribute = q{};
377     for my $code (@codes) {
378         $code = lc($code);
379         if (defined($ATTRIBUTES{$code})) {
380             $attribute .= $ATTRIBUTES{$code} . q{;};
381         } elsif (defined($ALIASES{$code})) {
382             $attribute .= $ALIASES{$code} . q{;};
383         } else {
384             croak("Invalid attribute name $code");
385         }
386     }
387
388     # We added one too many semicolons for simplicity.  Remove the last one.
389     chop($attribute);
390
391     # Return undef if there were no attributes.
392     return ($attribute ne q{}) ? "\e[${attribute}m" : undef;
393 }
394
395 # Return a list of named color attributes for a given set of escape codes.
396 # Escape sequences can be given with or without enclosing "\e[" and "m".  The
397 # empty escape sequence '' or "\e[m" gives an empty list of attrs.
398 #
399 # There is one special case.  256-color codes start with 38 or 48, followed by
400 # a 5 and then the 256-color code.
401 #
402 # @escapes - A list of escape sequences or escape sequence numbers
403 #
404 # Returns: An array of attribute names corresponding to those sequences
405 #  Throws: Text exceptions on invalid escape sequences or unknown colors
406 sub uncolor {
407     my (@escapes) = @_;
408     my (@nums, @result);
409
410     # Walk the list of escapes and build a list of attribute numbers.
411     for my $escape (@escapes) {
412         $escape =~ s{ \A \e\[ }{}xms;
413         $escape =~ s{ m \z }   {}xms;
414         my ($attrs) = $escape =~ m{ \A ((?:\d+;)* \d*) \z }xms;
415         if (!defined($attrs)) {
416             croak("Bad escape sequence $escape");
417         }
418
419         # Pull off 256-color codes (38;5;n or 48;5;n) as a unit.
420         push(@nums, $attrs =~ m{ ( 0*[34]8;0*5;\d+ | \d+ ) (?: ; | \z ) }xmsg);
421     }
422
423     # Now, walk the list of numbers and convert them to attribute names.
424     # Strip leading zeroes from any of the numbers.  (xterm, at least, allows
425     # leading zeroes to be added to any number in an escape sequence.)
426     for my $num (@nums) {
427         $num =~ s{ ( \A | ; ) 0+ (\d) }{$1$2}xmsg;
428         my $name = $ATTRIBUTES_R{$num};
429         if (!defined($name)) {
430             croak("No name for escape sequence $num");
431         }
432         push(@result, $name);
433     }
434
435     # Return the attribute names.
436     return @result;
437 }
438
439 # Given a string and a set of attributes, returns the string surrounded by
440 # escape codes to set those attributes and then clear them at the end of the
441 # string.  The attributes can be given either as an array ref as the first
442 # argument or as a list as the second and subsequent arguments.
443 #
444 # If $EACHLINE is set, insert a reset before each occurrence of the string
445 # $EACHLINE and the starting attribute code after the string $EACHLINE, so
446 # that no attribute crosses line delimiters (this is often desirable if the
447 # output is to be piped to a pager or some other program).
448 #
449 # $first - An anonymous array of attributes or the text to color
450 # @rest  - The text to color or the list of attributes
451 #
452 # Returns: The text, concatenated if necessary, surrounded by escapes to set
453 #          the desired colors and reset them afterwards
454 #  Throws: Text exception on invalid attributes
455 sub colored {
456     my ($first, @rest) = @_;
457     my ($string, @codes);
458     if (ref($first) && ref($first) eq 'ARRAY') {
459         @codes = @{$first};
460         $string = join(q{}, @rest);
461     } else {
462         $string = $first;
463         @codes  = @rest;
464     }
465
466     # Return the string unmolested if colors are disabled.
467     if ($ENV{ANSI_COLORS_DISABLED}) {
468         return $string;
469     }
470
471     # Find the attribute string for our colors.
472     my $attr = color(@codes);
473
474     # If $EACHLINE is defined, split the string on line boundaries, suppress
475     # empty segments, and then colorize each of the line sections.
476     if (defined($EACHLINE)) {
477         my @text = map { ($_ ne $EACHLINE) ? $attr . $_ . "\e[0m" : $_ }
478           grep { length > 0 }
479           split(m{ (\Q$EACHLINE\E) }xms, $string);
480         return join(q{}, @text);
481     } else {
482         return $attr . $string . "\e[0m";
483     }
484 }
485
486 # Define a new color alias, or return the value of an existing alias.
487 #
488 # $alias - The color alias to define
489 # $color - The standard color the alias will correspond to (optional)
490 #
491 # Returns: The standard color value of the alias
492 #          undef if one argument was given and the alias was not recognized
493 #  Throws: Text exceptions for invalid alias names, attempts to use a
494 #          standard color name as an alias, or an unknown standard color name
495 sub coloralias {
496     my ($alias, $color) = @_;
497     if (!defined($color)) {
498         if (!exists $ALIASES{$alias}) {
499             return;
500         } else {
501             return $ATTRIBUTES_R{ $ALIASES{$alias} };
502         }
503     }
504     if ($alias !~ m{ \A [\w._-]+ \z }xms) {
505         croak(qq{Invalid alias name "$alias"});
506     } elsif ($ATTRIBUTES{$alias}) {
507         croak(qq{Cannot alias standard color "$alias"});
508     } elsif (!exists $ATTRIBUTES{$color}) {
509         croak(qq{Invalid attribute name "$color"});
510     }
511     $ALIASES{$alias} = $ATTRIBUTES{$color};
512     return $color;
513 }
514
515 # Given a string, strip the ANSI color codes out of that string and return the
516 # result.  This removes only ANSI color codes, not movement codes and other
517 # escape sequences.
518 #
519 # @string - The list of strings to sanitize
520 #
521 # Returns: (array)  The strings stripped of ANSI color escape sequences
522 #          (scalar) The same, concatenated
523 sub colorstrip {
524     my (@string) = @_;
525     for my $string (@string) {
526         $string =~ s{ \e\[ [\d;]* m }{}xmsg;
527     }
528     return wantarray ? @string : join(q{}, @string);
529 }
530
531 # Given a list of color attributes (arguments for color, for instance), return
532 # true if they're all valid or false if any of them are invalid.
533 #
534 # @codes - A list of color attributes, possibly space-separated
535 #
536 # Returns: True if all the attributes are valid, false otherwise.
537 sub colorvalid {
538     my (@codes) = @_;
539     @codes = map { split(q{ }, lc) } @codes;
540     for my $code (@codes) {
541         if (!(defined($ATTRIBUTES{$code}) || defined($ALIASES{$code}))) {
542             return;
543         }
544     }
545     return 1;
546 }
547
548 ##############################################################################
549 # Module return value and documentation
550 ##############################################################################
551
552 # Ensure we evaluate to true.
553 1;
554 __END__
555
556 =head1 NAME
557
558 Term::ANSIColor - Color screen output using ANSI escape sequences
559
560 =for stopwords
561 cyan colorize namespace runtime TMTOWTDI cmd.exe cmd.exe. 4nt.exe. 4nt.exe
562 command.com NT ESC Delvare SSH OpenSSH aixterm ECMA-048 Fraktur overlining
563 Zenin reimplemented Allbery PUSHCOLOR POPCOLOR LOCALCOLOR openmethods.com
564 openmethods.com. grey ATTR urxvt mistyped prepending Bareword filehandle
565 Cygwin Starsinic aterm rxvt CPAN RGB Solarized Whitespace alphanumerics
566 undef
567
568 =head1 SYNOPSIS
569
570     use Term::ANSIColor;
571     print color('bold blue');
572     print "This text is bold blue.\n";
573     print color('reset');
574     print "This text is normal.\n";
575     print colored("Yellow on magenta.", 'yellow on_magenta'), "\n";
576     print "This text is normal.\n";
577     print colored(['yellow on_magenta'], 'Yellow on magenta.', "\n");
578     print colored(['red on_bright_yellow'], 'Red on bright yellow.', "\n");
579     print colored(['bright_red on_black'], 'Bright red on black.', "\n");
580     print "\n";
581
582     # Map escape sequences back to color names.
583     use Term::ANSIColor 1.04 qw(uncolor);
584     my $names = uncolor('01;31');
585     print join(q{ }, @{$names}), "\n";
586
587     # Strip all color escape sequences.
588     use Term::ANSIColor 2.01 qw(colorstrip);
589     print colorstrip("\e[1mThis is bold\e[0m"), "\n";
590
591     # Determine whether a color is valid.
592     use Term::ANSIColor 2.02 qw(colorvalid);
593     my $valid = colorvalid('blue bold', 'on_magenta');
594     print "Color string is ", $valid ? "valid\n" : "invalid\n";
595
596     # Create new aliases for colors.
597     use Term::ANSIColor 4.00 qw(coloralias);
598     coloralias('alert', 'red');
599     print "Alert is ", coloralias('alert'), "\n";
600     print colored("This is in red.", 'alert'), "\n";
601
602     use Term::ANSIColor qw(:constants);
603     print BOLD, BLUE, "This text is in bold blue.\n", RESET;
604
605     use Term::ANSIColor qw(:constants);
606     {
607         local $Term::ANSIColor::AUTORESET = 1;
608         print BOLD BLUE "This text is in bold blue.\n";
609         print "This text is normal.\n";
610     }
611
612     use Term::ANSIColor 2.00 qw(:pushpop);
613     print PUSHCOLOR RED ON_GREEN "This text is red on green.\n";
614     print PUSHCOLOR BRIGHT_BLUE "This text is bright blue on green.\n";
615     print RESET BRIGHT_BLUE "This text is just bright blue.\n";
616     print POPCOLOR "Back to red on green.\n";
617     print LOCALCOLOR GREEN ON_BLUE "This text is green on blue.\n";
618     print "This text is red on green.\n";
619     {
620         local $Term::ANSIColor::AUTOLOCAL = 1;
621         print ON_BLUE "This text is red on blue.\n";
622         print "This text is red on green.\n";
623     }
624     print POPCOLOR "Back to whatever we started as.\n";
625
626 =head1 DESCRIPTION
627
628 This module has two interfaces, one through color() and colored() and the
629 other through constants.  It also offers the utility functions uncolor(),
630 colorstrip(), colorvalid(), and coloralias(), which have to be explicitly
631 imported to be used (see L</SYNOPSIS>).
632
633 See L</COMPATIBILITY> for the versions of Term::ANSIColor that introduced
634 particular features and the versions of Perl that included them.
635
636 =head2 Supported Colors
637
638 Terminal emulators that support color divide into three types: ones that
639 support only eight colors, ones that support sixteen, and ones that
640 support 256.  This module provides the ANSI escape codes for all of them.
641 These colors are referred to as ANSI colors 0 through 7 (normal), 8
642 through 15 (16-color), and 16 through 255 (256-color).
643
644 Unfortunately, interpretation of colors 0 through 7 often depends on
645 whether the emulator supports eight colors or sixteen colors.  Emulators
646 that only support eight colors (such as the Linux console) will display
647 colors 0 through 7 with normal brightness and ignore colors 8 through 15,
648 treating them the same as white.  Emulators that support 16 colors, such
649 as gnome-terminal, normally display colors 0 through 7 as dim or darker
650 versions and colors 8 through 15 as normal brightness.  On such emulators,
651 the "normal" white (color 7) usually is shown as pale grey, requiring
652 bright white (15) to be used to get a real white color.  Bright black
653 usually is a dark grey color, although some terminals display it as pure
654 black.  Some sixteen-color terminal emulators also treat normal yellow
655 (color 3) as orange or brown, and bright yellow (color 11) as yellow.
656
657 Following the normal convention of sixteen-color emulators, this module
658 provides a pair of attributes for each color.  For every normal color (0
659 through 7), the corresponding bright color (8 through 15) is obtained by
660 prepending the string C<bright_> to the normal color name.  For example,
661 C<red> is color 1 and C<bright_red> is color 9.  The same applies for
662 background colors: C<on_red> is the normal color and C<on_bright_red> is
663 the bright color.  Capitalize these strings for the constant interface.
664
665 For 256-color emulators, this module additionally provides C<ansi0>
666 through C<ansi15>, which are the same as colors 0 through 15 in
667 sixteen-color emulators but use the 256-color escape syntax, C<grey0>
668 through C<grey23> ranging from nearly black to nearly white, and a set of
669 RGB colors.  The RGB colors are of the form C<rgbI<RGB>> where I<R>, I<G>,
670 and I<B> are numbers from 0 to 5 giving the intensity of red, green, and
671 blue.  C<on_> variants of all of these colors are also provided.  These
672 colors may be ignored completely on non-256-color terminals or may be
673 misinterpreted and produce random behavior.  Additional attributes such as
674 blink, italic, or bold may not work with the 256-color palette.
675
676 There is unfortunately no way to know whether the current emulator
677 supports more than eight colors, which makes the choice of colors
678 difficult.  The most conservative choice is to use only the regular
679 colors, which are at least displayed on all emulators.  However, they will
680 appear dark in sixteen-color terminal emulators, including most common
681 emulators in UNIX X environments.  If you know the display is one of those
682 emulators, you may wish to use the bright variants instead.  Even better,
683 offer the user a way to configure the colors for a given application to
684 fit their terminal emulator.
685
686 =head2 Function Interface
687
688 The function interface uses attribute strings to describe the colors and
689 text attributes to assign to text.  The recognized non-color attributes
690 are clear, reset, bold, dark, faint, italic, underline, underscore, blink,
691 reverse, and concealed.  Clear and reset (reset to default attributes),
692 dark and faint (dim and saturated), and underline and underscore are
693 equivalent, so use whichever is the most intuitive to you.
694
695 Note that not all attributes are supported by all terminal types, and some
696 terminals may not support any of these sequences.  Dark and faint, italic,
697 blink, and concealed in particular are frequently not implemented.
698
699 The recognized normal foreground color attributes (colors 0 to 7) are:
700
701   black  red  green  yellow  blue  magenta  cyan  white
702
703 The corresponding bright foreground color attributes (colors 8 to 15) are:
704
705   bright_black  bright_red      bright_green  bright_yellow
706   bright_blue   bright_magenta  bright_cyan   bright_white
707
708 The recognized normal background color attributes (colors 0 to 7) are:
709
710   on_black  on_red      on_green  on yellow
711   on_blue   on_magenta  on_cyan   on_white
712
713 The recognized bright background color attributes (colors 8 to 15) are:
714
715   on_bright_black  on_bright_red      on_bright_green  on_bright_yellow
716   on_bright_blue   on_bright_magenta  on_bright_cyan   on_bright_white
717
718 For 256-color terminals, the recognized foreground colors are:
719
720   ansi0 .. ansi15
721   grey0 .. grey23
722
723 plus C<rgbI<RGB>> for I<R>, I<G>, and I<B> values from 0 to 5, such as
724 C<rgb000> or C<rgb515>.  Similarly, the recognized background colors are:
725
726   on_ansi0 .. on_ansi15
727   on_grey0 .. on_grey23
728
729 plus C<on_rgbI<RGB>> for I<R>, I<G>, and I<B> values from 0 to 5.
730
731 For any of the above listed attributes, case is not significant.
732
733 Attributes, once set, last until they are unset (by printing the attribute
734 C<clear> or C<reset>).  Be careful to do this, or otherwise your attribute
735 will last after your script is done running, and people get very annoyed
736 at having their prompt and typing changed to weird colors.
737
738 =over 4
739
740 =item color(ATTR[, ATTR ...])
741
742 color() takes any number of strings as arguments and considers them to be
743 space-separated lists of attributes.  It then forms and returns the escape
744 sequence to set those attributes.  It doesn't print it out, just returns
745 it, so you'll have to print it yourself if you want to.  This is so that
746 you can save it as a string, pass it to something else, send it to a file
747 handle, or do anything else with it that you might care to.  color()
748 throws an exception if given an invalid attribute.
749
750 =item colored(STRING, ATTR[, ATTR ...])
751
752 =item colored(ATTR-REF, STRING[, STRING...])
753
754 As an aid in resetting colors, colored() takes a scalar as the first
755 argument and any number of attribute strings as the second argument and
756 returns the scalar wrapped in escape codes so that the attributes will be
757 set as requested before the string and reset to normal after the string.
758 Alternately, you can pass a reference to an array as the first argument,
759 and then the contents of that array will be taken as attributes and color
760 codes and the remainder of the arguments as text to colorize.
761
762 Normally, colored() just puts attribute codes at the beginning and end of
763 the string, but if you set $Term::ANSIColor::EACHLINE to some string, that
764 string will be considered the line delimiter and the attribute will be set
765 at the beginning of each line of the passed string and reset at the end of
766 each line.  This is often desirable if the output contains newlines and
767 you're using background colors, since a background color that persists
768 across a newline is often interpreted by the terminal as providing the
769 default background color for the next line.  Programs like pagers can also
770 be confused by attributes that span lines.  Normally you'll want to set
771 $Term::ANSIColor::EACHLINE to C<"\n"> to use this feature.
772
773 =item uncolor(ESCAPE)
774
775 uncolor() performs the opposite translation as color(), turning escape
776 sequences into a list of strings corresponding to the attributes being set
777 by those sequences.
778
779 =item colorstrip(STRING[, STRING ...])
780
781 colorstrip() removes all color escape sequences from the provided strings,
782 returning the modified strings separately in array context or joined
783 together in scalar context.  Its arguments are not modified.
784
785 =item colorvalid(ATTR[, ATTR ...])
786
787 colorvalid() takes attribute strings the same as color() and returns true
788 if all attributes are known and false otherwise.
789
790 =item coloralias(ALIAS[, ATTR])
791
792 If ATTR is specified, coloralias() sets up an alias of ALIAS for the
793 standard color ATTR.  From that point forward, ALIAS can be passed into
794 color(), colored(), and colorvalid() and will have the same meaning as
795 ATTR.  One possible use of this facility is to give more meaningful names
796 to the 256-color RGB colors.  Only alphanumerics, C<.>, C<_>, and C<-> are
797 allowed in alias names.
798
799 If ATTR is not specified, coloralias() returns the standard color name to
800 which ALIAS is aliased, if any, or undef if ALIAS does not exist.
801
802 This is the same facility used by the ANSI_COLORS_ALIASES environment
803 variable (see L</ENVIRONMENT> below) but can be used at runtime, not just
804 when the module is loaded.
805
806 Later invocations of coloralias() with the same ALIAS will override
807 earlier aliases.  There is no way to remove an alias.
808
809 Aliases have no effect on the return value of uncolor().
810
811 B<WARNING>: Aliases are global and affect all callers in the same process.
812 There is no way to set an alias limited to a particular block of code or a
813 particular object.
814
815 =back
816
817 =head2 Constant Interface
818
819 Alternately, if you import C<:constants>, you can use the following
820 constants directly:
821
822   CLEAR           RESET             BOLD            DARK
823   FAINT           ITALIC            UNDERLINE       UNDERSCORE
824   BLINK           REVERSE           CONCEALED
825
826   BLACK           RED               GREEN           YELLOW
827   BLUE            MAGENTA           CYAN            WHITE
828   BRIGHT_BLACK    BRIGHT_RED        BRIGHT_GREEN    BRIGHT_YELLOW
829   BRIGHT_BLUE     BRIGHT_MAGENTA    BRIGHT_CYAN     BRIGHT_WHITE
830
831   ON_BLACK        ON_RED            ON_GREEN        ON_YELLOW
832   ON_BLUE         ON_MAGENTA        ON_CYAN         ON_WHITE
833   ON_BRIGHT_BLACK ON_BRIGHT_RED     ON_BRIGHT_GREEN ON_BRIGHT_YELLOW
834   ON_BRIGHT_BLUE  ON_BRIGHT_MAGENTA ON_BRIGHT_CYAN  ON_BRIGHT_WHITE
835
836 These are the same as color('attribute') and can be used if you prefer
837 typing:
838
839     print BOLD BLUE ON_WHITE "Text", RESET, "\n";
840
841 to
842
843     print colored ("Text", 'bold blue on_white'), "\n";
844
845 (Note that the newline is kept separate to avoid confusing the terminal as
846 described above since a background color is being used.)
847
848 If you import C<:constants256>, you can use the following constants
849 directly:
850
851   ANSI0 .. ANSI15
852   GREY0 .. GREY23
853
854   RGBXYZ (for X, Y, and Z values from 0 to 5, like RGB000 or RGB515)
855
856   ON_ANSI0 .. ON_ANSI15
857   ON_GREY0 .. ON_GREY23
858
859   ON_RGBXYZ (for X, Y, and Z values from 0 to 5)
860
861 Note that C<:constants256> does not include the other constants, so if you
862 want to mix both, you need to include C<:constants> as well.  You may want
863 to explicitly import at least C<RESET>, as in:
864
865     use Term::ANSIColor 4.00 qw(RESET :constants256);
866
867 When using the constants, if you don't want to have to remember to add the
868 C<, RESET> at the end of each print line, you can set
869 $Term::ANSIColor::AUTORESET to a true value.  Then, the display mode will
870 automatically be reset if there is no comma after the constant.  In other
871 words, with that variable set:
872
873     print BOLD BLUE "Text\n";
874
875 will reset the display mode afterward, whereas:
876
877     print BOLD, BLUE, "Text\n";
878
879 will not.  If you are using background colors, you will probably want to
880 either use say() (in newer versions of Perl) or print the newline with a
881 separate print statement to avoid confusing the terminal.
882
883 If $Term::ANSIColor::AUTOLOCAL is set (see below), it takes precedence
884 over $Term::ANSIColor::AUTORESET, and the latter is ignored.
885
886 The subroutine interface has the advantage over the constants interface in
887 that only two subroutines are exported into your namespace, versus
888 thirty-eight in the constants interface.  On the flip side, the constants
889 interface has the advantage of better compile time error checking, since
890 misspelled names of colors or attributes in calls to color() and colored()
891 won't be caught until runtime whereas misspelled names of constants will
892 be caught at compile time.  So, pollute your namespace with almost two
893 dozen subroutines that you may not even use that often, or risk a silly
894 bug by mistyping an attribute.  Your choice, TMTOWTDI after all.
895
896 =head2 The Color Stack
897
898 You can import C<:pushpop> and maintain a stack of colors using PUSHCOLOR,
899 POPCOLOR, and LOCALCOLOR.  PUSHCOLOR takes the attribute string that
900 starts its argument and pushes it onto a stack of attributes.  POPCOLOR
901 removes the top of the stack and restores the previous attributes set by
902 the argument of a prior PUSHCOLOR.  LOCALCOLOR surrounds its argument in a
903 PUSHCOLOR and POPCOLOR so that the color resets afterward.
904
905 If $Term::ANSIColor::AUTOLOCAL is set, each sequence of color constants
906 will be implicitly preceded by LOCALCOLOR.  In other words, the following:
907
908     {
909         local $Term::ANSIColor::AUTOLOCAL = 1;
910         print BLUE "Text\n";
911     }
912
913 is equivalent to:
914
915     print LOCALCOLOR BLUE "Text\n";
916
917 If $Term::ANSIColor::AUTOLOCAL is set, it takes precedence over
918 $Term::ANSIColor::AUTORESET, and the latter is ignored.
919
920 When using PUSHCOLOR, POPCOLOR, and LOCALCOLOR, it's particularly
921 important to not put commas between the constants.
922
923     print PUSHCOLOR BLUE "Text\n";
924
925 will correctly push BLUE onto the top of the stack.
926
927     print PUSHCOLOR, BLUE, "Text\n";    # wrong!
928
929 will not, and a subsequent pop won't restore the correct attributes.
930 PUSHCOLOR pushes the attributes set by its argument, which is normally a
931 string of color constants.  It can't ask the terminal what the current
932 attributes are.
933
934 =head1 DIAGNOSTICS
935
936 =over 4
937
938 =item Bad color mapping %s
939
940 (W) The specified color mapping from ANSI_COLORS_ALIASES is not valid and
941 could not be parsed.  It was ignored.
942
943 =item Bad escape sequence %s
944
945 (F) You passed an invalid ANSI escape sequence to uncolor().
946
947 =item Bareword "%s" not allowed while "strict subs" in use
948
949 (F) You probably mistyped a constant color name such as:
950
951     $Foobar = FOOBAR . "This line should be blue\n";
952
953 or:
954
955     @Foobar = FOOBAR, "This line should be blue\n";
956
957 This will only show up under use strict (another good reason to run under
958 use strict).
959
960 =item Cannot alias standard color %s
961
962 (F) The alias name passed to coloralias() matches a standard color name.
963 Standard color names cannot be aliased.
964
965 =item Cannot alias standard color %s in %s
966
967 (W) The same, but in ANSI_COLORS_ALIASES.  The color mapping was ignored.
968
969 =item Invalid alias name %s
970
971 (F) You passed an invalid alias name to coloralias().  Alias names must
972 consist only of alphanumerics, C<.>, C<->, and C<_>.
973
974 =item Invalid alias name %s in %s
975
976 (W) You specified an invalid alias name on the left hand of the equal sign
977 in a color mapping in ANSI_COLORS_ALIASES.  The color mapping was ignored.
978
979 =item Invalid attribute name %s
980
981 (F) You passed an invalid attribute name to color(), colored(), or
982 coloralias().
983
984 =item Invalid attribute name %s in %s
985
986 (W) You specified an invalid attribute name on the right hand of the equal
987 sign in a color mapping in ANSI_COLORS_ALIASES.  The color mapping was
988 ignored.
989
990 =item Name "%s" used only once: possible typo
991
992 (W) You probably mistyped a constant color name such as:
993
994     print FOOBAR "This text is color FOOBAR\n";
995
996 It's probably better to always use commas after constant names in order to
997 force the next error.
998
999 =item No comma allowed after filehandle
1000
1001 (F) You probably mistyped a constant color name such as:
1002
1003     print FOOBAR, "This text is color FOOBAR\n";
1004
1005 Generating this fatal compile error is one of the main advantages of using
1006 the constants interface, since you'll immediately know if you mistype a
1007 color name.
1008
1009 =item No name for escape sequence %s
1010
1011 (F) The ANSI escape sequence passed to uncolor() contains escapes which
1012 aren't recognized and can't be translated to names.
1013
1014 =back
1015
1016 =head1 ENVIRONMENT
1017
1018 =over 4
1019
1020 =item ANSI_COLORS_ALIASES
1021
1022 This environment variable allows the user to specify custom color aliases
1023 that will be understood by color(), colored(), and colorvalid().  None of
1024 the other functions will be affected, and no new color constants will be
1025 created.  The custom colors are aliases for existing color names; no new
1026 escape sequences can be introduced.  Only alphanumerics, C<.>, C<_>, and
1027 C<-> are allowed in alias names.
1028
1029 The format is:
1030
1031     ANSI_COLORS_ALIASES='newcolor1=oldcolor1,newcolor2=oldcolor2'
1032
1033 Whitespace is ignored.
1034
1035 For example the L<Solarized|http://ethanschoonover.com/solarized> colors
1036 can be mapped with:
1037
1038     ANSI_COLORS_ALIASES='\
1039         base00=bright_yellow, on_base00=on_bright_yellow,\
1040         base01=bright_green,  on_base01=on_bright_green, \
1041         base02=black,         on_base02=on_black,        \
1042         base03=bright_black,  on_base03=on_bright_black, \
1043         base0=bright_blue,    on_base0=on_bright_blue,   \
1044         base1=bright_cyan,    on_base1=on_bright_cyan,   \
1045         base2=white,          on_base2=on_white,         \
1046         base3=bright_white,   on_base3=on_bright_white,  \
1047         orange=bright_red,    on_orange=on_bright_red,   \
1048         violet=bright_magenta,on_violet=on_bright_magenta'
1049
1050 This environment variable is read and applied when the Term::ANSIColor
1051 module is loaded and is then subsequently ignored.  Changes to
1052 ANSI_COLORS_ALIASES after the module is loaded will have no effect.  See
1053 coloralias() for an equivalent facility that can be used at runtime.
1054
1055 =item ANSI_COLORS_DISABLED
1056
1057 If this environment variable is set to a true value, all of the functions
1058 defined by this module (color(), colored(), and all of the constants not
1059 previously used in the program) will not output any escape sequences and
1060 instead will just return the empty string or pass through the original
1061 text as appropriate.  This is intended to support easy use of scripts
1062 using this module on platforms that don't support ANSI escape sequences.
1063
1064 =back
1065
1066 =head1 COMPATIBILITY
1067
1068 Term::ANSIColor was first included with Perl in Perl 5.6.0.
1069
1070 The uncolor() function and support for ANSI_COLORS_DISABLED were added in
1071 Term::ANSIColor 1.04, included in Perl 5.8.0.
1072
1073 Support for dark was added in Term::ANSIColor 1.08, included in Perl
1074 5.8.4.
1075
1076 The color stack, including the C<:pushpop> import tag, PUSHCOLOR,
1077 POPCOLOR, LOCALCOLOR, and the $Term::ANSIColor::AUTOLOCAL variable, was
1078 added in Term::ANSIColor 2.00, included in Perl 5.10.1.
1079
1080 colorstrip() was added in Term::ANSIColor 2.01 and colorvalid() was added
1081 in Term::ANSIColor 2.02, both included in Perl 5.11.0.
1082
1083 Support for colors 8 through 15 (the C<bright_> variants) was added in
1084 Term::ANSIColor 3.00, included in Perl 5.13.3.
1085
1086 Support for italic was added in Term::ANSIColor 3.02, included in Perl
1087 5.17.1.
1088
1089 Support for colors 16 through 256 (the C<ansi>, C<rgb>, and C<grey>
1090 colors), the C<:constants256> import tag, the coloralias() function, and
1091 support for the ANSI_COLORS_ALIASES environment variable were added in
1092 Term::ANSIColor 4.00, included in Perl 5.17.8.
1093
1094 $Term::ANSIColor::AUTOLOCAL was changed to take precedence over
1095 $Term::ANSIColor::AUTORESET, rather than the other way around, in
1096 Term::ANSIColor 4.00, included in Perl 5.17.8.
1097
1098 =head1 RESTRICTIONS
1099
1100 It would be nice if one could leave off the commas around the constants
1101 entirely and just say:
1102
1103     print BOLD BLUE ON_WHITE "Text\n" RESET;
1104
1105 but the syntax of Perl doesn't allow this.  You need a comma after the
1106 string.  (Of course, you may consider it a bug that commas between all the
1107 constants aren't required, in which case you may feel free to insert
1108 commas unless you're using $Term::ANSIColor::AUTORESET or
1109 PUSHCOLOR/POPCOLOR.)
1110
1111 For easier debugging, you may prefer to always use the commas when not
1112 setting $Term::ANSIColor::AUTORESET or PUSHCOLOR/POPCOLOR so that you'll
1113 get a fatal compile error rather than a warning.
1114
1115 It's not possible to use this module to embed formatting and color
1116 attributes using Perl formats.  They replace the escape character with a
1117 space (as documented in L<perlform(1)>), resulting in garbled output from
1118 the unrecognized attribute.  Even if there were a way around that problem,
1119 the format doesn't know that the non-printing escape sequence is
1120 zero-length and would incorrectly format the output.  For formatted output
1121 using color or other attributes, either use sprintf() instead or use
1122 formline() and then add the color or other attributes after formatting and
1123 before output.
1124
1125 =head1 NOTES
1126
1127 The codes generated by this module are standard terminal control codes,
1128 complying with ECMA-048 and ISO 6429 (generally referred to as "ANSI
1129 color" for the color codes).  The non-color control codes (bold, dark,
1130 italic, underline, and reverse) are part of the earlier ANSI X3.64
1131 standard for control sequences for video terminals and peripherals.
1132
1133 Note that not all displays are ISO 6429-compliant, or even X3.64-compliant
1134 (or are even attempting to be so).  This module will not work as expected
1135 on displays that do not honor these escape sequences, such as cmd.exe,
1136 4nt.exe, and command.com under either Windows NT or Windows 2000.  They
1137 may just be ignored, or they may display as an ESC character followed by
1138 some apparent garbage.
1139
1140 Jean Delvare provided the following table of different common terminal
1141 emulators and their support for the various attributes and others have
1142 helped me flesh it out:
1143
1144               clear    bold     faint   under    blink   reverse  conceal
1145  ------------------------------------------------------------------------
1146  xterm         yes      yes      no      yes      yes      yes      yes
1147  linux         yes      yes      yes    bold      yes      yes      no
1148  rxvt          yes      yes      no      yes  bold/black   yes      no
1149  dtterm        yes      yes      yes     yes    reverse    yes      yes
1150  teraterm      yes    reverse    no      yes    rev/red    yes      no
1151  aixterm      kinda   normal     no      yes      no       yes      yes
1152  PuTTY         yes     color     no      yes      no       yes      no
1153  Windows       yes      no       no      no       no       yes      no
1154  Cygwin SSH    yes      yes      no     color    color    color     yes
1155  Terminal.app  yes      yes      no      yes      yes      yes      yes
1156
1157 Windows is Windows telnet, Cygwin SSH is the OpenSSH implementation under
1158 Cygwin on Windows NT, and Mac Terminal is the Terminal application in Mac
1159 OS X.  Where the entry is other than yes or no, that emulator displays the
1160 given attribute as something else instead.  Note that on an aixterm, clear
1161 doesn't reset colors; you have to explicitly set the colors back to what
1162 you want.  More entries in this table are welcome.
1163
1164 Support for code 3 (italic) is rare and therefore not mentioned in that
1165 table.  It is not believed to be fully supported by any of the terminals
1166 listed, although it's displayed as green in the Linux console, but it is
1167 reportedly supported by urxvt.
1168
1169 Note that codes 6 (rapid blink) and 9 (strike-through) are specified in
1170 ANSI X3.64 and ECMA-048 but are not commonly supported by most displays
1171 and emulators and therefore aren't supported by this module at the present
1172 time.  ECMA-048 also specifies a large number of other attributes,
1173 including a sequence of attributes for font changes, Fraktur characters,
1174 double-underlining, framing, circling, and overlining.  As none of these
1175 attributes are widely supported or useful, they also aren't currently
1176 supported by this module.
1177
1178 Most modern X terminal emulators support 256 colors.  Known to not support
1179 those colors are aterm, rxvt, Terminal.app, and TTY/VC.
1180
1181 =head1 AUTHORS
1182
1183 Original idea (using constants) by Zenin, reimplemented using subs by Russ
1184 Allbery <rra@cpan.org>, and then combined with the original idea by
1185 Russ with input from Zenin.  256-color support is based on work by Kurt
1186 Starsinic.  Russ Allbery now maintains this module.
1187
1188 PUSHCOLOR, POPCOLOR, and LOCALCOLOR were contributed by openmethods.com
1189 voice solutions.
1190
1191 =head1 COPYRIGHT AND LICENSE
1192
1193 Copyright 1996 Zenin
1194
1195 Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2008, 2009, 2010,
1196 2011, 2012, 2013, 2014, 2015 Russ Allbery <rra@cpan.org>
1197
1198 Copyright 2012 Kurt Starsinic <kstarsinic@gmail.com>
1199
1200 This program is free software; you may redistribute it and/or modify it
1201 under the same terms as Perl itself.
1202
1203 =head1 SEE ALSO
1204
1205 The CPAN module L<Term::ExtendedColor> provides a different and more
1206 comprehensive interface for 256-color emulators that may be more
1207 convenient.  The CPAN module L<Win32::Console::ANSI> provides ANSI color
1208 (and other escape sequence) support in the Win32 Console environment.
1209
1210 ECMA-048 is available on-line (at least at the time of this writing) at
1211 L<http://www.ecma-international.org/publications/standards/Ecma-048.htm>.
1212
1213 ISO 6429 is available from ISO for a charge; the author of this module
1214 does not own a copy of it.  Since the source material for ISO 6429 was
1215 ECMA-048 and the latter is available for free, there seems little reason
1216 to obtain the ISO standard.
1217
1218 The 256-color control sequences are documented at
1219 L<http://invisible-island.net/xterm/ctlseqs/ctlseqs.html> (search for
1220 256-color).
1221
1222 The current version of this module is always available from its web site
1223 at L<http://www.eyrie.org/~eagle/software/ansicolor/>.  It is also part of
1224 the Perl core distribution as of 5.6.0.
1225
1226 =cut