aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--[-rwxr-xr-x]STYLE-GUIDE.md32
-rwxr-xr-xbin/app-conf21
-rwxr-xr-xbin/app-init2
-rwxr-xr-xlib/common21
-rwxr-xr-xlibexec/app-cat-conf3
-rwxr-xr-xlibexec/app-install-file3
-rwxr-xr-xlibexec/app-resolver-maven2
-rwxr-xr-xlibexec/app-run-hook4
-rwxr-xr-xtest/app-conf.bats2
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" {