process-args and usage (#22)

This PR does a few things around error cases of `process-args` and
`usage`:

* Makes `usage` no longer "magically" exit when `$?` is non-zero upon
being called.
* Drops the extra newline before a `usage --short` message.
* Makes `process-args` print out `usage --short` when reporting errors
(along with that extra newline which used to be in `usage --short`).

example/scripts/my-util

@@ -26,7 +26,7 @@ positional-arg --var=cmdName subcommand
 # The subcommand arguments (including possibly sub-subcommand names).
 rest-arg --var=args args
 
-process-args "$@" || usage --short "$?"
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/buildy/clean

@@ -24,7 +24,7 @@ define-usage --with-help $'
 # Built output directory.
 opt-value --var=outDir out
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/buildy/ls-files

@@ -78,7 +78,7 @@ function parse-rest {
     fi
 }
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/buildy/make-distro

@@ -28,7 +28,7 @@ opt-value --var=outDir out
 # Directory containing the built project.
 positional-arg --var=builtDir built-dir
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/buildy/out-dir

@@ -43,7 +43,7 @@ opt-toggle --var=doCreate create
 opt-toggle --var=doPrint print
 opt-toggle --var=doRemove remove
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/buildy/pull-repo

@@ -53,7 +53,7 @@ opt-value --var=tagSpec --filter='/./' tag
 # Repo URL.
 positional-arg --var=repoUrl repo-url
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/jarray

@@ -33,7 +33,7 @@ opt-value --var=inputStyle --init=json --enum='json strings' input
 # The array elements.
 rest-arg --var=values values
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/jget

@@ -40,7 +40,7 @@ positional-arg --required --var=value value
 # Expressions to operate on the value.
 rest-arg --var=exprArgs jval-exprs
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 if [[ ${filePath} != '' ]]; then
     if [[ ${value} != '' ]]; then

scripts/lib/bashy-basics/jlength

@@ -19,7 +19,7 @@ define-usage --with-help $'
 # JSON value.
 positional-arg --required --var=value json-value
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/jstring

@@ -20,7 +20,7 @@ define-usage --with-help $'
 # Strings to convert
 rest-arg --var=values string
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/jval

@@ -122,7 +122,7 @@ function parse-rest {
     fi
 }
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/ls-files

@@ -113,7 +113,7 @@ function parse-rest {
     fi
 }
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/rsync-local

@@ -44,7 +44,7 @@ opt-value --call='{ excludeOpts+=("--exclude=$1") }' exclude
 # Paths to copy from/to.
 rest-arg --var=paths paths
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 if (( ${#paths} < 2 )); then
     error-msg 'Must specify at least two paths.'

scripts/lib/bashy-basics/tempy/mkdir

@@ -24,7 +24,7 @@ define-usage --with-help $'
 # Prefix.
 opt-value --var=prefix --init='tmp-' prefix
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/tempy/name

@@ -26,7 +26,7 @@ define-usage --with-help $'
 # Prefix.
 opt-value --var=prefix --init='tmp-' prefix
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/timey/now-stamp

@@ -29,7 +29,7 @@ opt-value --var=prefix prefix
 # Suffix.
 opt-value --var=suffix suffix
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/timey/print

@@ -38,7 +38,7 @@ positional-arg --required --var=time time
 # Output format.
 positional-arg --var=format --filter='/^[+]/' format
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-basics/timey/secs

@@ -28,7 +28,7 @@ opt-value --var=inputType --init='secs' --enum='secs rfc822' input
 # Time value to parse.
 positional-arg --required --var=time time
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-core/_default-run

@@ -39,7 +39,7 @@ positional-arg --var=command command
 # The original command arguments, including any subcommands and other arguments.
 rest-arg --var=origArgs args
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-core/arg-processor.sh

@@ -266,14 +266,16 @@ function post-process-args-call {
 }
 
 # Processes all of the given arguments, according to the configured handlers.
-# Returns non-zero if there is trouble parsing options or if any handler returns
-# non-zero.
+# Returns normally upon successful processing. If there is any trouble parsing
+# (including if there were errors during argument/option declaration), this
+# prints the short form of the `usage` message (if `usage` is available) and
+# then returns with a non-zero code.
 function process-args {
     local _argproc_error=0
     local _argproc_s
 
     if (( _argproc_declarationError )); then
-        error-msg 'Cannot process arguments, due to declaration errors.'
+        _argproc_error-coda 'Cannot process arguments, due to declaration errors.'
         return 1
     fi
 
@@ -295,6 +297,7 @@ function process-args {
         # Don't continue if there were problems above, because that will lead to
         # spurious extra errors (e.g. "missing" a required option that was
         # present but didn't pass a validity check).
+        _argproc_error-coda
         return "${_argproc_error}"
     fi
 
@@ -303,7 +306,10 @@ function process-args {
         eval "${_argproc_s}" || _argproc_error="$?"
     done
 
-    return "${_argproc_error}"
+    if (( _argproc_error )); then
+        _argproc_error-coda
+        return "${_argproc_error}"
+    fi
 }
 
 # Requires that exactly one of the indicated arguments / options is present.
@@ -567,6 +573,21 @@ function _argproc_define-value-taking-arg {
     fi
 }
 
+# Helper for `process-args`, which prints an optional final error message and
+# then short `usage` if it is defined.
+function _argproc_error-coda {
+    local msg=("$@")
+
+    if (( ${#msg[@]} != 0 )); then
+        error-msg "${msg[@]}"
+    fi
+
+    if declare -F usage >/dev/null; then
+        error-msg ''
+        usage --short
+    fi
+}
+
 # Produces an argument handler body, from the given components.
 function _argproc_handler-body {
     local longName="$1"

scripts/lib/bashy-core/helpy/print-all-commands

@@ -28,7 +28,7 @@ opt-value --var=unitNames --filter='/^[-_.a-zA-Z0-9 ]+$/' units
 # Prefix string.
 opt-value --var=prefix prefix
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-core/helpy/print-subcommands

@@ -23,7 +23,7 @@ positional-arg --required --var=cmdName --filter='/^[-a-z]/' command
 # Subcommands if any.
 rest-arg --var=subWords --filter='/^[-a-z]/' subcommands
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-core/helpy/print-usage

@@ -33,9 +33,9 @@ define-usage --with-help $'
     --short
       Prints a short version of the <message>, intended to be the coda on some
       other error message. This only prints double-newline delimited sections
-      whose first line starts with the value of `$${name}`. In addition, it
-      prepends an extra newline at the start. Note: For this to work as intended,
-      always put a double-newline after each command summary section.
+      whose first line starts with the value of `$${name}`. Note: For this to
+      work as intended, always put a double-newline after each command summary
+      section.
 '
 
 # Command name.
@@ -47,7 +47,7 @@ opt-toggle --var=short short
 # Usage message to print.
 positional-arg --required --var=message message
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #
@@ -128,7 +128,6 @@ END {
     message = vars["message"];
 
     if (short) {
-        print "";
         print shorten(message, vars["name"]);
     } else {
         print message;

scripts/lib/bashy-core/misc.sh

@@ -19,12 +19,8 @@ _bashy_usageMessage=''
 #
 
 # Defines a standard-form `usage` function, optionally adding standardized help
-# options. When `usage` is defined with this, any non-zero pending exit code
-# (`$?`) becomes a process exit, so, for example, it is possible to say
-# something like `process-args "$@" || usage --short`, and know that that exit
-# the process on error. With option `--with-help`, this defines standard help
-# options `--help` and short form `-h`, and appends help-for-help to the
-# description.
+# options. With option `--with-help`, this defines standard help options
+# `--help` and short form `-h`, and appends help-for-help to the description.
 function define-usage {
     local withHelp=0
     if [[ $1 == --with-help ]]; then
@@ -49,11 +45,7 @@ function define-usage {
     fi
 
     local func=$'function usage {
-        local exitCode="$?"
         lib helpy print-usage --name="$(this-cmd-name)" "$@" "${_bashy_usageMessage}"
-        if (( exitCode != 0 )); then
-            exit "${exitCode}"
-        fi
     }'
 
     eval "${func}"

scripts/lib/bashy-net/cidr-calc

@@ -60,7 +60,7 @@ positional-arg --required --var=command command
 # Command arguments.
 rest-arg --var=args args
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-net/extract-public-key

@@ -37,7 +37,7 @@ opt-value --var=outputStyle --init=public-key \
 # File path.
 positional-arg --init='/dev/stdin' --var=path file-path
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-net/generate-private-key

@@ -35,7 +35,7 @@ opt-value --required --var=type \
 # Where to output.
 opt-value --var=out --init='/dev/stdout' out
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-node/node-project/build-main-module

@@ -61,7 +61,7 @@ opt-toggle --var=runNpmInstallScripts unsafely-run-npm-install-scripts
 # Project name.
 positional-arg --filter='/^[-a-z0-9]+$/' --var=projectName project-name
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-node/node-project/find-module-dependencies

@@ -48,7 +48,7 @@ require-exactly-one-arg-of modules-dir modules-dirs
 # The module to start at.
 positional-arg --required --var=moduleName module-name
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-node/node-project/fix-package-json

@@ -20,7 +20,7 @@ define-usage --with-help $'
 # Specific paths to process
 rest-arg --var=files --filter=/./ file
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/lib/bashy-node/node-project/sort-imports

@@ -21,7 +21,7 @@ define-usage --with-help $'
 # Specific paths to process
 rest-arg --var=files --filter=/./ file
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #

scripts/ubik

@@ -27,7 +27,7 @@ positional-arg --var=cmdName command
 # The actual command arguments.
 rest-arg --var=args args
 
-process-args "$@" || usage --short
+process-args "$@" || exit "$?"
 
 
 #