The YAML style configuration is the preferred way to configure colorisations. It provides a strucured approach and supports different “contexts” (see below) which make it easier to organise rules.


As the name implies, this uses YAML as config syntax. Comparing to .ini and json files (both included in the Python stdlib), this syntax lends itself much better to the requirements of this application.

Basic structure

  • The config file is separated into sections (contexts). It has to have at least the root context.

  • Each context has a list of rules. These rules fire if a line contains a given regular expresssion. The first matching rule wins.

  • The line will then be replaced with the string contained in the replace value. You can use back-refs if you used capture groups in your regular expressions. Colours can be insterted using {color_name}. You should always insert a {reset} after using a color, to reset to the terminal default. Color names are provided by strec.themes.ansi.ANSI.

  • Rules may define that processing should not stop using the continue: yes flag. In that case, the same line will be matched with the following rule as well.

  • Additionally, rules may “push” another context onto the stack. If that’s the case, the rule will be processed, and all following lines will be matched against rules contained in the context named by the push value.

  • A non-root context, a rule may “pop” the current context from the stack using the pop: true action.

See Reference for more details.

Annotated Example

# the primary context. This section must exist!
    - match: '^(running)(.*)'
      # demonstrating replacements /and/ colorizing
      replace: '*** ${green}\1{reset}\2'

    - match: '^(writing)(.*)'
      replace: '>>> ${yellow}\1{reset}\2'

    - match: '^(reading)(.*)'
      replace: '<<< ${blue}\1{reset}\2'

    - match: '^(Processing dependencies for)(.*)'
      replace: '${green}\1{reset}\2'
      # switch to the "dependencies" context
      # Any subsequent input-lines will use the rules from the
      # "dependencies" context
      push: dependencies

    - match: '^(Installing.*)'
      replace: '>>> ${green}\1{reset}'

# the "dependencies" context
    - match: '^(Finished processing dependencies for)(.*)'
      replace: '${green}\1{reset}\2'
      # Revert back to the "root" context
      pop: true

    - match: '^(Searching for )(.*)$'
      replace: '\1${blue}\2{reset}'
      # switch to the "dependency" context
      push: dependency

# the "dependency" context
    # Let's prepend all lines with a small indent and pipe.
    # To do this, we specify a "match-all" regex, replace the line, and
    # specify that we will continue with the next matching rule using
    # "continue"
    - match: '(.*)'
      replace: ' | \1'
      continue: true

    # Note that after the above rule, all lines are prepended with
    # additional text. We need to include this in the regex!
    - match: '^ \| (Installing.*)'
      replace: ' | >>> ${green}\1{reset}'

    - match: '^ \| (Running.*)'
      replace: ' | ${green}\1{reset}'

    - match: '^ \| (Best match.*)'
      replace: ' | ${green}\1{reset}'

    - match: '^ \| (WARNING|warning)'
      replace: ' | ${yellow}\1{reset}'

    - match: '^ \| Installed(.*)'
      replace: ' | Installed\1\n'
      pop: true


Main Level


Specifies the primary context

All other keys represent a context you pushed somewhere.


A context is simply a list of rules



Type: string

A python regular expression. If this matches somewhere in the input line, all occurrences will be replaced with the string specified in replace.


While YAML does not enforce you to enclose strings in quotes, I is strongly recommend you use single quotes for regexps to avoid trouble with string escapes (backslashes).


For very long regexes, YAML makes it possible to split them into multiple lines. This time, a double-quote is required however to support adding a trailing backslash to lines. This trailing backslash joins the following line without adding a space! Example:

match: "a very long regular\

The above will result in the string a very long regularexpression


Type: string

If continue is false (the default), this string will be emitted to stdout. Otherwise, this string will be passed to the next matching rule. Note that the following rule sees the modified string!


Type: boolean

If true, don’t write the string yet to stdout. Instead, pass it on to the next matching rule.


Type: string

Pushes a new context onto the stack. All following lines from stdin will be matched against rules in the new context.


Type: boolean

If this is set to true, then return to the previous context after this rule has been processed. If in the root context, this is a no-op.