From da0699845797817e74228e61678449f6fcbcc3f6 Mon Sep 17 00:00:00 2001 From: Yamashita Yuu Date: Fri, 18 Jan 2013 17:41:41 +0900 Subject: [PATCH] import rbenv-help from rbenv 0.4.0 --- libexec/pyenv-commands | 3 + libexec/pyenv-completions | 4 +- libexec/pyenv-exec | 17 ++- libexec/pyenv-global | 13 ++ libexec/pyenv-help | 237 +++++++++++++++++++------------ libexec/pyenv-hooks | 5 +- libexec/pyenv-init | 3 + libexec/pyenv-local | 24 ++++ libexec/pyenv-prefix | 7 + libexec/pyenv-rehash | 2 + libexec/pyenv-root | 1 + libexec/pyenv-sh-pop | 1 + libexec/pyenv-sh-push | 1 + libexec/pyenv-sh-shell | 14 ++ libexec/pyenv-shims | 3 + libexec/pyenv-version | 6 + libexec/pyenv-version-file | 1 + libexec/pyenv-version-file-read | 1 + libexec/pyenv-version-file-write | 4 +- libexec/pyenv-version-name | 1 + libexec/pyenv-version-origin | 1 + libexec/pyenv-versions | 5 + libexec/pyenv-whence | 5 +- libexec/pyenv-which | 10 +- 24 files changed, 276 insertions(+), 93 deletions(-) diff --git a/libexec/pyenv-commands b/libexec/pyenv-commands index f526515a..14e8e6af 100755 --- a/libexec/pyenv-commands +++ b/libexec/pyenv-commands @@ -1,4 +1,7 @@ #!/usr/bin/env bash +# Summary: List all available pyenv commands +# Usage: pyenv commands [--sh|--no-sh] + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-completions b/libexec/pyenv-completions index bd2dbb43..c6785caa 100755 --- a/libexec/pyenv-completions +++ b/libexec/pyenv-completions @@ -1,10 +1,12 @@ #!/usr/bin/env bash +# Usage: pyenv completions [arg1 arg2...] + set -e [ -n "$PYENV_DEBUG" ] && set -x COMMAND="$1" if [ -z "$COMMAND" ]; then - echo "usage: pyenv completions COMMAND [arg1 arg2...]" >&2 + pyenv-help --usage completions >&2 exit 1 fi diff --git a/libexec/pyenv-exec b/libexec/pyenv-exec index 0b07db8f..30f4191e 100755 --- a/libexec/pyenv-exec +++ b/libexec/pyenv-exec @@ -1,4 +1,18 @@ #!/usr/bin/env bash +# +# Summary: Run an executable with the selected Python version +# +# Usage: pyenv exec [arg1 arg2...] +# +# Runs an executable by first preparing PATH so that the selected Python +# version's `bin' directory is at the front. +# +# For example, if the currently selected Python version is 2.7.7: +# pyenv exec pip install -rrequirements.txt +# +# is equivalent to: +# PATH="$PYENV_ROOT/versions/2.7.7/bin:$PATH" pip install -rrequirements.txt + set -e [ -n "$PYENV_DEBUG" ] && set -x @@ -8,8 +22,9 @@ if [ "$1" = "--complete" ]; then fi PYENV_COMMAND="$1" + if [ -z "$PYENV_COMMAND" ]; then - echo "usage: pyenv exec COMMAND [arg1 arg2...]" >&2 + pyenv-help --usage exec >&2 exit 1 fi diff --git a/libexec/pyenv-global b/libexec/pyenv-global index f3dc712b..2bc13ce4 100755 --- a/libexec/pyenv-global +++ b/libexec/pyenv-global @@ -1,4 +1,17 @@ #!/usr/bin/env bash +# +# Summary: Set or show the global Python version +# +# Usage: pyenv global +# +# Sets the global Python version. You can override the global version at +# any time by setting a directory-specific version with `pyenv local' +# or by setting the `PYENV_VERSION' environment variable. +# +# should be a string matching a Python version known to pyenv. +# The special version string `system' will use your default system Python. +# Run `pyenv versions' for a list of available Python versions. + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-help b/libexec/pyenv-help index 4767592c..d6db968d 100755 --- a/libexec/pyenv-help +++ b/libexec/pyenv-help @@ -1,99 +1,162 @@ #!/usr/bin/env bash +# +# Summary: Display help for a command +# +# Usage: pyenv help [--usage] COMMAND +# +# Parses and displays help contents from a command's source file. +# +# A command is considered documented if it starts with a comment block +# that has a `Summary:' or `Usage:' section. Usage instructions can +# span multiple lines as long as subsequent lines are indented. +# The remainder of the comment block is displayed as extended +# documentation. + set -e [ -n "$PYENV_DEBUG" ] && set -x -print_set_version() { - echo " should be a string matching a Python version known by pyenv." +command_path() { + local command="$1" + command -v pyenv-"$command" || command -v pyenv-sh-"$command" || true +} + +extract_initial_comment_block() { + sed -ne " + /^#/ !{ + q + } + + s/^#$/# / + + /^# / { + s/^# // + p + } + " +} + +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" + fi +} + +print_summaries() { + for command; do + print_summary "$command" + done +} - local versions="$(pyenv-versions --bare)" - if [ -z "$versions" ]; then - echo "There are currently no Python versions installed for pyenv." +print_help() { + local command="$1" + local summary usage help + eval "$(documentation_for "$command")" + [ -n "$help" ] || help="$summary" + + if [ -n "$usage" -o -n "$summary" ]; then + if [ -n "$usage" ]; then + echo "$usage" + else + echo "Usage: pyenv ${command}" + fi + if [ -n "$help" ]; then + echo + echo "$help" + echo + fi else - echo "The currently installed Python versions are:" - echo "$versions" | sed 's/^/ /' + echo "Sorry, this command isn't documented yet." >&2 + return 1 fi +} - echo - echo "The special version string 'system' will use your default system Python" +print_usage() { + local command="$1" + local summary usage help + eval "$(documentation_for "$command")" + [ -z "$usage" ] || echo "$usage" } -case "$1" in -"") echo "usage: pyenv [] - -Some useful pyenv commands are: - commands List all pyenv commands - rehash Rehash pyenv shims (run this after installing binaries) - global Set or show the global Python version - local Set or show the local directory-specific Python version - shell Set or show the shell-specific Python version - version Show the current Python version - versions List all Python versions known by pyenv - which Show the full path for the given Python command - whence List all Python versions with the given command - -See 'pyenv help ' for information on a specific command. -For full documentation, see: https://github.com/yyuu/pyenv#readme" -;; -commands) echo "usage: pyenv commands - pyenv commands --sh - pyenv commands --no-sh - -List all pyenv commands." -;; -global) echo "usage: pyenv global - -Sets the global Python version. You can override the global version at -any time by setting a directory-specific version with \`pyenv local' -or by setting the PYENV_VERSION environment variable. - -$(print_set_version)" -;; -local) echo "usage: pyenv local - pyenv local --unset - -Sets the local directory-specific Python version by writing the version -name to a file named '.pyenv-version'. - -When you run a Python command, pyenv will look for an '.pyenv-version' -file in the current directory and each parent directory. If no such -file is found in the tree, pyenv will use the global Python version -specified with \`pyenv global', or the version specified in the -PYENV_VERSION environment variable. - -$(print_set_version)" -;; -shell) echo "usage: pyenv shell - pyenv shell --unset - -Sets a shell-specific Python version by setting the 'PYENV_VERSION' -environment variable in your shell. This version overrides both -project-specific versions and the global version. - -$(print_set_version)" -;; -versions) echo "usage: pyenv versions - pyenv versions --bare - -Lists all Python versions known by pyenv." -;; -which) echo "usage: pyenv which - -Displays the full path to the binary that pyenv will execute when you -run the given command." -;; -whence) echo "usage: pyenv whence - -Lists all Python versions with the given command installed." -;; -*) - command_path="$(command -v "pyenv-$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 +unset usage +if [ "$1" = "--usage" ]; then + usage="1" + shift +fi + +if [ -z "$1" ] || [ "$1" == "pyenv" ]; then + echo "Usage: pyenv []" + [ -z "$usage" ] || exit + echo + echo "Some useful pyenv commands are:" + print_summaries commands local global shell install uninstall rehash version versions which whence + echo + echo "See \`pyenv help ' for information on a specific command." + echo "For full documentation, see: https://github.com/yyuu/pyenv#readme" +else + command="$1" + if [ -n "$(command_path "$command")" ]; then + if [ -n "$usage" ]; then + print_usage "$command" + else + print_help "$command" + fi else - echo "pyenv: no such command \`$1'" + echo "pyenv: no such command \`$command'" >&2 + exit 1 fi -esac +fi diff --git a/libexec/pyenv-hooks b/libexec/pyenv-hooks index ec98a545..8394138b 100755 --- a/libexec/pyenv-hooks +++ b/libexec/pyenv-hooks @@ -1,4 +1,7 @@ #!/usr/bin/env bash +# Summary: List hook scripts for a given pyenv command +# Usage: pyenv hooks + set -e [ -n "$PYENV_DEBUG" ] && set -x @@ -12,7 +15,7 @@ fi PYENV_COMMAND="$1" if [ -z "$PYENV_COMMAND" ]; then - echo "usage: pyenv hooks COMMAND" >&2 + pyenv-help --usage hooks >&2 exit 1 fi diff --git a/libexec/pyenv-init b/libexec/pyenv-init index c5bb3a1e..f8012827 100755 --- a/libexec/pyenv-init +++ b/libexec/pyenv-init @@ -1,4 +1,7 @@ #!/usr/bin/env bash +# Summary: Configure the shell environment for pyenv +# Usage: eval "$(pyenv init - [--no-rehash] [])" + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-local b/libexec/pyenv-local index c7c72d35..66f63c1a 100755 --- a/libexec/pyenv-local +++ b/libexec/pyenv-local @@ -1,4 +1,28 @@ #!/usr/bin/env bash +# +# Summary: Set or show the local application-specific Python version +# +# Usage: pyenv local +# pyenv local --unset +# +# Sets the local application-specific Python version by writing the +# version name to a file named `.python-version'. +# +# When you run a Python command, pyenv will look for a `.python-version' +# file in the current directory and each parent directory. If no such +# file is found in the tree, pyenv will use the global Python version +# specified with `pyenv global'. A version specified with the +# `PYENV_VERSION' environment variable takes precedence over local +# and global versions. +# +# For backwards compatibility, pyenv will also read version +# specifications from `.pyenv-version' files, but a `.python-version' +# file in the same directory takes precedence. +# +# should be a string matching a Python version known to pyenv. +# The special version string `system' will use your default system Python. +# Run `pyenv versions' for a list of available Python versions. + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-prefix b/libexec/pyenv-prefix index 287ad4f9..1ee317bb 100755 --- a/libexec/pyenv-prefix +++ b/libexec/pyenv-prefix @@ -1,4 +1,11 @@ #!/usr/bin/env bash +# Summary: Display prefix for a Python version +# Usage: pyenv prefix [] +# +# Displays the directory where a Python version is installed. If no +# version is given, `pyenv prefix' displays the location of the +# currently selected version. + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-rehash b/libexec/pyenv-rehash index d76f862d..13c327b3 100755 --- a/libexec/pyenv-rehash +++ b/libexec/pyenv-rehash @@ -1,4 +1,6 @@ #!/usr/bin/env bash +# Summary: Rehash pyenv shims (run this after installing executables) + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-root b/libexec/pyenv-root index 0468423e..6669caa2 100755 --- a/libexec/pyenv-root +++ b/libexec/pyenv-root @@ -1,2 +1,3 @@ #!/usr/bin/env bash +# Summary: Display the root directory where versions and shims are kept echo $PYENV_ROOT diff --git a/libexec/pyenv-sh-pop b/libexec/pyenv-sh-pop index 944422d3..cf39750a 100755 --- a/libexec/pyenv-sh-pop +++ b/libexec/pyenv-sh-pop @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# Usage: pyenv pop set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-sh-push b/libexec/pyenv-sh-push index 5ab3ee33..9b2f4944 100755 --- a/libexec/pyenv-sh-push +++ b/libexec/pyenv-sh-push @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# Usage: pyenv push set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-sh-shell b/libexec/pyenv-sh-shell index 5b47b739..e33c47e4 100755 --- a/libexec/pyenv-sh-shell +++ b/libexec/pyenv-sh-shell @@ -1,4 +1,18 @@ #!/usr/bin/env bash +# +# Summary: Set or show the shell-specific Python version +# +# Usage: pyenv shell +# pyenv shell --unset +# +# Sets a shell-specific Python version by setting the `PYENV_VERSION' +# environment variable in your shell. This version overrides local +# application-specific versions and the global version. +# +# should be a string matching a Python version known to pyenv. +# The special version string `system' will use your default system Python. +# Run `pyenv versions' for a list of available Python versions. + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-shims b/libexec/pyenv-shims index f4fb8b86..3aae3caf 100755 --- a/libexec/pyenv-shims +++ b/libexec/pyenv-shims @@ -1,4 +1,7 @@ #!/usr/bin/env bash +# Summary: List existing pyenv shims +# Usage: pyenv shims [--short] + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-version b/libexec/pyenv-version index 992b1261..efd9eadc 100755 --- a/libexec/pyenv-version +++ b/libexec/pyenv-version @@ -1,4 +1,10 @@ #!/usr/bin/env bash +# Summary: Show the current Python version and its origin +# +# Shows the currently selected Python version and how it was +# selected. To obtain only the version string, use `pyenv +# version-name'. + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-version-file b/libexec/pyenv-version-file index ddd88076..cd15373b 100755 --- a/libexec/pyenv-version-file +++ b/libexec/pyenv-version-file @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# Summary: Detect the file that sets the current pyenv version set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-version-file-read b/libexec/pyenv-version-file-read index 9fed7f69..c29577d8 100755 --- a/libexec/pyenv-version-file-read +++ b/libexec/pyenv-version-file-read @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# Usage: pyenv version-file-read set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-version-file-write b/libexec/pyenv-version-file-write index cca0c36a..c826df40 100755 --- a/libexec/pyenv-version-file-write +++ b/libexec/pyenv-version-file-write @@ -1,4 +1,6 @@ #!/usr/bin/env bash +# Usage: pyenv version-file-write + set -e [ -n "$PYENV_DEBUG" ] && set -x @@ -7,7 +9,7 @@ shift versions=("$@") if [ -z "$versions" ] || [ -z "$PYENV_VERSION_FILE" ]; then - echo "usage: pyenv write-version-file FILENAME VERSIONS..." >&2 + pyenv-help --usage version-file-write >&2 exit 1 fi diff --git a/libexec/pyenv-version-name b/libexec/pyenv-version-name index 45646a07..85d9c1d0 100755 --- a/libexec/pyenv-version-name +++ b/libexec/pyenv-version-name @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# Summary: Show the current Python version set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-version-origin b/libexec/pyenv-version-origin index 2c826b15..9f5259f9 100755 --- a/libexec/pyenv-version-origin +++ b/libexec/pyenv-version-origin @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# Summary: Explain how the current Python version is set set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-versions b/libexec/pyenv-versions index b784d2c7..3dac25e3 100755 --- a/libexec/pyenv-versions +++ b/libexec/pyenv-versions @@ -1,4 +1,9 @@ #!/usr/bin/env bash +# Summary: List all Python versions available to pyenv +# Usage: pyenv versions [--bare] +# +# Lists all Python versions found in `$PYENV_ROOT/versions/*'. + set -e [ -n "$PYENV_DEBUG" ] && set -x diff --git a/libexec/pyenv-whence b/libexec/pyenv-whence index b9ba8381..101c5e27 100755 --- a/libexec/pyenv-whence +++ b/libexec/pyenv-whence @@ -1,4 +1,7 @@ #!/usr/bin/env bash +# Summary: List all Python versions that contain the given executable +# Usage: pyenv whence [--path] + set -e [ -n "$PYENV_DEBUG" ] && set -x @@ -27,7 +30,7 @@ whence() { PYENV_COMMAND="$1" if [ -z "$PYENV_COMMAND" ]; then - echo "usage: pyenv whence [--path] COMMAND" >&2 + pyenv-help --usage whence >&2 exit 1 fi diff --git a/libexec/pyenv-which b/libexec/pyenv-which index 24a573a3..afb8e3e9 100755 --- a/libexec/pyenv-which +++ b/libexec/pyenv-which @@ -1,4 +1,12 @@ #!/usr/bin/env bash +# +# Summary: Display the full path to an executable +# +# Usage: pyenv which +# +# Displays the full path to the executable that pyenv will invoke when +# you run the given command. + set -e [ -n "$PYENV_DEBUG" ] && set -x @@ -45,7 +53,7 @@ IFS=: PYENV_VERSION="${versions[*]}" PYENV_COMMAND="$1" if [ -z "$PYENV_COMMAND" ]; then - echo "usage: pyenv which COMMAND" >&2 + pyenv-help --usage which >&2 exit 1 fi