gergely/taskwarrior-2.x
1
0
Fork 0
Code Issues Actions Packages Projects Releases 1 Wiki Activity

reformat to one sentence per line

Browse Source
This commit is contained in:
Dustin J. Mitchell
2022-04-21 01:15:17 +00:00
committed by Tomas Babej
parent ade706a72e
commit b1ca5d4cf8
17 changed files with 842 additions and 1052 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/rfcs/dom.md
View File

@@ -4,14 +4,14 @@ 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.
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:
Taskwarrior currently supports DOM references that can access any stored data item.
The general forms supported are:
[ <id> | <uuid> ] <attribute> [ <part> ]
@@ -23,8 +23,7 @@ Examples include:
123.annotations.0.entry.year
a87bc10f-931b-4558-a44a-e901a77db011.description
Additionally there are references for accessing configuration and system/program
level items.
Additionally there are references for accessing configuration and system/program level items.
rc.<name>
context.program
@@ -34,10 +33,8 @@ level items.
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.
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
@@ -50,12 +47,11 @@ 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.
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:
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
@@ -161,8 +157,7 @@ json
`"<attribute>":"<value>"`
There will also be a set of attribute-specific formats, similar to the currently
supported set:
There will also be a set of attribute-specific formats, similar to the currently supported set:
depends.list
depends.count
@@ -186,21 +181,19 @@ supported set:
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.
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`:
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:
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
@@ -209,8 +202,8 @@ combination of the two. Other examples may include:
## 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:
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
@@ -219,8 +212,7 @@ further and reference a component or format, it may be writable. For example:
## 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:
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
@@ -228,32 +220,30 @@ and this will also be available as a DOM format:
## 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.
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.
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.
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).
- 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).