geminstaller 0.2.0

data/COPYING

@@ -0,0 +1 @@
+Placeholder...

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 / 2006-07-29
+
+* 1 major enhancement
+  * Initial Creation

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2006 Chad Woolley
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/Manifest.txt

@@ -0,0 +1,62 @@
+COPYING
+History.txt
+LICENSE
+Manifest.txt
+README.txt
+Rakefile
+TODO.txt
+bin/geminstaller
+geminstaller.yml
+lib/geminstaller.rb
+lib/geminstaller/application.rb
+lib/geminstaller/arg_parser.rb
+lib/geminstaller/autogem.rb
+lib/geminstaller/config.rb
+lib/geminstaller/config_builder.rb
+lib/geminstaller/dependency_injector.rb
+lib/geminstaller/enhanced_stream_ui.rb
+lib/geminstaller/exact_match_list_command.rb
+lib/geminstaller/file_reader.rb
+lib/geminstaller/gem_arg_processor.rb
+lib/geminstaller/gem_command_line_proxy.rb
+lib/geminstaller/gem_command_manager.rb
+lib/geminstaller/gem_interaction_handler.rb
+lib/geminstaller/gem_list_checker.rb
+lib/geminstaller/gem_runner_proxy.rb
+lib/geminstaller/gem_source_index_proxy.rb
+lib/geminstaller/gem_spec_manager.rb
+lib/geminstaller/geminstaller_error.rb
+lib/geminstaller/hoe_extensions.rb
+lib/geminstaller/install_processor.rb
+lib/geminstaller/missing_dependency_finder.rb
+lib/geminstaller/missing_file_error.rb
+lib/geminstaller/noninteractive_chooser.rb
+lib/geminstaller/output_filter.rb
+lib/geminstaller/output_listener.rb
+lib/geminstaller/output_observer.rb
+lib/geminstaller/output_proxy.rb
+lib/geminstaller/requires.rb
+lib/geminstaller/rogue_gem_finder.rb
+lib/geminstaller/ruby_gem.rb
+lib/geminstaller/rubygems_exit.rb
+lib/geminstaller/rubygems_extensions.rb
+lib/geminstaller/unauthorized_dependency_prompt_error.rb
+lib/geminstaller/unexpected_prompt_error.rb
+lib/geminstaller/valid_platform_selector.rb
+lib/geminstaller/version_specifier.rb
+lib/geminstaller/yaml_loader.rb
+start_local_gem_server.sh
+test/test_all.rb
+website/config.yaml
+website/metainfo.yaml
+website/src/code/index.page
+website/src/community/index.page
+website/src/community/links.page
+website/src/default.css
+website/src/default.template
+website/src/documentation/documentation.page
+website/src/documentation/index.page
+website/src/documentation/tutorials.page
+website/src/download.page
+website/src/faq.page
+website/src/index.page

data/README.txt

@@ -0,0 +1,60 @@
+GemInstaller
+    by Chad Woolley
+    http://geminstaller.rubyforge.org
+
+== DESCRIPTION:
+  
+GemInstaller provides automated management of RubyGems.
+
+== FEATURES:
+  
+GemInstaller provides automated management of RubyGems.  It uses a simple YAML config file to:
+
+* Automatically install the correct versions of all required gems wherever your app runs.
+* Automatically ensure installed gems and versions are consistent across multiple applications, machines, platforms, and environments 
+* Automatically add correct versions of gems to the ruby load path when your app runs ('require_gem'/'gem')
+* Automatically reinstall missing dependency gems
+* Automatically guess at correct platform to install for multi-platform gems
+* Print YAML for "rogue gems" which are not specified in the current config, to easily bootstrap your config file, or find gems that were manually installed without GemInstaller.
+* Avoid the "works on demo, broken on production" syndrome
+
+== SYNOPSYS:
+
+GemInstaller provides automated management of RubyGems.
+
+=== Download:
+
+Downloads are available at http://rubyforge.org/frs/?group_id=1902
+
+=== Quick Start:
+
+See http://geminstaller.rubyforge.org/documentation/index.html
+
+== INSTALL:
+
+* [sudo] gem install geminstaller
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2006 Chad Woolley
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,92 @@
+# -*- ruby -*-
+
+require 'rubygems'
+begin
+  require 'hoe'
+rescue LoadError
+  abort "ERROR: GemInstaller has build- and test-time dependencies
+       on Hoe and other libraries.  Run the 'geminstaller'
+       executable from the root of the geminstaller source
+       tree, and GemInstaller will automatically install
+       these dependencies."
+end
+
+require './lib/geminstaller.rb'
+require './lib/geminstaller/hoe_extensions.rb'
+
+IndependentHoe.new('geminstaller', GemInstaller.version) do |p|
+  p.author = 'Chad Woolley'
+  p.rubyforge_name = 'geminstaller'
+  p.summary = p.paragraphs_of('README.txt', 1).first.split(/\n/)[2]
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.clean_globs << 'coverage'
+  p.clean_globs << 'website/output'
+  p.extra_deps = []
+end
+
+desc "Run all metrics"
+task :metrics do
+  Rake::Task[:coverage].invoke
+  Rake::Task[:audit].invoke
+end
+
+task :coverage do
+  rm_rf "coverage"
+  rm_rf "website/output/code/coverage"
+  sh "mkdir -p website/output/code"
+  sh "rcov -o website/output/code/coverage test/test_all.rb"
+end
+
+desc "Diff the manifest"
+task :diff_manifest => :clean do
+  f = "Manifest.tmp"
+  require 'find'
+  files = []
+  Find.find '.' do |path|
+    next unless File.file? path
+    next if path =~ /\.svn|tmp$|CVS/
+    next if path =~ /\.iml|\.ipr|\.iws|\.kpf|\.tmproj|\.project/
+    next if path =~ /\.\/spec/
+    next if path =~ /\.\/pkg/
+    next if path =~ /\.\/output/
+    next if path =~ /\.\/website\/output/
+    files << path[2..-1]
+  end
+  files = files.sort.join "\n"
+  File.open f, 'w' do |fp| fp.puts files end
+  system "diff -du Manifest.txt #{f}"
+  rm f
+end
+
+desc "Update the manifest"
+task :update_manifest do
+  system('rake diff_manifest | patch -p0 Manifest.txt')
+end
+
+desc "Run Webgen to generate website"
+task :webgen do
+#  rm_rf "website/output"
+  sh "webgen -d website"
+end
+
+desc "Move ri docs to website"
+task :website_rdocs => :docs do
+  rm_rf "website/output/code/rdoc"
+  sh "mkdir -p website/output/code/"
+  mv "doc", "website/output/code/rdoc"
+end
+
+desc "Generate ri locally for testing"
+task :website => [:webgen, :website_rdocs, :coverage] do
+end
+
+desc 'Publish website to RubyForge'
+task :publish_website => [:clean, :website] do
+  host = "thewoolleyman@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/geminstaller"
+  local_dir = 'website/output'
+  sh %{rsync -av --delete --exclude=statsvn #{local_dir}/ #{host}:#{remote_dir}}
+end
+# vim: syntax=Ruby

data/TODO.txt

@@ -0,0 +1,88 @@
+* upload gem
+================ 0.2.0 release ===================
+* docs should indicate that I eat my own dog food
+* update docs with details on how to handle unmet dependencies when -y is not specified
+* tutorial: rails
+* tutorial: using common or shared config files, with different configs for different environments - test (rspec) vs. dev (capistrano) vs. demo/staging/prod
+* tutorial: running via capistrano
+* crossreference front page, tutorials, and docs
+* put mongrel/rails startup bug in tracker, add link in "known bugs" section on home page.
+* links - rspec, rubygems
+================ 0.2.0 finishing website ===================
+* make valid_platform_selector use data from tattle
+* autogem and run args can be passed as string or array
+* tell rspec not to alphabetize my specs, or figure out how to not run testgemhome in the middle and have it set up test gem home twice
+* better test coverage for --sudo and --exception options
+* Verify compatibility with RubyGems trunk - especially Gem::ListCommand vs. Gem::Commands::ListCommand
+* use rspec context_setup
+* split out geminstaller_spec into application_spec and geminstaller_spec.  Fix reference in docs / design
+* newlines printed between dots when "updating" message is included in error message
+* Error on activerecord for brand-new rubygems installation - couldn't find gem.  Did a gem list --remote activerecord, then it went away (got sudo error), then happened again, then worked when I passed -gall -rall options.
+* Fastthread = only shows version 0.6.2 on windows, rubygems 0.9 ???
+* geminstaller_spec autogem spec must have the GemRunner "initialized" or else the stub gem in test_gem_home won't be found by autogem.
+* fix_dependencies=true takes FOREVER on windows
+* echo stdin, lists presented for debug output levels
+* Just ignore sudo option on windows, rather than throwing an error
+* why does windows try to reinstall fxruby 1.6.6 when it is already installed???
+* Figure out how to avoid checking dependency gems multiple times if multiple dependent gems depend on them.
+* write coverage_no_platform_specific rake task (to get 100% coverage on a mac)
+* On rogue gems, allow configuration of gems which are auto-installed and/or should be ignored.
+* add option to print rogue gems with no extra output, for concatenation to existing gem list
+* Research what all existing gem platforms are.  See if they can all be covered in valid_platform_selector
+* Can GemInstaller handle multiple gem server sources via multiple config files?
+* Handle default gems that come with ruby/rubygems windows distro. 
+* refactor enhanced_stream_ui.ask_yes_no - does it need to catch the exception?  Also review context name (no OutputProxy) and use of StringIO, and exception tests.
+* rename enhanced_stream_ui to noninteractive_stream_ug
+* add multilevel dependency smoketests for autogem (old rails version)
+* refactor duplication in autogem/rogue_gem_finder using blocks
+* rubygems stdout - don't print prefix for single dot
+* clean up regexps - no leading or trailing .*
+* Return meaningful message instructing to use the --sudo option if Errno::EACCES is caught on a sudo-able platform - should throw GemInstaller::AccessException, which can be caught
+* Rails integration doesn't work under mongrel when invoked via executable (e.g, actionmailer gem not recognized after install, only after mongrel restart).  Does't occur under webrick, or if geminstaller is invoked programatically via class.
+* rails example doesn't print any warning if geminstaller is not installed
+* "Installing gem" messages are duplicated if info message is specified, one from rubygems, one from geminstaller.  See todo in install_processor.rb
+* boot.rb parsed twice under webrick?
+* commandecho doesn't print regexps correctly
+* code coverage for logic paths supporting old rubygems versions
+* spec_utils - use extend+include ClassAndInstanceMethods approach
+* clean up registry - third-party first, no dependency next, alphabetized
+* review/clean up ri/rdoc
+* Better errors for invalid yaml (unsupported keys)
+========= 0.3.0 release ==============
+* patch hoe to install_gem without sudo on windows
+* understand why '> 1' must be quoted to be a valid yaml value - see yaml_loader_spec.rb
+* tests failed when "partially" connected to network? (wireless at office)
+* tests fail with timeouts intermittently on windows
+* add more tests for dependencies to geminstaller_spec
+* reconcile methods for testing error messages - manually vs proc_should_raise_with_message.  Probably should patch rspec.
+* remove test_gem_home.reset from geminstaller_spec.rb WITHOUT breaking the test suite.
+* tests fail on windows - seems to be related to test_gem_home running twice.  smoketest still passes.
+* Use rubygems executables from test_gem_home.  In order to do this, we must run test_gem_home and ensure it is on the load path BEFORE the system installation of rubygems ever gets initialized.  We will also have to manually include all geminstaller test dependency gems in test_gem_home or on the path.  Tried this once and failed, patch on linux box...
+* clean up spec_utils - remove duplication of class and instance methods
+* spec_utils global teardown method which uninstalls all gems
+* can't run binary out of source dir unless running it via ruby
+* running binary via ruby out of bin dir will pick up gem first on load path if it is installed
+* verify that >= version spec works with a specific platform, if that platform is not available for the highest version
+* Check for write access, and exit with warning to use sudo if there is no write access.
+* store rubygems dist as a tar, and untar it on demand
+* Add spec file name to all contexts (or see if rspec can do it automatically)
+* Make GemInstaller.run take a parameter to not fail if there is any error
+* Embedded gem_server process doesn't get killed on windows during tests - need to use ruby services, see comment in embedded_gem_server.rb
+* Embedded gem_server ports aren't handled correctly on linux during tests - port conflict on startup, open ports die off slowly after tests finish
+* Do a port check before starting embedded gem server, give option to kill process or at least exit with a descriptive warning.
+* Clean up spec_helper, find out simplest way to invoke rspec via test_unit, and still provide proper return codes/output
+* remove cruft from test output - intercept output streams from gem_server and rubygems setup
+* enhance DependencyInjector - allow items to be substituted prior to initialization - then geminstaller_spec could simply set a mock output_proxy on the registry instead of explicitly setting it every place it is used.
+* ensure --debug install option works as expected
+* fix all Zentest warnings
+* Rename RubyGem class to RubyGemAction, add install vs. uninstall actions in config (install is default)
+* Automate process for creating a stubgem
+* Give nice error message if gem server is unavailable (check socket)
+* Make tests run under RadRails debugger
+* handle unsupported gem install options - for example, -t gives uninitialized constant Gem::Validator
+* update info in stubgem (not sow defaults)
+* Fix errors when using relative or ~/ dir in --config path
+* make verbose option specify --backtrace on all gem commands
+* Add support, syntax, and options for uninstalling gems - completely, or down to highest specified version.
+* add feature to automatically warn if there is a more recent version of the gem available and check_for_upgrade == false.  Use "gem outdated" command
+* auto-generate geminstaller.yml files (possibly by parsing source, or based on all gems installed locally)

data/bin/geminstaller

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+dir = File.dirname(__FILE__)
+
+begin
+  require 'geminstaller'
+rescue LoadError
+  require 'rubygems'
+  begin
+    # try load path
+    require 'geminstaller'
+  rescue LoadError
+    begin
+      # try lib subdir (TODO: is this necessary?)
+      require 'lib/geminstaller'
+    rescue LoadError
+      # try lib dir as peer of current dir
+      require "#{dir}/../lib/geminstaller"
+    end
+  end
+end
+
+geminstaller_executable ||= File.join(File.expand_path(dir), 'geminstaller')
+
+if ARGV.include?('--geminstaller-exec-path')
+  print "geminstaller_exec_path=#{geminstaller_executable}"
+  exit 0
+end
+
+exit GemInstaller.run(ARGV, geminstaller_executable)

data/geminstaller.yml

@@ -0,0 +1,34 @@
+---
+# GemInstaller config file which specifies the actual build, test, and doc dependencies for GemInstaller itself.
+defaults:
+  install_options: --include-dependencies
+gems:
+- name: diff-lcs
+  version: '>= 1.1.2'
+- name: hoe
+  version: '>= 1.1.6'
+- name: rake
+  version: '>= 0.7.1'
+- name: rcov
+  version: '>= 0.7.0.1'
+  platform: <%= RUBY_PLATFORM =~ /mswin/ ? 'mswin32' : 'ruby'%>
+- name: RedCloth
+  version: '>= 3.0.4'
+- name: rspec
+  version: '= 0.9.3'
+- name: cmdparse
+  version: '>= 2.0.2'
+- name: webgen
+  version: '>= 0.4.2'
+<% if RUBY_PLATFORM =~ /mswin/ %>
+- name: win32-process
+  version: '>= 0.5.0'
+  platform: 'mswin32'
+- name: win32console
+  version: '>= 1.0.8'
+  platform: 'mswin32'
+- name: win32-open3
+  version: '>= 0.2.5'
+  platform: 'mswin32'
+<% end %>
+    

data/lib/geminstaller/application.rb

@@ -0,0 +1,105 @@
+module GemInstaller
+  class Application
+    # we have accessors instead of just writers so that we can ensure it is assembled correctly in the dependency injector test
+    attr_accessor :config_builder, :install_processor, :output_filter, :arg_parser, :args, :options, :rogue_gem_finder
+    attr_writer :autogem
+    
+    def initialize
+      @args = nil
+    end
+    
+    def run
+      begin
+        exit_flag_and_return_code = handle_args
+        if exit_flag_and_return_code[0]
+          return exit_flag_and_return_code[1]
+        end
+        gems = create_gems_from_config
+        if @options[:print_rogue_gems]
+          @rogue_gem_finder.print_rogue_gems(gems, @config_builder.config_file_paths_array)
+          return 0
+        end
+        if gems.size == 0
+          message = "No gems found in config file.  Try the --print-rogue-gems option to help populate your config file."
+          @output_filter.geminstaller_output(:info,message + "\n")          
+        else
+          process_gems(gems)
+        end
+      rescue Exception => e
+        handle_exception(e)
+        return 1
+      end
+      return 0
+    end
+    
+    def autogem
+      begin
+        # TODO: do some validation that args only contains --config option, especially not print_rogue_gems since this would mask a missing file error
+        exit_flag_and_return_code = handle_args
+        if exit_flag_and_return_code[0]
+          return exit_flag_and_return_code[1]
+        end
+        gems = create_gems_from_config
+        message = "GemInstaller is automatically requiring gems: "
+        print_startup_message(gems, message)
+        return @autogem.autogem(gems)
+      rescue Exception => e
+        handle_exception(e)
+        return 1
+      end
+    end
+    
+    def handle_exception(e)
+      message = e.message
+      message += "\n"
+      @output_filter.geminstaller_output(:error,message)
+      backtrace_as_string = e.backtrace.join("\n")
+      @output_filter.geminstaller_output(:debug,"#{backtrace_as_string}\n")
+      raise e if @options[:exceptions]
+    end
+    
+    def create_gems_from_config
+      begin
+        config = @config_builder.build_config
+      rescue GemInstaller::MissingFileError => e
+        # if user wants to print rogue gems and they have no config at all, don't show an error
+        return [] if @options[:print_rogue_gems] && (@config_builder.config_file_paths_array.size == 1) 
+        missing_path = e.message
+        error_message = "Error: A GemInstaller config file is missing at #{missing_path}.  You can generate one with the --print-rogue-gems option.  See the GemInstaller docs at http://geminstaller.rubyforge.org for more info."
+        raise GemInstaller::MissingFileError.new(error_message)
+      end
+      config.gems
+    end
+    
+    def process_gems(gems)
+      message = "GemInstaller is verifying gem installation: "
+      print_startup_message(gems, message)
+      @install_processor.process(gems)
+    end
+
+    def handle_args
+      return_code = @arg_parser.parse(@args)
+      arg_parser_output = @arg_parser.output
+      if (arg_parser_output && arg_parser_output != '')
+        if return_code == 0
+          @output_filter.geminstaller_output(:info,arg_parser_output)
+        else
+          @output_filter.geminstaller_output(:error,arg_parser_output)
+        end
+        return [true, return_code]
+      end
+      config_file_paths = @options[:config_paths]
+      @config_builder.config_file_paths = config_file_paths if config_file_paths
+      return [false, 0]
+    end
+
+    def print_startup_message(gems, message)
+      gems.each_with_index do |gem, index|
+        gem_info = "#{gem.name} #{gem.version}"
+        message += gem_info 
+        message += ", " if index + 1 < gems.size
+      end
+      @output_filter.geminstaller_output(:info,message + "\n")
+    end
+  end
+end

data/lib/geminstaller/arg_parser.rb

@@ -0,0 +1,162 @@
+module GemInstaller
+  class ArgParser
+    attr_reader :output
+    attr_writer :options
+    
+    VALID_GEMINSTALLER_OUTPUT_FLAGS = [:none,:error,:install,:info,:commandecho,:debug,:all]
+    VALID_RUBYGEMS_OUTPUT_FLAGS = [:none,:stdout,:stderr,:all]
+    
+    def parse(args = [])
+      raise GemInstaller::GemInstallerError.new("Args must be passed as an array.") unless args.nil? or args.respond_to? :shift
+      args = ARGV if args.nil? || args == []
+
+      @options[:exceptions] = false
+      @options[:redirect_stderr_to_stdout] = false
+      @options[:silent] = false
+      @options[:sudo] = false
+      @options[:geminstaller_output] = [:error,:install,:info]
+      @options[:rubygems_output] = [:stderr]
+      @output = ""
+      opts = OptionParser.new do |opts|
+        opts.banner = "Usage: geminstaller [options]"
+
+        opts.separator ""
+
+        config_msg =                         "Comma-delimited path(s) to GemInstaller config file(s)."
+        exceptions_msg =                     "Raise any exceptions, rather than just printing them and exiting\n" +
+        "                                     with a non-zero return code."
+        redirect_stderr_to_stdout_msg =      "Redirect all STDERR output to STDOUT.  Useful to get all output when\n" +
+        "                                     invoking GemInstaller via system()."
+        geminstaller_output_msg =            "Comma-delimited list of output types to show from GemInstaller.\n" +
+        "                                       Examples:\n" + 
+        "                                         --gall\n" +
+        "                                         --geminstaller-output=error,install,commandecho\n" +
+        "                                       Default: error,install,info\n" +
+        "                                       Valid types:\n" +
+        "                                         - none:        print only fatal errors\n" +
+        "                                         - error:       print error messages\n" +
+        "                                         - install:     print install messages\n" +
+        "                                         - info:        print informational messages\n" +
+        "                                         - commandecho: print rubygems commands as they are invoked\n" +
+        "                                         - debug:       print debug messages\n" +
+        "                                         - all:         print all messages"
+        help_msg =                           "Show this message."
+        print_rogue_gems_msg =               "Print a report of all locally installed gems which are not specified\n" +
+        "                                     in the geminstaller config file."
+        rubygems_output_msg =                "Comma-delimited list of output types to show from internal:\n" +
+        "                                       RubyGems command invocation.\n" +
+        "                                       Examples:\n" + 
+        "                                         --rall\n" +
+        "                                         --rubygems-output=stderr\n" +
+        "                                       Default: stderr\n" +
+        "                                       Valid types:\n" +
+        "                                         - none:        print no output\n" +
+        "                                         - stdout:      print standard output stream\n" +
+        "                                         - stderr:      print standard error stream\n" +
+        "                                         - all:         print all output"
+        sudo_msg =                           "Perform all gem operations under sudo (as root).  Will only work on\n" +
+        "                                     correctly configured, supported systems.  See docs for more info."
+        silent_msg =                         "Suppress all output except fatal exceptions, and output from\n" +
+        "                                     rogue-gems option."
+        version_msg =                        "Show GemInstaller version and exit."
+
+        opts.on("-cCONFIGPATHS", "--config=CONFIGPATHS", String, config_msg) do |config_paths|
+          @options[:config_paths] = config_paths
+        end
+
+        opts.on("-e", "--exceptions", exceptions_msg) do
+          @options[:exceptions] = true
+        end
+
+        opts.on("-d", "--redirect-stderr-to-stdout", redirect_stderr_to_stdout_msg) do
+          @options[:redirect_stderr_to_stdout] = true
+        end
+
+        opts.on("-gTYPES", "--geminstaller-output=TYPES", String, geminstaller_output_msg) do |geminstaller_output_flags|
+          @unparsed_geminstaller_output_flags = geminstaller_output_flags
+        end
+
+        opts.on("-h", "--help", help_msg) do
+          @output = opts.to_s
+        end
+
+        opts.on("-p", "--print-rogue-gems", print_rogue_gems_msg) do
+          @options[:print_rogue_gems] = true
+        end
+
+        opts.on("-rTYPES", "--rubygems-output=TYPES", String, rubygems_output_msg) do |rubygems_output_flags|
+          @unparsed_rubygems_output_flags = rubygems_output_flags
+        end
+
+        opts.on("-s", "--sudo", sudo_msg) do
+          @options[:sudo] = true
+        end
+
+        opts.on("-t", "--silent", silent_msg) do
+          @options[:silent] = true
+        end
+
+        opts.on("-v", "--version", version_msg) do
+          @output = "#{GemInstaller::version}\n"
+        end
+      end
+
+      begin
+        opts.parse!(args)
+      rescue(OptionParser::InvalidOption)
+        @output << opts.to_s
+        return 1
+      end
+      
+      if @options[:silent] and (@unparsed_geminstaller_output_flags or @unparsed_rubygems_output_flags)
+        @output = "The rubygems-output or geminstaller-output option cannot be specified if the silent option is true."
+        return 1
+      end
+
+      if (@options[:sudo])
+        @output = "The sudo option is not (yet) supported when invoking GemInstaller programatically.  It is only supported when using the command line 'geminstaller' executable.  See the docs for more info."
+        return 1
+      end
+      
+      # TODO: remove duplication
+      if @unparsed_geminstaller_output_flags
+        flags = @unparsed_geminstaller_output_flags.split(',') 
+        flags.delete_if {|flag| flag == nil or flag == ''}
+        flags.map! {|flag| flag.downcase}
+        flags.sort!
+        flags.uniq!
+        flags.map! {|flag| flag.to_sym}
+        geminstaller_output_valid = true
+        flags.each do |flag|
+          unless VALID_GEMINSTALLER_OUTPUT_FLAGS.include?(flag)
+            @output = "Invalid geminstaller-output flag: #{flag}\n" 
+            geminstaller_output_valid = false
+          end
+        end
+        @options[:geminstaller_output] = flags if geminstaller_output_valid
+      end
+
+      if @unparsed_rubygems_output_flags
+        flags = @unparsed_rubygems_output_flags.split(',') 
+        flags.delete_if {|flag| flag == nil or flag == ''}
+        flags.map! {|flag| flag.downcase}
+        flags.sort!
+        flags.uniq!
+        flags.map! {|flag| flag.to_sym}
+        rubygems_output_valid = true
+        flags.each do |flag|
+          unless VALID_RUBYGEMS_OUTPUT_FLAGS.include?(flag)
+            @output = "Invalid rubygems-output flag: #{flag}\n" 
+            rubygems_output_valid = false
+          end
+        end
+        @options[:rubygems_output] = flags if rubygems_output_valid
+      end
+
+      # nil out @output if there was no output
+      @output = nil if @output == ""
+      return 0
+      
+    end
+  end
+end