From 51291f76fe4b1efadf0675e52ac4f7a5ae41b04e Mon Sep 17 00:00:00 2001
From: Paul Beckingham <paul@beckingham.net>
Date: Tue, 9 Sep 2014 23:09:24 -0400
Subject: [PATCH] Hooks

- Updated documentation and style of example hook scripts.
---
 scripts/hooks/on-add    | 24 +++++++++++-------------
 scripts/hooks/on-exit   | 24 ++++++++++++------------
 scripts/hooks/on-launch | 25 +++++++++++--------------
 scripts/hooks/on-modify | 28 +++++++++++++---------------
 4 files changed, 47 insertions(+), 54 deletions(-)

diff --git a/scripts/hooks/on-add b/scripts/hooks/on-add
index 350aec2d0..2403dcbec 100755
--- a/scripts/hooks/on-add
+++ b/scripts/hooks/on-add
@@ -3,20 +3,18 @@
 # The on-add event is triggered separately for each task added
 
 # Input:
-# - A line of JSON for the task added
-read new_task
-
-# Processing goes here
+# - line of JSON for the task added
 
 # Output:
-# - all emitted JSON lines must be fully-formed tasks
-# - all emitted non-JSON lines are considered feedback messages
-echo on-add
+# - all emitted JSON lines are added/modified as tasks, if the exit code is
+#   zero, otherwise ignored.
+# - minimal new task:  {"description":"Buy milk"}
+# - to modify a task include complete JSON
+# - all emitted non-JSON lines are considered feedback messages if the exit
+#   code is zero, otherwise they are considerederrors.
 
-# Exit:
-#   0 Means:     - all emitted JSON lines are added/modified
-#                - all emitted non-JSON lines become footnote entries
-#   non-0 Means: - all emitted JSON lines are ignored
-#                - all emitted non-JSON lines become error entries
+read new_task
+
+echo $new_task
+echo 'on-add'
 exit 0
-
diff --git a/scripts/hooks/on-exit b/scripts/hooks/on-exit
index 4e9fe952c..c9b65b77c 100755
--- a/scripts/hooks/on-exit
+++ b/scripts/hooks/on-exit
@@ -1,20 +1,20 @@
 #!/bin/bash
 
-# The on-exit event is triggered once, after all processing is complete
+# The on-exit event is triggered once, after all processing is complete, i.e.
+# last
 
 # Input:
-# - A read-only line of JSON for each task added/modified
-
-# Processing goes here
+# - read-only line of JSON for each task added/modified
 
 # Output:
-# - all emitted non-JSON lines are considered feedback messages
-# - The onExit event occurs too late to allow any changes, so the input is not
-#   to be modified
-echo on-exit
+# - any emitted JSON is ignored
+# - all emitted non-JSON lines are considered feedback messages if the exit
+#   code is zero, otherwise they are considerederrors.
 
-# Exit:
-#   0 Means:     - all emitted non-JSON lines become footnote entries
-#   non-0 Means: - all emitted non-JSON lines become error entries
+while read modified_task
+do
+  # Scan task
+done
+
+echo 'on-exit'
 exit 0
-
diff --git a/scripts/hooks/on-launch b/scripts/hooks/on-launch
index 14218e993..27c793c58 100755
--- a/scripts/hooks/on-launch
+++ b/scripts/hooks/on-launch
@@ -1,21 +1,18 @@
 #!/bin/bash
 
-# The on-launch event is triggered once, after initialization, before an
-# processing occurs
+# The on-launch event is triggered once, after initialization, before any
+# processing occurs, i.e first
 
-# No input
-
-# Processing goes here
+# Input:
+# - none
 
 # Output:
-# - all emitted JSON lines must be fully-formed tasks
-# - all emitted non-JSON lines are considered feedback messages
-echo on-launch
+# - all emitted JSON lines are added/modified as tasks, if the exit code is
+#   zero, otherwise ignored.
+# - minimal new task:  {"description":"Buy milk"}
+# - to modify a task include complete JSON
+# - all emitted non-JSON lines are considered feedback messages if the exit
+#   code is zero, otherwise they are considerederrors.
 
-# Exit:
-#   0 Means:     - all emitted JSON lines are added/modified
-#                - all emitted non-JSON lines become footnote entries
-#   non-0 Means: - all emitted JSON lines are ignored
-#                - all emitted non-JSON lines become error entries
+echo 'on-launch'
 exit 0
-
diff --git a/scripts/hooks/on-modify b/scripts/hooks/on-modify
index 0167d283d..3e410c607 100755
--- a/scripts/hooks/on-modify
+++ b/scripts/hooks/on-modify
@@ -3,22 +3,20 @@
 # The on-modify event is triggered separately for each task added or modified
 
 # Input:
-# - A line of JSON for the original task
-# - A line of JSON for the modified task
+# - line of JSON for the original task
+# - line of JSON for the modified task, the diff being the modification
+
+# Output:
+# - all emitted JSON lines are added/modified as tasks, if the exit code is
+#   zero, otherwise ignored.
+# - minimal new task:  {"description":"Buy milk"}
+# - to modify a task include complete JSON
+# - all emitted non-JSON lines are considered feedback messages if the exit
+#   code is zero, otherwise they are considerederrors.
+
 read original_task
 read modified_task
 
-# Processing goes here
-
-# Output:
-# - all emitted JSON lines must be fully-formed tasks
-# - all emitted non-JSON lines are considered feedback messages
-echo on-modify
-
-# Exit:
-#   0 Means:     - all emitted JSON lines are added/modified
-#                - all emitted non-JSON lines become footnote entries
-#   non-0 Means: - all emitted JSON lines are ignored
-#                - all emitted non-JSON lines become error entries
+echo $modified_task
+echo 'on-modify'
 exit 0
-