YAML¶

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.

Syntax¶

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!
root:
    - 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
dependencies:
    - 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
dependency:
    # 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

Reference¶

Main Level¶

root: Specifies the primary context

All other keys represent a context you pushed somewhere.

Contexts¶

A context is simply a list of rules

Rules¶

match

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.

Note

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).

Note

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\
  expression"

The above will result in the string a very long regularexpression

replace

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!

continue

Type: boolean

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

push

Type: string

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

pop

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.