From: Tomas Babej Date: Sat, 17 Jan 2015 10:14:16 +0000 (+0100) Subject: Docs: Provide documentation for using tasklib in hooks scripts X-Git-Url: https://git.madduck.net/etc/taskwarrior.git/commitdiff_plain/9b4cc3df6a161710e26a08dab9e549292720f407?ds=inline;hp=--cc Docs: Provide documentation for using tasklib in hooks scripts --- 9b4cc3df6a161710e26a08dab9e549292720f407 diff --git a/docs/index.rst b/docs/index.rst index 44ef469..5c8b387 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -309,6 +309,44 @@ To pass your own configuration, you just need to update this dictionary:: >>> tw.config.update({'hooks': 'off'}) # tasklib will not trigger hooks +Creating hook scripts +--------------------- + +From version 2.4.0, TaskWarrior has support for hook scripts. Tasklib provides +some very useful helpers to write those. With tasklib, writing these becomes +a breeze:: + + #!/usr/bin/python + + from tasklib.task import Task + task = Task.from_input() + # ... + print task.export_data() + +For example, plugin which would assign the priority "H" to any task containing +three exclamation marks in the description, would go like this:: + + #!/usr/bin/python + + from tasklib.task import Task + task = Task.from_input() + + if "!!!" in task['description']: + task['priority'] = "H" + + print task.export_data() + +Tasklib can automatically detect whether it's running in the ``on-modify`` event, +which provides more input than ``on-add`` event and reads the data accordingly. + +This means the example above works both for ``on-add`` and ``on-modify`` events! + +Consenquently, you can create just one hook file for both ``on-add`` and +``on-modify`` events, and you just need to create a symlink for the other one. +This removes the need for maintaining two copies of the same code base and/or +boilerplate code. + + Working with UDAs -----------------