Add tags matching to clock tables

Add tags matching to clock tables

Adam Elliott writes:

> I have attached a git patch against master that implements a new
> parameter to clock tables, "tags".  This parameter is a tags-query as a
> string and is used to filter the headlines which are consulted when
> building the clock table.
>
> In my search of the archives to see if this feature already existed, I
> found a reference here:
>  http://article.gmane.org/gmane.emacs.orgmode/17304
> suggesting it was difficult.  The patch is not so large, though, so
> perhaps I am missing something.
>
> My rationale in implementing this feature was to keep track of the
> occasional task item that is not billable, yet still makes sense to
> include in the overall project structure.  Of course I could just avoid
> clocking the task item, or manually delete clock lines before generating
> a report, but this feature reduces the chance for error; no doubt there
> are other workflows enabled with this feature as well.  I don't make
> significant use of tags myself, but I know many do.
>
> In order to maintain a sensible report, headlines that don't match the
> tag filter may be included if they have descendants that do.  Any time
> clocked directly on non-matching headlines, however, is excluded.
>
> Specifying even a simple filter noticeably slows down clock table
> generation for non-toy reports, particularly for clock table reports
> with :step.  If there is no filter, though, there is no degradation in
> performance.
>
> Tag filter syntax is the standard one, as described at:
>  http://orgmode.org/manual/Matching-tags-and-properties.html
> Only tags are considered at the moment, although I suspect querying
> against all properties would be possible (if even slower).
>
> Examples:
>
> * development
>  CLOCK: => 1:00
> *** task 1
>    CLOCK: => 1:00
> *** task 2                                              :must:
> ***** task 2a
>      CLOCK: => 1:00
> ***** task 2b                                           :mustnot:
>      CLOCK: => 1:00
>
> Note I am using an unconventional but legal(ish) clock format for
> brevity.  Clock tables are also pruned to only relevant lines.
>
> [1] #+BEGIN: clocktable
> |   | *Total time* | *4:00* |      |      |
> |---+--------------+--------+------+------|
> | 1 | development  | 4:00   |      |      |
> | 2 | task 1       |        | 1:00 |      |
> | 2 | task 2       |        | 2:00 |      |
> | 3 | task 2a      |        |      | 1:00 |
> | 3 | task 2b      |        |      | 1:00 |
>
> [2] #+BEGIN: clocktable :tags "must"
> |   | *Total time* | *2:00* |      |      |
> |---+--------------+--------+------+------|
> | 1 | development  | 2:00   |      |      |
> | 2 | task 2       |        | 2:00 |      |
> | 3 | task 2a      |        |      | 1:00 |
> | 3 | task 2b      |        |      | 1:00 |
>
> [3] #+BEGIN: clocktable :tags "-mustnot"
> |   | *Total time* | *3:00* |      |      |
> |---+--------------+--------+------+------|
> | 1 | development  | 3:00   |      |      |
> | 2 | task 1       |        | 1:00 |      |
> | 2 | task 2       |        | 1:00 |      |
> | 3 | task 2a      |        |      | 1:00 |
>
> [4] #+BEGIN: clocktable :tags "must-mustnot"
> |   | *Total time* | *1:00* |      |      |
> |---+--------------+--------+------+------|
> | 1 | development  | 1:00   |      |      |
> | 2 | task 2       |        | 1:00 |      |
> | 3 | task 2a      |        |      | 1:00 |
>
> [5] #+BEGIN: clocktable :tags "must+mustnot"
> |   | *Total time* | *1:00* |      |      |
> |---+--------------+--------+------+------|
> | 1 | development  | 1:00   |      |      |
> | 2 | task 2       |        | 1:00 |      |
> | 3 | task 2b      |        |      | 1:00 |
>
> As you can see, in examples 2, 4, and 5, the time clocked on
> "development" itself is being removed.  Example 2 illustrates the effect
> of tag inheritance.
>
> Adam