From 4c19dc22d7b1f674058acb95d51bde417dc80a62 Mon Sep 17 00:00:00 2001 From: Sam Stephenson Date: Sat, 29 Dec 2012 12:06:20 -0600 Subject: [PATCH] Improve syntax for inline documentation and allow for multi-line usage --- libexec/rbenv-commands | 5 +- libexec/rbenv-global | 13 +++ libexec/rbenv-help | 195 ++++++++++++++++++++++------------------- libexec/rbenv-local | 19 ++++ libexec/rbenv-rehash | 3 +- libexec/rbenv-sh-shell | 14 +++ libexec/rbenv-version | 2 + libexec/rbenv-versions | 3 +- libexec/rbenv-whence | 3 +- libexec/rbenv-which | 10 ++- 10 files changed, 170 insertions(+), 97 deletions(-) diff --git a/libexec/rbenv-commands b/libexec/rbenv-commands index 67bc7fb9..58aab012 100755 --- a/libexec/rbenv-commands +++ b/libexec/rbenv-commands @@ -1,6 +1,7 @@ #!/usr/bin/env bash -# Usage: rbenv commands [ --sh | --no-sh ] -# Summary: List all rbenv commands +# Summary: List all available rbenv commands +# Usage: rbenv commands [--sh|--no-sh] + set -e [ -n "$RBENV_DEBUG" ] && set -x diff --git a/libexec/rbenv-global b/libexec/rbenv-global index 2f68f2ec..c003359b 100755 --- a/libexec/rbenv-global +++ b/libexec/rbenv-global @@ -1,4 +1,17 @@ #!/usr/bin/env bash +# +# Summary: Set or show the global Ruby version +# +# Usage: rbenv global +# +# Sets the global Ruby version. You can override the global version at +# any time by setting a directory-specific version with `rbenv local' +# or by setting the `RBENV_VERSION' environment variable. +# +# should be a string matching a Ruby version known to rbenv. +# The special version string `system' will use your default system Ruby. +# Run `rbenv versions' for a list of available Ruby versions. + set -e [ -n "$RBENV_DEBUG" ] && set -x diff --git a/libexec/rbenv-help b/libexec/rbenv-help index 7a710512..00eaab15 100755 --- a/libexec/rbenv-help +++ b/libexec/rbenv-help @@ -2,112 +2,129 @@ 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- +command_path() { + local command="$1" + command -v rbenv-"$command" || command -v rbenv-sh-"$command" || true } -# content of multiple consecutive commented lines starting with a word such as "Help" -extract_section() { - sed -En "/^# ${1}: /,/^[^#]/s/^# ?//p" "$2" | sed "1s/${1}: //" +extract_initial_comment_block() { + sed -ne " + /^#/ !{ + q + } + + s/^#$/# / + + /^# / { + s/^# // + p + } + " } -# 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 +collect_documentation() { + awk ' + /^Summary:/ { + summary = substr($0, 10) + next + } + + /^Usage:/ { + reading_usage = 1 + usage = usage "\n" $0 + next + } + + /^( *$| )/ && reading_usage { + usage = usage "\n" $0 + next + } + + /^([^ ]|$)/ { + reading_usage = 0 + help = help "\n" $0 + } + + function escape(str) { + gsub(/[`\\$"]/, "\\\\&", str) + return str + } + + function trim(str) { + gsub(/^\n*/, "", str) + gsub(/\n*$/, "", str) + return str + } + + END { + if (usage || summary) { + print "summary=\"" escape(summary) "\"" + print "usage=\"" escape(trim(usage)) "\"" + print "help=\"" escape(trim(help)) "\"" + } + } + ' +} + +documentation_for() { + local filename="$(command_path "$1")" + if [ -n "$filename" ]; then + extract_initial_comment_block < "$filename" | collect_documentation fi } +print_summary() { + local command="$1" + local summary usage help + eval "$(documentation_for "$command")" + + if [ -n "$summary" ]; then + printf " %-9s %s\n" "$command" "$summary" + else + return 1 + fi +} + +print_summaries() { + for command; do + print_summary "$command" + done +} + print_help() { - local usage="$(extract_line Usage "$1")" - local halp="$(extract_section Help "$1")" - [ -z "$halp" ] && halp="$(extract_line Summary "$1")" + local command="$1" + local summary usage help + eval "$(documentation_for "$command")" + [ -n "$help" ] || help="$summary" if [ -n "$usage" ]; then - echo usage: $usage - [ -n "$halp" ] && echo && echo "$halp" + echo "$usage" + if [ -n "$help" ]; then + echo + echo "$help" + echo + fi 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 " should be a string matching a Ruby version known by rbenv." - - local versions="$(rbenv-versions --bare)" - if [ -z "$versions" ]; then - echo "There are currently no Ruby versions installed for rbenv." - else - echo "The currently installed Ruby versions are:" - echo "$versions" | sed 's/^/ /' - fi - +if [ -z "$1" ]; then + rbenv---version + echo "Usage: rbenv []" echo - echo "The special version string 'system' will use your default system Ruby." -} - -case "$1" in -"") echo "usage: rbenv [] - -Some useful rbenv commands are: -$(print_summaries "commands rehash global local shell version versions which whence") - -See 'rbenv help ' for information on a specific command. -For full documentation, see: https://github.com/sstephenson/rbenv#readme" -;; -global) echo "usage: rbenv global - -Sets the global Ruby version. You can override the global version at -any time by setting a directory-specific version with \`rbenv local' -or by setting the RBENV_VERSION environment variable. - -$(print_set_version)" -;; -local) echo "usage: rbenv local - rbenv local --unset - -Sets the local directory-specific Ruby version by writing the version -name to a file named '.rbenv-version'. - -When you run a Ruby command, rbenv will look for an '.rbenv-version' -file in the current directory and each parent directory. If no such -file is found in the tree, rbenv will use the global Ruby version -specified with \`rbenv global', or the version specified in the -RBENV_VERSION environment variable. - -$(print_set_version)" -;; -shell) echo "usage: rbenv shell - rbenv shell --unset - -Sets a shell-specific Ruby version by setting the 'RBENV_VERSION' -environment variable in your shell. This version overrides both -project-specific versions and the global version. - -$(print_set_version)" -;; -*) - command_path="$(command -v "rbenv-$1" || true)" - if [ -n "$command_path" ]; then - print_help "$command_path" + echo "Some useful rbenv commands are:" + print_summaries commands rehash global local shell version versions which whence + echo + echo "See \`rbenv help ' for information on a specific command." + echo "For full documentation, see: https://github.com/sstephenson/rbenv#readme" +else + command="$1" + if [ -n "$(command_path "$command")" ]; then + print_help "$command" else - echo "rbenv: no such command \`$1'" >&2 + echo "rbenv: no such command \`$command'" >&2 exit 1 fi -esac +fi diff --git a/libexec/rbenv-local b/libexec/rbenv-local index 9b102c5c..a0b3fe76 100755 --- a/libexec/rbenv-local +++ b/libexec/rbenv-local @@ -1,4 +1,23 @@ #!/usr/bin/env bash +# +# Summary: Set or show the local directory-specific Ruby version +# +# Usage: rbenv local +# rbenv local --unset +# +# Sets the local directory-specific Ruby version by writing the version +# name to a file named `.rbenv-version'. +# +# When you run a Ruby command, rbenv will look for an `.rbenv-version' +# file in the current directory and each parent directory. If no such +# file is found in the tree, rbenv will use the global Ruby version +# specified with `rbenv global', or the version specified in the +# RBENV_VERSION environment variable. +# +# should be a string matching a Ruby version known to rbenv. +# The special version string `system' will use your default system Ruby. +# Run `rbenv versions' for a list of available Ruby versions. + set -e [ -n "$RBENV_DEBUG" ] && set -x diff --git a/libexec/rbenv-rehash b/libexec/rbenv-rehash index 916323a3..0f147385 100755 --- a/libexec/rbenv-rehash +++ b/libexec/rbenv-rehash @@ -1,6 +1,7 @@ #!/usr/bin/env bash -# Usage: rbenv rehash # Summary: Rehash rbenv shims (run this after installing binaries) +# Usage: rbenv rehash + set -e [ -n "$RBENV_DEBUG" ] && set -x diff --git a/libexec/rbenv-sh-shell b/libexec/rbenv-sh-shell index 34a0a354..d49eaa52 100755 --- a/libexec/rbenv-sh-shell +++ b/libexec/rbenv-sh-shell @@ -1,4 +1,18 @@ #!/usr/bin/env bash +# +# Summary: Set or show the shell-specific Ruby version +# +# Usage: rbenv shell +# rbenv shell --unset +# +# Sets a shell-specific Ruby version by setting the `RBENV_VERSION' +# environment variable in your shell. This version overrides both +# project-specific versions and the global version. +# +# should be a string matching a Ruby version known to rbenv. +# The special version string `system' will use your default system Ruby. +# Run `rbenv versions' for a list of available Ruby versions. + set -e [ -n "$RBENV_DEBUG" ] && set -x diff --git a/libexec/rbenv-version b/libexec/rbenv-version index 7251a4c9..82624ff1 100755 --- a/libexec/rbenv-version +++ b/libexec/rbenv-version @@ -1,4 +1,6 @@ #!/usr/bin/env bash +# Summary: Show the current Ruby version + set -e [ -n "$RBENV_DEBUG" ] && set -x diff --git a/libexec/rbenv-versions b/libexec/rbenv-versions index 46b8a021..3fcf1ef9 100755 --- a/libexec/rbenv-versions +++ b/libexec/rbenv-versions @@ -1,6 +1,7 @@ #!/usr/bin/env bash -# Usage: rbenv versions [--bare] # Summary: List all Ruby versions known by rbenv +# Usage: rbenv versions [--bare] + set -e [ -n "$RBENV_DEBUG" ] && set -x diff --git a/libexec/rbenv-whence b/libexec/rbenv-whence index 5e49d527..5bb499b9 100755 --- a/libexec/rbenv-whence +++ b/libexec/rbenv-whence @@ -1,6 +1,7 @@ #!/usr/bin/env bash -# Usage: rbenv whence [--path] COMMAND # Summary: List all Ruby versions with the given command installed +# Usage: rbenv whence [--path] COMMAND + set -e [ -n "$RBENV_DEBUG" ] && set -x diff --git a/libexec/rbenv-which b/libexec/rbenv-which index 3cdddd01..6c62f5ca 100755 --- a/libexec/rbenv-which +++ b/libexec/rbenv-which @@ -1,8 +1,12 @@ #!/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 +# +# Summary: Display the full path to a binary +# +# Usage: rbenv which +# +# Displays the full path to the binary that rbenv will execute when you # run the given command. + set -e [ -n "$RBENV_DEBUG" ] && set -x