=encoding UTF-8

=head1 NAME

colout - Color Up Arbitrary Command Output

=head1 SYNOPSIS

    colout [-h] [-r RESOURCE]

    colout [-g] [-c] [-l] [-a] [-t] [-T] [-P] [-s] PATTERN [COLOR(S) [STYLE(S)]]

=head1 DESCRIPTION

C<colout> read lines of text stream on the standard input and output characters
matching a given regular expression C<PATTERN> in given C<COLOR> and C<STYLE>.

If groups are specified in the regular expression pattern, only them are taken
into account, else the whole matching pattern is colored.

You can specify several colors or styles when using groups by separating them
with commas. If you indicate more colors than groups, the last ones will be ignored.
If you ask for fewer colors, the last one will be duplicated across remaining
groups.

Available colors are: I<blue>, I<black>, I<yellow>, I<cyan>, I<green>, I<magenta>, I<white>, I<red>,
I<rainbow>, I<random>, I<Random>, I<scale>, I<none>, an RGB hexadecimal triplet or any number
between 0 and 255.

Available styles are: I<normal>, I<bold>, I<faint>, I<italic>, I<underline>, I<blink>,
I<rapid_blink>, I<reverse>, I<conceal> or I<random> (some styles may have no effect, depending
on your terminal).

I<rainbow> will cycle over a 8 colors rainbow at each matching pattern.
I<Rainbow> will do the same over 24 colors (this requires a terminal that supports
the 256 color escape sequences).

I<Random> will color each matching pattern with a random color among the 255
available in the ANSI table. I<random> will do the same in 8 colors mode.

I<scale> (8 colors) and I<Scale> (36 colors) will parse the numbers characters in
the matching text as a decimal number and apply the rainbow colormap according
to its position on the scale defined by the C<-l> option (see below, I<0,100> by
default).

Before interpreting the matched string as a number, colout will remove any
character not supposed to be used to write down numbers. This permits to apply
this special color on a large group, while interpreting only its numerical part.

If the python-pygments library is installed, you can use the name of a
syntax-coloring "lexer" as a color (for example: I<Cpp>, I<ruby>, I<xml+django>, etc.).

If GIMP palettes files (F<*.gpl>) are available, you can also use their names as a
colormap (see the C<-P> switch below).

Note that the RGB colors (either the hex triplets or the palettes's colors) will
be converted to their nearest ANSI 256 color mode equivalents.

When not specified, a C<COLOR> defaults to I<red> and a C<STYLE> defaults to I<bold>.

C<colout> comes with some predefined themes to rapidly color well-known outputs
(see the C<-t> switch below).

If the python-pygments library is available, C<colout> can be used as an interface
to it (see also the C<-s> switch below).

To have a list of all colors, styles, special colormaps, themes, palettes and lexers,
use the C<-r> switch (see below).

C<colout> is released under the GNU Public License v3.

=head1 OPTIONS

=over

=item * C<-h>, C<--help>:

Show a help message and exit

=item * C<-g>, C<--groups>:

For color maps (like I<rainbow>), iterate over matching groups in the pattern instead of over patterns.

=item * C<-c>, C<--colormap>:

Use the given list of comma-separated colors as a colormap (cycle the colors at each match).

=item * C<-l min,max>, C<--scale min,max>:

When using the I<scale> colormap, parse matches as decimal numbers (taking your locale into account)
and apply the rainbow colormap linearly between the given min,max (I<0,100> by default).

=item * C<-a>, C<--all>:

Color the whole input at once instead of line per line
(really useful for coloring a source code file with strings on multiple lines).

=item * C<-t>, C<--theme>:

Interpret C<PATTERN> as a predefined theme (I<perm>, I<cmake>, I<g++>, etc.).

=item * C<-T DIR>, C<--themes-dir DIR>:

Search for additional themes (F<colout_*.py> files) in this directory.

=item * C<-P DIR>, C<--palettes-dir DIR>:

Search for additional palettes (F<*.gpl> files) in this directory.

=item * C<-r TYPE(S)>, C<--resources TYPE(S)>:

Print the names of available resources. Use a comma-separated list of resources names
(styles, colors, special, themes, palettes, colormaps or lexers),
use I<all> to print everything.

=item * C<-s>, C<--source>:

Interpret C<PATTERN> as source code readable by the Pygments library. If the first letter of C<PATTERN>
is upper case, use the 256 color mode, if it is lower case, use the 8 colors mode.
In 256 color mode, interpret C<COLOR> as a Pygments style (e.g. I<default>).

=item * C<--debug>:

Debug mode: print what's going on internally, if you want to check what features are available.

=back

=head1 REGULAR EXPRESSIONS

A regular expression (or regex) is a pattern that describes a set of strings
that matches it.

C<colout> understands regex as specified in the C<re> python module. Given that
C<colout> is generally called by the command line, you may have to escape
special characters that would be recognize by your shell.

=head1 LIMITATIONS

Don't use nested groups or colout will duplicate the corresponding input text with each matching colors.

=head1 EXAMPLES

=head2 Simple

=over

=item * Color in bold red every occurrence of the word C<color> in colout sources:

    cat colout.py | colout color red bold

=item * Color in bold violet home directories in F</etc/passwd>:

    colout '/home/[a-z]+' 135 < /etc/passwd

=item * Color in yellow user/groups id, in bold green name and in bold red home directories in F</etc/passwd>:

    colout ':x:([0-9]+:[0-9]+):([^:]+).*(/home/[a-z]+)' yellow,green,red normal,bold < /etc/passwd

=item * Color in yellow file permissions with read rights for everyone:

    ls -l | colout '.(r.-){3}' yellow normal

=item * Color in green read permission, in bold red write and execution ones:

    ls -l | colout '(r)(w*)(x*)' green,red normal,bold

=item * Color in green comments in colout sources:

    colout '.*(#.*)$' green normal < colout.py

=item * Color in bold green every numbers and in bold red the words C<error> in make output:

    make 2>&1 | colout '[0-9]+' green normal | colout error

=back

=head2 Somewhat useful

=over

=item * Use a different color for each line of the auth log

    grep user /var/log/auth.log | colout "^.*$" rainbow

=item * Color each line of a file with a different color among a 256 color gradient from cyan to green:

    head /var/log/auth.log | colout -c "^.*$" 39,38,37,36,35,34

=item * Color permissions with a predefined template:

    ls -l | colout -t perm

=item * Color in light green comments in non-empty colout sources, with the sharp in bold green:

    grep -v '^\s*$' colout.py | colout '.*(#)(.*)$' green,119 bold,normal

=item * Color a make output, line numbers in yellow, errors in bold red, warning in magenta, pragma in green and C++ file base names in cyan:

    make 2>&1 | colout ':([0-9]+):[0-9]*' yellow normal | colout error | colout warning magenta | colout pragma green normal | colout '/(\w+)*\.(h|cpp)' cyan normal

Or using themes:

    make 2>&1 | colout -t cmake | colout -t g++

=item * Color each word in the head of auth.log with a rainbow color map, starting a new colormap at each new line (the
beginning of the command is just bash magic to repeat the string C<(\\w+)\\W+>:

    L=$(seq 10) ; P=${L//??/(\\w+)\\W+} ; head /var/log/auth.log | colout -g "^${P}(.*)$" rainbow

=item * Color source code in 8 colors mode, without seeing comments:

    cat colout.py | grep -v "#" | colout -s python

=item * Color source code in 256 color mode:

    cat colout.py | colout -s Python monokai

=item * Color a JSON stream:

    echo '{"foo": "lorem", "bar":"ipsum"}' | python -mjson.tool | colout -t json

=item * Color a source code substring:

    echo "There is an error in 'static void Functor::operator()( EOT& indiv ) { return indiv; }' you should fix it" | colout "'(.*)'" Cpp monokai

=item * Color the percent of progress part of a CMake's makefile output, with a color
related to the value of the progress (from C<0%=blue> to C<100%=red>):

    cmake .. && make | colout "^(\[\s*[0-9]+%\])" Scale

=back

=head2 Bash alias

The following bash function color the output of any command with the
I<cmake> and I<g77> themes:

    function cm()
    {
        set -o pipefail
        $@ 2>&1  | colout -t cmake | colout -t g++
    }

You then can use the C<cm> alias as a prefix to your build command,
for example: C<cm make test>