GothenburgBitFactory/taskwarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskwarrior.git synced 2025-07-07 20:06:36 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

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

117
docs/rfcs/rules.md
View file

@ -4,16 +4,14 @@ title: "Taskwarrior - Rule System"
## 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.
# Rule System
The rule system is a framework that supports highly configurable features, with
runtime evaluation, DOM access and an internal API. Implementing a rule system
meets the goal of shrinking and stabilizing the product core, while adding new
features, and enabling many more.
The rule system is a framework that supports highly configurable features, with runtime evaluation, DOM access and an internal API.
Implementing a rule system meets the goal of shrinking and stabilizing the product core, while adding new features, and enabling many more.
## Required Enhancements
@ -60,16 +58,14 @@ To prepare for a Rules System, various subsystems must first be enhanced:
- The RC file will support environment variable expansion, where `${NAME}`
will be replaced by its corresponding value at launch time
At that point, the rules system can be implemented in `libshared`, and will use
a pluggable architecture to allow its integration into several projects.
At that point, the rules system can be implemented in `libshared`, and will use a pluggable architecture to allow its integration into several projects.
## DOM Enhancements
DOM references will be enhanced, with many more references supported. All DOM
references will begin with `dom.`, yielding unambiguous references. References
will have a type. Types will support sub-references (`<date>.<month>`,
`<tags>.<N>`, `<annotation>.<description>`), and display formats included.
DOM references will be enhanced, with many more references supported.
All DOM references will begin with `dom.`, yielding unambiguous references.
References will have a type.
Types will support sub-references (`<date>.<month>`, `<tags>.<N>`, `<annotation>.<description>`), and display formats included.
dom . [<id> .] <attribute> [. <sub-reference>] . <format>
@ -79,18 +75,15 @@ will have a type. Types will support sub-references (`<date>.<month>`,
dom . 123 . tags . count
dom . 123 . tags . 1
In addition to direct attribute access, DOM references will also support tw
references beyond the current set:
In addition to direct attribute access, DOM references will also support tw references beyond the current set: dom.rc.<name>
dom.rc.<name>
dom.cli.args
dom.terminal.width
dom.terminal.height
dom.system.version
dom.system.oѕ
And will also support higher-level constructs that do not directly correlate to
attributes, for example:
And will also support higher-level constructs that do not directly correlate to attributes, for example:
dom.active Boolean indicator of any active tasks
dom.synced Boolean indicator of the need to sync
@ -115,47 +108,49 @@ The current configuration system supports only two different forms of syntax:
include <file>
A rule is a new form of syntax that consists of the rule keyword, a name,
optional trigger, followed by indented actions in the form of API calls and flow
control. For example:
A rule is a new form of syntax that consists of the rule keyword, a name, optional trigger, followed by indented actions in the form of API calls and flow control.
For example:
rule myRule() on_launch:
# Some code here
A rule definition will appear in the RC file, alongside all the existing
settings. The rule syntax will require a blank line to terminate the rule
definition, the result being that the RC file should be quite readable, although
it will look like Python.
A rule definition will appear in the RC file, alongside all the existing settings.
The rule syntax will require a blank line to terminate the rule definition, the result being that the RC file should be quite readable, although it will look like Python.
## Hook Scripts
While this functionality can also be implemented using hook scripts, rules will
run in-process, and therefore do not require external interpreters to be
launched every time. This creates the potential to run faster than a hook
script.
While this functionality can also be implemented using hook scripts, rules will run in-process, and therefore do not require external interpreters to be launched every time.
This creates the potential to run faster than a hook script.
For complex processing, hook scripts will be the preferred mechanism, but as the
rules system matures, rules will be made to run more quickly. With adequate
performance, a rule will be the preferred implementation over a hook script.
For complex processing, hook scripts will be the preferred mechanism, but as the rules system matures, rules will be made to run more quickly.
With adequate performance, a rule will be the preferred implementation over a hook script.
This is not expected to be the case at first.
Hook scripts are not likely to be extended beyond their current form, and with
greater DOM access and a growing API, rules should be able to supplant most hook
script use cases.
Hook scripts are not likely to be extended beyond their current form, and with greater DOM access and a growing API, rules should be able to supplant most hook script use cases.
## Rule Triggers
The set of supported rule types will include:
* `on_launch` - Triggered on program launch.
* `on_add` - Triggered when a task is added. A context task will be provided. The rule can modify the task, and approve or reject it.
* `on_modify` - Triggered when a task is modified. A before and after context task will be provided. The rule can modify the task, and approve or reject it.
* `on_exit` - Triggered on program exit.
* `color` - Triggered when colors are being determined.
* `virtual tag` - Defines a new virtual tag.
* `format` - Triggered when an attribute needs formatting, defines are new format.
* `on_launch` - Triggered on program launch.
* `on_add` - Triggered when a task is added.
A context task will be provided.
The rule can modify the task, and approve or reject it.
* `on_modify` - Triggered when a task is modified.
A before and after context task will be provided.
The rule can modify the task, and approve or reject it.
* `on_exit` - Triggered on program exit.
* `color` - Triggered when colors are being determined.
* `virtual tag` - Defines a new virtual tag.
* `format` - Triggered when an attribute needs formatting, defines are new format.
More rules types will be added for more capabilities in future releases.
@ -164,24 +159,38 @@ More rules types will be added for more capabilities in future releases.
The API is a simple set of actions that may be taken by a rule.
* `debug(<string>)` - Displays the string in debug mode only and continues processing.
* `warn(<string>)` - Displays the string as a warning continues processing.
* `error(<string>)` - Displays the string as an error and terminates processing.
* `exec(<binary> [ <args> ... ])` - Executes the external program and passes arguments to it. If the program exits with non-zero status, it is treated as an error.
* `return <value>` - Provides a result value for the rule, when necessary.
* `debug(<string>)` - Displays the string in debug mode only and continues processing.
This is a very limited set at first, and more API calls will be added to support
capabilities in future releases.
* `warn(<string>)` - Displays the string as a warning continues processing.
* `error(<string>)` - Displays the string as an error and terminates processing.
* `exec(<binary> [ <args> ... ])` - Executes the external program and passes arguments to it.
If the program exits with non-zero status, it is treated as an error.
* `return <value>` - Provides a result value for the rule, when necessary.
This is a very limited set at first, and more API calls will be added to support capabilities in future releases.
## Grammar
The grammar closely tracks that of Python. Blocks are indented consistently.
The grammar closely tracks that of Python.
Blocks are indented consistently.
* `if <condition>: ... else: ... ` - The condition is a full Algebraic expression, and supports none of the command line conveniences. Terms must be combined with logical operators. The condition is an expression that is evaluated and converted to a Boolean value.
* `for <name> in <collection>: ` - There is no native type for a collection, but there are DOM references (`tags` \...) that reference collections. This provides a way to iterate.
* `set <name> = <expression> ` - Writes to a named type. The name may be a writable DOM object (`dom...`) or temporary variable storage (`tmp...`). Writing to a read-only DOM reference is an error.
* `<function>([<args>]) ` - A function is either a rule or an API call. Calling an undefined function is an error.
* `if <condition>: ... else: ...` - The condition is a full Algebraic expression, and supports none of the command line conveniences.
Terms must be combined with logical operators.
The condition is an expression that is evaluated and converted to a Boolean value.
* `for <name> in <collection>:` - There is no native type for a collection, but there are DOM references (`tags` \...) that reference collections.
This provides a way to iterate.
* `set <name> = <expression>` - Writes to a named type.
The name may be a writable DOM object (`dom...`) or temporary variable storage (`tmp...`).
Writing to a read-only DOM reference is an error.
* `<function>([<args>])` - A function is either a rule or an API call.
Calling an undefined function is an error.
## Examples