Extensions

- Removed the redundant README file, which is now better presented in
  rfc5-hooks.txt.
- Modified all the sample Lua to be rfc5 compliant.

scripts/extensions/README

@@ -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
-
----
-

scripts/extensions/command.lua

@@ -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
+-- Returns:   1 --> command failed
---            0, nil     --> success
+--            0 --> success
-function execute ()
+function execute (command_line)
-  return 1, 'Not implemented'
+  task_footnote_message ('Not implemented')
+  return 1
 end
 

scripts/extensions/dom.lua

@@ -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

scripts/extensions/format.lua

@@ -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

scripts/extensions/program_hook.lua

@@ -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
+-- Returns:   0 --> success only
---            0, nil     --> success
 function goodbye ()
   print ('Goodbye.')
-  return 0, nil
 end
 

scripts/extensions/task_hook.lua

@@ -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
+-- Returns:   1 --> failure
---            0, nil     --> success
+--            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
 

scripts/extensions/uda.lua

@@ -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
+-- Arguments: None
--- Returns:   1 --> allowed
+-- Returns:   List of allowable values
---            0 --> disallowed
+function allowed ()
-function allowed (value)
+  return 'H', 'M', 'L', ''
-  if value == 'H' ||
-     value == 'M' ||
-     value == 'L' ||
-     value == '' then
-    return 1
-  end
-
-  return 0
 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