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.