view release on metacpan or  search on metacpan

script/ansiecho  view on Meta::CPAN

=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 commands produce
same output, but second one looks better.

    ansiecho -f -f '%%%ds' 16 hello

    ansiecho -f '%*s' 16 hello

=item B<-S> I<spec>

If option C<-S> found, all following arguments are considered as a
color spec given to B<-s> option, until option B<-E> is 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<Term::ANSIColor::Concise/COLOR SPEC> for
complete description.  Try next command to see 256 color table.

    perl -MTerm::ANSIColor::Concise::Table=:all -E colortable

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> <honeydew> <hotpink> <moccasin>
    <medium_aqua_marine>

with other special effects :

    N    None
    Z  0 Zero (reset)
    D  1 Double strike (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)
    H  8 Hide (concealed)
    X  9 Cross 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.  On some terminals which set the environment
variable C<COLORTERM> as C<truecolor> (e.g. iTerm), 24bit color mode
is automatically enabled.  Otherwise, 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

From GIT repository:

    cpanm https://github.com/kaz-utashiro/App-ansiecho.git

=head1 SEE ALSO

L<perlop/"Quote and Quote-like Operators">

L<Term::ANSIColor::Concise>

L<https://en.wikipedia.org/wiki/ANSI_escape_code>

L<Graphics::ColorNames::X>

L<https://en.wikipedia.org/wiki/X11_color_names>

L<App::ansifold>, L<App::ansicolumn>