mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
103 lines
3.3 KiB
Text
103 lines
3.3 KiB
Text
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 ---
|
||
|