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.

Іf all reports are extension scripts/programs, utilizing some form of 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 evolve.

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

There will be a default report, which is configurable so that one of the reports
can be hte 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 it 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.

---

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