diff --git a/doc/api.txt b/doc/api.txt new file mode 100644 index 00000000..652c865d --- /dev/null +++ b/doc/api.txt @@ -0,0 +1,103 @@ +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: + + : + +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 --- + diff --git a/doc/project.txt b/doc/project.txt index ccfd0d35..e12a4f50 100644 --- a/doc/project.txt +++ b/doc/project.txt @@ -40,6 +40,24 @@ Non-Goals - No features without a compelling use case. +Reports +------- +Anticipating all reporting needs is impossible, therefore custom reports are +required. Rather than copy the Taskwarrior design where flexibility is provided +via configurable options for fixed-format reports, Timewarrior will use a more +flexible approach of providing configuration and data via an extension API. +This will not limit the kind of reports or supported formats that can be added. + +Timewarrior will ship with several reports, which serve as example extensions +for users to modify and improve, perhaps contribute back to the project. + +Purely as an example of what might be implemented, here are some report mockups: + + ./report.week.txt + ./report.day.1.txt + ./report.exc.week.txt + + Tags ---- Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may @@ -130,3 +148,14 @@ data. command, instead of "stop" use "forgot" or directly "edit". Then I would like to express either "stopped 30min ago" or "it lasted only 1hour”. +- Need a JSON --> CSV converter, for spreadsheet folks. Therefore csv.py could + be an extension that converts the format. + +- Use display granularity/resolution to see more or less details. This would + combine nicely with a tag hierarchy. (Tomas Babej) + +- Need reports to help users doing fixed-rate work - finding the longest task + for example. + +- If an interval has more than one tag with a defined color, and is being + rendered, then use the first tag color. It doesn't really matter which. diff --git a/doc/reports.txt b/doc/reports.txt deleted file mode 100644 index af7c4453..00000000 --- a/doc/reports.txt +++ /dev/null @@ -1,96 +0,0 @@ -Reporting -========= -Anticipating all reporting needs is impossible, therefore custom reports are -required. Rather than copy the Taskwarrior design where flexibility is provided -via configurable options for fixed-format reports, Timewarrior will use a more -flexible approach of providing configuration and data via an API. This will not -limit the kind of reports or supported formats that can be added. - - -Requirements ------------- -Timewarrior will ship with several reports, which serve as example extensions -for users to modify and improve. - -Timewarrior will handle the command line options for reports, then pass off a -standardized set of parameters to the report extension. These parameters will -include: - -- Date range. Although Timewarrior might support "last month" as a reporting - range, the extensions themselves would be passed precise values, therefore - reducing the complexity of the extensions. - -- Data will be filtered by Timewarrior, so that extensions will not need to - reimplement this. - -- Reports will be sized according to need, not according to available terminal - width. If a report does not fit in a window, it is not an error. - -There will be a default report, which is configurable so that one of the reports -or commands can be the default. - - -Report Mockups --------------- -Purely as an example of what might be implemented, here are some report mockups: - - ./report.week.txt - ./report.day.1.txt - ./report.exc.week.txt - - TBD (calendar like "task calendar" with table below) - TBD (timeline, l-r) - TBD (table with subtotals) - - -Example Commands ----------------- -Here are some provisional examples of report commands: - - $ timew report day [monday] [± ...] - $ timew report week [± ...] - $ timew report month|quarter|year - - -Report API ----------- -The report API is simple - it invokes a program and feeds it input. All output -is generated by the program. When running this command: - - $ timew report x ... - -Timewarrior then runs this: - - $ ~/.timewarrior/extensions/x.* - -With standard input consisting of: - - filter: ... - name1: value1 - - [ - { ... }, - { ... }, - ... - ] - -That is, the input is line-oriented, with first a header block of name/value -pairs, then a blank line, then the JSON filtered data. The header block has all -configuration names flattened, i.e. no hierarchy. - - ---- Raw Notes --- - -- Need a JSON --> CSV converter, for spreadsheet folks. - -- Use display granularity/resolution to see more or less details. This would - combine nicely with a tag hierarchy. (Tomas Babej) - -- Need reports to help users doing fixed-rate work - finding the longest task - for example. - -- If an interval has more than one tag with a defined color, and is being - rendered, then use the first tag color. It doesn't really matter which. - -- Need a formal API description, for extension authors. -