o Consistent usage() usage/flow.

9 files changed, 59 insertions, 31 deletions

diff --git a/STYLE-GUIDE.md b/STYLE-GUIDE.md
index dc897ba..2f9c6e6 100755..100644
--- a/STYLE-GUIDE.md
+++ b/STYLE-GUIDE.md
@@ -6,17 +6,37 @@ Basic
 
 * Indent: two spaces. Spaces >> tabs.
 
-Creating `usage()`
-==================
+Creating `usage()` and `help()`
+===============================
+
+The general semantics
+---------------------
+
+When the user requests help through `-h` or no arguments,
+`show_help()` should be used. This will output the info on stdout
+because the user explicitly requested so. If the user gives some form
+of invalid argument or there is any other error the usage should go to
+stderr because the user might be using pipes.
+
+
+How app.sh does it
+------------------
+
+Each command should implement `usage_text`. The command should call
+`show_help()` and `usage()` as appropriate. These functions are
+defined in `lib/common` and will both call `usage_app()` to get the
+usage info. `usage()` will send the info to stderr.
+
+* `show_help()` will exit with 0, while `usage()` will exit with code 1.
+
+Formatting of usage output
+--------------------------
 
-* Always echo to `stderr`.
-* Exit with code 1.
 * Enclose required arguments in angle brackets: `-v <version>`
 * Enclose optional arguments in square brackets: `[-h hook]`
 
-    usage() {
+    usage_text() {
       echo "usage: $0 -v <version> [-h hook]"
-      exit 1
     }
 
 Executing Commands
diff --git a/bin/app-conf b/bin/app-conf
index 3cf0383..2681f59 100755
--- a/bin/app-conf
+++ b/bin/app-conf
@@ -69,20 +69,15 @@ conf_import() {
   mv "$dst.tmp" "$dst" 
 }
 
-usage() {
-  if [ $# -gt 0 ]
-  then
-    echo "Error: $@" >&2
-  fi
-
-  echo "usage: $0 conf <command>" >&2
+usage_text() {
+  echo "usage: $0 conf <command>"
   echo ""
-  echo "Available commands:" >&2
-  echo "  get [name]         - returns a single value" >&2
-  echo "  list               - list all config values" >&2
-  echo "  set [name] [value] - set a config parameter" >&2
-  echo "  delete [name]      - deletes a config parameter" >&2
-  echo "  import [file]      - import a file" >&2
+  echo "Available commands:"
+  echo "  get [name]         - returns a single value"
+  echo "  list               - list all config values"
+  echo "  set [name] [value] - set a config parameter"
+  echo "  delete [name]      - deletes a config parameter"
+  echo "  import [file]      - import a file"
   exit 1
 }
 
diff --git a/bin/app-init b/bin/app-init
index ba97ebd..c59ba77 100755
--- a/bin/app-init
+++ b/bin/app-init
@@ -8,7 +8,7 @@ APPSH_HOME=$(cd $(dirname "$0")/.. && pwd)
 . $APPSH_HOME/lib/common
 # HEADER END
 
-usage_inner() {
+usage_text() {
   echo "usage: $usage_app -d dir <resolver> <resolver args>"
 }
 
diff --git a/lib/common b/lib/common
index 63f712a..0c8cdbd 100755
--- a/lib/common
+++ b/lib/common
@@ -40,7 +40,7 @@ assert_is_app() {
   fi
 }
 
-usage() {
+show_help() {
   message=${1-}
 
   if [[ $message != "" ]]
@@ -48,9 +48,24 @@ usage() {
     echo $message
   fi
 
-  if [ "`declare -f usage_inner >/dev/null; echo $?`" = 0 ]
+  if [ "`declare -f usage_text >/dev/null; echo $?`" = 0 ]
+  then
+    usage_text
+  fi
+  exit 1
+}
+
+usage() {
+  message=${1-}
+
+  if [[ $message != "" ]]
+  then
+    echo $message >&2
+  fi
+
+  if [ "`declare -f usage_text >/dev/null; echo $?`" = 0 ]
   then
-    usage_inner >&2
+    usage_text >&2
   fi
   exit 1
 }
diff --git a/libexec/app-cat-conf b/libexec/app-cat-conf
index c75955b..af382f7 100755
--- a/libexec/app-cat-conf
+++ b/libexec/app-cat-conf
@@ -32,8 +32,7 @@ do
       name=$OPTARG
       ;;
     \?)
-      echo "Invalid option: $OPTARG" >&2
-      exit 1
+      usage "Invalid option: $OPTARG"
       ;;
   esac
 done
diff --git a/libexec/app-install-file b/libexec/app-install-file
index c08a632..e2707a0 100755
--- a/libexec/app-install-file
+++ b/libexec/app-install-file
@@ -8,9 +8,8 @@ APPSH_HOME=$(cd $(dirname "$0")/.. && pwd)
 . $APPSH_HOME/lib/common
 # HEADER END
 
-usage() {
+usage_text() {
   echo "usage: $0 -v <version> -f <file>"
-  exit 1
 }
 
 version=
diff --git a/libexec/app-resolver-maven b/libexec/app-resolver-maven
index 81e85ab..8394ee1 100755
--- a/libexec/app-resolver-maven
+++ b/libexec/app-resolver-maven
@@ -8,7 +8,7 @@ APPSH_HOME=$(cd $(dirname "$0")/.. && pwd)
 . $APPSH_HOME/lib/common
 # HEADER END
 
-usage_inner() {
+usage_text() {
   echo "usage: $usage_app init -r <repo> <maven url>"
   echo "usage: $usage_app resolve-version"
   echo "usage: $usage_app download-version -v <version> -f <download target>"
diff --git a/libexec/app-run-hook b/libexec/app-run-hook
index 6f1eab5..f1b2457 100755
--- a/libexec/app-run-hook
+++ b/libexec/app-run-hook
@@ -8,8 +8,8 @@ APPSH_HOME=$(cd $(dirname "$0")/.. && pwd)
 . $APPSH_HOME/lib/common
 # HEADER END
 
-usage() {
-  echo "usage: $usage_app -v [version] -h [hook]" 2>&1
+usage_text() {
+  echo "usage: $usage_app -v [version] -h [hook]"
 }
 
 version=
diff --git a/test/app-conf.bats b/test/app-conf.bats
index e805ff3..257564b 100755
--- a/test/app-conf.bats
+++ b/test/app-conf.bats
@@ -54,7 +54,7 @@ setup_inner() {
 @test "./app conf wat" {
   app conf wat; echo_lines
   eq '$status' 1
-  eq '${lines[0]}' "Error: Unknown command: wat" 
+  eq '${lines[0]}' "Unknown command: wat" 
 }
 
 @test "./app conf list" {