From: Tomas Babej <tomasbabej@gmail.com>
Date: Tue, 7 Apr 2015 17:42:12 +0000 (+0200)
Subject: Add readme instructions
X-Git-Url: https://git.madduck.net/etc/taskwarrior.git/commitdiff_plain/7aea4167500640a74eccd19d10aa0a353bc530f5

Add readme instructions
---

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..be5d6a6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+Taskpirate
+----------
+
+Taskpirate is a pluggable system for TaskWarrior python hooks.
+
+Why?
+----
+
+* simpler hooks
+
+    def hook_example(task):
+        task['description'] += "changed by a hook"
+
+The above is fully working example, no more boilerplate needed.
+
+* much faster execution time
+
+Install
+-------
+
+You'll need tasklib as a dependency:
+
+    pip install --user git+git://github.com/tbabej/tasklib@develop
+
+Then you need to drop ```on-add-pirate``` and ```on-modify-pirate``` into ~/.task/hooks/.
+
+After that, you can just clone any taskpirate-enabled hook as a subfolder into ~/.task/hooks/:
+
+    git clone https://github.com/tbabej/task.default-date-time ~/.task/hooks/default-date-time/
+
+How to write a taskpirate hook
+------------------------------
+
+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.
+
+Now, the pirate_add_example.py might look as follows:
+
+    def hook_example(task):
+        task['description'] += "changed by a hook"
+
+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).
+
+More details
+------------
+
+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.
+
+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.
+
+This becomes a problem when user has multiple tasklib-based hooks, since the import time adds up.
+
+Also, note that taskpirate with arbitrary number of hooks will be most likely faster than 2-3 regular python hooks.
+
+Example hooks
+-------------
+
+You can look into my ```task.default-date-time``` or ```task.shift-recurrence``` hooks.