diff options
| -rw-r--r--[-rwxr-xr-x] | STYLE-GUIDE.md | 32 | ||||
| -rwxr-xr-x | bin/app-conf | 21 | ||||
| -rwxr-xr-x | bin/app-init | 2 | ||||
| -rwxr-xr-x | lib/common | 21 | ||||
| -rwxr-xr-x | libexec/app-cat-conf | 3 | ||||
| -rwxr-xr-x | libexec/app-install-file | 3 | ||||
| -rwxr-xr-x | libexec/app-resolver-maven | 2 | ||||
| -rwxr-xr-x | libexec/app-run-hook | 4 | ||||
| -rwxr-xr-x | test/app-conf.bats | 2 |
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>" } @@ -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" { |