Merge pull request #89 from inkarkat/individual-help-enhancement

Individual help enhancement

.gitignore

@@ -1,3 +1,6 @@
 VERSION-FILE
 tests/test-results
 tests/trash\ directory.*
+done.txt
+report.txt
+todo.txt

tests/README

@@ -191,11 +191,18 @@ library for your script to use.
    This takes three strings as parameter.  Based on <cmdline>,
    the todo_completion script is triggered in the current test
    environment and completions are compared with <completions>,
-   which should be a space-separated list.  Include a trailing
-   space in <cmdline> when you want to check new argument
-   completion; otherwise, completion is triggered with the
-   context of the last argument.  <message> should state what it
-   is testing.
+   which should be a space-separated list.  If any completion
+   contains whitespace, quote it; the entire <completions>
+   argument is eval()'ed.
+   Include a trailing space in <cmdline> when you want to check
+   new argument completion; otherwise, completion is triggered
+   with the context of the last argument. <message> should state
+   what it is testing.
+
+ - test_todo_custom_completion <completefunc> <message> <cmdline> <completions>
+
+   Same as above, but in addition allows to specify a custom
+   completion function.
 
  - test_tick [interval]
 
@@ -216,6 +223,13 @@ library for your script to use.
 	    'git-write-tree should be able to write an empty tree.' \
 	    'tree=$(git-write-tree)'
 
+ - test_expect_code <code> <message> <script>
+
+   This takes an exit status and two strings as parameter, and
+   evaluates the <script>.  If it yields <code>, test is
+   considered successful.  <message> should state what it is
+   testing.
+
  - test_expect_failure <message> <script>
 
    This is NOT the opposite of test_expect_success, but is used

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/t6000-completion.sh

@@ -7,12 +7,16 @@ This test checks basic todo_completion of actions and options
 '
 . ./test-lib.sh
 
-readonly ACTIONS='add a addto addm append app archive command del rm depri dp do help list ls listall lsa listcon lsc listfile lf listpri lsp listproj lsprj move mv prepend prep pri p replace report shorthelp'
+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 OPTIONS='-@ -@@ -+ -++ -d -f -h -p -P -PP -a -n -t -v -vv -V -x'
 
 test_todo_completion 'all arguments' 'todo.sh ' "$ACTIONS $OPTIONS"
 test_todo_completion 'arguments beginning with a' 'todo.sh a' 'add a addto addm append app archive'
 test_todo_completion 'all options' 'todo.sh -' "$OPTIONS"
 test_todo_completion 'all actions after command action' 'todo.sh command ' "$ACTIONS"
+test_todo_completion 'all arguments after option' 'todo.sh -a ' "$ACTIONS $OPTIONS"
+test_todo_completion 'all arguments after options' 'todo.sh -a -p ' "$ACTIONS $OPTIONS"
+test_todo_completion 'all options after options' 'todo.sh -a -p -' "$OPTIONS"
+test_todo_completion 'nothing after action' 'todo.sh archive ' ''
 
 test_done

tests/t6030-completion-tasks.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+#
+
+test_description='Bash task number completion functionality
+
+This test checks todo_completion of a task number into the abbreviated task text.
+'
+. ./test-lib.sh
+
+cat > todo.txt <<EOF
+simple task
+notice the sunflowers +sunflowers @outside @garden +shared +landscape
+(B) smell the +roses flower @outside @outdoor +shared
+(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"'
+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/t6040-completion-files.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+#
+
+test_description='Bash todo file completion functionality
+
+This test checks todo_completion of files in TODO_DIR.
+'
+. ./test-lib.sh
+
+> dummy.txt
+readonly FILES='done.txt dummy.txt report.txt todo.txt'
+test_todo_completion 'all files after addto' 'todo.sh addto ' "$FILES"
+test_todo_completion 'files beginning with d after addto' 'todo.sh addto d' 'done.txt dummy.txt'
+test_todo_completion 'all files after listfile' 'todo.sh listfile ' "$FILES"
+test_todo_completion 'all files after lf' 'todo.sh -v lf ' "$FILES"
+test_todo_completion 'nothing after move' 'todo.sh move ' ''
+test_todo_completion 'all files after move ITEM#' 'todo.sh move 1 ' "$FILES"
+test_todo_completion 'all files after mv ITEM#' 'todo.sh mv 1 ' "$FILES"
+test_todo_completion 'all files after move ITEM# DEST' 'todo.sh move 1 todo.sh ' "$FILES"
+
+test_done

tests/t6050-completion-addons.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+#
+
+test_description='Bash add-on action completion functionality
+
+This test checks todo_completion of custom actions in .todo.actions.d
+'
+. ./test-lib.sh
+
+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 OPTIONS='-@ -@@ -+ -++ -d -f -h -p -P -PP -a -n -t -v -vv -V -x'
+
+readonly ADDONS='bar baz foobar'
+makeCustomActions()
+{
+    set -e
+    mkdir "${1:?}"
+    for addon in $ADDONS
+    do
+        addonFile="${1}/$addon"
+        > "$addonFile"
+        chmod +x "$addonFile"
+    done
+
+    # Also create a subdirectory, to test that it is skipped.
+    mkdir "${1}/subdir"
+
+    # Also create a non-executable file, to test that it is skipped.
+    datafile="${1:?}/datafile"
+    > "$datafile"
+    chmod -x "$datafile"
+    [ -x "$datafile" ] && rm "$datafile"    # Some file systems may always make files executable; then, skip this check.
+
+    set +e
+}
+removeCustomActions()
+{
+    set -e
+    rmdir "${1}/subdir"
+    rm "${1:?}/"*
+    rmdir "$1"
+    set +e
+}
+
+#
+# Test resolution of the default TODO_ACTIONS_DIR.
+#
+makeCustomActions "$HOME/.todo.actions.d"
+test_todo_completion 'all arguments' 'todo.sh ' "$ACTIONS $ADDONS $OPTIONS"
+test_todo_completion 'all arguments after option' 'todo.sh -a ' "$ACTIONS $ADDONS $OPTIONS"
+test_todo_completion 'all arguments beginning with b' 'todo.sh b' 'bar baz'
+test_todo_completion 'all arguments beginning with f after options' 'todo.sh -a -v f' 'foobar'
+test_todo_completion 'nothing after addon action' 'todo.sh foobar ' ''
+removeCustomActions "$HOME/.todo.actions.d"
+
+#
+# Test resolution of an alternative TODO_ACTIONS_DIR.
+#
+mkdir  "$HOME/.todo"
+makeCustomActions "$HOME/.todo/actions"
+test_todo_completion 'all arguments with actions from .todo/actions/' 'todo.sh ' "$ACTIONS $ADDONS $OPTIONS"
+removeCustomActions "$HOME/.todo/actions"
+
+#
+# Test resolution of a configured TODO_ACTIONS_DIR.
+#
+makeCustomActions "$HOME/addons"
+cat >> todo.cfg <<'EOF'
+export TODO_ACTIONS_DIR="$HOME/addons"
+EOF
+test_todo_completion 'all arguments with actions from addons/' 'todo.sh ' "$ACTIONS $ADDONS $OPTIONS"
+removeCustomActions "$HOME/addons"
+
+test_done

tests/t6080-completion-path.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+#
+
+test_description='Bash completion with different path functionality
+
+This test checks that todo_completion can use a different path to todo.sh when
+it is not accessible through PATH.
+'
+. ./test-lib.sh
+
+cat > todo.txt <<EOF
+(B) smell the +roses @outside @outdoor +shared
+notice the sunflowers +sunflowers @outside @garden +shared +landscape
+stop
+EOF
+
+mv bin/todo.sh bin/todo2.sh
+test_expect_success 'todo2.sh executable' 'todo2.sh list'
+
+# Define a second completion function that injects the different executable. In
+# real use, this would be installed via
+#   complete -F _todo2 todo2.sh
+_todo2()
+{
+    local _todo_sh='todo2.sh'
+    _todo "$@"
+}
+
+test_todo_custom_completion _todo2 'all todo2 contexts' 'todo2 list @' '@garden @outdoor @outside'
+
+
+
+# Remove the test environment's bin directory from the PATH, so that our test
+# executable must be launched with an explicit path.
+PATH=${PATH##"${PWD}/bin:"}
+test_expect_code 127 'todo2.sh executable not in PATH' 'todo2.sh'
+
+_todo2path()
+{
+    local _todo_sh='./bin/todo2.sh'
+    _todo "$@"
+}
+test_todo_custom_completion _todo2path 'all todo2 contexts' 'todo2 list @' '@garden @outdoor @outside'
+
+test_done

tests/t6090-completion-aliases.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+#
+
+test_description='Bash completion with different aliases functionality
+
+This test checks that todo_completion can use a different configuration
+when another todo.sh alias is defined that uses that configuration.
+'
+. ./test-lib.sh
+
+cat > todo.txt <<EOF
+(B) smell the +roses @outside @outdoor +shared
+notice the sunflowers +sunflowers @outside @garden +shared +landscape
+stop
+EOF
+cat > todo2.txt <<EOF
++herbs @oriental buy spices
++slack @home watch tv
+EOF
+
+cp todo.cfg todo2.cfg
+cat >> todo2.cfg <<'EOF'
+export TODO_FILE="$TODO_DIR/todo2.txt"
+EOF
+
+# Note: We cannot use aliases within the test framework, but functions are
+# equivalent and work fine.
+todo1()
+{
+    todo.sh "$@"
+}
+todo2()
+{
+    todo.sh -d "$HOME/todo2.cfg" "$@"
+}
+
+# Ensure that the test fixture works as planned.
+test_todo_session 'todo 1 and 2 contexts' <<EOF
+>>> todo1 listcon
+@garden
+@outdoor
+@outside
+
+>>> todo2 listcon
+@home
+@oriental
+EOF
+
+
+# Define a second completion function that injects the different configuration
+# file. In real use, this would be installed via
+#   complete -F _todo2 todo2
+_todo2()
+{
+    local _todo_sh='todo.sh -d "$HOME/todo2.cfg"'
+    _todo "$@"
+}
+
+test_todo_completion               'all todo1 contexts' 'todo1 list @' '@garden @outdoor @outside'
+test_todo_custom_completion _todo2 'all todo2 contexts' 'todo2 list @' '@home @oriental'
+
+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 "$@"
-	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 0 "$@"
 }
 
 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
-# output4
+# output3 with empty line (must be escaped here)
+# \
+# 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
 	    ;;
@@ -632,9 +623,11 @@ EOF
 	exit 0
 }
 
-test_todo_completion () {
-	test "$#" = 3 ||
-	error "bug in the test script: not 3 parameters to test_todo_completion"
+test_todo_custom_completion () {
+	test "$#" = 4 ||
+	error "bug in the test script: not 4 parameters to test_todo_custom_completion"
+	completeFunc=$1
+	shift
 	if ! test_skip "$@"
 	then
 		description=$1
@@ -653,11 +646,11 @@ test_todo_completion () {
 		IFS=' ' set -- $2
 		COMP_WORDS=("$@")
 		COMP_CWORD=$(($# - $offset))
-		IFS=' ' set -- $expected
+		IFS=' ' eval "set -- $expected"
 		EXPECT=("$@")
 
 		source "$TEST_DIRECTORY/../todo_completion"
-		_todo
+		$completeFunc
 		ret=$?
 		if [ "$ret" = 0 ]
 		then
@@ -684,6 +677,11 @@ $(test_cmp expect compreply)"
 	fi
 	echo >&3 ""
 }
+test_todo_completion () {
+	test "$#" = 3 ||
+	error "bug in the test script: not 3 parameters to test_todo_completion"
+	test_todo_custom_completion _todo "$@"
+}
 
 test_init_todo "$test"
 # Use -P to resolve symlinks in our working directory so that the pwd

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,10 +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...]
-		    listcon|lsc
+		    listaddons
+		    listcon|lsc [TERM...]
 		    listfile|lf [SRC [TERM...]]
 		    listpri|lsp [PRIORITIES] [TERM...]
 		    listproj|lsprj [TERM...]
@@ -153,6 +154,12 @@ help()
 
 
 	EndVerboseHelp
+        actionsHelp
+        addonHelp
+}
+
+actionsHelp()
+{
     cat <<-EndActionsHelp
 		  Built-in Actions:
 		    add "THING I NEED TO DO +project @context"
@@ -199,8 +206,9 @@ help()
 		    do ITEM#[, ITEM#, ITEM#, ...]
 		      Marks task(s) on line ITEM# as done in todo.txt.
 
-		    help
-		      Display this help message.
+		    help [ACTION...]
+		      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...]
@@ -219,9 +227,13 @@ help()
 		      TERM specified, lists entire todo.txt AND done.txt
 		      concatenated and sorted.
 
-		    listcon
-		    lsc
+		    listaddons
+		      Lists all added and overridden actions in the actions directory.
+
+		    listcon [TERM...]
+		    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...]]
@@ -241,10 +253,11 @@ help()
 		      Hides all tasks that contain TERM(s) preceded by a minus sign
 		      (i.e. -TERM).  
 
-		    listproj
-		    lsprj
+		    listproj [TERM...]
+		    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]
@@ -274,9 +287,6 @@ help()
 		      List the one-line usage of all built-in and add-on actions.
 
 	EndActionsHelp
-
-        addonHelp
-    exit 1
 }
 
 addonHelp()
@@ -298,6 +308,25 @@ 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
+}
+
 die()
 {
     echo "$*"
@@ -385,21 +414,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")
-  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")
+  local -r priAndDateExpr='^\((.) \)\{0,1\}\([0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} \)\{0,1\}'
+  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 the replaced text starts with a date, it will replace the existing
-    # date, too.
+  if [ "$prepdate" -a "$action" = "replace" ] && [ "$(echo "$input"|sed -e "s/${priAndDateExpr}.*/\\1\\2/")" ]; then
+      # If the replaced text starts with a [priority +] date, it will replace
+      # 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"
@@ -854,7 +884,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' )
@@ -1071,13 +1111,19 @@ case $action in
     ;;
 
 "help" )
-    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
+    shift  ## Was help; new $1 is first help topic / action name
+    if [ $# -gt 0 ]; then
+        # Don't use PAGER here; we don't expect much usage output from one / few actions.
+        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" )
@@ -1101,7 +1147,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
@@ -1129,23 +1175,20 @@ case $action in
     ;;
 
 "listcon" | "lsc" )
-    FILE=$TODO_FILE
-    [ "$TODOTXT_SOURCEVAR" ] && eval "FILE=$TODOTXT_SOURCEVAR"
-    grep -ho '[^ ]*@[^ ]\+' "${FILE[@]}" | grep '^@' | sort -u
+    shift
+    listWordsWithSigil '@' "$@"
     ;;
 
 "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" "$@"
     ;;
 
@@ -1300,6 +1343,18 @@ note: PRIORITY must be anywhere from A to Z."
     fi
     ;;
 
+"listaddons" )
+    if [ -d "$TODO_ACTIONS_DIR" ]; then
+        cd "$TODO_ACTIONS_DIR" || exit $?
+        for action in *
+        do
+            if [ -f "$action" -a -x "$action" ]; then
+                echo "$action"
+            fi
+        done
+    fi
+    ;;
+
 * )
     usage;;
 esac

todo_completion

@@ -11,41 +11,41 @@ _todo()
     local -r OPTS="-@ -@@ -+ -++ -d -f -h -p -P -PP -a -n -t -v -vv -V -x"
     local -r COMMANDS="\
         add a addto addm append app archive command del  \
-        rm depri dp do help list ls listall lsa listcon  \
+        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)$'
 
-    # Add custom commands from add-ons, if installed.
-    # TODO: Filter for executable flag of files found in $TODO_ACTIONS_DIR.
-    local allCommands="$COMMANDS $('ls' "${TODO_ACTIONS_DIR:-$HOME/.todo.actions.d}/" 2>/dev/null)"
-
+    local _todo_sh=${_todo_sh:-todo.sh}
     local completions
     if [ $COMP_CWORD -eq 1 ]; then
-        completions="$allCommands $OPTS"
+        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-3]}" =~ ^(move|mv)$ ) ]]; then
+        "${COMP_WORDS[COMP_CWORD-2]}" =~ $MOVE_COMMAND_PATTERN || \
+        "${COMP_WORDS[COMP_CWORD-3]}" =~ $MOVE_COMMAND_PATTERN ) ]]; then
         # "move ITEM# DEST [SRC]" has file arguments on positions 2 and 3.
-        completions=$(TODOTXT_VERBOSE=0 todo.sh command listfile)
+        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=$(TODOTXT_VERBOSE=0 todo.sh command listfile);;
-            -*) completions="$allCommands $OPTS";;
+                completions=$(eval TODOTXT_VERBOSE=0 $_todo_sh command listfile);;
+            -*) completions="$COMMANDS $(eval TODOTXT_VERBOSE=0 $_todo_sh command listaddons) $OPTS";;
             *)  case "$cur" in
-                    +*) completions=$(TODOTXT_VERBOSE=0 todo.sh command listproj)
+                    +*) completions=$(eval TODOTXT_VERBOSE=0 $_todo_sh command listproj)
                         COMPREPLY=( $( compgen -W "$completions" -- $cur ))
                         [ ${#COMPREPLY[@]} -gt 0 ] && return 0
                         # Fall back to projects extracted from done tasks.
-                        completions=$(TODOTXT_VERBOSE=0 TODOTXT_SOURCEVAR=\$DONE_FILE todo.sh command listproj)
+                        completions=$(eval 'TODOTXT_VERBOSE=0 TODOTXT_SOURCEVAR=\$DONE_FILE' $_todo_sh command listproj)
                         ;;
-                    @*) completions=$(TODOTXT_VERBOSE=0 todo.sh command listcon)
+                    @*) completions=$(eval TODOTXT_VERBOSE=0 $_todo_sh command listcon)
                         COMPREPLY=( $( compgen -W "$completions" -- $cur ))
                         [ ${#COMPREPLY[@]} -gt 0 ] && return 0
                         # Fall back to contexts extracted from done tasks.
-                        completions=$(TODOTXT_VERBOSE=0 TODOTXT_SOURCEVAR=\$DONE_FILE todo.sh command listcon)
+                        completions=$(eval 'TODOTXT_VERBOSE=0 TODOTXT_SOURCEVAR=\$DONE_FILE' $_todo_sh command listcon)
                         ;;
                     *)  if [[ "$cur" =~ ^[0-9]+$ ]]; then
                             # Remove the (padded) task number; we prepend the
@@ -60,9 +60,9 @@ _todo()
                             # Finally, limit the output to a single line just as
                             # a safety check of the ls action output.
                             local todo=$( \
-                                TODOTXT_VERBOSE=0 todo.sh -@ -+ -p -x command ls "^ *${cur} " | \
-                                sed -e 's/^ *[0-9]\+ //' -e 's/\((.) \)[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/' \
+                                eval TODOTXT_VERBOSE=0 $_todo_sh '-@ -+ -p -x command ls "^ *${cur} "' | \
+                                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/[[:space:]]*$//' \
                                     -e '1q' \
                             )
@@ -84,6 +84,30 @@ _todo()
     return 0
 }
 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:
+#_todoElsewhere()
+#{
+#    local _todo_sh='/path/to/todo2.sh'
+#    _todo "$@"
+#}
+#complete -F _todoElsewhere /path/to/todo2.sh
+
+# If you use aliases to use different configuration(s), you need to add and use
+# a wrapper completion function for each configuration if you want to complete
+# fron the actual configured task locations:
+#alias todo2='todo.sh -d "$HOME/todo2.cfg"'
+#_todo2()
+#{
+#    local _todo_sh='todo.sh -d "$HOME/todo2.cfg"'
+#    _todo "$@"
+#}
+#complete -F _todo2 todo2