acoc.conf - configuration file for acoc(1)
/etc/acoc.conf
acoc is a regular expression based colour formatter for programs that
display output on the command-line. It works as a wrapper around the
target program, executing it and capturing the stdout stream.
Optionally, stderr can be redirected to stdout, so that it, too, can
be manipulated.
acoc then applies matching rules to patterns in the output and
applies colour sets to those matches.
The configuration files used by the program are /etc/acoc.conf
and/or ~/acoc.conf. The former file is supplied with some sample
matching rules.
Blank lines and those that begin with a '#' are ignored.
A program configuration stanza is introduced as follows:
[program_spec]
(The square brackets are mandatory literal characters.)
where 'program_spec' is defined as one or more instances of the
following component, separated by a comma:
name[/flags]
where 'name' is the program's name (not including its directory) and
'flags', if present, is separated from the 'name' by a slash and
consists of one or more of the following characters:
a - continue to attempt to find matching patterns after the first
match has been found. By default, acoc will stop processing a
line and display it after the first match has been found.
e - redirect the target program's stderr to stdout, allowing it, too,
to be matched by rules
t - apply colour formatting even if stdout is not a tty. By default,
formatting is not applied if the output stream is not attached to
a terminal.
Here's an example of a line that introduces a configuration stanza:
[rpm/ae,rpmbuild/ae]
which says to apply the following rules to the rpm and rpmbuild
commands, attempt to apply all matching rules, and also apply those
rules to the programs' stderr stream.
After defining the program name and operational flags, matching rules
can be defined. These take the following form:
/regex/[flags] colour_spec
where 'regex' is a Ruby-compatible regular expression. The delimiting
'/' characters can be any character, as long as that character is not
present in the regular expression itself.
'flags', if present, consists of one or more characters from the
following list:
g - find every match on the line, not just the first. When using this
flag, 'regex' should not include parentheses.
'colour_spec' is defined as a comma-separated list of one or more
'colour_groups', which are defined as a plus-separated (+) list of
one or more of the following:
black
blink
blue
bold
clear
concealed
cyan
dark
green
italic
magenta
negative
on_black
on_blue
on_cyan
on_green
on_magenta
on_red
on_white
on_yellow
rapid_blink
red
reset
strikethrough
underline
underscore
white
yellow
Examples of a 'colour_group' are 'white+bold', 'black+on_white', etc.
A complete 'colour_spec' might look like this:
red+bold,white,yellow+bold,black+on_green
Except when using the 'g' flag, each component of the 'regex' that
you wish to colour should be placed in parentheses. Text outside
parentheses will be used for matching, but will not be coloured.
For example, examine the following:
/^(\d+)foo\s*(\w+)/
This will match a line that starts with more or one digits, followed
by the string 'foo' and any amount of white space, followed by one or
more 'word' characters. However, only the initial group of digits and
the group of word characters will be coloured. The string 'foo' and
the white space that follows it will be used for matching, but will
not be coloured.
Separated from the 'regex' by white space is the 'colour_spec'.
Usually, you will include in this as many colours (separated by
commas) as you have parenthesised expressions in the 'regex'.
However, it's also permissible to have fewer. If, for example, you
have three parenthesised expressions in the 'regex', but only two
colours listed in the 'colour_spec', then the second colour will be
used for colouring both the second and third matches.
If you have more colours listed in the 'colour_spec' than there are
parenthesised expressions in the 'regex', the surplus colours are
ignored.
When using the 'g' flag to perform a global match on the line, you
may list as many colours as you want. The same rules apply here. If
there are more matches than colours, the remaining matches will be
coloured using the last colour listed. Surplus colours are ignored.
A program may be listed in more than one 'program_spec'. For example, you might wish to add all of gcc's matching rules to those used by rpmbuild without having to list them twice. You would therefore first define a stanza that contained the matching rules that apply to both programs: [rpmbuild,gcc] ... and then later define a second stanza for rpmbuild only, in which you would list only the rules that apply to that one program. With the current implementation, any program flags should be specified in the last 'program_spec' that relates to the program in question.
A 'program_spec' may be defined with the name 'default'. If this is done, the rules in this stanza will be used to match the output of any program that doesn not have its own specific 'program_spec'.
Nesting parenthesised regular expression components is possible, but
will have unexpected results if the inner match creates a
backreference.
As an example, the following 'regex' could be used to superficially
match an IP address:
((\d?\d?\d\.){3}\d?\d?\d)/
but the second '(' starts a new backreference. Use this instead:
((?:\d?\d?\d\.){3}\d?\d?\d)/
The (?:pattern) construct clusters, but does not capture, so no
backreference will be made.
Another way of saying this is to say that nested subexpressions can
be used for matching, but cannot be coloured.
Written by Ian Macdonald <ian@caliban.org>
acoc is only as good as the configuration file that it uses. If you compose pattern-matching rules that you think would be useful to other people, please send them to me for inclusion in a subsequent release.