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