260 lines
5.4 KiB
Markdown
260 lines
5.4 KiB
Markdown
---
|
||
title: "Taskwarrior - Full DOM Support"
|
||
---
|
||
|
||
## Work in Progress
|
||
|
||
This design document is a work in progress, and subject to change. Once
|
||
finalized, the feature will be scheduled for an upcoming release.
|
||
|
||
|
||
# Full DOM Support
|
||
|
||
Taskwarrior currently supports DOM references that can access any stored data
|
||
item. The general forms supported are:
|
||
|
||
[ <id> | <uuid> ] <attribute> [ <part> ]
|
||
|
||
Examples include:
|
||
|
||
due
|
||
123.uuid
|
||
entry.month
|
||
123.annotations.0.entry.year
|
||
a87bc10f-931b-4558-a44a-e901a77db011.description
|
||
|
||
Additionally there are references for accessing configuration and system/program
|
||
level items.
|
||
|
||
rc.<name>
|
||
context.program
|
||
context.args
|
||
context.width
|
||
context.height
|
||
system.version
|
||
system.os
|
||
|
||
While this is adequate for data retrieval, we have the possibility of extending
|
||
it further to include data formats, higher-level constructs, and then to make
|
||
use of DOM references in more locations. This contributes to our goal of
|
||
simplifying Taskwarrior.
|
||
|
||
|
||
## Proposed Format Support
|
||
|
||
When defining a custom report, the columns shown are defined like this:
|
||
|
||
report.x.columns=uuid.short,description.oneline ...
|
||
|
||
This syntax is:
|
||
|
||
<attribute> [ . <format> ]
|
||
|
||
If no `format` is specified, then `default` is assumed. The src/columns/ColΧ\*
|
||
objects are responsible for supporting and rendering these formats. There is
|
||
currently no consistency among these formats based on data type.
|
||
|
||
By incorporating formats into DOM references, we eliminate the need for a
|
||
separate syntax for custom reports, and provide this:
|
||
|
||
123.due.iso
|
||
123.due.month.short
|
||
123.uuid.short
|
||
|
||
A standard set of formats per data type would be:
|
||
|
||
Type
|
||
|
||
Formats
|
||
|
||
Example
|
||
|
||
Numeric
|
||
|
||
default
|
||
|
||
`123 `
|
||
|
||
indicator
|
||
|
||
Based on `rc.<attribute>.indicator` which overrides `rc.numeric.indicator`.
|
||
|
||
json
|
||
|
||
`"<attribute>":"<value>"`
|
||
|
||
String
|
||
|
||
default
|
||
|
||
Buy milk
|
||
|
||
short
|
||
|
||
Feb
|
||
|
||
indicator
|
||
|
||
Based on `rc.<attribute>.indicator` which overrides `rc.string.indicator`.
|
||
|
||
json
|
||
|
||
`"<attribute>":"<value>"`
|
||
|
||
Date
|
||
|
||
default
|
||
|
||
Based on `rc.dateformat`
|
||
|
||
iso
|
||
|
||
2017-02-20T09:02:12
|
||
|
||
julian
|
||
|
||
2457805.12858
|
||
|
||
epoch
|
||
|
||
1234567890
|
||
|
||
age
|
||
|
||
2min
|
||
|
||
relative
|
||
|
||
-2min
|
||
|
||
remaining
|
||
|
||
0:02:04
|
||
|
||
countdown
|
||
|
||
0:02:04
|
||
|
||
indicator
|
||
|
||
Based on `rc.<attribute>.indicator` which overrides `rc.date.indicator`.
|
||
|
||
json
|
||
|
||
`"<attribute>":"<value>"`
|
||
|
||
Duration
|
||
|
||
default
|
||
|
||
1wk
|
||
|
||
iso
|
||
|
||
P1W
|
||
|
||
indicator
|
||
|
||
Based on `rc.<attribute>.indicator` which overrides `rc.duration.indicator`.
|
||
|
||
json
|
||
|
||
`"<attribute>":"<value>"`
|
||
|
||
There will also be a set of attribute-specific formats, similar to the currently
|
||
supported set:
|
||
|
||
depends.list
|
||
depends.count
|
||
description.combined
|
||
description.desc
|
||
description.oneline
|
||
description.truncated
|
||
description.count
|
||
description.truncated_count
|
||
parent.default|long
|
||
parent.short
|
||
project.full
|
||
project.parent
|
||
project.indented
|
||
status.default|long
|
||
status.short
|
||
tags.default|list
|
||
tags.count
|
||
urgency.default|real
|
||
urgency.integer
|
||
uuid.default|long
|
||
uuid.short
|
||
|
||
Custom report sort criteria will also use DOM references. This will be augmented
|
||
by the `+`/`-` sort direction and `/` break indicator, which are not part of the
|
||
DOM.
|
||
|
||
|
||
## High Level Construct Support
|
||
|
||
There need to be read-only DOM references that do not correspond directly to
|
||
stored attributes. Tasks have emergent properties represented by virtual tags,
|
||
which will be accessible, in this case returning a `0` or `1`:
|
||
|
||
123.tags.OVERDUE
|
||
|
||
Using `rc.due` and the `due` attribute, the `OVERDUE` virtual tag is a
|
||
combination of the two. Other examples may include:
|
||
|
||
task.syncneeded
|
||
task.pending.count
|
||
task.hooks.installed
|
||
|
||
|
||
## Writable References
|
||
|
||
When a DOM reference refers to an attribute or RC setting, and does not extend
|
||
further and reference a component or format, it may be writable. For example:
|
||
|
||
rc.hooks # writable
|
||
123.description # writable
|
||
123.entry.month # not writable, not an attribute
|
||
|
||
|
||
## Data Interchange
|
||
|
||
The export command can be used to show a filtered set of tasks in JSON format,
|
||
and this will also be available as a DOM format:
|
||
|
||
123.json
|
||
a87bc10f-931b-4558-a44a-e901a77db011.json
|
||
|
||
|
||
## RC File Support
|
||
|
||
The RC file (`~/.taskrc`) will support DOM references in values. This will form
|
||
a late-bound reference, which is evaluated at runtime, every time.
|
||
|
||
An example is to make two reports share the same description:
|
||
|
||
$ task config -- report.ls.description rc.report.list.description
|
||
|
||
This sets the description for the `ls` report to be a reference to the
|
||
description of the `list` report. This reference is not evaluated when the entry
|
||
is written, but is evaluated every time the value is read, thus providing
|
||
late-bound behavior. Then if the description of the `list` report changes, so
|
||
does that of the `ls` report automatically.
|
||
|
||
|
||
## Implementation Details
|
||
|
||
These notes list a series of anticipated changes to the codebase.
|
||
|
||
- The `src/columns/Col*` objects will implement type-specific and
|
||
attribute-specific DOM support. DOM reference lookup will defer to the
|
||
column objects first.
|
||
- Some DOM references will be writable, permitting a `_set` command to
|
||
complement the `_get` command.
|
||
- The `Config` object will recognize DOM references in values and perform
|
||
lookup at read time. This will require circularity detection.
|
||
- `src/DOM.cpp` will provide a memoized function to determine whether a DOM
|
||
reference is valid.
|
||
- `src/DOM.cpp` will provide a function to obtain a DOM reference value, with
|
||
supporting metadata (type, writable).
|