FIX: Built-in action help for OS X.

POSIX sed doesn't support regex branches; I don't want to switch to modern regexp (via -E), since that makes more characters special. Rather, expand the alternatives into two sed commands.

.gitignore

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

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/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,7 +7,7 @@ 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"

tests/t6050-completion-addons.sh

@@ -7,20 +7,68 @@ 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 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'
 
 readonly ADDONS='bar baz foobar'
-mkdir "$HOME/.todo.actions.d"
-for addon in $ADDONS
-do
-    > "$HOME/.todo.actions.d/$addon"
-    chmod +x "$HOME/.todo.actions.d/$addon"
-done
+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/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

todo.sh

@@ -54,9 +54,10 @@ 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
 		    listfile|lf [SRC [TERM...]]
 		    listpri|lsp [PRIORITIES] [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,6 +227,9 @@ help()
 		      TERM specified, lists entire todo.txt AND done.txt
 		      concatenated and sorted.
 
+		    listaddons
+		      Lists all added and overridden actions in the actions directory.
+
 		    listcon
 		    lsc
 		      Lists all the task contexts that start with the @ sign in todo.txt.
@@ -274,9 +285,6 @@ help()
 		      List the one-line usage of all built-in and add-on actions.
 
 	EndActionsHelp
-
-        addonHelp
-    exit 1
 }
 
 addonHelp()
@@ -298,6 +306,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 "$*"
@@ -1071,6 +1098,11 @@ case $action in
     ;;
 
 "help" )
+    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)
@@ -1078,6 +1110,7 @@ case $action in
             fi
         fi
         help # just in case something failed above, we go ahead and just spew to STDOUT
+    fi
     ;;
 
 "shorthelp" )
@@ -1300,6 +1333,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,18 +11,14 @@ _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"
 
-    # 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
@@ -32,9 +28,11 @@ _todo()
         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="$allCommands $OPTS";;
+            -*) completions="$COMMANDS $(eval TODOTXT_VERBOSE=0 $_todo_sh command listaddons) $OPTS";;
             *)  case "$cur" in
                     +*) completions=$(eval TODOTXT_VERBOSE=0 $_todo_sh command listproj)
                         COMPREPLY=( $( compgen -W "$completions" -- $cur ))
@@ -62,7 +60,7 @@ _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]\+ //' -e 's/\((.) \)[0-9]\{2,4\}-[0-9]\{2\}-[0-9]\{2\} /\1/' \
+                                sed -e 's/^ *[0-9]\{1,\} //' -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/' \
                                     -e 's/[[:space:]]*$//' \
                                     -e '1q' \