mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-06-26 10:54:28 +02:00
107 lines
3.5 KiB
Text
107 lines
3.5 KiB
Text
Extension API
|
||
=============
|
||
Several 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, the extension has no way to communicate back to Timewarrior.
|
||
Future rules will allow this.
|
||
|
||
|
||
Integration
|
||
-----------
|
||
Simply placing an executable script/program in the ~/.timewarrior/ext directory
|
||
is sufficient to configure and enable the extension. Alternately a symlink can
|
||
also be placed there. 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 provides all configuration and filtered data in JSON format to the
|
||
standard input of the extension. There are no command line arguments used, and
|
||
no environment changes. The extension must be a standalone executable entity,
|
||
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.
|
||
|
||
|
||
Input Format
|
||
------------
|
||
The input format looks like this:
|
||
|
||
name1: value1
|
||
name2: value2
|
||
...
|
||
|
||
[
|
||
{ ... },
|
||
{ ... },
|
||
...
|
||
]
|
||
|
||
Each line is terminated by the newline character U+000A. 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>
|
||
|
||
Between the <name> and <value> are the characters U+003A and U+0020.
|
||
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
|
||
temp.version: 0.1.0
|
||
|
||
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 used here 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. Any active interval is not necessarily the last element in the
|
||
array.
|
||
|
||
|
||
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 should tend toward 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 should tend toward 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 ---
|
||
|