-
Notifications
You must be signed in to change notification settings - Fork 33
Concepts
This page summarises the principal concepts and design ideas of taskopen 2.0.
Originally, taskopen was created to extend the functionality of taskwarrior with respect to annotations. As taskwarrior lacks multi-line annotations, the idea was to attach a notes file to a task and make it accessible by taskopen instead.
As the feature set of taskopen grew, it became clear that taskopen has the potential for more sophisticated use cases. While the original taskopen was limited to act on task annotations, the concept of opening a task can be generalised to include arbitrary task attributes.
One of the main goals of taskopen 2.0 is not only to generalise functionality but also to clarify how taskopen operates on tasks. Its mechanisms and concepts must be easy-to-grasp in order to foster user customisation. Additionally, backwards compatibility should always be kept in mind.
In general, taskopen is configured with a set of filters, operations and actions. When executed, it passes the given filter to taskwarrior, and presents the user with a set of actions that it considers applicable to the returned tasks and their annotations.
Taskwarrior has a large feature set for filtering on a task-level basis for generating the reports (task list). However, as taskopen may offer multiple (and different) actions for individual task attributes and annotations, it must perform additional filtering.
In a first stage, the task filter is provided to taskopen on the command line and passed to taskwarrior to limit the set of considered tasks. In a second stage, taskopen checks what actions are applicable to these tasks (i.e. their attributes).
By default, taskopen operates on the task annotations. As a generalisation, other attributes can be processed and filtered to determine the applicable actions.
An annotation in taskwarrior is a single-line of arbitrary text with a timestamp. A task can have multiple of these annotations. For taskopen, the following format of annotations has been established:
label: arbitrary text (e.g. url, file path)
The label part is optional and used for further filtering (e.g. to distinguish different actions on the same annotation). Taskopen used the following perl regex for this:
(?:(\S+):\s+)?(.*)
The first match is called the label part whereas the second match is the file part. Taskopen 2.0 should allow filtering of both parts via regular expressions.
A task in taskwarrior has various attributes (e.g. project, tags, description). Taskwarrior even supports user-defined attributes (UDAs), which can for instance used to link to a issue id of a bug tracker. It therefore appears natural to use taskopen also for defining actions on UDAs. In contrast to annotation filtering, a single regular expression is sufficient.
An action defines what taskopen shall do with the filtered annotations/attributes. It is defined by four parameters: _target, filter, command and modes. The _target specifies for what task attribute the action is defined. The filter defines the regular expression(s) used for determining valid annotations/attributes. The command determines the command line that implements the actual action. The following placeholders for defining the command line exist:
-
$ANNOTATION: the undecoded (raw) annotation text -
$LABEL: the label part of the annotation text -
$FILE: the file part of the annotation text -
$UUID: the UUID of the task -
$ID: the running ID of the task -
$LAST_MATCH: the last sub-pattern of the regular expression used for filtering -
$TASK_*: any task attribute (e.g.$TASK_PROJECT) or UDA -
$ARGS: user-defined arguments specified on the taskopen command line
The modes of an action is a list of valid modes in which the action is applicable (see next section). Optionally (for extensibility), a filter command could be specified to implement additional filters such as file type checking. Furthermore, an inline command can be defined to execute a particular command for every actionable annotation and display its output interleaved with the list of actionable annotations.
The former version of taskopen already implemented multiple operation modes.
In normal mode, taskopen shows a list of actionable annotations and executes the first matching action for the annotation selected by the user.
In batch mode (taskopen -b), taskopen performs the first matching action on every actionable annotation.
Taskopen 2.0 introduces an additional any mode similar to normal mode that presents the user with all matching actions to choose from instead of only the first matching action.
Note, that earlier versions of taskopen also supported modes for editing annotations and deleting annotations that can be implemented by commands in taskopen 2.0.