/ 
Getopt-EX-v1.1.1
River stage two • 11 direct dependents • 15 total dependents
/ Getopt::EX::Colormap

NAME

Getopt::EX::Colormap - ANSI terminal color and option support

SYNOPSIS

GetOptions('colormap|cm:s' => @opt_colormap);

require Getopt::EX::Colormap;
my $handler = new Getopt::EX::Colormap;
$handler->load_params(@opt_colormap);  

print handler->color('FILE', 'FILE labeled text');

print handler->index_color($index, 'TEXT');

  or

use Getopt::EX::Colormap qw(colorize);
$text = colorize(SPEC, TEXT);
$text = colorize(SPEC_1, TEXT_1, SPEC_2, TEXT_2, ...);

DESCRIPTION

Coloring text capability is not strongly bound to option processing, but it may be useful to give simple uniform way to specify complicated color setting from command line.

This module assumes the color information is given in two ways: one in labeled table, and one in indexed list.

This is a example of labeled table:

--cm 'COMMAND=SE,OMARK=CS,NMARK=MS' \
--cm 'OTEXT=C,NTEXT=M,*CHANGE=BD/445,DELETE=APPEND=RD/544' \
--cm 'CMARK=GS,MMARK=YS,CTEXT=G,MTEXT=Y'

Each color definitions are separated by comma (,) and label is specified by LABEL= style precedence. Multiple labels can be set for same value by connecting them together. Label name can be specified with * and ? wild characters.

List example is like this:

--cm 555/100,555/010,555/001 \
--cm 555/011,555/101,555/110 \
--cm 555/021,555/201,555/210 \
--cm 555/012,555/102,555/120

This is the example of RGB 6x6x6 216 colors specification. Left side of slash is foreground color, and right side is for background. This color list is accessed by index.

Handler maintains hash and list objects, and labeled colors are stored in hash, non-label colors are in list automatically. User can mix both specifications.

Besides producing ANSI colored text, this module supports calling arbitrary function to handle a string. See "FUNCTION SPEC" section for more detail.

COLOR SPEC

Color specification is combination of single uppercase character representing 8 colors :

R  Red
G  Green
B  Blue
C  Cyan
M  Magenta
Y  Yellow
K  Black
W  White

and alternative (usually brighter) colors in lowercase:

r, g, b, c, m, y, k, w

or RGB values and 24 grey levels if using ANSI 256 or full color terminal :

000000 .. FFFFFF : 24bit RGB colors
000 .. 555       : 6x6x6 RGB 216 colors
L00 .. L23       : 24 grey levels

    Note that, when values are all same in 24bit RGB, it is converted to 24 grey level, otherwise 6x6x6 216 color.

with other special effects :

Z  0 Zero (reset)
D  1 Double-struck (boldface)
P  2 Pale (dark)
I  3 Italic
U  4 Underline
F  5 Flash (blink: slow)
Q  6 Quick (blink: rapid)
S  7 Stand-out (reverse video)
V  8 Vanish (concealed)
J  9 Junk (crossed out)

;  No effect
X  No effect

and arbitrary numbers beginning with "H", those are directly converted into escape sequence. Use "x" to indicate multiple numbers. Remember associated with Hollerith constants.

H4      underline
H1x3x7  bold / italic / stand-out

If the spec includes /, left side is considered as foreground color and right side as background. If multiple colors are given in same spec, all indicators are produced in the order of their presence. Consequently, the last one takes effect.

Effect characters are case insensitive, and can be found anywhere and in any order in color spec string. Because X and ; takes no effect, you can use them to improve readability, like SxD;K/544.

Samples:

RGB  6x6x6    24bit           color
===  =======  =============   ==================
B    005      0000FF        : blue foreground
 /M     /505        /FF00FF : magenta background
K/W  000/555  000000/FFFFFF : black on white
R/G  500/050  FF0000/00FF00 : red on green
W/w  L03/L20  303030/c6c6c6 : grey on grey

24-bit RGB color sequence is supported but disabled by default. Set $COLOR_RGB24 module variable to enable.

FUNCTION SPEC

It is also possible to set arbitrary function which is called to handle string in place of color, and that is not necessarily concerned with color. This scheme is quite powerful and the module name itself may be somewhat misleading. Spec string which start with sub{ is considered as a function definition. So

% example --cm 'sub{uc}'

set the function object in the color entry. And when color method is called with that object, specified function is called instead of producing ANSI color sequence. Function is supposed to get the target text as a global variable $_, and return the result as a string. Function sub{uc} in the above example returns uppercase version of $_.

If your script prints file name according to the color spec labeled by FILE, then

% example --cm FILE=R

prints the file name in red, but

% example --cm FILE=sub{uc}

will print the name in uppercases.

Spec start with & is considered as a function name. If the function double is defined like:

sub double { $_ . $_ }

then, command

% example --cm '&double'

produces doubled text by color method. Function can also take parameters, so the next example

    sub repeat {
	my %opt = @_;
	$_ x $opt{count} // 1;
    }

    % example --cm '&repeat(count=3)'

produces tripled text.

Function object is created by <Getopt::EX::Func> module. Take a look at the module for detail.

EXAMPLE CODE

#!/usr/bin/perl

use strict;
use warnings;

my @opt_colormap;
use Getopt::EX::Long;
GetOptions("colormap|cm=s" => \@opt_colormap);

my %colormap = ( # default color map
    FILE => 'R',
    LINE => 'G',
    TEXT => 'B',
    );
my @colors;

require Getopt::EX::Colormap;
my $handler = new Getopt::EX::Colormap
    HASH => \%colormap,
    LIST => \@colors;

$handler->load_params(@opt_colormap);

for (0 .. $#colors) {
    print $handler->index_color($_, "COLOR $_"), "\n";
}

for (sort keys %colormap) {
    print $handler->color($_, $_), "\n";
}

This sample program is complete to work. If you save this script as a file example, try to put following contents in ~/.examplerc and see what happens.

option default \
    --cm 555/100,555/010,555/001 \
    --cm 555/011,555/101,555/110 \
    --cm 555/021,555/201,555/210 \
    --cm 555/012,555/102,555/120

METHODS

color label, TEXT
color color_spec, TEXT

Return colored text indicated by label or color spec string.

index_color index, TEXT

Return colored text indicated by index. If the index is bigger than color list, it rounds up.

new
append
load_params

See super class Getopt::EX::LabeledParam.

SEE ALSO

Getopt::EX, Getopt::EX::LabeledParam