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 example,
for PDF or 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
  ./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] [±<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 ---

- 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.