ENH: Handle -h, shorthelp and help when a Fatal Error happens.

The user may need the help to solve any fatal error that appears while todo.sh isn't properly set up. As the help actions do not depend on any setting that the fatal errors check, we can still invoke them.

Factor out dieWithHelp() and use that for printing the fatal errors.

tests/actions-test-lib.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+make_action()
+{
+    unset TODO_ACTIONS_DIR
+    [ -d .todo.actions.d ] || mkdir .todo.actions.d
+    cat > ".todo.actions.d/$1" <<EOF
+#!/bin/bash
+[ "\$1" = "usage" ] && {
+    echo "    $1 ITEM#[, ITEM#, ...] [TERM...]"
+    echo "      This custom action does $1."
+    echo ""
+    exit
+}
+echo "custom action $1"
+EOF
+chmod +x ".todo.actions.d/$1"
+}

tests/t0100-code-nobacktick.sh

@@ -9,8 +9,15 @@ On failure, it will print each offending line number and line.
 '
 . ./test-lib.sh
 
+backtick_check()
+{
+    sed -n -e 's/\(^\|[ \t]\)#.*//' -e '/`/{' -e '=;p' -e '}' "$@"
+}
+
 test_todo_session 'no old-style backtick command substitution' <<EOF
->>> sed -n -e 's/\(^\|[ \t]\)#.*//' -e '/\`/{' -e '=;p' -e '}' "$(which todo.sh)"
+>>> backtick_check bin/todo.sh
+
+>>> backtick_check ../../todo.cfg
 EOF
 
 test_done

tests/t1100-replace.sh

@@ -164,4 +164,12 @@ TODO: Replaced task with:
 1 (A) 2010-07-04 this also has a new date
 EOF
 
+echo '2009-02-13 this is just a new one' > todo.txt
+test_todo_session 'replace with prepended priority and date replaces existing date' <<EOF
+>>> todo.sh replace 1 '(B) 2010-07-04 this also has a new date'
+1 2009-02-13 this is just a new one
+TODO: Replaced task with:
+1 (B) 2010-07-04 this also has a new date
+EOF
+
 test_done

tests/t1310-listcon.sh

@@ -55,6 +55,16 @@ test_todo_session 'listcon e-mail address test' <<EOF
 @con02
 EOF
 
+cat > todo.txt <<EOF
+(B) smell the uppercase Roses +roses @outside +shared
+(C) notice the sunflowers +sunflowers @garden +shared +landscape
+stop
+EOF
+test_todo_session 'listcon with project' <<EOF
+>>> todo.sh listcon +landscape
+@garden
+EOF
+
 cat > todo.txt <<EOF
 @con01 -- Some context 1 task
 EOF

tests/t2100-help.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+#
+
+test_description='help functionality
+
+This test covers the help output.
+'
+. ./actions-test-lib.sh
+. ./test-lib.sh
+
+# Note: To avoid having to adapt the test whenever the help documentation
+# slightly changes, only check for the section headers.
+test_todo_session 'help output' <<EOF
+>>> todo.sh help | sed '/^  [A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Options:
+  Built-in Actions:
+EOF
+
+test_todo_session 'verbose help output' <<EOF
+>>> todo.sh -v help | sed '/^  [A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Options:
+  Built-in Actions:
+EOF
+
+test_todo_session 'very verbose help output' <<EOF
+>>> todo.sh -vv help | sed '/^  [A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Options:
+  Environment variables:
+  Built-in Actions:
+EOF
+
+make_action "foo"
+test_todo_session 'help output with custom action' <<EOF
+>>> todo.sh -v help | sed '/^  [A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Options:
+  Built-in Actions:
+  Add-on Actions:
+EOF
+
+test_done

tests/t2110-help-action.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+
+test_description='built-in actions help functionality
+
+This test checks listing the usage help of a built-in action.
+'
+. ./test-lib.sh
+
+test_todo_session 'nonexisting action help' <<'EOF'
+>>> todo.sh help doesnotexist
+TODO: No action "doesnotexist" exists.
+=== 1
+
+>>> todo.sh help hel
+TODO: No action "hel" exists.
+=== 1
+
+>>> todo.sh help h
+TODO: No action "h" exists.
+=== 1
+EOF
+
+test_todo_session 'single action help' <<'EOF'
+>>> todo.sh help shorthelp
+    shorthelp
+      List the one-line usage of all built-in and add-on actions.
+\
+EOF
+
+test_todo_session 'multiple actions help' <<'EOF'
+>>> todo.sh help shorthelp append
+    shorthelp
+      List the one-line usage of all built-in and add-on actions.
+\
+    append ITEM# "TEXT TO APPEND"
+    app ITEM# "TEXT TO APPEND"
+      Adds TEXT TO APPEND to the end of the task on line ITEM#.
+      Quotes optional.
+\
+EOF
+
+test_todo_session 'short and long form of action help' <<'EOF'
+>>> todo.sh help append
+    append ITEM# "TEXT TO APPEND"
+    app ITEM# "TEXT TO APPEND"
+      Adds TEXT TO APPEND to the end of the task on line ITEM#.
+      Quotes optional.
+\
+
+>>> todo.sh help app
+    app ITEM# "TEXT TO APPEND"
+      Adds TEXT TO APPEND to the end of the task on line ITEM#.
+      Quotes optional.
+\
+EOF
+
+test_todo_session 'mixed existing and nonexisting action help' <<'EOF'
+>>> todo.sh help shorthelp doesnotexist list
+    shorthelp
+      List the one-line usage of all built-in and add-on actions.
+\
+TODO: No action "doesnotexist" exists.
+=== 1
+EOF
+
+test_done

tests/t2120-shorthelp.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+#
+
+test_description='shorthelp functionality
+
+This test covers the output of the -h option and the shorthelp action.
+'
+. ./actions-test-lib.sh
+. ./test-lib.sh
+
+# Note: To avoid having to adapt the test whenever the actions change, only
+# check for the section headers.
+test_todo_session '-h output' <<EOF
+>>> todo.sh -h | sed '/^  [A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Actions:
+  Actions can be added and overridden using scripts in the actions
+  See "help" for more details.
+EOF
+
+test_todo_session 'shorthelp output' <<EOF
+>>> todo.sh shorthelp | sed '/^  [A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Actions:
+  Actions can be added and overridden using scripts in the actions
+  See "help" for more details.
+EOF
+
+make_action "foo"
+test_todo_session 'shorthelp output with custom action' <<EOF
+>>> todo.sh -v shorthelp | sed '/^  [A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Actions:
+  Actions can be added and overridden using scripts in the actions
+  Add-on Actions:
+  See "help" for more details.
+EOF
+
+
+# Verify that custom configuration is actually processed (when the -d option
+# precedes the -h option) by specifying a different actions directory and moving
+# our custom action there. The help output should mention the "Add-On Actions".
+set -o pipefail # So that the sed filter doesn't swallow todo.sh's exit code.
+mv todo.cfg custom.cfg
+mv .todo.actions.d custom.actions
+echo 'export TODO_ACTIONS_DIR=$HOME/custom.actions' >> custom.cfg
+
+test_todo_session '-h and fatal error without config' <<EOF
+>>> todo.sh -h | sed '/^ \\{0,2\\}[A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Actions:
+  Actions can be added and overridden using scripts in the actions
+  See "help" for more details.
+Fatal Error: Cannot read configuration file $HOME/.todo/config
+=== 1
+EOF
+
+# Config option comes too late; "Add-on Actions" is *not* mentioned here.
+test_todo_session '-h and fatal error with trailing custom config' <<EOF
+>>> todo.sh -h -d custom.cfg | sed '/^ \\{0,2\\}[A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Actions:
+  Actions can be added and overridden using scripts in the actions
+  See "help" for more details.
+Fatal Error: Cannot read configuration file $HOME/.todo/config
+=== 1
+EOF
+
+# Config option processed; "Add-on Actions" is mentioned here.
+test_todo_session '-h output with preceding custom config' <<EOF
+>>> todo.sh -d custom.cfg -h | sed '/^ \\{0,2\\}[A-Z]/!d'
+  Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]
+  Actions:
+  Actions can be added and overridden using scripts in the actions
+  Add-on Actions:
+  See "help" for more details.
+EOF
+
+test_done

tests/t6030-completion-tasks.sh

@@ -14,6 +14,7 @@ notice the sunflowers +sunflowers @outside @garden +shared +landscape
 (C) 2012-02-28 @outside mow the lawn
 x 2012-02-21 +herbs @oriental buy spices
 x 2012-02-28 2012-02-21 +slack @home watch tv
+2012-02-28 +herbs buy cinnamon @grocer
 EOF
 test_todo_completion 'simple task' 'todo.sh list 1' '"1 # simple task"'
 test_todo_completion 'remove projects and contents from task' 'todo.sh list 2' '"2 # notice the sunflowers"'
@@ -21,5 +22,6 @@ test_todo_completion 'keep priority' 'todo.sh list 3' '"3 # (B) smell the flower
 test_todo_completion 'keep priority and remove timestamp' 'todo.sh list 4' '"4 # (C) mow the lawn"'
 test_todo_completion 'keep done marker and remove done date' 'todo.sh list 5' '"5 # x buy spices"'
 test_todo_completion 'keep done marker and remove timestamp and done date' 'todo.sh list 6' '"6 # x watch tv"'
+test_todo_completion 'remove add date' 'todo.sh list 7' '"7 # buy cinnamon"'
 
 test_done

tests/t6100-completion-help.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+#
+
+test_description='Bash help completion functionality
+
+This test checks todo_completion of actions for usage help.
+'
+. ./actions-test-lib.sh
+. ./test-lib.sh
+make_action "zany"
+make_action "aardvark"
+
+readonly ACTIONS='add a addto addm append app archive command del rm depri dp do help list ls listaddons listall lsa listcon lsc listfile lf listpri lsp listproj lsprj move mv prepend prep pri p replace report shorthelp'
+readonly ADDONS='aardvark zany'
+
+test_todo_completion 'all actions after help' 'todo.sh help ' "$ACTIONS $ADDONS"
+test_todo_completion 'all actions after command help' 'todo.sh command help ' "$ACTIONS $ADDONS"
+test_todo_completion 'actions beginning with a' 'todo.sh help a' 'add a addto addm append app archive aardvark'
+
+test_done

tests/t8000-actions.sh

@@ -4,19 +4,9 @@ test_description='custom actions functionality
 
 This test covers the contract between todo.sh and custom actions.
 '
+. ./actions-test-lib.sh
 . ./test-lib.sh
 
-unset TODO_ACTIONS_DIR
-mkdir .todo.actions.d
-make_action()
-{
-	cat > ".todo.actions.d/$1" <<- EOF
-	#!/bin/bash
-	echo "custom action $1"
-EOF
-chmod +x ".todo.actions.d/$1"
-}
-
 make_action "foo"
 test_todo_session 'executable action' <<EOF
 >>> todo.sh foo

tests/t8010-listaddons.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+
+test_description='listaddons functionality
+
+This test checks listing of custom actions.
+'
+. ./actions-test-lib.sh
+. ./test-lib.sh
+
+test_todo_session 'no custom actions' <<EOF
+>>> todo.sh listaddons
+EOF
+
+make_action "foo"
+test_todo_session 'one custom action' <<EOF
+>>> todo.sh listaddons
+foo
+EOF
+
+make_action "bar"
+make_action "ls"
+make_action "quux"
+test_todo_session 'multiple custom actions' <<EOF
+>>> todo.sh listaddons
+bar
+foo
+ls
+quux
+EOF
+
+chmod -x .todo.actions.d/foo
+# On Cygwin, clearing the executable flag may have no effect, as the Windows ACL
+# may still grant execution rights. In this case, we skip the test.
+if [ -x .todo.actions.d/foo ]; then
+    SKIP_TESTS="${SKIP_TESTS}${SKIP_TESTS+ }t8010.4"
+fi
+test_todo_session 'nonexecutable action' <<EOF
+>>> todo.sh listaddons
+bar
+ls
+quux
+EOF
+
+test_done

tests/t8020-actions-help.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+
+test_description='custom actions help functionality
+
+This test checks listing the usage help of a custom action.
+'
+. ./actions-test-lib.sh
+. ./test-lib.sh
+
+test_todo_session 'custom action help with no custom action directory' <<'EOF'
+>>> todo.sh help foo
+TODO: No action "foo" exists.
+=== 1
+EOF
+
+make_action "foo"
+make_action "bar"
+make_action "ls"
+make_action "quux"
+
+test_todo_session 'custom action help' <<'EOF'
+>>> todo.sh help foo
+    foo ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does foo.
+\
+
+>>> todo.sh help bar
+    bar ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does bar.
+\
+EOF
+
+test_todo_session 'multiple custom actions help' <<'EOF'
+>>> todo.sh help foo bar
+    foo ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does foo.
+\
+    bar ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does bar.
+\
+EOF
+
+test_todo_session 'nonexisting action help' <<'EOF'
+>>> todo.sh help doesnotexist
+TODO: No action "doesnotexist" exists.
+=== 1
+
+>>> todo.sh help foo doesnotexist bar
+    foo ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does foo.
+\
+TODO: No action "doesnotexist" exists.
+=== 1
+EOF
+
+test_todo_session 'mixed built-in and custom actions help' <<'EOF'
+>>> todo.sh help foo shorthelp bar
+    foo ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does foo.
+\
+    shorthelp
+      List the one-line usage of all built-in and add-on actions.
+\
+    bar ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does bar.
+\
+EOF
+
+test_todo_session 'custom override of built-in action help' <<'EOF'
+>>> todo.sh help ls
+    ls ITEM#[, ITEM#, ...] [TERM...]
+      This custom action does ls.
+\
+EOF
+
+test_done

tests/test-lib.sh

@@ -264,25 +264,7 @@ test_expect_success () {
 test_expect_output () {
 	test "$#" = 2 ||
 	error "bug in the test script: not 2 parameters to test-expect-output"
-	if ! test_skip "$@"
+	test_expect_code_and_output 0 "$@"
-	then
-		say >&3 "expecting success and output: $2"
-		test_run_ "$2"
-		if [ "$?" = 0 -a "$eval_ret" = 0 ]
-		then
-			cmp_output=$(test_cmp expect output)
-			if [ "$?" = 0 ]
-			then
-				test_ok_ "$1"
-			else
-				test_failure_ "$@" "
-$cmp_output"
-			fi
-		else
-			test_failure_ "$@"
-		fi
-	fi
-	echo >&3 ""
 }
 
 test_expect_code_and_output () {
@@ -290,7 +272,11 @@ test_expect_code_and_output () {
 	error "bug in the test script: not 3 parameters to test-expect-code-and-output"
 	if ! test_skip "$@"
 	then
-		say >&3 "expecting exit code $1 and output: $3"
+		if [ "$1" = 0 ]; then
+			say >&3 "expecting success and output: $3"
+		else
+			say >&3 "expecting exit code $1 and output: $3"
+		fi
 		test_run_ "$3"
 		if [ "$?" = 0 -a "$eval_ret" = "$1" ]
 		then
@@ -566,14 +552,16 @@ test_tick () {
 }
 
 # Generate and run a series of tests based on a transcript.
-# Usage: test_todo_session "description" <<EOF
+# Usage: test_todo_session "description" <<'EOF'
 # >>> command
 # output1
 # output2
+#
 # >>> command
 # === exit status
-# output3
+# output3 with empty line (must be escaped here)
-# output4
+# \
+# output5
 # EOF
 test_todo_session () {
     test "$#" = 1 ||
@@ -582,7 +570,7 @@ test_todo_session () {
     cmd=""
     status=0
     > expect
-    while read -r line
+    while IFS= read -r line
     do
 	case $line in
 	">>> "*)
@@ -606,6 +594,9 @@ test_todo_session () {
 		> expect
 	    fi
 	    ;;
+	\\)
+	    echo "" >> expect
+	    ;;
 	*)
 	    echo "$line" >> expect
 	    ;;

todo.cfg

@@ -2,7 +2,7 @@
 
 # Your todo.txt directory
 #export TODO_DIR="/Users/gina/Documents/todo"
-export TODO_DIR=`dirname "$0"`
+export TODO_DIR=$(dirname "$0")
 
 # Your todo/done/report.txt locations
 export TODO_FILE="$TODO_DIR/todo.txt"

todo.sh

@@ -54,11 +54,11 @@ shorthelp()
 		    del|rm ITEM# [TERM]
 		    depri|dp ITEM#[, ITEM#, ITEM#, ...]
 		    do ITEM#[, ITEM#, ITEM#, ...]
-		    help
+		    help [ACTION...]
 		    list|ls [TERM...]
 		    listall|lsa [TERM...]
 		    listaddons
-		    listcon|lsc
+		    listcon|lsc [TERM...]
 		    listfile|lf [SRC [TERM...]]
 		    listpri|lsp [PRIORITIES] [TERM...]
 		    listproj|lsprj [TERM...]
@@ -81,7 +81,6 @@ shorthelp()
 
 		  See "help" for more details.
 	EndHelpFooter
-    exit 0
 }
 
 help()
@@ -154,6 +153,12 @@ help()
 
 
 	EndVerboseHelp
+        actionsHelp
+        addonHelp
+}
+
+actionsHelp()
+{
     cat <<-EndActionsHelp
 		  Built-in Actions:
 		    add "THING I NEED TO DO +project @context"
@@ -200,8 +205,9 @@ help()
 		    do ITEM#[, ITEM#, ITEM#, ...]
 		      Marks task(s) on line ITEM# as done in todo.txt.
 
-		    help
+		    help [ACTION...]
-		      Display this help message.
+		      Display help about usage, options, built-in and add-on actions,
+		      or just the usage help for the passed ACTION(s).
 
 		    list [TERM...]
 		    ls [TERM...]
@@ -223,9 +229,10 @@ help()
 		    listaddons
 		      Lists all added and overridden actions in the actions directory.
 
-		    listcon
+		    listcon [TERM...]
-		    lsc
+		    lsc [TERM...]
 		      Lists all the task contexts that start with the @ sign in todo.txt.
+		      If TERM specified, considers only tasks that contain TERM(s).
 
 		    listfile [SRC [TERM...]]
 		    lf [SRC [TERM...]]
@@ -245,10 +252,11 @@ help()
 		      Hides all tasks that contain TERM(s) preceded by a minus sign
 		      (i.e. -TERM).  
 
-		    listproj
+		    listproj [TERM...]
-		    lsprj
+		    lsprj [TERM...]
 		      Lists all the projects (terms that start with a + sign) in
 		      todo.txt.
+		      If TERM specified, considers only tasks that contain TERM(s).
 
 		    move ITEM# DEST [SRC]
 		    mv ITEM# DEST [SRC]
@@ -278,9 +286,6 @@ help()
 		      List the one-line usage of all built-in and add-on actions.
 
 	EndActionsHelp
-
-        addonHelp
-    exit 1
 }
 
 addonHelp()
@@ -302,6 +307,35 @@ addonHelp()
     fi
 }
 
+actionUsage()
+{
+    for actionName
+    do
+        action="${TODO_ACTIONS_DIR}/${actionName}"
+        if [ -f "$action" -a -x "$action" ]; then
+            "$action" usage
+        else
+            builtinActionUsage=$(actionsHelp | sed -n -e "/^    ${actionName//\//\\/} /,/^\$/p" -e "/^    ${actionName//\//\\/}$/,/^\$/p")
+            if [ "$builtinActionUsage" ]; then
+                echo "$builtinActionUsage"
+                echo
+            else
+                die "TODO: No action \"${actionName}\" exists."
+            fi
+        fi
+    done
+}
+
+dieWithHelp()
+{
+    case "$1" in
+        help)       help;;
+        shorthelp)  shorthelp;;
+    esac
+    shift
+
+    die "$@"
+}
 die()
 {
     echo "$*"
@@ -389,21 +423,22 @@ replaceOrPrepend()
   else
     input=$*
   fi
-  cleaninput "for sed"
 
   # Retrieve existing priority and prepended date
-  priority=$(sed -e "$item!d" -e $item's/^\((.) \)\{0,1\}\([0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} \)\{0,1\}.*/\1/' "$TODO_FILE")
+  local -r priAndDateExpr='^\((.) \)\{0,1\}\([0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} \)\{0,1\}'
-  prepdate=$(sed -e "$item!d" -e $item's/^\((.) \)\{0,1\}\([0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} \)\{0,1\}.*/\2/' "$TODO_FILE")
+  priority=$(sed -e "$item!d" -e "${item}s/${priAndDateExpr}.*/\\1/" "$TODO_FILE")
+  prepdate=$(sed -e "$item!d" -e "${item}s/${priAndDateExpr}.*/\\2/" "$TODO_FILE")
 
-  if [ "$prepdate" -a "$action" = "replace" ] && [ "$(echo "$input"|sed -e 's/^\([0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\}\)\{0,1\}.*/\1/')" ]; then
+  if [ "$prepdate" -a "$action" = "replace" ] && [ "$(echo "$input"|sed -e "s/${priAndDateExpr}.*/\\1\\2/")" ]; then
-    # If the replaced text starts with a date, it will replace the existing
+      # If the replaced text starts with a [priority +] date, it will replace
-    # date, too.
+      # the existing date, too.
     prepdate=
   fi
 
   # Temporarily remove any existing priority and prepended date, perform the
   # change (replace/prepend) and re-insert the existing priority and prepended
   # date again.
+  cleaninput "for sed"
   sed -i.bak -e "$item s/^${priority}${prepdate}//" -e "$item s|^.*|${priority}${prepdate}${input}${backref}|" "$TODO_FILE"
   if [ $TODOTXT_VERBOSE -gt 0 ]; then
     getNewtodo "$item"
@@ -488,6 +523,7 @@ do
         # Cannot just invoke shorthelp() because we need the configuration
         # processed to locate the add-on actions directory.
         set -- '-h' 'shorthelp'
+        OPTIND=2
         ;;
     n )
         OVR_TODOTXT_PRESERVE_LINE_NUMBERS=0
@@ -628,7 +664,7 @@ fi
 }
 
 # === SANITY CHECKS (thanks Karl!) ===
-[ -r "$TODOTXT_CFG_FILE" ] || die "Fatal Error: Cannot read configuration file $TODOTXT_CFG_FILE"
+[ -r "$TODOTXT_CFG_FILE" ] || dieWithHelp "$1" "Fatal Error: Cannot read configuration file $TODOTXT_CFG_FILE"
 
 . "$TODOTXT_CFG_FILE"
 
@@ -667,8 +703,8 @@ fi
 ACTION=${1:-$TODOTXT_DEFAULT_ACTION}
 
 [ -z "$ACTION" ]    && usage
-[ -d "$TODO_DIR" ]  || die "Fatal Error: $TODO_DIR is not a directory"
+[ -d "$TODO_DIR" ]  || dieWithHelp "$1" "Fatal Error: $TODO_DIR is not a directory"
-( cd "$TODO_DIR" )  || die "Fatal Error: Unable to cd to $TODO_DIR"
+( cd "$TODO_DIR" )  || dieWithHelp "$1" "Fatal Error: Unable to cd to $TODO_DIR"
 
 [ -f "$TODO_FILE" ] || cp /dev/null "$TODO_FILE"
 [ -f "$DONE_FILE" ] || cp /dev/null "$DONE_FILE"
@@ -858,7 +894,17 @@ _format()
     fi
 }
 
-export -f cleaninput getPrefix getTodo getNewtodo shellquote filtercommand _list getPadding _format die
+listWordsWithSigil()
+{
+    sigil=$1
+    shift
+
+    FILE=$TODO_FILE
+    [ "$TODOTXT_SOURCEVAR" ] && eval "FILE=$TODOTXT_SOURCEVAR"
+    eval "$(filtercommand 'cat "${FILE[@]}"' '' "$@")" | grep -o "[^ ]*${sigil}[^ ]\\+" | grep "^$sigil" | sort -u
+}
+
+export -f cleaninput getPrefix getTodo getNewtodo shellquote filtercommand _list listWordsWithSigil getPadding _format die
 
 # == HANDLE ACTION ==
 action=$( printf "%s\n" "$ACTION" | tr 'A-Z' 'a-z' )
@@ -1075,13 +1121,19 @@ case $action in
     ;;
 
 "help" )
-    if [ -t 1 ] ; then # STDOUT is a TTY
+    shift  ## Was help; new $1 is first help topic / action name
-        if which "${PAGER:-less}" >/dev/null 2>&1; then
+    if [ $# -gt 0 ]; then
-            # we have a working PAGER (or less as a default)
+        # Don't use PAGER here; we don't expect much usage output from one / few actions.
-            help | "${PAGER:-less}" && exit 0
+        actionUsage "$@"
+    else
+        if [ -t 1 ] ; then # STDOUT is a TTY
+            if which "${PAGER:-less}" >/dev/null 2>&1; then
+                # we have a working PAGER (or less as a default)
+                help | "${PAGER:-less}" && exit 0
+            fi
         fi
+        help # just in case something failed above, we go ahead and just spew to STDOUT
     fi
-    help # just in case something failed above, we go ahead and just spew to STDOUT
     ;;
 
 "shorthelp" )
@@ -1105,7 +1157,7 @@ case $action in
     TOTAL=$( sed -n '$ =' "$TODO_FILE" )
     PADDING=${#TOTAL}
 
-    post_filter_command="awk -v TOTAL=$TOTAL -v PADDING=$PADDING '{ \$1 = sprintf(\"%\" PADDING \"d\", (\$1 > TOTAL ? 0 : \$1)); print }' "
+    post_filter_command="${post_filter_command:-}${post_filter_command:+ | }awk -v TOTAL=$TOTAL -v PADDING=$PADDING '{ \$1 = sprintf(\"%\" PADDING \"d\", (\$1 > TOTAL ? 0 : \$1)); print }' "
     cat "$TODO_FILE" "$DONE_FILE" | TODOTXT_VERBOSE=0 _format '' "$PADDING" "$@"
 
     if [ $TODOTXT_VERBOSE -gt 0 ]; then
@@ -1133,23 +1185,20 @@ case $action in
     ;;
 
 "listcon" | "lsc" )
-    FILE=$TODO_FILE
+    shift
-    [ "$TODOTXT_SOURCEVAR" ] && eval "FILE=$TODOTXT_SOURCEVAR"
+    listWordsWithSigil '@' "$@"
-    grep -ho '[^ ]*@[^ ]\+' "${FILE[@]}" | grep '^@' | sort -u
     ;;
 
 "listproj" | "lsprj" )
-    FILE=$TODO_FILE
-    [ "$TODOTXT_SOURCEVAR" ] && eval "FILE=$TODOTXT_SOURCEVAR"
     shift
-    eval "$(filtercommand 'cat "${FILE[@]}"' '' "$@")" | grep -o '[^ ]*+[^ ]\+' | grep '^+' | sort -u
+    listWordsWithSigil '+' "$@"
     ;;
 
 "listpri" | "lsp" )
     shift ## was "listpri", new $1 is priority to list or first TERM
 
     pri=$(printf "%s\n" "$1" | tr 'a-z' 'A-Z' | grep -e '^[A-Z]$' -e '^[A-Z]-[A-Z]$') && shift || pri="A-Z"
-    post_filter_command="grep '^ *[0-9]\+ ([${pri}]) '"
+    post_filter_command="${post_filter_command:-}${post_filter_command:+ | }grep '^ *[0-9]\+ ([${pri}]) '"
     _list "$TODO_FILE" "$@"
     ;;
 

todo_completion

@@ -14,20 +14,23 @@ _todo()
         rm depri dp do help list ls listaddons listall lsa listcon  \
         lsc listfile lf listpri lsp listproj lsprj move \
         mv prepend prep pri p replace report shorthelp"
+    local -r MOVE_COMMAND_PATTERN='^(move|mv)$'
 
     local _todo_sh=${_todo_sh:-todo.sh}
     local completions
     if [ $COMP_CWORD -eq 1 ]; then
         completions="$COMMANDS $(eval TODOTXT_VERBOSE=0 $_todo_sh command listaddons) $OPTS"
     elif [[ $COMP_CWORD -gt 2 && ( \
-        "${COMP_WORDS[COMP_CWORD-2]}" =~ ^(move|mv)$ || \
+        "${COMP_WORDS[COMP_CWORD-2]}" =~ $MOVE_COMMAND_PATTERN || \
-        "${COMP_WORDS[COMP_CWORD-3]}" =~ ^(move|mv)$ ) ]]; then
+        "${COMP_WORDS[COMP_CWORD-3]}" =~ $MOVE_COMMAND_PATTERN ) ]]; then
         # "move ITEM# DEST [SRC]" has file arguments on positions 2 and 3.
         completions=$(eval TODOTXT_VERBOSE=0 $_todo_sh command listfile)
     else
         case "$prev" in
             command)
                 completions=$COMMANDS;;
+            help)
+                completions="$COMMANDS $(eval TODOTXT_VERBOSE=0 $_todo_sh command listaddons)";;
             addto|listfile|lf)
                 completions=$(eval TODOTXT_VERBOSE=0 $_todo_sh command listfile);;
             -*) completions="$COMMANDS $(eval TODOTXT_VERBOSE=0 $_todo_sh command listaddons) $OPTS";;
@@ -58,8 +61,8 @@ _todo()
                             # a safety check of the ls action output.
                             local todo=$( \
                                 eval TODOTXT_VERBOSE=0 $_todo_sh '-@ -+ -p -x command ls "^ *${cur} "' | \
-                                sed -e 's/^ *[0-9]\{1,\} //' -e 's/\((.) \)[0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} /\1/' \
+                                sed -e 's/^ *[0-9]\{1,\} //' -e 's/^\((.) \)\{0,1\}[0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} /\1/' \
-                                    -e 's/\([xX] \)\([0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} \)\{1,2\}/\1/' \
+                                    -e 's/^\([xX] \)\([0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} \)\{1,2\}/\1/' \
                                     -e 's/[[:space:]]*$//' \
                                     -e '1q' \
                             )
@@ -85,6 +88,9 @@ complete -F _todo todo.sh
 # If you define an alias (e.g. "t") to todo.sh, you need to explicitly enable
 # completion for it, too:
 #complete -F _todo t
+# It is recommended to put this line next to your alias definition in your
+# ~/.bashrc (or wherever else you're defining your alias). If you simply
+# uncomment it here, you will need to redo this on every todo.txt update!
 
 # If you have renamed the todo.sh executable, or if it is not accessible through
 # PATH, you need to add and use a wrapper completion function, like this: