#!/usr/bin/env perl
use v5.14;
App::ansiecho->new->run(splice @ARGV);
exit;
__END__
=encoding utf-8
=head1 NAME
ansiecho - Colored echo command using ANSI terminal sequence
=head1 VERSION
Version 0.03
=head1 SYNOPSIS
ansiecho [ options ] args ...
Command Options:
-n Do not print the trailing newline
-j --join Do not print space between arguments
-e --escape Enable backslash escape notation
--rgb24 Produce 24bit color sequence
--separate=s Set argument separator
-h --help Print this message
-v --version Print version
Prefix Options:
-s/-S SPEC Produce ANSI sequence
-c/-C SPEC ARG Colorize next argument
-f/-F FORMAT ARGS Format arguments
-E Terminate -C -S -F effect
-i/-a SPEC Insert/Append ANSI sequence
Example:
ansiecho -c R Red -c M/551 Magenta/Yellow -c FSDB BlinkReverseBoldBlue
ansiecho -f '[ %12s ]' -c SR -f '%+06d' 123
ansiecho -C '555/(132,0,41)' d i g i t a l
read -a color < <( ansiecho -S ZE K/544 K/454 K/445 )
=head1 DESCRIPTION
=head2 ECHO
B<ansiecho> print arguments with ANSI terminal escape sequence
according to the given color specification.
In a simple case, B<ansiecho> behave exactly same as L<echo> command.
ansiecho a b c
Like L<echo> command, option B<-n> disables to print newline at the
end. Option B<-j> (or B<--join>) removes white space between
arguments.
Arguments can include backslash escaped characters, such as C<\n> for
a new line. There is an bash-echo-compatible B<-e> option, but it is
enabled by default. You can include control and named Unicode
characters using this.
ansiecho '\t\N{ALARM CLOCK}\a'
See L<STRING LITERAL> section for detail.
=head2 COLOR and EFFECT
You can specify color of each argument by preceding with B<-c> option:
ansiecho -c R a -c GI b -c BD c
This command print strings C<a>, C<b> and C<c> according to the color
spec of C<R> (Red), C<GI> (I<Green Italic>) and C<BD> (B<Blue Bold>)
respectively.
Foreground and background color is specified in the form of
C<fore/back>.
ansiecho -c B/M 'Blue on Magenta' -c '<pink>/<salmon>' fish
Color can be described by 8+8 standard colors, 24 gray scales, 6x6x6
216 colors, RGB values or color names, with special effects such as I
(Italic), D (Double-struck; Bold), S (Stand-out; Reverse Video) and
such. More information is described in L<COLOR SPEC> section.
=head2 FORMAT
Format string can be specified by B<-f> option, and it behaves like a
L<printf(1)> command.
ansiecho -f '[ %5s : %5s : %5s ]' -c R RED -c G GREEN -c B BLUE
As in above example, colored text can be given as an argument for
B<-f> option, and the string width is calculated as you expect.
Formatted result becomes a single argument, and can be a subject of
other operation. In the next example, numbers are formatted, colored,
and gave to other format.
ansiecho -f '\N{ALARM CLOCK} %s' -c KF/544 -f ' %02d:%02d:%02d ' 1 2 3
Formatting is done by Perl C<sprintf> function. See
L<perlfunc/sprintf> for detail.
=head2 ANSI SEQUENCE
To get desired ANSI sequence, use B<-s> option. Next example produce
ANSI terminal sequence to indicate C<deeppink> color on C<lightyellow>
background.
ansiecho -n -s '<deeppink>/<lightyellow>'
You will get the next result for the 256-color terminal:
^[[38;5;198;48;5;230m
and the next for the full-color terminal:
^[[38;2;255;20;147;48;2;255;255;224m
Using B<-S> option, you can set multiple ANSI sequences at once in a
shell script. Next B<bash> code will initialize multiple variables
with the sequence for given color specs.
read ZE C1 C2 C3 < <( ansiecho -S ZE K/544 K/454 K/445 )
Or you can set array variable.
read -a color < <( ansiecho -S ZE K/544 K/454 K/445 )
Then use this variable like:
echo "${C1} COLOR 1 ${ZE}"
echo "${C2} COLOR 2 ${ZE}"
echo "${C3} COLOR 3 ${ZE}"
reset=${color[0]}
echo "${color[1]} COLOR 1 ${reset}"
echo "${color[2]} COLOR 2 ${reset}"
echo "${color[3]} COLOR 3 ${reset}"
=head1 COMMAND OPTIONS
=over 7
=item B<-n>
Do not print newline at the end.
=item B<-e>, B<-->[B<no->]B<escape>
Enable interpretation of backslash escapes in the normal string
argument. This option is enabled by default, unlike bash built-in
L<echo(1)> command. Use B<--no-escape> to disable it.
=item B<-j>, B<--join>
Do not print space between arguments. This is a short-cut for
C<--separate ''>.
=item B<--separate> I<string>
Set separator string between each arguments. Option B<-j> is a
short-cut for B<--separate ''>.
=item B<-->[B<no>]B<rgb24>
Produce 24bit full-color sequence for 12bit/24bit specified colors.
They are converted to 216 colors by default.
=item B<-h>, B<--help>
Print help.
=item B<-v>, B<--version>
Print version.
=back
=head1 PREFIX OPTIONS
=over 7
=item B<-s> I<spec>
Print raw ANSI sequence for given I<spec>.
=item B<-c> I<spec> I<string>
Print I<string> in a color given by I<spec>.
=item B<-f> I<format> I<args> ...
Print I<args> in a given I<format>. Backslash escape is always
interpreted in the format string.
The result of B<-f> sequence ends up to a single argument, and can be
a subject of other B<-c> or B<-f> option.
Number of arguments are calculated from the number of C<%> characters
in the format string except C<%%>. Variable width and precision
parameter C<*> can be used like C<%*s> or C<%*.*s>.
Format string also can be made by B<-f> option. Next command works,
but second one is better.
ansiecho -f -f '%%%ds' 16 hello
ansiecho -f '%*s' 16 hello
=item B<-S> I<spec>
If option C<-S> found, all following argument is considered as a color
spec given to B<-s> option, until option B<-E> found.
Next two commands are equivalent.
ansiecho -s ZE -s K/544 -s K/454 -s K/445
ansiecho -S ZE K/544 K/454 K/445
=item B<-C> I<spec>
Option B<-C> set permanent color which is applied to all following
arguments until option B<-E> found.
Next command prints only a word C<Yellow> in yellow, but second one
print C<Yellow>, C<Brick>, and C<Road> in yellow.
ansiecho Follow the -cYS Yellow Brick Road
ansiecho Follow the -CYS Yellow Brick Road
You may want to color the phrase instead.
ansiecho Follow the -cYS "Yellow Brick Road"
Option C<-C> can be used multiple times mixed with C<-F> option. See
below.
=item B<-F> I<format>
As with the C<-C> option, C<-F> defines a format which is applied to
all arguments until option B<-E> found. Format string have to include
single C<%s> placeholder.
ansiecho Follow the -CYS -F ' %s ' Yellow Brick Road
Option B<-C> and B<-F> can be used repeatedly, and they will take
effect in the reverse order of their appearance.
Next command show argument C<A> in underline/bold with blinking red
arrow.
ansiecho -cRF -f'->%s' -cUD A B C
Next one does the same thing for all arguments.
ansiecho -CRF -F'->%s' -CUD A B C
=item B<-E>
Terminate B<-C>, B<-F> and B<-S> effects.
=item B<-i> I<spec>
=item B<-a> I<spec>
Add raw ANSI sequence given by I<spec>. Option B<-i> insert the
sequence before the next argument, while B<-a> append to the final
argument.
Next two commands are equivalent.
ansiecho -c R Red
ansiecho -i R Red -a ZE
Color spec C<ZE> produces RESET and ERASE LINE sequence.
Because B<-i> and B<-a> does not produce RESET sequence, you can use
them to accumulate the effects.
ansiecho -i R R -i U RU -i I RUI -i S RUIS -i F RUISF -a Z
=back
=head1 STRING LITERAL
This is a backslash escape samples described in L<perlop/"Quote and
Quote-like Operators">. Non-alphabetical character after backslash is
always correspond to the character itself.
Sequence Description
\t tab (HT, TAB)
\n newline (NL)
\r return (CR)
\f form feed (FF)
\b backspace (BS)
\a alarm (bell) (BEL)
\e escape (ESC)
\x{263A} hex char (example: SMILEY)
\x1b restricted range hex char (example: ESC)
\N{name} named Unicode character or character sequence
\N{U+263D} Unicode character (example: FIRST QUARTER MOON)
\c[ control char (example: chr(27))
\o{23072} octal char (example: SMILEY)
\033 restricted range octal char (example: ESC)
=head1 COLOR SPEC
This is a brief summary. Read L<Getopt::EX::Colormap/COLOR SPEC> for
complete description.
Color specification is a combination of single uppercase character
representing 8 colors, and alternative (usually brighter) colors in
lowercase :
R r Red
G g Green
B b Blue
C c Cyan
M m Magenta
Y y Yellow
K k Black
W w White
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)
or color names enclosed by angle bracket :
<red> <blue> <green> <cyan> <magenta> <yellow>
<aliceblue> <honeydue> <hotpink> <mooccasin>
<medium_aqua_marine>
with other special effects :
N None
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)
X 9 Crossed out
E Erase Line
; No effect
/ Toggle foreground/background
^ Reset to foreground
~ Cancel following effect
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>
=head1 256/24BIT COLORS
12bit/24bit colors are converted to 216 colors because most terminal
can not display them. If you are using full-color terminal, such as
iTerm2 on Mac, use B<--rgb24> option or set C<GETOPTEX_RGB24>
environment variable to produce full-color sequence.
=head1 INSTALL
=head2 CPANMINUS
From CPAN archive:
$ cpanm App::ansiecho
or
$ curl -sL http://cpanmin.us | perl - App::ansiecho
From GIT repository:
=head1 SEE ALSO
L<perlop/"Quote and Quote-like Operators">
L<Getopt::EX::Colormap>
L<Graphics::ColorNames::X>
L<App::ansifold>, L<App::ansicolumn>
=head1 AUTHOR
Kazumasa Utashiro
=head1 LICENSE
Copyright 2021 Kazumasa Utashiro.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=cut
# LocalWords: perl ARGV utf ansiecho RGB printf sprintf deeppink
# LocalWords: lightyellow cpanm Kazumasa Utashiro perlfunc perlop
# LocalWords: Unicode Cyan cyan stringify CPANMINUS CPAN args ESC
# LocalWords: chr iTerm rgb GETOPTEX