Getopt::EX::Colormap - ANSI terminal color and option support
GetOptions('colormap|cm:s' => @opt_colormap); require Getopt::EX::Colormap; my $cm = new Getopt::EX::Colormap; $cm->load_params(@opt_colormap); print $cm->color('FILE', 'FILE labeled text'); print $cm->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, ...);
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 list, and one in indexed list.
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'
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.
,
*
?
If the color spec start with plus (+) mark with 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'
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 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 specification is a 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 :
(255,255,255) : 24bit decimal RGB colors #000000 .. #FFFFFF : 24bit hex RGB colors #000 .. #FFF : 12bit hex RGB 4096 colors 000 .. 555 : 6x6x6 RGB 216 colors L00 .. L25 : Black (L00), 24 grey levels, White (L25)
Begining # can be omitted in 24bit RGB notation.
When values are all same in 24bit or 12bit RGB, it is converted to 24 grey level, otherwise 6x6x6 216 color.
Until version v1.9.0, grey levels were assigned to L00-L23. In this version, L00 and L25 represent black and white, and 24 grey levels are assigned to L01-L24.
or color names enclosed by angle bracket :
<red> <blue> <green> <cyan> <magenta> <yellow> <aliceblue> <honeydue> <hotpink> <mooccasin> <medium_aqua_marine>
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) E Erase Line ; No effect X No effect / Toggle foreground/background ^ Reset to foreground
At first the color is considered as foreground, and slash (/) switches foreground and background. If multiple colors are given in the same spec, all indicators are produced in the order of their presence. Consequently, the last one takes effect.
/
If the spec start with plus (+) or minus (-) character, following characters are appneded/deleted from previous value. Reset mark (^) is inserted before appended string.
-
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.
X
;
SxD;K/544
Samples:
RGB 6x6x6 12bit 24bit color name === ======= ========= ============= ================== B 005 #00F (0,0,255) <blue> /M /505 /#F0F /(255,0,255) /<magenta> K/W 000/555 #000/#FFF 000000/FFFFFF <black>/<white> R/G 500/050 #F00/#0F0 FF0000/00FF00 <red>/<green> W/w L03/L20 #333/#ccc 303030/c6c6c6 <dimgrey>/<lightgrey>
24-bit RGB color sequence is supported but disabled by default. Set $COLOR_RGB24 module variable to enable it.
$COLOR_RGB24
Character "E" is an abbreviation for "{EL}", and it clears the line from cursor to the end of the line. At this time, background color is set to the area. When this code is found in the start sequence, it is copied to just before ending reset sequence, with preceding sequence if necessary, to keep the effect even when the text is wrapped to multiple lines.
Other ANSI CSI sequences are also available in the form of "{NAME}", despite there are few reasons to use them.
CUU n Cursor up CUD n Cursor Down CUF n Cursor Forward CUB n Cursor Back CNL n Cursor Next Line CPL n Cursor Previous line CHA n Cursor Horizontal Absolute CUP n,m Cursor Position ED n Erase in Display (0 after, 1 before, 2 entire, 3 w/buffer) EL n Erase in Line (0 after, 1 before, 2 entire) SU n Scroll Up SD n Scroll Down HVP n,m Horizontal Vertical Position SGR n* Select Graphic Rendition SCP Save Cursor Position RCP Restore Cursor Position
These name accept following optional numerical parameters, using comma (',') or semicolon (';') to separate multiple ones, with optional braces. For example, color spec DK/544 can be described as {SGR1;30;48;5;224} or more readable {SGR(1,30,48,5,224)}.
DK/544
{SGR1;30;48;5;224}
{SGR(1,30,48,5,224)}
Color names are experimentaly supported in this version. Currently names are listed in Graphics::ColorNames::WWW module. Following colors are available.
aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia fuscia gainsboro ghostwhite gold goldenrod gray grey green greenyellow honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum powderblue purple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen
Enclose them by angle bracket to use, like:
<deeppink>/<lightyellow>
Although these colors are defined in 24bit value, they are mapped to 6x6x6 216 colors by default. Set $COLOR_RGB24 module variable to use 24bit color mode.
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
sub{
% 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 $_.
color
$_
sub{uc}
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:
&
double
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.
#!/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
Return colored text indicated by label or color spec string.
Return colored text indicated by index. If the index is bigger than color list, it rounds up.
See super class Getopt::EX::LabeledParam.
Return string which can be used for option definition. Some parameters can be specified like:
$obj->colormap(name => "--newopt", option => "--colormap");
Specify new option name.
Specify option name for colormap setup.
Default value is length and sort options by their length. Use alphabet to sort them alphabetically.
length
alphabet
Colormap label is aligned so that `=' marks are lined vertically. Give true value to noalign parameter, if you don't like this behaviour.
Getopt::EX, Getopt::EX::LabeledParam
Graphics::ColorNames::WWW
https://en.wikipedia.org/wiki/ANSI_escape_code
To install Getopt::EX, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::EX
CPAN shell
perl -MCPAN -e shell install Getopt::EX
For more information on module installation, please visit the detailed CPAN module installation guide.