/ 
Getopt-EX-2.3.1
River stage two • 11 direct dependents • 18 total dependents
⭐ Starred 1 GitHub stars
/ 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 tightly bound to option processing, but it may be useful to provide a simple uniform way to specify complicated color settings from the command line.

The coloring function is now implemented in a different module Term::ANSIColor::Concise. Details about color specifications are described in its documentation.

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

The handler maintains hash and list objects, and labeled colors are stored in the hash, while indexed colors are in the list automatically. Users 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 commas (,) and the label is specified by LABEL= style prefix. Multiple labels can be set for the same value by connecting them together. Label names can be specified with * and ? wildcard characters.

If the color spec starts with a plus (+) mark in the labeled list format, it is appended to the current value with a reset mark (^). The next example uses a wildcard to set all labels ending with `CHANGE' to `R' and sets `R^S' to the `OCHANGE' label.

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

INDEX COLOR

An 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 an RGB 6x6x6 216 colors specification. The left side of the slash is for foreground, and the 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 an arbitrary function which is called to handle a 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. A spec string which starts with sub{ is considered a function definition. So

% example --cm 'sub{uc}'

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

If your script prints a 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.

A spec starting with & is considered a function name. If the function double is defined like:

sub double { $_ . $_ }

then the command

% example --cm '&double'

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

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

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

produces tripled text.

The function object is created by the Getopt::EX::Func module. Take a look at the module for details.

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 larger than the color list, it wraps around.

new
append
load_params

See super class Getopt::EX::LabeledParam.

colormap

Return a 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

The default value is length and sorts options by their length. Use alphabet to sort them alphabetically.

noalign

Colormap labels are aligned so that `=' marks are lined up vertically. Give a true value to the noalign parameter if you don't like this behavior.

FUNCTION

These functions are now implemented in the Term::ANSIColor::Concise module with slightly different names. The interface is retained for compatibility but using them in new code is strongly discouraged.

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

Return colorized version of given text.

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

ansi_code(color_spec)

Produces an introducer sequence for the given spec. A reset code can be obtained by ansi_code("Z").

ansi_pair(color_spec)

Produces introducer and recovery sequences for the given spec. The recovery sequence includes Erase Line related controls along with a simple SGR reset code.

csi_code(name, params)

Produces a 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])

Prints a visual 256 color matrix table on the screen. The default width is 144. Use it like this:

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

ENVIRONMENT

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

If the environment variable NO_COLOR is set, regardless of its value, the colorizing interface in this module never produces color sequences. Primitive functions such as ansi_code are not affected. See https://no-color.org/.

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

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

If the module variable $NO_RESET_EL is set, or the GETOPTEX_NO_RESET_EL environment variable is set, the Erase Line sequence is not produced after a 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-2025 Kazumasa Utashiro

LICENSE

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