foundation for a help system where each command holds its own docs

Docs are comprised from "Usage", "Summary" and "Help" sections, where
"Help" can span multiple commented lines. If it is missing, "Summary" is
shown in its place.

References #204, references #206
This commit is contained in:
Mislav Marohnić 2012-12-13 05:48:28 +01:00
parent 7fe9231e64
commit b8715bfee6
6 changed files with 63 additions and 37 deletions

View file

@ -1,4 +1,6 @@
#!/usr/bin/env bash
# Usage: rbenv commands [ --sh | --no-sh ]
# Summary: List all rbenv commands
set -e
[ -n "$RBENV_DEBUG" ] && set -x

View file

@ -2,6 +2,51 @@
set -e
[ -n "$RBENV_DEBUG" ] && set -x
# content from single commented line marked with a word such as "Usage" or "Summary"
extract_line() {
grep "^# ${1}:" "$2" | head -1 | cut -d ' ' -f3-
}
# content of multiple consecutive commented lines starting with a word such as "Help"
extract_section() {
sed -En "/^# ${1}: /,/^[^#]/s/^# ?//p" "$2" | sed "1s/${1}: //"
}
# print aligned command names with help summary
print_summary() {
if [ ! -h "$1" ]; then
local summary=$(extract_line Summary "$1")
if [ -n "$summary" ]; then
local name=$(basename "$1")
echo "${name#rbenv-}" | awk '{ printf " %-14s ", $1 }'
echo -n $summary
echo
else
return 1
fi
fi
}
print_help() {
local usage="$(extract_line Usage "$1")"
local halp="$(extract_section Help "$1")"
[ -z "$halp" ] && halp="$(extract_line Summary "$1")"
if [ -n "$usage" ]; then
echo usage: $usage
[ -n "$halp" ] && echo && echo "$halp"
else
echo "Sorry, this command isn't documented yet." >&2
return 1
fi
}
print_summaries() {
for command in $1; do
print_summary "$(command -v rbenv-"$command")"
done
}
print_set_version() {
echo "<version> should be a string matching a Ruby version known by rbenv."
@ -21,25 +66,11 @@ case "$1" in
"") echo "usage: rbenv <command> [<args>]
Some useful rbenv commands are:
commands List all rbenv commands
rehash Rehash rbenv shims (run this after installing binaries)
global Set or show the global Ruby version
local Set or show the local directory-specific Ruby version
shell Set or show the shell-specific Ruby version
version Show the current Ruby version
versions List all Ruby versions known by rbenv
which Show the full path for the given Ruby command
whence List all Ruby versions with the given command
$(print_summaries "commands rehash global local shell version versions which whence")
See 'rbenv help <command>' for information on a specific command.
For full documentation, see: https://github.com/sstephenson/rbenv#readme"
;;
commands) echo "usage: rbenv commands
rbenv commands --sh
rbenv commands --no-sh
List all rbenv commands."
;;
global) echo "usage: rbenv global <version>
Sets the global Ruby version. You can override the global version at
@ -71,29 +102,12 @@ project-specific versions and the global version.
$(print_set_version)"
;;
versions) echo "usage: rbenv versions
rbenv versions --bare
Lists all Ruby versions known by rbenv."
;;
which) echo "usage: rbenv which <command>
Displays the full path to the binary that rbenv will execute when you
run the given command."
;;
whence) echo "usage: rbenv whence <command>
Lists all Ruby versions with the given command installed."
;;
*)
command_path="$(command -v "rbenv-$1" || true)"
if [ -n "$command_path" ]; then
echo "Sorry, the \`$1' command isn't documented yet."
echo
echo "You can view the command's source here:"
echo "$command_path"
echo
print_help "$command_path"
else
echo "rbenv: no such command \`$1'"
echo "rbenv: no such command \`$1'" >&2
exit 1
fi
esac

View file

@ -1,4 +1,6 @@
#!/usr/bin/env bash
# Usage: rbenv rehash
# Summary: Rehash rbenv shims (run this after installing binaries)
set -e
[ -n "$RBENV_DEBUG" ] && set -x

View file

@ -1,4 +1,6 @@
#!/usr/bin/env bash
# Usage: rbenv versions [--bare]
# Summary: List all Ruby versions known by rbenv
set -e
[ -n "$RBENV_DEBUG" ] && set -x

View file

@ -1,4 +1,6 @@
#!/usr/bin/env bash
# Usage: rbenv whence [--path] COMMAND
# Summary: List all Ruby versions with the given command installed
set -e
[ -n "$RBENV_DEBUG" ] && set -x
@ -27,7 +29,7 @@ whence() {
RBENV_COMMAND="$1"
if [ -z "$RBENV_COMMAND" ]; then
echo "usage: rbenv whence [--path] COMMAND" >&2
rbenv-help whence | head -1 >&2
exit 1
fi

View file

@ -1,4 +1,8 @@
#!/usr/bin/env bash
# Usage: rbenv which COMMAND
# Summary: Display full path to a binary
# Help: Displays the full path to the binary that rbenv will execute when you
# run the given command.
set -e
[ -n "$RBENV_DEBUG" ] && set -x
@ -44,7 +48,7 @@ RBENV_VERSION="$(rbenv-version-name)"
RBENV_COMMAND="$1"
if [ -z "$RBENV_COMMAND" ]; then
echo "usage: rbenv which COMMAND" >&2
rbenv-help which | head -1 >&2
exit 1
fi