# Color screen output using ANSI escape sequences.

#

# Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2008, 2009, 2010,

#     2011, 2012, 2013, 2014, 2015, 2016 Russ Allbery <rra@cpan.org>

# Copyright 1996 Zenin

# Copyright 2012 Kurt Starsinic <kstarsinic@gmail.com>

#

# This program is free software; you may redistribute it and/or modify it

# under the same terms as Perl itself.

#

# PUSH/POP support submitted 2007 by openmethods.com voice solutions

#

# Ah, September, when the sysadmins turn colors and fall off the trees....

#                               -- Dave Van Domelen

##############################################################################

# Modules and declarations

##############################################################################

package Term::ANSIColor;

use 5.006;

use strict;

use warnings;

# Also uses Carp but loads it on demand to reduce memory usage.

use Exporter ();

# use Exporter plus @ISA instead of use base for 5.6 compatibility.

## no critic (ClassHierarchies::ProhibitExplicitISA)

# Declare variables that should be set in BEGIN for robustness.

## no critic (Modules::ProhibitAutomaticExportation)

our (@EXPORT, @EXPORT_OK, %EXPORT_TAGS, @ISA, $VERSION);

# We use autoloading, which sets this variable to the name of the called sub.

our $AUTOLOAD;

# Set $VERSION and everything export-related in a BEGIN block for robustness

# against circular module loading (not that we load any modules, but

# consistency is good).

BEGIN {

    $VERSION = '4.06';

    # All of the basic supported constants, used in %EXPORT_TAGS.

    my @colorlist = qw(

      CLEAR           RESET             BOLD            DARK

      FAINT           ITALIC            UNDERLINE       UNDERSCORE

      BLINK           REVERSE           CONCEALED

      BLACK           RED               GREEN           YELLOW

      BLUE            MAGENTA           CYAN            WHITE

      ON_BLACK        ON_RED            ON_GREEN        ON_YELLOW

      ON_BLUE         ON_MAGENTA        ON_CYAN         ON_WHITE

      BRIGHT_BLACK    BRIGHT_RED        BRIGHT_GREEN    BRIGHT_YELLOW

      BRIGHT_BLUE     BRIGHT_MAGENTA    BRIGHT_CYAN     BRIGHT_WHITE

      ON_BRIGHT_BLACK ON_BRIGHT_RED     ON_BRIGHT_GREEN ON_BRIGHT_YELLOW

      ON_BRIGHT_BLUE  ON_BRIGHT_MAGENTA ON_BRIGHT_CYAN  ON_BRIGHT_WHITE

    );

    # 256-color constants, used in %EXPORT_TAGS.

    my @colorlist256 = (

        (map { ("ANSI$_", "ON_ANSI$_") } 0 .. 255),

        (map { ("GREY$_", "ON_GREY$_") } 0 .. 23),

    );

    for my $r (0 .. 5) {

        for my $g (0 .. 5) {

            push(@colorlist256, map { ("RGB$r$g$_", "ON_RGB$r$g$_") } 0 .. 5);

        }

    }

    # Exported symbol configuration.

    @ISA         = qw(Exporter);

    @EXPORT      = qw(color colored);

    @EXPORT_OK   = qw(uncolor colorstrip colorvalid coloralias);

    %EXPORT_TAGS = (

        constants    => \@colorlist,

        constants256 => \@colorlist256,

        pushpop      => [@colorlist, qw(PUSHCOLOR POPCOLOR LOCALCOLOR)],

    );

    Exporter::export_ok_tags('pushpop', 'constants256');

}

##############################################################################

# Package variables

##############################################################################

# If this is set, any color changes will implicitly push the current color

# onto the stack and then pop it at the end of the constant sequence, just as

# if LOCALCOLOR were used.

our $AUTOLOCAL;

# Caller sets this to force a reset at the end of each constant sequence.

our $AUTORESET;

# Caller sets this to force colors to be reset at the end of each line.

our $EACHLINE;

##############################################################################

# Internal data structures

##############################################################################

# This module does quite a bit of initialization at the time it is first

# loaded, primarily to set up the package-global %ATTRIBUTES hash.  The

# entries for 256-color names are easier to handle programmatically, and

# custom colors are also imported from the environment if any are set.

# All basic supported attributes, including aliases.

#<<<

our %ATTRIBUTES = (

    'clear'          => 0,

    'reset'          => 0,

    'bold'           => 1,

    'dark'           => 2,

    'faint'          => 2,

    'italic'         => 3,

    'underline'      => 4,

    'underscore'     => 4,

    'blink'          => 5,

    'reverse'        => 7,

    'concealed'      => 8,

    'black'          => 30,   'on_black'          => 40,

    'red'            => 31,   'on_red'            => 41,

    'green'          => 32,   'on_green'          => 42,

    'yellow'         => 33,   'on_yellow'         => 43,

    'blue'           => 34,   'on_blue'           => 44,

    'magenta'        => 35,   'on_magenta'        => 45,

    'cyan'           => 36,   'on_cyan'           => 46,

    'white'          => 37,   'on_white'          => 47,

    'bright_black'   => 90,   'on_bright_black'   => 100,

    'bright_red'     => 91,   'on_bright_red'     => 101,

    'bright_green'   => 92,   'on_bright_green'   => 102,

    'bright_yellow'  => 93,   'on_bright_yellow'  => 103,

    'bright_blue'    => 94,   'on_bright_blue'    => 104,

    'bright_magenta' => 95,   'on_bright_magenta' => 105,

    'bright_cyan'    => 96,   'on_bright_cyan'    => 106,

    'bright_white'   => 97,   'on_bright_white'   => 107,

);

#>>>

# Generating the 256-color codes involves a lot of codes and offsets that are

# not helped by turning them into constants.

# The first 16 256-color codes are duplicates of the 16 ANSI colors.  The rest

# are RBG and greyscale values.

for my $code (0 .. 15) {

    $ATTRIBUTES{"ansi$code"}    = "38;5;$code";

    $ATTRIBUTES{"on_ansi$code"} = "48;5;$code";

}

# 256-color RGB colors.  Red, green, and blue can each be values 0 through 5,

# and the resulting 216 colors start with color 16.

for my $r (0 .. 5) {

    for my $g (0 .. 5) {

        for my $b (0 .. 5) {

            my $code = 16 + (6 * 6 * $r) + (6 * $g) + $b;

            $ATTRIBUTES{"rgb$r$g$b"}    = "38;5;$code";

            $ATTRIBUTES{"on_rgb$r$g$b"} = "48;5;$code";

        }

    }

}

# The last 256-color codes are 24 shades of grey.

for my $n (0 .. 23) {

    my $code = $n + 232;

    $ATTRIBUTES{"grey$n"}    = "38;5;$code";

    $ATTRIBUTES{"on_grey$n"} = "48;5;$code";

}

# Reverse lookup.  Alphabetically first name for a sequence is preferred.

our %ATTRIBUTES_R;

for my $attr (reverse sort keys %ATTRIBUTES) {

    $ATTRIBUTES_R{ $ATTRIBUTES{$attr} } = $attr;

}

# Provide ansiN names for all 256 characters to provide a convenient flat

# namespace if one doesn't want to mess with the RGB and greyscale naming.  Do

# this after creating %ATTRIBUTES_R since we want to use the canonical names

# when reversing a color.

for my $code (16 .. 255) {

    $ATTRIBUTES{"ansi$code"}    = "38;5;$code";

    $ATTRIBUTES{"on_ansi$code"} = "48;5;$code";

}

# Import any custom colors set in the environment.

our %ALIASES;

if (exists $ENV{ANSI_COLORS_ALIASES}) {

    my $spec = $ENV{ANSI_COLORS_ALIASES};

    $spec =~ s{\s+}{}xmsg;

    # Error reporting here is an interesting question.  Use warn rather than

    # carp because carp would report the line of the use or require, which

    # doesn't help anyone understand what's going on, whereas seeing this code

    # will be more helpful.

    ## no critic (ErrorHandling::RequireCarping)

    for my $definition (split m{,}xms, $spec) {

        my ($new, $old) = split m{=}xms, $definition, 2;

        if (!$new || !$old) {

            warn qq{Bad color mapping "$definition"};

        } else {

            my $result = eval { coloralias($new, $old) };

            if (!$result) {

                my $error = $@;

                $error =~ s{ [ ] at [ ] .* }{}xms;

                warn qq{$error in "$definition"};

            }

        }

    }

}

# Stores the current color stack maintained by PUSHCOLOR and POPCOLOR.  This

# is global and therefore not threadsafe.

our @COLORSTACK;

##############################################################################

# Helper functions

##############################################################################

# Stub to load the Carp module on demand.

sub croak {

    my (@args) = @_;

    require Carp;

    Carp::croak(@args);

}

##############################################################################

# Implementation (constant form)

##############################################################################

# Time to have fun!  We now want to define the constant subs, which are named

# the same as the attributes above but in all caps.  Each constant sub needs

# to act differently depending on whether $AUTORESET is set.  Without

# autoreset:

#

#     BLUE "text\n"  ==>  "\e[34mtext\n"

#

# If $AUTORESET is set, we should instead get:

#

#     BLUE "text\n"  ==>  "\e[34mtext\n\e[0m"

#

# The sub also needs to handle the case where it has no arguments correctly.

# Maintaining all of this as separate subs would be a major nightmare, as well

# as duplicate the %ATTRIBUTES hash, so instead we define an AUTOLOAD sub to

# define the constant subs on demand.  To do that, we check the name of the

# called sub against the list of attributes, and if it's an all-caps version

# of one of them, we define the sub on the fly and then run it.

#

# If the environment variable ANSI_COLORS_DISABLED is set to a true value,

# just return the arguments without adding any escape sequences.  This is to

# make it easier to write scripts that also work on systems without any ANSI

# support, like Windows consoles.

#

# Avoid using character classes like [:upper:] and \w here, since they load

# Unicode character tables and consume a ton of memory.  All of our constants

# only use ASCII characters.

#

## no critic (ClassHierarchies::ProhibitAutoloading)

## no critic (Subroutines::RequireArgUnpacking)

## no critic (RegularExpressions::ProhibitEnumeratedClasses)

sub AUTOLOAD {

    my ($sub, $attr) = $AUTOLOAD =~ m{

        \A ( [a-zA-Z0-9:]* :: ([A-Z0-9_]+) ) \z

    }xms;

    # Check if we were called with something that doesn't look like an

    # attribute.

    if (!($attr && defined($ATTRIBUTES{ lc $attr }))) {

        croak("undefined subroutine &$AUTOLOAD called");

    }

    # If colors are disabled, just return the input.  Do this without

    # installing a sub for (marginal, unbenchmarked) speed.

    if ($ENV{ANSI_COLORS_DISABLED}) {

        return join(q{}, @_);

    }

    # We've untainted the name of the sub.

    $AUTOLOAD = $sub;

    # Figure out the ANSI string to set the desired attribute.

    my $escape = "\e[" . $ATTRIBUTES{ lc $attr } . 'm';

    # Save the current value of $@.  We can't just use local since we want to

    # restore it before dispatching to the newly-created sub.  (The caller may

    # be colorizing output that includes $@.)

    my $eval_err = $@;

    # Generate the constant sub, which should still recognize some of our

    # package variables.  Use string eval to avoid a dependency on

    # Sub::Install, even though it makes it somewhat less readable.

    ## no critic (BuiltinFunctions::ProhibitStringyEval)

    ## no critic (ValuesAndExpressions::ProhibitImplicitNewlines)

    my $eval_result = eval qq{

        sub $AUTOLOAD {

            if (\$ENV{ANSI_COLORS_DISABLED}) {

                return join(q{}, \@_);

            } elsif (\$AUTOLOCAL && \@_) {

                return PUSHCOLOR('$escape') . join(q{}, \@_) . POPCOLOR;

            } elsif (\$AUTORESET && \@_) {

                return '$escape' . join(q{}, \@_) . "\e[0m";

            } else {

                return '$escape' . join(q{}, \@_);

            }

        }

        1;

    };

    # Failure is an internal error, not a problem with the caller.

    ## no critic (ErrorHandling::RequireCarping)

    if (!$eval_result) {

        die "failed to generate constant $attr: $@";

    }

    # Restore $@.

    ## no critic (Variables::RequireLocalizedPunctuationVars)

    $@ = $eval_err;

    # Dispatch to the newly-created sub.

    ## no critic (References::ProhibitDoubleSigils)

    goto &$AUTOLOAD;

}

## use critic

# Append a new color to the top of the color stack and return the top of

# the stack.

#

# $text - Any text we're applying colors to, with color escapes prepended

#

# Returns: The text passed in

sub PUSHCOLOR {

    my (@text) = @_;

    my $text = join(q{}, @text);

    # Extract any number of color-setting escape sequences from the start of

    # the string.

    my ($color) = $text =~ m{ \A ( (?:\e\[ [\d;]+ m)+ ) }xms;

    # If we already have a stack, append these escapes to the set from the top

    # of the stack.  This way, each position in the stack stores the complete

    # enabled colors for that stage, at the cost of some potential

    # inefficiency.

    if (@COLORSTACK) {

        $color = $COLORSTACK[-1] . $color;

    }

    # Push the color onto the stack.

    push(@COLORSTACK, $color);

    return $text;

}

# Pop the color stack and return the new top of the stack (or reset, if

# the stack is empty).

#

# @text - Any text we're applying colors to

#

# Returns: The concatenation of @text prepended with the new stack color

sub POPCOLOR {

    my (@text) = @_;

    pop(@COLORSTACK);

    if (@COLORSTACK) {

        return $COLORSTACK[-1] . join(q{}, @text);

    } else {

        return RESET(@text);

    }

}

# Surround arguments with a push and a pop.  The effect will be to reset the

# colors to whatever was on the color stack before this sequence of colors was

# applied.

#

# @text - Any text we're applying colors to

#

# Returns: The concatenation of the text and the proper color reset sequence.

sub LOCALCOLOR {

    my (@text) = @_;

    return PUSHCOLOR(join(q{}, @text)) . POPCOLOR();

}

##############################################################################

# Implementation (attribute string form)

##############################################################################

# Return the escape code for a given set of color attributes.

#

# @codes - A list of possibly space-separated color attributes

#

# Returns: The escape sequence setting those color attributes

#          undef if no escape sequences were given

#  Throws: Text exception for any invalid attribute

sub color {

    my (@codes) = @_;

    @codes = map { split } @codes;

    # Return the empty string if colors are disabled.

    if ($ENV{ANSI_COLORS_DISABLED}) {

        return q{};

    }

    # Build the attribute string from semicolon-separated numbers.

    my $attribute = q{};

    for my $code (@codes) {

        $code = lc($code);

        if (defined($ATTRIBUTES{$code})) {

            $attribute .= $ATTRIBUTES{$code} . q{;};

        } elsif (defined($ALIASES{$code})) {

            $attribute .= $ALIASES{$code} . q{;};

        } else {

            croak("Invalid attribute name $code");

        }

    }

    # We added one too many semicolons for simplicity.  Remove the last one.

    chop($attribute);

    # Return undef if there were no attributes.

    return ($attribute ne q{}) ? "\e[${attribute}m" : undef;

}

# Return a list of named color attributes for a given set of escape codes.

# Escape sequences can be given with or without enclosing "\e[" and "m".  The

# empty escape sequence '' or "\e[m" gives an empty list of attrs.

#

# There is one special case.  256-color codes start with 38 or 48, followed by

# a 5 and then the 256-color code.

#

# @escapes - A list of escape sequences or escape sequence numbers

#

# Returns: An array of attribute names corresponding to those sequences

#  Throws: Text exceptions on invalid escape sequences or unknown colors

sub uncolor {

    my (@escapes) = @_;

    my (@nums, @result);

    # Walk the list of escapes and build a list of attribute numbers.

    for my $escape (@escapes) {

        $escape =~ s{ \A \e\[ }{}xms;

        $escape =~ s{ m \z }   {}xms;

        my ($attrs) = $escape =~ m{ \A ((?:\d+;)* \d*) \z }xms;

        if (!defined($attrs)) {

            croak("Bad escape sequence $escape");

        }

        # Pull off 256-color codes (38;5;n or 48;5;n) as a unit.

        push(@nums, $attrs =~ m{ ( 0*[34]8;0*5;\d+ | \d+ ) (?: ; | \z ) }xmsg);

    }

    # Now, walk the list of numbers and convert them to attribute names.

    # Strip leading zeroes from any of the numbers.  (xterm, at least, allows

    # leading zeroes to be added to any number in an escape sequence.)

    for my $num (@nums) {

        $num =~ s{ ( \A | ; ) 0+ (\d) }{$1$2}xmsg;

        my $name = $ATTRIBUTES_R{$num};

        if (!defined($name)) {

            croak("No name for escape sequence $num");

        }

        push(@result, $name);

    }

    # Return the attribute names.

    return @result;

}

# Given a string and a set of attributes, returns the string surrounded by

# escape codes to set those attributes and then clear them at the end of the

# string.  The attributes can be given either as an array ref as the first

# argument or as a list as the second and subsequent arguments.

#

# If $EACHLINE is set, insert a reset before each occurrence of the string

# $EACHLINE and the starting attribute code after the string $EACHLINE, so

# that no attribute crosses line delimiters (this is often desirable if the

# output is to be piped to a pager or some other program).

#

# $first - An anonymous array of attributes or the text to color

# @rest  - The text to color or the list of attributes

#

# Returns: The text, concatenated if necessary, surrounded by escapes to set

#          the desired colors and reset them afterwards

#  Throws: Text exception on invalid attributes

sub colored {

    my ($first, @rest) = @_;

    my ($string, @codes);

    if (ref($first) && ref($first) eq 'ARRAY') {

        @codes = @{$first};

        $string = join(q{}, @rest);

    } else {

        $string = $first;

        @codes  = @rest;

    }

    # Return the string unmolested if colors are disabled.

    if ($ENV{ANSI_COLORS_DISABLED}) {

        return $string;

    }

    # Find the attribute string for our colors.

    my $attr = color(@codes);

    # If $EACHLINE is defined, split the string on line boundaries, suppress

    # empty segments, and then colorize each of the line sections.

    if (defined($EACHLINE)) {

        my @text = map { ($_ ne $EACHLINE) ? $attr . $_ . "\e[0m" : $_ }

          grep { length > 0 }

          split(m{ (\Q$EACHLINE\E) }xms, $string);

        return join(q{}, @text);

    } else {

        return $attr . $string . "\e[0m";

    }

}

# Define a new color alias, or return the value of an existing alias.

#

# $alias - The color alias to define

# $color - The standard color the alias will correspond to (optional)

#

# Returns: The standard color value of the alias

#          undef if one argument was given and the alias was not recognized

#  Throws: Text exceptions for invalid alias names, attempts to use a

#          standard color name as an alias, or an unknown standard color name

sub coloralias {

    my ($alias, $color) = @_;

    if (!defined($color)) {

        if (!exists $ALIASES{$alias}) {

            return;

        } else {

            return $ATTRIBUTES_R{ $ALIASES{$alias} };

        }

    }

    # Avoid \w here to not load Unicode character tables, which increases the

    # memory footprint of this module considerably.

    #

    ## no critic (RegularExpressions::ProhibitEnumeratedClasses)

    if ($alias !~ m{ \A [a-zA-Z0-9._-]+ \z }xms) {

        croak(qq{Invalid alias name "$alias"});

    } elsif ($ATTRIBUTES{$alias}) {

        croak(qq{Cannot alias standard color "$alias"});

    } elsif (!exists $ATTRIBUTES{$color}) {

        croak(qq{Invalid attribute name "$color"});

    }

    ## use critic

    # Set the alias and return.

    $ALIASES{$alias} = $ATTRIBUTES{$color};

    return $color;

}

# Given a string, strip the ANSI color codes out of that string and return the

# result.  This removes only ANSI color codes, not movement codes and other

# escape sequences.

#

# @string - The list of strings to sanitize

#

# Returns: (array)  The strings stripped of ANSI color escape sequences

#          (scalar) The same, concatenated

sub colorstrip {

    my (@string) = @_;

    for my $string (@string) {

        $string =~ s{ \e\[ [\d;]* m }{}xmsg;

    }

    return wantarray ? @string : join(q{}, @string);

}

# Given a list of color attributes (arguments for color, for instance), return

# true if they're all valid or false if any of them are invalid.

#

# @codes - A list of color attributes, possibly space-separated

#

# Returns: True if all the attributes are valid, false otherwise.

sub colorvalid {

    my (@codes) = @_;

    @codes = map { split(q{ }, lc) } @codes;

    for my $code (@codes) {

        if (!(defined($ATTRIBUTES{$code}) || defined($ALIASES{$code}))) {

            return;

        }

    }

    return 1;

}

##############################################################################

# Module return value and documentation

##############################################################################

# Ensure we evaluate to true.

1;

__END__

=head1 NAME

Term::ANSIColor - Color screen output using ANSI escape sequences

=for stopwords

cyan colorize namespace runtime TMTOWTDI cmd.exe cmd.exe. 4nt.exe. 4nt.exe

command.com NT ESC Delvare SSH OpenSSH aixterm ECMA-048 Fraktur overlining

Zenin reimplemented Allbery PUSHCOLOR POPCOLOR LOCALCOLOR openmethods.com

openmethods.com. grey ATTR urxvt mistyped prepending Bareword filehandle

Cygwin Starsinic aterm rxvt CPAN RGB Solarized Whitespace alphanumerics

undef

=head1 SYNOPSIS

    use Term::ANSIColor;

    print color('bold blue');

    print "This text is bold blue.\n";

    print color('reset');

    print "This text is normal.\n";

    print colored("Yellow on magenta.", 'yellow on_magenta'), "\n";

    print "This text is normal.\n";

    print colored(['yellow on_magenta'], 'Yellow on magenta.', "\n");

    print colored(['red on_bright_yellow'], 'Red on bright yellow.', "\n");

    print colored(['bright_red on_black'], 'Bright red on black.', "\n");

    print "\n";

    # Map escape sequences back to color names.

    use Term::ANSIColor 1.04 qw(uncolor);

    my $names = uncolor('01;31');

    print join(q{ }, @{$names}), "\n";

    # Strip all color escape sequences.

    use Term::ANSIColor 2.01 qw(colorstrip);

    print colorstrip("\e[1mThis is bold\e[0m"), "\n";

    # Determine whether a color is valid.

    use Term::ANSIColor 2.02 qw(colorvalid);

    my $valid = colorvalid('blue bold', 'on_magenta');

    print "Color string is ", $valid ? "valid\n" : "invalid\n";

    # Create new aliases for colors.

    use Term::ANSIColor 4.00 qw(coloralias);

    coloralias('alert', 'red');

    print "Alert is ", coloralias('alert'), "\n";

    print colored("This is in red.", 'alert'), "\n";

    use Term::ANSIColor qw(:constants);

    print BOLD, BLUE, "This text is in bold blue.\n", RESET;

    use Term::ANSIColor qw(:constants);

    {

        local $Term::ANSIColor::AUTORESET = 1;

        print BOLD BLUE "This text is in bold blue.\n";

        print "This text is normal.\n";

    }

    use Term::ANSIColor 2.00 qw(:pushpop);

    print PUSHCOLOR RED ON_GREEN "This text is red on green.\n";

    print PUSHCOLOR BRIGHT_BLUE "This text is bright blue on green.\n";

    print RESET BRIGHT_BLUE "This text is just bright blue.\n";

    print POPCOLOR "Back to red on green.\n";

    print LOCALCOLOR GREEN ON_BLUE "This text is green on blue.\n";

    print "This text is red on green.\n";

    {

        local $Term::ANSIColor::AUTOLOCAL = 1;

        print ON_BLUE "This text is red on blue.\n";

        print "This text is red on green.\n";

    }

    print POPCOLOR "Back to whatever we started as.\n";

=head1 DESCRIPTION

This module has two interfaces, one through color() and colored() and the

other through constants.  It also offers the utility functions uncolor(),

colorstrip(), colorvalid(), and coloralias(), which have to be explicitly

imported to be used (see L</SYNOPSIS>).

See L</COMPATIBILITY> for the versions of Term::ANSIColor that introduced

particular features and the versions of Perl that included them.

=head2 Supported Colors

Terminal emulators that support color divide into three types: ones that

support only eight colors, ones that support sixteen, and ones that

support 256.  This module provides the ANSI escape codes for all of them.

These colors are referred to as ANSI colors 0 through 7 (normal), 8

through 15 (16-color), and 16 through 255 (256-color).

Unfortunately, interpretation of colors 0 through 7 often depends on

whether the emulator supports eight colors or sixteen colors.  Emulators

that only support eight colors (such as the Linux console) will display

colors 0 through 7 with normal brightness and ignore colors 8 through 15,

treating them the same as white.  Emulators that support 16 colors, such

as gnome-terminal, normally display colors 0 through 7 as dim or darker

versions and colors 8 through 15 as normal brightness.  On such emulators,

the "normal" white (color 7) usually is shown as pale grey, requiring

bright white (15) to be used to get a real white color.  Bright black

usually is a dark grey color, although some terminals display it as pure

black.  Some sixteen-color terminal emulators also treat normal yellow

(color 3) as orange or brown, and bright yellow (color 11) as yellow.

Following the normal convention of sixteen-color emulators, this module

provides a pair of attributes for each color.  For every normal color (0

through 7), the corresponding bright color (8 through 15) is obtained by

prepending the string C<bright_> to the normal color name.  For example,

C<red> is color 1 and C<bright_red> is color 9.  The same applies for

background colors: C<on_red> is the normal color and C<on_bright_red> is

the bright color.  Capitalize these strings for the constant interface.

For 256-color emulators, this module additionally provides C<ansi0>

through C<ansi15>, which are the same as colors 0 through 15 in

sixteen-color emulators but use the 256-color escape syntax, C<grey0>

through C<grey23> ranging from nearly black to nearly white, and a set of

RGB colors.  The RGB colors are of the form C<rgbI<RGB>> where I<R>, I<G>,

and I are numbers from 0 to 5 giving the intensity of red, green, and

blue.  The grey and RGB colors are also available as C<ansi16> through

C<ansi255> if you want simple names for all 256 colors.  C<on_> variants

of all of these colors are also provided.  These colors may be ignored

completely on non-256-color terminals or may be misinterpreted and produce

random behavior.  Additional attributes such as blink, italic, or bold may

not work with the 256-color palette.

There is unfortunately no way to know whether the current emulator

supports more than eight colors, which makes the choice of colors

difficult.  The most conservative choice is to use only the regular

colors, which are at least displayed on all emulators.  However, they will

appear dark in sixteen-color terminal emulators, including most common

emulators in UNIX X environments.  If you know the display is one of those

emulators, you may wish to use the bright variants instead.  Even better,

offer the user a way to configure the colors for a given application to

fit their terminal emulator.

=head2 Function Interface

The function interface uses attribute strings to describe the colors and

text attributes to assign to text.  The recognized non-color attributes

are clear, reset, bold, dark, faint, italic, underline, underscore, blink,

reverse, and concealed.  Clear and reset (reset to default attributes),

dark and faint (dim and saturated), and underline and underscore are

equivalent, so use whichever is the most intuitive to you.

Note that not all attributes are supported by all terminal types, and some

terminals may not support any of these sequences.  Dark and faint, italic,

blink, and concealed in particular are frequently not implemented.

The recognized normal foreground color attributes (colors 0 to 7) are:

  black  red  green  yellow  blue  magenta  cyan  white

The corresponding bright foreground color attributes (colors 8 to 15) are:

  bright_black  bright_red      bright_green  bright_yellow

  bright_blue   bright_magenta  bright_cyan   bright_white

The recognized normal background color attributes (colors 0 to 7) are:

  on_black  on_red      on_green  on yellow

  on_blue   on_magenta  on_cyan   on_white

The recognized bright background color attributes (colors 8 to 15) are:

  on_bright_black  on_bright_red      on_bright_green  on_bright_yellow

  on_bright_blue   on_bright_magenta  on_bright_cyan   on_bright_white

For 256-color terminals, the recognized foreground colors are:

  ansi0 .. ansi255

  grey0 .. grey23

plus C<rgbI<RGB>> for I<R>, I<G>, and I values from 0 to 5, such as

C<rgb000> or C<rgb515>.  Similarly, the recognized background colors are:

  on_ansi0 .. on_ansi255

  on_grey0 .. on_grey23

plus C<on_rgbI<RGB>> for I<R>, I<G>, and I values from 0 to 5.

For any of the above listed attributes, case is not significant.

Attributes, once set, last until they are unset (by printing the attribute

C<clear> or C<reset>).  Be careful to do this, or otherwise your attribute

will last after your script is done running, and people get very annoyed

at having their prompt and typing changed to weird colors.

=over 4

=item color(ATTR[, ATTR ...])

color() takes any number of strings as arguments and considers them to be

space-separated lists of attributes.  It then forms and returns the escape

sequence to set those attributes.  It doesn't print it out, just returns

it, so you'll have to print it yourself if you want to.  This is so that

you can save it as a string, pass it to something else, send it to a file

handle, or do anything else with it that you might care to.  color()

throws an exception if given an invalid attribute.

=item colored(STRING, ATTR[, ATTR ...])

=item colored(ATTR-REF, STRING[, STRING...])

As an aid in resetting colors, colored() takes a scalar as the first

argument and any number of attribute strings as the second argument and

returns the scalar wrapped in escape codes so that the attributes will be

set as requested before the string and reset to normal after the string.

Alternately, you can pass a reference to an array as the first argument,

and then the contents of that array will be taken as attributes and color

codes and the remainder of the arguments as text to colorize.

Normally, colored() just puts attribute codes at the beginning and end of

the string, but if you set $Term::ANSIColor::EACHLINE to some string, that

string will be considered the line delimiter and the attribute will be set

at the beginning of each line of the passed string and reset at the end of

each line.  This is often desirable if the output contains newlines and

you're using background colors, since a background color that persists

across a newline is often interpreted by the terminal as providing the

default background color for the next line.  Programs like pagers can also

be confused by attributes that span lines.  Normally you'll want to set

$Term::ANSIColor::EACHLINE to C<"\n"> to use this feature.

=item uncolor(ESCAPE)

uncolor() performs the opposite translation as color(), turning escape

sequences into a list of strings corresponding to the attributes being set

by those sequences.  uncolor() will never return C<ansi16> through

C<ansi255>, instead preferring the C<grey> and C<rgb> names (and likewise

for C<on_ansi16> through C<on_ansi255>).

=item colorstrip(STRING[, STRING ...])

colorstrip() removes all color escape sequences from the provided strings,

returning the modified strings separately in array context or joined

together in scalar context.  Its arguments are not modified.

=item colorvalid(ATTR[, ATTR ...])

colorvalid() takes attribute strings the same as color() and returns true

if all attributes are known and false otherwise.

=item coloralias(ALIAS[, ATTR])

If ATTR is specified, coloralias() sets up an alias of ALIAS for the

standard color ATTR.  From that point forward, ALIAS can be passed into

color(), colored(), and colorvalid() and will have the same meaning as

ATTR.  One possible use of this facility is to give more meaningful names

to the 256-color RGB colors.  Only ASCII alphanumerics, C<.>, C<_>, and

C<-> are allowed in alias names.

If ATTR is not specified, coloralias() returns the standard color name to

which ALIAS is aliased, if any, or undef if ALIAS does not exist.

This is the same facility used by the ANSI_COLORS_ALIASES environment

variable (see L</ENVIRONMENT> below) but can be used at runtime, not just

when the module is loaded.

Later invocations of coloralias() with the same ALIAS will override

earlier aliases.  There is no way to remove an alias.

Aliases have no effect on the return value of uncolor().

B<WARNING>: Aliases are global and affect all callers in the same process.

There is no way to set an alias limited to a particular block of code or a

particular object.

=back

=head2 Constant Interface

Alternately, if you import C<:constants>, you can use the following

constants directly:

  CLEAR           RESET             BOLD            DARK

  FAINT           ITALIC            UNDERLINE       UNDERSCORE

  BLINK           REVERSE           CONCEALED

  BLACK           RED               GREEN           YELLOW

  BLUE            MAGENTA           CYAN            WHITE

  BRIGHT_BLACK    BRIGHT_RED        BRIGHT_GREEN    BRIGHT_YELLOW

  BRIGHT_BLUE     BRIGHT_MAGENTA    BRIGHT_CYAN     BRIGHT_WHITE

  ON_BLACK        ON_RED            ON_GREEN        ON_YELLOW

  ON_BLUE         ON_MAGENTA        ON_CYAN         ON_WHITE

  ON_BRIGHT_BLACK ON_BRIGHT_RED     ON_BRIGHT_GREEN ON_BRIGHT_YELLOW

  ON_BRIGHT_BLUE  ON_BRIGHT_MAGENTA ON_BRIGHT_CYAN  ON_BRIGHT_WHITE

These are the same as color('attribute') and can be used if you prefer

typing:

    print BOLD BLUE ON_WHITE "Text", RESET, "\n";