README.md

   1 Taskpirate
   2 ----------
   3
   4 Taskpirate is a pluggable system for TaskWarrior python hooks.
   5
   6 Why?
   7 ----
   8
   9 Simpler hooks:
  10
  11     def hook_example(task):
  12         task['description'] += "changed by a hook"
  13
  14 The above is fully working example, no more boilerplate needed.
  15
  16 Much faster execution time in case of multiple hooks (read the more details section).
  17
  18 Install
  19 -------
  20
  21 You'll need tasklib as a dependency:
  22
  23     pip install --user git+git://github.com/tbabej/tasklib@develop
  24
  25 Then you need to drop ```on-add-pirate``` and ```on-modify-pirate``` into ~/.task/hooks/.
  26
  27 After that, you can just clone any taskpirate-enabled hook as a subfolder into ~/.task/hooks/:
  28
  29     git clone https://github.com/tbabej/task.default-date-time ~/.task/hooks/default-date-time/
  30
  31 How to write a taskpirate hook
  32 ------------------------------
  33
  34 In your hook's repository, any file matching ```pirate_add*.py``` will be searched for hooks in on-add event. In the same sense, any file matching ```pirate_mod*.py``` will be searched for hooks in on-modify event.
  35
  36 Now, the pirate_add_example.py might look as follows:
  37
  38     def hook_example(task):
  39         task['description'] += "changed by a hook"
  40
  41 Any function in pirate_add_example that is called ```hook_*``` will be considered as a hook in on-add event. It will be passed the ```Task``` object corresponding to the current state of the task being added (as modified by the previous hooks).
  42
  43 More details
  44 ------------
  45
  46 TaskWarrior hooks are intended to be simple, but they involve writing some boilerplate code (parsing/formatting json). To allow users to write dead simple code, they can leverage tasklib.
  47
  48 Using tasklib simplifies things a lot, however, it's not a super-lightweight - usage of tasklib can slow down the hook by as much as 30-50ms (usual python hook can probably run in under 40ms), since it imports multiple libraries.
  49
  50 This becomes a problem when user has multiple tasklib-based hooks, since the import time adds up.
  51
  52 Also, note that taskpirate with arbitrary number of hooks will be most likely faster than 2-3 regular python hooks.
  53
  54 Example hooks
  55 -------------
  56
  57 You can look into my ```task.default-date-time``` or ```task.shift-recurrence``` hooks.