NAME

Term::ExtendedColor - Color screen output using extended escape sequences

SYNOPSIS

use Term::ExtendedColor qw(:all);

# Or use the 'attributes' tag to only import the functions for setting
# attributes.
# This will import the following functions:

# fg(), bg(), bold(), underline(), inverse(), italic(), clear()
use Term::ExtendedColor ':attributes';

## Foreground colors

my $red_text = fg('red2', 'this is in red');
my $spring   = fg('springgreen3', 'this is green');

## Background colors

print bg('red5', "Default foreground text on dark red background"), "\n";
my $red_on_green = fg('red3', bg('green12', 'Red text on green background'));
print "$red_on_green\n";

## Fall-through attributes

Term::ExtendedColor::autoreset(0);
my $bold  = fg('bold', 'This is bold');
my $red   = fg('red2', 'This is red... and bold');
my $green = bg('green28', 'This is bold red on green background');

# Make sure to clear all attributes when autoreset turned OFF,
# or else the users shell will be messed up

my $clear = clear();
print "$bold\n";
print "$red\n";
print "$green $clear\n";

## Non-color attributes

# Turn on autoreset again
Term::ExtendedColor::autoreset(1);

for(qw(italic underline blink reverse bold)) {
  print fg($_, $_), "\n";
}

# For convenience

my $bolded = bold("Bold text!");
my $italic = italic("Text in italics!");

## Remove all attributes from input data
my @colored;
push(@colored, fg('bold', fg('red2', 'Bold and red')));
push(@colored, fg('green13', fg('italic', 'Green, italic')));

print "$_\n" for @colored;
print "$_\n" for uncolor(@colored);

DESCRIPTION

Term::ExtendedColor provides functions for sending so called extended escape sequences, most notably colors. It can be used to set the current text attributes or to apply a set of attributes to a string and reset the current text attributes at the end of the string.

This module does (almost) the same thing as the core Term::ANSIColor module, plus a little more. First off, as the name suggests, it handles the extended colorset - that means, the ANSI colors plus 240 extra colors, building up a matrix of a total of 256 colors.

EXPORTS

None by default.

FUNCTIONS

fg()

Parameters: $color_by_name || $color_by_index | \@strings, \@integers

Returns: $string | \@strings

my $green = fg('green2', 'green foreground');
my @blue  = fg('blue4',  ['takes arrayrefs as well']);

my $x_color = fg('mediumorchid1', 'Using mappings from the X11 rgb.txt');

my $arbitary_color = fg(4, 'This is colored in the fifth ANSI color');

Set foreground colors and attributes.

Called without arguments is the same as calling clear().

expects a string with an attribute attached to it as its first argument, and optionally any number of additional strings which the operation will be performed upon. If the internal $AUTORESET variabe is non-zero (default), the list of strings will be mapped with the attribute in front and the 'reset' attribute in the end. This is for convience, but the behaviour can be changed by calling Term::ExtendedColor::autoreset(0).

Be warned, you'll need to reset manually, or else the set attributes will last after your program is finished, leaving the user with a not-so-funny prompt.

If you pass an invalid attribute, the original data will be returned unmodified.

bg()

Parameters: $color_by_name || $color_by_index | \@strings, \@integers

Returns: $string | \@strings

my $green_bg = bg('green4', 'green background');
my @blue_bg  = bg('blue6',  ['blue background']);

Like fg(), but sets background colors.

uncolor()

Parameters: $string | \@strings

Returns: $string | \@strings

my $stripped = uncolor($colored_data);
my @no_color = uncolor(\@colored);

strips the input data from escape sequences.

get_colors()

Parameters: None

Returns: \%attributes

my $colors = get_colors();

returns a hash reference with all available attributes and colors.

clear()

Parameters: None

Returns: $string

returns the code for clearing current attributes and resets to normal

autoreset

Parameters: Boolean

turn autoreset on/off. Default is on. autoreset is not exported by default, you have to call it using the fully qualified name Term::ExtendedColor::autoreset().

WRAPPERS

A couple of simple wrappers are provided for convenience.

bold()

Parameters: @data | \@data

Convenience function that might be used in place of fg('bold', @data);

italic()

Parameters: @data | \@data

Convenience function that might be used in place of fg('italic', @data);

underline()

Parameters: @data | \@data

Convenience function that might be used in place of fg('underline', @data);

inverse()

Parameters: @data | \@data

Reverse video / inverse. Convenience function that might be used in place of fg('inverse', @data);

NOTES

The codes generated by this module complies to the extension of the ANSI colors standard first implemented in xterm in 1999. The first 16 color indexes (0 - 15) is the regular ANSI colors, while index 16 - 255 is the extension. Not all terminal emulators support this extension, though I've had a hard time finding one that doesn't. :)

Terminal    256 colors
----------------------
aterm               no
eterm              yes
gnome-terminal     yes
konsole            yes
lxterminal         yes
mrxvt              yes
roxterm            yes
rxvt                no
rxvt-unicode       yes *
sakura             yes
terminal           yes
terminator         yes
vte                yes
xterm              yes
iTerm2             yes
Terminal.app        no

GNU Screen         yes
tmux               yes
TTY/VC              no

* Previously needed a patch. Full support was added in version 9.09.

There's no way to give these extended colors meaningful names.

Our first thought was to map them against some standard color names, like those in the HTML 4.0 specification or the SVG one. They didn’t match.

Therefore, they are named by their base color (red, green, magenta) plus index; The first index (always 1) is the brightest shade of that particular color, while the last index is the darkest.

It's also possible to use some X color names, as defined in rgb.txt. Do note that the color values do not match exactly; it's just an approximation.

A full list of available color can be retrieved with get_colors(). Here's a full list for referencce;

Attributes

reset, clear, normal        reset all attributes
bold, bright                bold or bright, depending on implementation
faint                       decreased intensity (not widely supported)
italic, cursive             italic or cursive
underline, underscore       underline
blink                       slow blink
blink_ms                    rapid blink (only supported in MS DOS)
reverse, inverse, negative  reverse video
conceal                     conceal, or hide (not widely supported)

Standard color map

FIRST       LAST

red1        red5
blue1       blue17
cyan1       cyan24
gray1       gray24
green1      green28
orange1     orange5
purple1     purple30
yellow1     yellow18
magenta1    magenta26

X color names

aquamarine1
aquamarine3
blueviolet
cadetblue1
cadetblue2
chartreuse1
chartreuse2
chartreuse3
chartreuse4
cornflowerblue
cornsilk1
darkblue
darkcyan
darkgoldenrod
darkgreen
darkkhaki
darkmagenta1
darkmagenta2
darkolivegreen1
darkolivegreen2
darkolivegreen3
darkolivegreen4
darkolivegreen5
darkorange3
darkorange4
darkorange1
darkred1
darkred2
darkseagreen1
darkseagreen2
darkseagreen3
darkseagreen4
darkslategray1
darkslategray2
darkslategray3
darkturquoise
darkviolet
deeppink1
deeppink2
deeppink3
deeppink4
deepskyblue1
deepskyblue2
deepskyblue3
deepskyblue4
deepskyblue4
dodgerblue1
dodgerblue2
dodgerblue3
gold1
gold3
greenyellow
grey0
grey100
grey11
grey15
grey19
grey23
grey27
grey30
grey3
grey35
grey37
grey39
grey42
grey46
grey50
grey53
grey54
grey58
grey62
grey63
grey66
grey69
grey70
grey74
grey7
grey78
grey82
grey84
grey85
grey89
grey93
honeydew2
hotpink2
hotpink3
hotpink
indianred1
indianred
khaki1
khaki3
lightcoral
lightcyan1
lightcyan3
lightgoldenrod1
lightgoldenrod2
lightgoldenrod3
lightgreen
lightpink1
lightpink3
lightpink4
lightsalmon1
lightsalmon3
lightsalmon3
lightseagreen
lightskyblue1
lightskyblue3
lightskyblue3
lightslateblue
lightslategrey
lightsteelblue1
lightsteelblue3
lightsteelblue
lightyellow3
mediumorchid1
mediumorchid3
mediumorchid
mediumpurple1
mediumpurple2
mediumpurple3
mediumpurple4
mediumpurple
mediumspringgreen
mediumturquoise
mediumvioletred
mistyrose1
mistyrose3
navajowhite1
navajowhite3
navyblue
orangered1
orchid1
orchid2
orchid
palegreen1
palegreen3
paleturquoise1
paleturquoise4
palevioletred1
pink1
pink3
plum1
plum2
plum3
plum4
purple
rosybrown
royalblue1
salmon1
sandybrown
seagreen1
seagreen2
seagreen3
skyblue1
skyblue2
skyblue3
slateblue1
slateblue3
springgreen1
springgreen2
springgreen3
springgreen4
steelblue1
steelblue3
steelblue
tan
thistle1
thistle3
turquoise2
turquoise4
violet
wheat1
wheat4

SEE ALSO

Term::ExtendedColor::Xresources, Term::ExtendedColor::TTY, Term::ANSIColor

AUTHOR

Magnus Woldrich
CPAN ID: WOLDRICH
magnus@trapd00r.se
http://japh.se

CONTRIBUTORS

None required yet.

COPYRIGHT

Copyright 2010, 2011 the Term::ExtendedColor "AUTHOR" and "CONTRIBUTORS" as listed above.

LICENSE

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

cpanm Term::ExtendedColor

perl -MCPAN -e shell
install Term::ExtendedColor