This design document is a work in progress, and subject to change. Once finalized, the feature will be scheduled for an upcoming release.
Taskwarrior currently supports DOM references that can access any stored data item. The general forms supported are:
[ <id> | <uuid> ] <attribute> [ <part> ]
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.
When defining a custom report, the columns shown are defined like this:
This syntax is:
<attribute> [ . <format> ]
format is specified, then
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:
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.
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
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
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
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:
The RC file (
~/.taskrc) will support DOM references in values.
This will form a late-bound reference, which is evaluated at runtime, every
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
list report changes, so does that of the
These notes list a series of anticipated changes to the codebase.
src/columns/Col*objects will implement type-specific and attribute-specific DOM support. DOM reference lookup will defer to the column objects first.
_setcommand to complement the
Configobject will recognize DOM references in values and perform lookup at read time. This will require circularity detection.
src/DOM.cppwill provide a memoized function to determine whether a DOM reference is valid.
src/DOM.cppwill provide a function to obtain a DOM reference value, with supporting metadata (type, writable).