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,
/usr/local/etc/acoc.conf and ~/.acoc.conf. They are sought and read
in that order. Obviously, at least one of them should exist on the
system.
A sample acoc.conf file is supplied with some sample matching rules.
The system configuration file is parsed before the user configuration
file. This allows the user to override the system configuration file
at will.
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. Alternatively,
the '@' symbol may be used, to allow '[' and ']' to retain their
usual semantics in program specs comprising a regular expression:
@program_spec@
'program_spec' is defined as one or more instances of the following
component, separated by a comma:
invocation[/flags]
where 'invocation' consists of the program's name (not including its
directory path component) plus any initial arguments.
Alternatively, 'invocation' may be a regular expression, which can be
used to match multiple programs and/or command-line arguments in
arbitrary order. Regular expressions are automatically anchored
to the beginning of the command line.
'flags', if present, is separated from 'invocation' 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.
p - allocate a pseudo-terminal in which to run the target program.
Some programs, such as ls(1), behave differently when their
stdout is not connected to a tty. Use of this option will fool
the target program into believing it is outputting to a tty,
rather than a pipe to acoc.
Use of this flag requires Masahiro Tomita's Ruby/TPty library to
be installed. Otherwise, the flag is silently ignored.
Note that the pseudo-terminal communication enabled by this flag
is one-way only, from the target program to acoc. It is thus not
possible to use acoc in combination with interactive programs,
such as the interactive Ruby interpreter (irb).
r - remove all previous rules for this program, regardless of
invocation. This is useful if you want to override the global
configuration file's settings for a given program in the user
configuration file.
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 rules that follow to the rpm(8) and
rpmbuild(8) commands, attempt to apply all matching rules, and also
apply those rules to the programs' stderr stream.
Another example:
[ls/p]
This says to allocate a pseudo-terminal to ls(1), fooling it into
believing that its output is being sent to a regular terminal instead
of a pipe to acoc.
With this flag, the effect will be this:
$ ls
file1 file2 file3 file4 file5 file6
Without it, ls will detect that its stdout is connected to a pipe and
behave accordingly:
$ ls
file1
file2
file3
file4
file5
file6
A third example:
[diff/t,rcsdiff/t,cvs diff/t,p4 diff/t]
This says that the rules that follow should be applied to all
invocations of diff(1) and rcsdiff(1), as well as those invocations
of cvs(1) and p4 that are followed by the argument 'diff'.
Additionally, colouring should be applied even when stdout is not
connected to a tty, so that the colours still show up when the output
is displayed in a pager such as more(1) or less(1).
Yet another example:
/ps -.*(e.*f|f.*e)/
In this example, the ps(1) command will be matched, as long as the
'e' and 'f' options are both passed in either order.
An alternative way to write the above spec is:
@ps -.*[ef].*[ef]@
There are two things to note in this alternative:
1. '@' has been used to delimit the spec, because '[' and ']' are
required for the character lists in the regular expression.
2. While this form is less specific (in that it allows matches
against duplicated command line options), it makes for
considerably shorter specs if one wishes to test for the inclusion
of a set of more than 2 or 3 command line flags. In the original
form, one must manually list all of the possible permutations,
which is equal to x! (factorial). For 3 command line flags, this
is 6 permutations; for 4, it is 24, etc.
Here's one more example:
[tcpdump/r]
If this were placed in ~/.acoc.conf, it would remove any matching
rules that had been installed for the tcpdump command by either
/etc/acoc.conf or /usr/local/etc/acoc.conf.
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.
An identical program invocation may be listed in more than one 'program_spec'. For example, you might wish to add all of gcc(1)'s matching rules to those used by rpmbuild(8) without having to list them twice. You would therefore first define a stanza that contained the matching rules that apply to both programs: [rpmbuild -b,gcc] ... and then later define a second stanza for 'rpmbuild -b' only, in which you would list only the rules that apply to that one program. Note, however, that a 'program_spec' that is a substring of another will not have its rules added to the longer spec. For example, the rules pertaining to a spec for 'rpmbuild -b' would not be added to those pertaining to a spec for 'rpmbuild -ba'.
A similar issue to the previous one is the question of what happens when a command line starts with, say, 'ps ax' and there are matching rules for both 'ps ax' and 'ps a', both of which match the command line when reading from left to right. In such cases, the longer (or more specific) match takes precedence.
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.
Python by Antti Haapala <antti@haapala.name>
Original Ruby implementation 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.