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

Extensions

Browse source 
- Removed the redundant README file, which is now better presented in
  rfc5-hooks.txt.
- Modified all the sample Lua to be rfc5 compliant.
This commit is contained in:
Paul Beckingham 2011-04-24 16:25:11 -04:00
parent 638fcd8ca0
commit 01df9e189e
7 changed files with 25 additions and 142 deletions
Download patch file Download diff file Expand all files Collapse all files

106
scripts/extensions/README
View file

@ -1,106 +0,0 @@
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
---

17
scripts/extensions/command.lua
View file

@ -7,7 +7,7 @@
function install ()
return 'command', -- Type
'random', -- Name
1.0, -- Version
'1.0', -- Version
'Displays a random pending task', -- Description
'Paul Beckingham', -- Author
'paul@beckingham.net', -- Contact
@ -26,20 +26,21 @@ end
-- Returns: 1 --> command does not modify data
-- 0 --> command modifies data
function read_only ()
return 1
return true
end
-- Arguments: None
-- Returns: 1 --> command displays task ID
-- 0 --> no ID dispalyed
-- 0 --> no ID displayed
function display_id ()
return 1
return true
end
-- Arguments: None
-- Returns: 1, 'error' --> command failed
-- 0, nil --> success
function execute ()
return 1, 'Not implemented'
-- Returns: 1 --> command failed
-- 0 --> success
function execute (command_line)
task_footnote_message ('Not implemented')
return 1
end

3
scripts/extensions/dom.lua
View file

@ -7,7 +7,7 @@
function install ()
return 'dom', -- Type
'system.load.average', -- Name
1.0, -- Version
'1.0', -- Version
'Provides access to system load', -- Description
'Paul Beckingham', -- Author
'paul@beckingham.net', -- Contact
@ -17,7 +17,6 @@ end
-- Arguments: The DOM reference to evaluate
-- Returns: The value from the DOM lookup
-- Note: 'name' may include '*' wildcards
function lookup (name)
return 1.23 -- Fake load average
end

2
scripts/extensions/format.lua
View file

@ -7,7 +7,7 @@
function install ()
return 'format', -- Type
'uuid.short', -- Name
1.0, -- Version
'1.0', -- Version
'Provides short formatted UUIDs', -- Description
'Paul Beckingham', -- Author
'paul@beckingham.net', -- Contact

6
scripts/extensions/program_hook.lua
View file

@ -7,7 +7,7 @@
function install ()
return 'program', -- Type
'goodbye', -- Name
1.0, -- Version
'1.0', -- Version
'Simply says goodbye', -- Description
'Paul Beckingham', -- Author
'paul@beckingham.net', -- Contact
@ -22,10 +22,8 @@ function hook ()
end
-- Arguments: None
-- Returns: 1, 'error' --> failure
-- 0, nil --> success
-- Returns: 0 --> success only
function goodbye ()
print ('Goodbye.')
return 0, nil
end

10
scripts/extensions/task_hook.lua
View file

@ -7,7 +7,7 @@
function install ()
return 'task', -- Type
'encourage', -- Name
1.0, -- Version
'1.0', -- Version
'Positive feedback', -- Description
'Paul Beckingham', -- Author
'paul@beckingham.net', -- Contact
@ -22,15 +22,15 @@ function hook ()
end
-- Arguments: None
-- Returns: 1, 'error' --> failure
-- 0, nil --> success
-- Returns: 1 --> failure
-- 0 --> success
function encourage ()
-- Only provide encouragement if the verbosity settings allow it.
verbosity = task_get ('rc.verbose')
if string.find (verbosity, 'encourage') ~= nil
then
print ('Good work.')
task_footnote_message ('Good work.')
end
return 0, nil
return 0
end

23
scripts/extensions/uda.lua
View file

@ -7,7 +7,7 @@
function install ()
return 'uda', -- Type
'priority', -- Name
1.0, -- Version
'1.0', -- Version
'Implements priority attribute', -- Description
'Paul Beckingham', -- Author
'paul@beckingham.net', -- Contact
@ -15,28 +15,19 @@ function install ()
'© 2011, Göteborg Bit Factory' -- Copyright
end
-- Arguments: None
-- Returns: Data type
function type ()
return 'custom'
end
-- Arguments: proposed value
-- Returns: 1 --> allowed
-- 0 --> disallowed
function allowed (value)
if value == 'H' ||
value == 'M' ||
value == 'L' ||
value == '' then
return 1
end
return 0
-- Arguments: None
-- Returns: List of allowable values
function allowed ()
return 'H', 'M', 'L', ''
end
-- Arguments: left and right values to compare
-- Arguments: Left and right values to compare
-- Returns: 1 --> left < right
-- 0 --> left >= right
function compare (left, right)
@ -63,7 +54,7 @@ end
-- Returns: Urgency Term
-- Note: Should reference rc.urgency.<field>.coefficient
function urgency (value)
coefficient = task_get ('urgency.<field>.coefficient')
coefficient = task_get ('urgency.priority.coefficient')
-- TODO Urgency calculation here