From b8715bfee6fe11aa1a09397859b55a01bfe33ac7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohnic=CC=81?= Date: Thu, 13 Dec 2012 05:48:28 +0100 Subject: [PATCH] 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 --- libexec/rbenv-commands | 2 + libexec/rbenv-help | 84 ++++++++++++++++++++++++------------------ libexec/rbenv-rehash | 2 + libexec/rbenv-versions | 2 + libexec/rbenv-whence | 4 +- libexec/rbenv-which | 6 ++- 6 files changed, 63 insertions(+), 37 deletions(-) diff --git a/libexec/rbenv-commands b/libexec/rbenv-commands index 297f8d99..67bc7fb9 100755 --- a/libexec/rbenv-commands +++ b/libexec/rbenv-commands @@ -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 diff --git a/libexec/rbenv-help b/libexec/rbenv-help index e1cbaf57..7a710512 100755 --- a/libexec/rbenv-help +++ b/libexec/rbenv-help @@ -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 " should be a string matching a Ruby version known by rbenv." @@ -21,25 +66,11 @@ case "$1" in "") echo "usage: rbenv [] 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 ' 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 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 - -Displays the full path to the binary that rbenv will execute when you -run the given command." -;; -whence) echo "usage: rbenv whence - -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 diff --git a/libexec/rbenv-rehash b/libexec/rbenv-rehash index eebc4d3c..13bd7938 100755 --- a/libexec/rbenv-rehash +++ b/libexec/rbenv-rehash @@ -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 diff --git a/libexec/rbenv-versions b/libexec/rbenv-versions index 346800a3..46b8a021 100755 --- a/libexec/rbenv-versions +++ b/libexec/rbenv-versions @@ -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 diff --git a/libexec/rbenv-whence b/libexec/rbenv-whence index 8a926877..5e49d527 100755 --- a/libexec/rbenv-whence +++ b/libexec/rbenv-whence @@ -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 diff --git a/libexec/rbenv-which b/libexec/rbenv-which index 204988b2..3cdddd01 100755 --- a/libexec/rbenv-which +++ b/libexec/rbenv-which @@ -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