mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-07-07 20:06:36 +02:00
106 lines
3.2 KiB
Text
106 lines
3.2 KiB
Text
Extensions
|
|
----------
|
|
|
|
Extensions are Lua scripts that require installation and configuration, and when
|
|
invoked have access to taskwarrior internals through a Lua API.
|
|
|
|
There are several types of extension. Each type has different requirements, and
|
|
is called in different ways.
|
|
|
|
All extensions must be installed using the 'install' command, which means they
|
|
must implement the 'install' function, which returns a set of string values for:
|
|
|
|
- Type One of: program, task, uda, command, format, dom
|
|
- Name Single word name
|
|
- Version Version string
|
|
- Description One to two line description
|
|
- Author Author's name
|
|
- Contact Author's contact
|
|
- License Distribution License
|
|
- Copyright Copyright notice
|
|
|
|
All extensions, on installation, will be copied into ~/.task/extensions, and the
|
|
corresponding configuration entry will be created:
|
|
|
|
extension.<uuid>=<JSON description block>
|
|
|
|
|
|
Program Hooks
|
|
-------------
|
|
|
|
These are scripts that are triggered by program-level events. The supported
|
|
program hooks are:
|
|
|
|
on-launch As soon as is convenient after program launch
|
|
on-exit As late as possible while still providing API
|
|
on-file-read Immediately before reading a data file
|
|
on-file-write Immediately after writing a data file
|
|
on-synch Immediately before a synch operation
|
|
on-merge Immediately before a merge operation
|
|
on-gc Immediately before a GC operation
|
|
|
|
When a program hook script is invoked, there is no context, so no arguments are
|
|
passed to the script.
|
|
|
|
|
|
Task Hooks
|
|
----------
|
|
|
|
These scripts are triggered by task-specific events. The supported task hooks
|
|
are:
|
|
|
|
on-task-add Immediately prior to committing an added task
|
|
on-task-modify Immediately prior to committing a modified task
|
|
on-task-complete Immediately prior to committing a completed task
|
|
on-task-delete Immediately prior to committing a deleted task
|
|
|
|
When a task hook script is invoked, the context is a specific task, and so the
|
|
task uuid is passed as the only argument.
|
|
|
|
|
|
User Defined Attribute
|
|
----------------------
|
|
|
|
It is possible to create a user-defined attribute with a UDA extension. These
|
|
extensions must provide:
|
|
|
|
- Data type (string, date, duration, integer, real, custom)
|
|
- Custom types must implement a compare function for sorting
|
|
- Default format rendering
|
|
- Allowed value checking
|
|
- Urgency calculation term
|
|
|
|
|
|
Command
|
|
-------
|
|
|
|
It is possible to implement a command using an extension. These extensions must
|
|
provide:
|
|
|
|
- BNF command syntax
|
|
- Declaration as read-only or write command, which allows taskwarrior to
|
|
allow this command when the database is read-only
|
|
- Declaration of whether the command displays ID values, which instructs
|
|
taskwarrior to run a GC beforehand
|
|
|
|
|
|
Format
|
|
------
|
|
|
|
A format extension is one that provides custom rendering for an attribute.
|
|
These extensions must provide:
|
|
|
|
- Must implement a format function.
|
|
|
|
|
|
DOM
|
|
---
|
|
|
|
DOM extensions provide a DOM address and can be called to respond to that name.
|
|
These extensions must provide:
|
|
|
|
- DOM name
|
|
- Evaluation function
|
|
|
|
---
|
|
|