Extension API
=============
Timewarrior reports are written as extensions, which uses an API to provide
filtered data and configuration to the external command. This is a one-way
process, and the extension has no way to communicate back to Timewarrior.
However, future rules features will allow this.


Integration
-----------
Simply placing an executable script/program in the ~/.timewarrior/ext directory
is sufficient to configure nad enable the extension. The name of the program is
leftmost matched, so that this extension:

  ~/.timewarrior/ext/my_report.py

Can be run using all of the following commands, depending on the uniqueness of
the name:

  $ timew report my_report.py
  $ timew report my_report
  $ timew report my_r
  $ timew my_report.py
  $ timew my_report
  $ timew my_r


APІ Mechanism
-------------
Timewarrior will provide all configuration and filtered data in JSON format to
the standard input of the extension program. There are no command line arguments
used, and no environment changes. The extension must be a standalone executable
entiry, as Timewarrior will fork/exec and not invoke a shell.

All standard output generated by the extension is captured and presented
verbatim by Timewarrior. There may be additional text prepended or appended to
this.


Input Format
------------
The input format looks like this:

  name1: value1
  name2: value2
  version: 0.1.0
  ...

  [
  { ... },
  { ... },
  ...
  ]

Specifically, there is an initial block of name/value pairs, which is a copy of
the complete current configuration data.  It has the form:

  <name>: <value>

This configuration block includes the Timewarrior version, so that multiple
releases maybe supported by the extension. Additionally, other data is included
with the 'temp.' prefix, indicating that it is not part of the configuration
data, but may be of use to the extension.  For example:

  temp.db: /home/user/.timewarrior
  temp.report.end: 20160401T000000Z
  temp.report.start: 20160430T235959Z
  temp.report.tags: "This is a multi-word tag",ProjectA,tag123

After the configuration block, there is a single blank line to separate it from
the JSON data.

The JSON data is a single JSON array, containing zero or more Interval objects
that look like this (line breaks for clarity):

  {"start":"20160405T162205Z",\
   "end":"20160405T162211Z",\
   "tags":["This is a multi-word tag","ProjectA","tag123"]},

Here the presence of the "end" data means this interval is closed, i.e. not
actively being tracked. There is one JSON object per line. The timestamps are
ISO format UTC.


Guidelines
----------
A well-behaved extension is one that follows these guidelines, and conforms to
the general pattern of behavior exhibited by Timewarrior. The guidelines are:

- Obey the 'verbose' setting, and if the value is neither on/1/yes/y/true, then
  consider it 'off', and generate minimal output, which may be no output at all.

- Obey the 'debug' setting, and if the value is either one/1/yes/y/true, then
  emit helpful feedback, but only that which can be useful for debugging a
  problem, which may be no output at all.

- Obey the 'confirmation' setting, and if the value is either one/1/yes/y/true,
  then obtain user permission interactively before proceeding with any data
  modification. Do not rely on, or implement a 'force'-like feature.


--- Raw Notes ---