utility in rvm-0.1.2

- old
+ new

@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
 
+# Query the rvm key-value database for a specific key
+# Allow overrides from user specifications in $rvm_config_path/user
 __rvm_db() {
   key=$1 ; variable=$2
   if [[ -f "$rvm_config_path/user" ]] ; then
     value="$($rvm_scripts_path/db "$rvm_config_path/user" "$key")"
   fi
@@ -18,10 +20,11 @@
     fi
   fi
   unset key value variable
 }
 
+# Ouput rvm environment information.
 __rvm_info() {
   if [[ ! -z "$(which ruby 2>/dev/null)" ]] ; then full_version=$(ruby -v) ; fi
 
   cat <<Info
 
@@ -49,14 +52,16 @@
 environment:
   GEM_HOME:     "$GEM_HOME"
   MY_RUBY_HOME: "$MY_RUBY_HOME"
   IRBRC:        "$IRBRC"
 Info
+if [[ ! -z "$MAGLEV_HOME" ]] ; then echo "  MAGLEV_HOME: $MAGLEV_HOME" ; fi
 
   unset full_version
 }
 
+# Output debugging information that has been found useful to help people identify and resolve issues.
 __rvm_debug() {
   $rvm_scripts_path/log "debug" "PATH:\n$(echo $PATH | awk -F":" '{print $1":"$2":"$3":"$4":"$5}')"
   $rvm_scripts_path/log "debug" "uname -a: $(uname -a)"
 
   if [[ "Darwin" = "$(uname)" ]] ; then
@@ -88,79 +93,87 @@
   done
 
   $rvm_scripts_path/log "debug" "gem sources:\n$(gem sources | awk '/gems/')"
 }
 
+# ZSH has 1 based array indexing, bash has 0 based.
 if [[ ! -z "$ZSH_VERSION" ]] ; then __shell_array_start=1 ; else __shell_array_start=0 ; fi
+
+# Push an item onto a given array.
 __rvm_push() {
   array=$1 ; shift ; item=$2
   # TODO: allow loop over more arguments.
   eval "index=\$((\${#${array}[*]} + $__shell_array_start))"
   eval "${array}[${index}]=${item}"
   unset array item
 }
 
+# Clean all *duplicate* items out of the path. (keep first occurrence of each)
 __rvm_clean_path() {
   PATH=$(echo $PATH | tr -s ':' '\n' | awk '!($0 in a){a[$0];print}' | tr -s '\n' ':' | sed 's#:$##')
   export PATH
 }
 
+# Clean all rvm items out of the current working path.
 __rvm_remove_rvm_from_path() {
   PATH=$(echo $PATH | tr -s ':' '\n' | grep -v "\.rvm" | tr -s '\n' ':' | sed 's#:$##')
   export PATH
 }
 
-__rvm_gi() { gem install $rvm_gem_options $* ; }
-
+# Run a specified command and log it.
 __rvm_run() {
   log_file_name="$1" ; command="$2" ; message="$3"
-  rvm_ruby_log_path="${rvm_ruby_log_path:-$rvm_log_path}"
-  mkdir -p $(dirname "$rvm_ruby_log_path/$log_file_name.log")
-
+  if [[ -z "$rvm_ruby_log_path" ]] ; then rvm_ruby_log_path="$rvm_log_path" ; fi
   if [[ ! -z "$message" ]] ; then $rvm_scripts_path/log "info" "$message" ; fi
   if [[ ! -z "$rvm_debug_flag" ]] ; then
     $rvm_scripts_path/log "debug" "Executing: $command"
   fi
 
   touch "$rvm_ruby_log_path/$log_file_name.log" "$rvm_ruby_log_path/$log_file_name.error.log" # for zsh :(
-  echo "[$(date +'%Y-%m-%d %H:%M:%S')] $command" | tee "$rvm_ruby_log_path/$log_file_name.log" > "$rvm_ruby_log_path/$log_file_name.error.log"
+  echo "[$(date +'%Y-%m-%d %H:%M:%S')] $command" | tee "$rvm_ruby_log_path/$log_file_name.log" >> "$rvm_ruby_log_path/$log_file_name.error.log"
   if [[ -z "$rvm_niceness" ]] || [[ "0" = "$rvm_niceness" ]] ; then
     eval "$command" >> "$rvm_ruby_log_path/$log_file_name.log" 2>> "$rvm_ruby_log_path/$log_file_name.error.log"
   else
     eval "nice -n $rvm_niceness $command" >> $rvm_ruby_log_path/$log_file_name.log 2>> $rvm_ruby_log_path/$log_file_name.error.log
   fi
   if [[ $? -gt 0 ]] ; then $rvm_scripts_path/log "error" "Error running '$command', please check $rvm_ruby_log_path/$log_file_name.error.log" ; __rvm_pushpop ; return 1 ; fi
   unset log_file command
 }
 
+# Unset both rvm variables as well as ruby-specific variables
+# Preserve gemset if 'rvm_sticky_gems' is set (persist gemset unless clear is explicitely called).
 __rvm_cleanup_variables() {
   __rvm_unset_ruby_variables
 
   if [[ "$rvm_sticky_gems" = "1" ]] ; then export rvm_gem_set_name ; else unset rvm_gem_set_name  ; fi
 
   unset rvm_action rvm_irbrc_file rvm_command rvm_error_message rvm_url rvm_force_flag rvm_all_flag rvm_reconfigure_flag rvm_make_flags rvm_bin_flag rvm_load_flag rvm_dump_flag rvm_self_flag rvm_gem_flag rvm_rubygems_flag rvm_debug_flag rvm_delete_flag rvm_summary_flag rvm_test_flag _rvm_spec_flag rvm_json_flag rvm_yaml_flag rvm_shebang_flag rvm_env_flag rvm_tail_flag rvm_use_flag rvm_dir_flag rvm_list_flag rvm_empty_flag rvm_file_name rvm_benchmark_flag rvm_clear_flag rvm_name_flag rvm_verbose_flag rvm_user_flag rvm_system_flag rvm_ruby_configure_flags rvm_uninstall_flag rvm_install_flag rvm_llvm_flag rvm_ruby_bits
 }
 
+# Unset ruby-specific variables
 __rvm_unset_ruby_variables() {
   unset rvm_ruby_interpreter rvm_ruby_version rvm_url rvm_ruby_repo_url rvm_ruby_package_name rvm_ruby_patch_level rvm_ruby_make rvm_ruby_make_install rvm_ruby_revision rvm_ruby_tag rvm_major_version rvm_minor_version rvm_ruby_gem_home rvm_ruby_binary rvm_ruby_home rvm_ruby_log_path rvm_ruby_src_path rvm_ruby_irbrc rvm_ruby_selected_flag rvm_ruby_string rvm_ruby_string rvm_ruby_src_path rvm_ruby_repo_url rvm_major_version rvm_minor_version rvm_ruby_gem_home rvm_head_flag rvm_ruby_configure rvm_ruby_mode rvm_ruby_patch rvm_ruby_package_file rvm_ruby_package_name
 }
 
 __rvm_load_rvmrc() {
   if [[ -f /etc/rvmrc ]] ; then source /etc/rvmrc ; fi
   if [[ -f "$HOME/.rvmrc" ]] ; then source "$HOME/.rvmrc" ; fi
 }
 
+# Loop over the currently installed rubies and refresh their binscripts.
 __rvm_bin_scripts() {
   for rvm_ruby_binary in $rvm_rubies_path/*/bin/ruby ; do
   if [[ -x "$rvm_ruby_binary" ]] ; then
     rvm_ruby_string=$(dirname "$rvm_ruby_binary" | xargs dirname | xargs basename)
     __rvm_select
     __rvm_bin_script
   fi
   done
 }
 
+# Write the bin/ wrapper script for currently selected ruby.
+# TODO: Adjust binscript to be able to handle all rubies not just the standard interpreteres.
 __rvm_bin_script() {
   if [[ -z "$rvm_ruby_selected_flag" ]] ; then __rvm_select ; fi
 ruby_wrapper=$(cat <<RubyWrapper
 #!/bin/bash
 
@@ -176,10 +189,11 @@
   echo "$ruby_wrapper" > $rvm_bin_path/$rvm_ruby_package_name
   unset ruby_wrapper
   chmod +x $rvm_bin_path/$rvm_ruby_package_name
 }
 
+# Load default ruby, if default is not set load system ruby.
 __rvm_load_defaults() {
   if [[ ! -s "$rvm_config_path/system" ]] ; then
     for variable in RUBY_VERSION GEM_HOME GEM_PATH MY_RUBY_HOME ; do
       eval value=\$${variable}
       if [[ -z "$value" ]] ; then
@@ -215,10 +229,12 @@
       fi
     fi
   fi
 }
 
+# Reset any rvm gathered information about the system and its state.
+# rvm will refresh the stored information the next time it is called after reset.
 __rvm_reset() {
   PATH=$(echo $PATH | tr ':' '\n' | awk '$0 !~ /rvm/' | paste -sd : -)
   PATH=$rvm_bin_path:$PATH ; export PATH
 
   for variable in RUBY_VERSION GEM_HOME MY_RUBY_HOME ; do unset $variable ; done
@@ -236,10 +252,11 @@
   done ; unset system_config variable
 
   rm -f $rvm_bin_path/ruby $rvm_bin_path/gem $rvm_bin_path/rake $rvm_bin_path/irb $rvm_bin_path/default*
 }
 
+# Implode removes the entire rvm installation under $rvm_path.
 __rvm_implode() {
   while : ; do
     $rvm_scripts_path/log "warn" "Are you SURE you wish for rvm to implode? This will remove $rvm_path ? (type 'yes' or 'no')"
     read response
     if [[ "yes" = "$response" ]] ; then
@@ -260,19 +277,29 @@
       break
     fi
   done
 }
 
+# Output the current ruby's rvm source path.
 __rvm_source_dir() {
   if [[ -z "$rvm_ruby_selected_flag" ]] ; then __rvm_select ; fi
   if [[ -z "$rvm_ruby_src_path" ]] ; then
     $rvm_scripts_path/log "fail" "No source directory exists for the default implementation."
   else
     echo "$rvm_ruby_src_path"
   fi
 }
 
+# List all rvm installed rubies.
+# This is meant to be used with scripting.
+__rvm_rubies() {
+  \ls $rvm_rubies_path
+}
+
+# List all rvm installed rubies, default ruby and system ruby.
+# Display the rubies, indicate their architecture and indicate which is currently used.
+# This is not meant to be used with scripting. This is for interactive mode usage only.
 __rvm_list() {
   echo
   if [[ ! -z "$rvm_all_flag" ]] ; then
     while read -r tag
     do
@@ -296,11 +323,13 @@
       current_ruby="$(echo $ruby | xargs dirname | xargs dirname | xargs basename 2> /dev/null)"
     fi
 
     for version in $(\ls $rvm_rubies_path/ 2> /dev/null | awk '/[a-z]*-.*/ {print $NF}') ; do
       if [[ ! -z "$(echo $version | awk '/^jruby-/')" ]] ; then
-        string="$($rvm_rubies_path/$version/bin/ruby -v | awk '{print $NF}')"
+        string="[ $($rvm_rubies_path/$version/bin/ruby -v | awk '{print $NF}') ]"
+      elif [[ ! -z "$(echo $version | awk '/^maglev-/')" ]] ; then
+        string="[ x86_64 ]"
       else
         string="[ $(file $rvm_rubies_path/$version/bin/ruby | awk '/x86.64/ {print "x86_64"} /386/ {print "i386"} /ppc/ {print "ppc"}' | tr "\n" ' ')]"
       fi
       if [[ "$version" = "$current_ruby" ]] ; then
         echo -e "=> $(tput setaf 2)$version$(tput sgr0) $string"
@@ -340,10 +369,11 @@
     unset current_ruby version selected system_ruby system_version string
   fi
   echo
 }
 
+# Initialize rvm, ensuring that the path and directories are as expected.
 __rvm_initialize() {
   rvm_ruby_load_path="."
   rvm_ruby_require=""
 
   __rvm_clean_path
@@ -353,10 +383,11 @@
   fi
 
   mkdir -p $rvm_src_path $rvm_bin_path $rvm_archives_path $rvm_gem_path $rvm_tmp_path
 }
 
+# Update rubygems or binscripts based on CLI selection.
 __rvm_update() {
   __rvm_pushpop $rvm_path
   if [[ "head" = "$rvm_ruby_revision" ]] || [[ ! -z "$rvm_self_flag" ]] || [[ "update" = "$rvm_action" ]] || [[ ! -z "$rvm_update_flag" ]] ; then
     __rvm_version
     __rvm_update_rvm
@@ -366,10 +397,12 @@
 
   unset rvm_update_flag rvm_action rvm_self_flag rvm_ruby_revision rvm_bin_flag rvm_rubygems_flag
   __rvm_pushpop
 }
 
+# Update rvm using rubygems
+# If --head was specified, update from git repository master branch.
 __rvm_update_rvm() {
   mkdir -p "$rvm_src_path"
   __rvm_pushpop "$rvm_src_path"
 
   ruby="$(which ruby 2>/dev/null)"
@@ -420,10 +453,11 @@
   else
     $rvm_scripts_path/log "info" "Carry on then..."
   fi ; unset response
 }
 
+# Perform an action using one of a selected ruby's specified binaries.
 __rvm_ruby_do() {
   __rvm_select
   __rvm_use
   binary="$(echo $rvm_action | sed 's#do$##')"
   if [[ -x "$rvm_ruby_home/bin/$binary" ]] ; then
@@ -479,10 +513,12 @@
   eval "rubies=(${rubies[*]} $rvm_ruby_string)"
   eval "statuses=(${statuses[*]} $result)"
   __rvm_unset_ruby_variables
 }
 
+# Loop over a set or all rvm installed rubies to perform some action.
+# Record the results and report based on CLI selections.
 __rvm_do() {
   __rvm_state
 
   rubies=() ; successes=() ; errors=() ; statuses=()
   # TODO: Extract the common functionality out of the if below
@@ -514,10 +550,11 @@
   $rvm_scripts_path/hook "after_do"
 
   return ${#errors[*]}
 }
 
+# Output the summary in a human readable format.
 __rvm_summary() {
   export successes errors statuses
   summary="\nSummary:\n\n"
   if [[ ${#successes[*]} -gt 0 ]] ; then
     summary="$summary \033[0;32m${#successes[*]} successful: $(echo "${successes[*]}" | sed 's# #, #g')\033[0m\n"
@@ -529,10 +566,11 @@
   if [[ ! -z "$ZSH_VERSION" ]] ; then array_start=1 ; else array_start=0 ; fi
   echo -e "$summary" | tee -a log/summary.log
   return ${#errors[*]}
 }
 
+# Output the summary in a yaml format.
 __rvm_yaml() {
   export successes errors statuses
   yaml="totals:\n  rubies: ${#rubies[*]}\n  successes: ${#successes[*]}\n  errors: ${#errors[*]}\nsuccesses:"
   for var in ${successes[*]} ; do yaml="$yaml\n  - $var" ; done
   yaml="$yaml\nerrors:"
@@ -550,10 +588,11 @@
   echo -e "$yaml" | tee -a log/summary.yaml
 
   return ${#errors[*]}
 }
 
+# Output the summary in a json format.
 __rvm_json() {
   json="{"
   json="$json\n  \"totals\": { \"rubies\": ${#rubies[*]}, \"successes\": ${#successes[*]}, \"errors\": ${#errors[*]}},"
   json="$json\n  \"successful\": [ "$(echo ${successes[*]} | sed 's# #", "#g')" ],"
   json="$json\n  \"errors\": [ "$(echo ${errors[*]} | sed 's# #", "#g')" ],"
@@ -574,10 +613,11 @@
   echo -e "$json" | tee -a log/summary.json
 
   return ${#errors[*]}
 }
 
+# Wrap the specified ruby code file in a Benchmark.bmbm block and execute it.
 __rvm_benchmark() {
   code="require \"benchmark\" \n Benchmark.bmbm do |benchmark| \n benchmark.report(\"${rvm_ruby_file}\") do \n"
   echo -e "$code" > "$rvm_tmp_path/$$.rb"
   unset code
   cat $rvm_ruby_file >> "$rvm_tmp_path/$$.rb"
@@ -587,25 +627,28 @@
   rvm_action="ruby"
   if [[ ! -z "$rvm_debug_flag" ]] ; then echo -e "$rvm_tmp_path/$$.rb:\n$(cat $rvm_tmp_path/$$.rb)" ; fi
   __rvm_do
 }
 
+# Create the irbrc for the currently selected ruby installation.
 __rvm_irbrc() {
-  # Create the irbrc for the currently selected ruby installation.
   if [[ -d "$rvm_ruby_home" ]] && [[ ! -s "$rvm_ruby_irbrc" ]] ; then
     cp $rvm_scripts_path/irbrc $rvm_ruby_irbrc
   fi
 }
 
+# Push or Pop a directory based on zero or one directory argument provided.
 __rvm_pushpop() {
   if [[ -z "$1" ]] ; then
     popd > /dev/null 2>&1
   else
     pushd "$1" > /dev/null 2>&1
   fi
 }
 
+# Save or restore the rvm's state. This is a toggle action.
+# Meant for use before and after an operation that might reset the currently selected ruby.
 __rvm_state() {
   if [[ -z "$rvm_state" ]] ; then
     if [[ -z "$(which ruby 2>/dev/null | awk /$(basename $rvm_rubies_path)/)" ]] ; then
       rvm_state=system
     else
@@ -617,10 +660,11 @@
     __rvm_use
     unset rvm_state
   fi
 }
 
+# Output an inspection of selected 'binary' scripts, based on CLI selection.
 __rvm_inspect() {
   for binary in $rvm_ruby_args ; do
     actual_file="$(which $binary 2>/dev/null)"
     $rvm_scripts_path/log "info" "$actual_file:"
     if [[ ! -z "$rvm_shebang_flag" ]] ; then cat $actual_file | head -n 1    ; fi
@@ -630,10 +674,12 @@
     if [[ ! -z "$rvm_tail_flag" ]]    ; then cat $actual_file | tail -n 5    ; fi
     if [[ ! -z "$rvm_all_flag" ]]     ; then cat $actual_file                ; fi
   done
 }
 
+# Attempt to override the Darwin build settings for rubies
+# This should only be used in extreme edge cases that will not work via the default way.
 __rvm_make_flags() {
   # This is only an issue with Darwin :/
   if [[ "Darwin" = "$(uname)" ]] ; then
     # ls /usr/lib/gcc/x86_64-apple-darwin10
 
@@ -665,10 +711,12 @@
       # CXXFLAGS="-mmacosx-version-min="$(sw_vers -productVersion | awk -F'.' '{print $1"."$2}')" -isysroot /Developer/SDKs/$rvm_sdk " ; export CXXFLAGS
     fi
   fi
 }
 
+# Select a gems(et) based on CLI set options and environment.
+# This only sets 'rvm_ruby_gem_home'
 __rvm_gems_select() {
   if [[ -z "$(which gem 2>/dev/null)" ]] ; then return 0 ; fi
 
   if [[ -z "$rvm_gem_set_name" ]] ; then
     # No longer defaulting to 'sticky' gem sets.
@@ -699,9 +747,10 @@
   else
     rvm_ruby_gem_home="$rvm_gem_path/$rvm_ruby_string%$rvm_gem_set_name"
   fi
 }
 
+# Use a gems(et) specified by 'rvm_ruby_gem_home'
 __rvm_gems_use() {
   if [[ -z "$rvm_ruby_selected_flag" ]] ; then __rvm_select ; fi
 
   if [[ ! -z "$rvm_ruby_gem_home" ]] ; then
     mkdir -p "$rvm_ruby_gem_home"