/ 
Term-ExtendedColor-0.171
River stage two • 13 direct dependents • 15 total dependents
/ Term::ExtendedColor

NAME

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

SYNOPSIS

use Term::ExtendedColor qw(fg bg uncolor get_colors clear lookup);

## Foreground colors

print fg 'green15', "this is bright green foreground\n";
my $red_text = fg('red2', "this is in red");

## 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";
}


## 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);

## Look up all mapped colors and print them in color

for(0..255) {
  my $color_str = lookup($_);
  if(defined($color_str)) {
    printf("%25s => %s\n", fg($color_str, $color_str), $_);
  }
}

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.

Exported are functions for setting the foreground as well as background colors. Other attributes are supported as well - bold, italic, underline and reverse.

There are support for doing the reverse thing - uncolor data; strip it from escape sequences.

Support is included for redefining colors - use with care, though.

EXPORTS

None by default.

FUNCTIONS

fg()

Parameters: $string, integer | \@strings, \@integers

Returns: $string | \@strings

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

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). Note that you will have to reset manually though, or else the set attributes will last after your script is finished, resulting in the prompt looking funny.

Optionally, you can pass a reference to an array as the second argument.

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

bg()

Parameters: $string | \@strings

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.

lookup()

Parameters: $string | \@strings

Returns: $string | \@strings

my $str = lookup(255); # gray1

my $fg  = fg('red4');
$str    = lookup($str);

my $data   = [197, 220, 148..196];
my @result = lookup($data);

look up argument in a reverse table. Argument can be either a full escape sequence or a number. Alternatively, you may pass a reference to an array as the first argument.

Returns undef if no such attribute exists.

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: 1/0 Returns: None

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().

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.

SEE ALSO

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

AUTHOR

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

COPYRIGHT

Copyright 2010, 2011 Magnus Woldrich <magnus@trapd00r.se>. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.