===================================================================
                  Generic Colouriser

Radovan Garabik  http://melkor.dnp.fmph.uniba.sk/~garabik/grc.html

===================================================================

Being overflooded with different logfile colo(u)?ri(s|z)ers, colortails,
gccolors, colormakes and similar programs for making  text files or outputs
of different programs more readable by inserting ansi colour control codes
into them, I decided to write  my very own colouriser, eventually providing
the functions of all those others.

Two programs are provided: grc and grcat.  The main is grcat, which acts as
a filter, i.e. taking standard input, colourising it and writing to
standard output.

grcat takes as a parameter the name of configuration file.

Directories  ~/.grc/, /usr/local/share/grc/, /usr/share/grc/ are searched
for the file (in this order). If the file is not found, it is assumed to be
an absolute path of a configuration file located elsewhere.

Configuration file consists of entries, one per regexp, entries are 
    separated with lines with first character non-alphanumeric (except #).
    Lines beginning with # or empty lines are ignored.

    Each entry consists of several lines.
    Each line has form:
        keyword=value
        where keyword is one of: regexp, colours, command, count
        Only regexp is mandatory, but it does not have much sense by itself
        unless you specify at least a colour or command keyword as well.

        regexp is the regular expression to match

        colours is the list of colours, separated by commas (you can specify only 
        one colour), each colour per one regexp group specified in regexp.

        command is command to be executed when regexp matches. Its output will
        be mixed with normal stdout, use redirectors ( >/dev/null) if you want
        to suppress it.

        count is one of words: once, more, or stop

            once means that if the regexp is matched, its first occurrence is coloured
            and the program will continue with other regexp's.

            more means that if there are multiple matches of the regexp in one line,
            all of them will be coloured.

            stop means that the regexp will be coloured and program will move to the
            next line (i.e. ignoring other regexp's) 

        example:

        # this is probably a pathname
        regexp=/[\w/\.]+
        colour=green
        count=more

        this will match /usr/bin, /usr/local/bin/, /etc/init.d/syslogd and similar
        strings and paint it with green.

    Regular expressions are evaluated from top to bottom, this allows nested
    and overlapped expressions. (e.g. you colour everything inside parentheses
    with one colour, and if a following expression matches the text inside 
    parentheses, it will be also coloured)

Typical usage:

grcat conf.log < /var/log/syslog
/usr/sbin/traceroute www.linux.org | grcat conf.traceroute
grcat conf.esperanto < Fundamento.txt  | less -r

To facilitate the use, command grc act as frontend for grcat, automatically 
choosing the configuration files.

    grc will execute command command with optional parameters piping its stdout
    into grcat.

    Configuration file for grcat is determined by /etc/grc.conf or 
    ~/.grc/grc.conf file.

    Format of /etc/grc.conf or ~/.grc/grc.conf: each entry consists of 2 lines,
        between entries there can be any number of empty lines or lines beginning
        with # (comments)

        First line is regular expression, second line the name of configuration
        file for grcat.

        Configuration file after the first regular expression matching the rest of
        line after grc will be passed to grcat as its configuration file

        For example, if you have 

        # log file
        \b\w+\b.*log\b
        conf.log

        # traceroute command
        (^|[/\w\.]+/)traceroute\s
        conf.traceroute

        in your /etc/grc.conf, then typing grc cat /var/log/syslog will use 
        conf.log to colourise the output,
        grc /usr/sbin/traceroute www.linux.org will use conf.traceroute
    
Miscellaneous remarks:
    Currently the program is in beta state. It works, but has its quirks and
    there are only a few examples of configuration files 
    available. (I am looking for configuration files... if you write one, send 
    it to me, if possible). 
    It is possible that the configuration file format will change in the 
    future.

    You should get yourself familiar with regular expressions. Good reading is 
    at http://www.python.org/doc/howto/regex/regex.html

    The program is not yet optimized for speed. There are places that can 
    give a big boost if optimized. This is planned for future versions.

    Regular expressions are handled by python, it means that they may be
    slightly different from those you know from perl or grep. It's not my 
    fault in that case.

    Colours are one of: 
        none, default, bold, underline, blink, reverse, concealed, 
        black, green, yellow, blue, magenta, cyan, white,
        on_black, on_green, on_yellow, on_blue, on_magenta, on_cyan, on_white
        beep
    on_red means that the background (instead of foreground) is painted 
    with red etc...
    there can be more attributes per line (separated by space), e.g.

    # this is probably a pathname
    regexp=/[\w/\.]+
    colours=bold blink green
    count=more

    will display pathnames in bold blinking green



Hint taken from logcoloriser README:

To have your syslog show on your tty12 in colour, do:
    mkfifo /dev/grc
    replace (or copy and edit) the /etc/syslog.conf line
    *.info;mail.*;authpriv.*;kern.*;local1.* |/dev/xconsole
    with :
    *.info;mail.*;authpriv.*;kern.*;local1.* |/dev/grc
    and add to your syslog startup script :
    grcat conf.log < /dev/grc >/dev/tty12 &

