mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
93 lines
2.7 KiB
Text
93 lines
2.7 KiB
Text
Reporting
|
||
=========
|
||
Anticipating all reporting needs is impossible, therefore custom reports are
|
||
required. Rather than copy the Taskwarrior design where a report is a
|
||
combination of a filter, sort, columns and labels, a more flexible approach
|
||
could encourage shared custom reports, and use a more complete API.
|
||
|
||
Іf all reports are extension scripts/programs, utilizing an API, then there is
|
||
no restriction on the kind of report generated, which would allow for HTML
|
||
reports, rather than simply supporting tabular text.
|
||
|
||
|
||
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
|
||
|
||
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] [±<tag> ...]
|
||
$ timew report week [±<tag> ...]
|
||
$ 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 ---
|
||
|
||
- The Taskwarrior hook script should use a set of attributes for time tracking
|
||
tags. Those will include: UUID, project, tags, description, and any chosen UDAs.
|
||
|
||
- 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)
|
||
|