Configuration Changes

There are a number of changes regarding the configuration of Watson. Two of the more significant ones is the ability to change the color of elements along with the format string used for reporting commands.

Coloring Elements

An element is specific piece of information that is shown in a reporting command. For example the log command shows the following:

$ watson log
Tuesday 12 December 2017 (30m)
    1e3235d  11:15 to 11:30       15m      Testing - Added unit tests
    4f06dc9  11:30 to 11:45       15m  Development  [cats] - Making a better kitty

This is the above output but with replaced with their element name:

$ watson log
{date} ({time})
    {short_id} {time} to {time}       {time} {project} - {message}
    {short_id} {time} to {time}       {time} {project} {tags} - {message}

The default color of time is a green text. If you wanted to change the element to cyan then the following configuration would be used

[style:time]
fg = cyan

The general rule for styling elements is

[style:element_name]
fg = color
bg = color
function = function_name

We will get to the function option later but for now lets talk about the section header. Each element's style is defined in its own section where the section name is style:element_name. In the earlier example the element name was time. The fg and bg options can contain valid color names. You can find a list of valid color codes further down this page.

Element List

This is a list of all valid element names along with their default values (if a fg= or bg= prefix is missing, then it is a function):

name	value	associated commands
{project}	fg=magenta
{tags}	_style_tags
{tag}	fg=blue
{time}	fg=green
{error}	fg=red
{date}	fg=cyan
{short_id}	_style_short_id
{id}	fg=white
{message}	fg=white

Function Configuration

Alongside being to change the color of elements, you can also change how some elements are rendered. For example, the tags element returns a format list of a frame's tags. This is done through a function _style_tags. Below is the default implementation of the function:

def _style_tags(tags):
  if not tags:
    return ''
  return '[{}]'.format(', '.join(
    style('tag', tag) for tag in tags
  ))

If you wanted to change the implemention to something like |tag, tag, tag| then you would use the function option that we saw earlier. User defined functions are loaded from a file called functions.py found in the watson app directory (On Linux, this is ~/.config/watson/).

Before we can use the functions defined in that file we have to enable the loading of it first. This is done in the [options] section of the Watson configuration. To enable it, add the following line:

[options]
load_functions_file = true

This tells to go ahead and load + execute the functions file at startup.

If we created the following definition in functions.py

def new_tag_style(tags):
  if not tags:
    return ''
  return '|{}|'.format(', '.join(
    style('tag', tag) for tag in tags
  ))

Then we could use the newly defined definition by adding (or changing) the tags style section to the following:

[style:tags]
function = new_tag_style

The function value must match the name a function defined in functions.py or a ```UsageError` will be thrown.

Format String Configuration

Another major change in the fork is the ability to change the format strings used in the reporting commands.

An example of a format string is as follows:

\t{id}  {start} to {stop}  {delta:>11}  {project}{tags} {message}

The above format string is the one used by log command for frame entries. Every name that is surrounded in curly braces should correspond to a valid value. A list of valid values for format strings can be found further below along with which format section they go with.

If we wanted to change the format string of a frame entry in the log command, we could do the following:

[log]
entry_format = \t{id} {project} {message}

This would change how the frame entries are rendered showing only the id, project, and frame message.

List of Format Strings

This is a list of format strings along with which command they go with and their default value.

Each default value uses all of the available keys.

section header	option name	default value
log	header_format	{date} ({daily_total})
log	entry_format	\t{id} {start} to {stop} {delta:>11} {project}{tags} {message}