/ 
Getopt-EX-2.2.1
River stage two • 10 direct dependents • 19 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 $cm = Getopt::EX::Colormap
    ->new
    ->load_params(@opt_colormap);

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

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

DESCRIPTION

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

Coloring function is now implemented in different module Term::ANSIColor::Concise. Detail about color spec is described in its document.

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

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

LABELED COLOR

This is an example of labeled list:

--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'

Color definitions are separated by comma (,) and the 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 ? wildcard characters.

If the color spec start with plus (+) mark with the labeled list format, it is appended to the current value with reset mark (^). Next example uses wildcard to set all labels end with `CHANGE' to `R' and set `R^S' to `OCHANGE' label.

--cm '*CHANGE=R,OCHANGE=+S'

INDEX COLOR

Indexed 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 an example of RGB 6x6x6 216 colors specification. Left side of slash is foreground, and right side is for background color. This color list is accessed by index.

If the special reset symbol @ is encountered, the index list is reset to empty at that point.

CALLING FUNCTIONS

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

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/env 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 = Getopt::EX::Colormap->new(
    HASH => \%colormap,
    LIST => \@colors,
    );

$handler->load_params(@opt_colormap);

for (keys @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

METHOD

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.

colormap

Return string which can be used for option definition. Some parameters can be specified like:

$obj->colormap(name => "--newopt", option => "--colormap");
name

Specify new option name.

option

Specify option name for colormap setup.

sort

Default value is length and sort options by their length. Use alphabet to sort them alphabetically.

noalign

Colormap label is aligned so that `=' marks are lined vertically. Give true value to noalign parameter, if you don't like this behavior.

FUNCTION

These functions are now implemented in Term::ANSIColor::Concise module by slightly different names. Interface is remained for compatibility but using them in the new code is strongly discouraged.

colorize(color_spec, text)
colorize24(color_spec, text)

Return colorized version of given text.

colorize produces 256 or 24bit colors depending on the setting, while colorize24 always produces 24bit color sequence for 24bit/12bit color spec. See ENVIRONMENT.

ansi_code(color_spec)

Produces introducer sequence for given spec. Reset code can be taken by ansi_code("Z").

ansi_pair(color_spec)

Produces introducer and recover sequences for given spec. Recover sequence includes Erase Line related control with simple SGR reset code.

csi_code(name, params)

Produce CSI (Control Sequence Introducer) sequence by name with numeric parameters. name is one of CUU, CUD, CUF, CUB, CNL, CPL, CHA, CUP, ED, EL, SU, SD, HVP, SGR, SCP, RCP.

colortable([width])

Print visual 256 color matrix table on the screen. Default width is 144. Use like this:

perl -MGetopt::EX::Colormap=colortable -e colortable

ENVIRONMENT

Environment variables are also implemented in slightly different way Term::ANSIColor::Concise module. Use ANSICOLOR_NO_NO_COLOR, ANSICOLOR_RGB24, ANSICOLOR_NO_RESET_EL if you are using newer version.

If the environment variable NO_COLOR is set, regardless of its value, colorizing interface in this module never produce color sequence. Primitive function such as ansi_code is not the case. See https://no-color.org/.

If the module variable $NO_NO_COLOR or GETOPTEX_NO_NO_COLOR environment is true, NO_COLOR value is ignored.

color method and colorize function produces 256 or 24bit colors depending on the value of $RGB24 module variable. Also 24bit mode is enabled when environment GETOPTEX_RGB24 is set or COLORTERM is truecolor.

If the module variable $NO_RESET_EL set, or GETOPTEX_NO_RESET_EL environment, Erase Line sequence is not produced after RESET code. See "RESET SEQUENCE".

SEE ALSO

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

Term::ANSIColor::Concise

https://en.wikipedia.org/wiki/ANSI_escape_code

https://en.wikipedia.org/wiki/X11_color_names

https://no-color.org/

AUTHOR

Kazumasa Utashiro

COPYRIGHT

The following copyright notice applies to all the files provided in this distribution, including binary files, unless explicitly noted otherwise.

Copyright 2015-2024 Kazumasa Utashiro

LICENSE

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