methadone 1.0.0.rc5 → 1.0.0.rc6

data/lib/methadone/cli.rb

@@ -1,6 +1,8 @@
 require 'erb'
 
 module Methadone
+  # <b>Methadone Internal - treat as private</b>
+  #
   # Stuff to implement methadone's CLI app.  These
   # stuff isn't generally for your use and it's not
   # included when you require 'methadone'

data/lib/methadone/cli_logging.rb

@@ -22,6 +22,9 @@ module Methadone
   #         debug("Done doing it")
   #       end
   #     end
+  #
+  # Note that every class that mixes this in shares the *same logger instance*, so if you call #change_logger, this
+  # will change the logger for all classes that mix this in.  This is likely what you want.
   module CLILogging
 
     def self.included(k)

data/lib/methadone/cucumber.rb

@@ -61,7 +61,7 @@ Then /^the following options should be documented:$/ do |options|
 end
 
 Then /^the option "([^"]*)" should be documented$/ do |option|
-  step %(the output should match /\\s*#{option}[\\s\\W]+\\w\\w\\w+/)
+  step %(the output should match /\\s*#{Regexp.escape(option)}[\\s\\W]+\\w\\w\\w+/)
 end
 
 Then /^the banner should be present$/ do

data/lib/methadone/error.rb

@@ -1,6 +1,8 @@
 module Methadone
   # Standard exception you can throw to exit with a given 
-  # status code. Prefer Methadone::Main#exit_now! over this
+  # status code. Generally, you should prefer Methadone::Main#exit_now! over using
+  # this directly, however you may wish to create a rich hierarchy of exceptions that extend from
+  # this in your app, so this is provided if you wish to do so.
   class Error < StandardError
     attr_reader :exit_code
     # Create an Error with the given status code and message
@@ -16,6 +18,11 @@ module Methadone
     # The command that caused the failure
     attr_reader :command
 
+    # exit_code:: exit code of the command that caused this
+    # command:: the entire command-line that caused this
+    # custom_error_message:: an error message to show the user instead of the boilerplate one.  Useful
+    #                        for allowing this exception to bubble up and exit the program, but to give
+    #                        the user something actionable.
     def initialize(exit_code,command,custom_error_message = nil)
       error_message = String(custom_error_message).empty? ?  "Command '#{command}' exited #{exit_code}" : custom_error_message
       super(exit_code,error_message)

data/lib/methadone/execution_strategy/jvm.rb

@@ -1,5 +1,7 @@
 module Methadone
   module ExecutionStrategy
+    # <b>Methadone Internal - treat as private</b>
+    #
     # Methadone::ExecutionStrategy for the JVM that uses JVM classes to run the command and get its results.
     class JVM < Base
       def run_command(command)

data/lib/methadone/execution_strategy/mri.rb

@@ -1,5 +1,7 @@
 module Methadone
   module ExecutionStrategy
+    # <b>Methadone Internal - treat as private</b>
+    #
     # Base strategy for MRI rubies.
     class MRI < Base
       def run_command(command)

data/lib/methadone/execution_strategy/open_3.rb

@@ -1,5 +1,7 @@
 module Methadone
   module ExecutionStrategy
+    # <b>Methadone Internal - treat as private</b>
+    #
     # Implementation for modern Rubies that uses the built-in Open3 library
     class Open_3 < MRI
       def run_command(command)

data/lib/methadone/execution_strategy/open_4.rb

@@ -1,5 +1,7 @@
 module Methadone
   module ExecutionStrategy
+    # <b>Methadone Internal - treat as private</b>
+    #
     # ExecutionStrategy for non-modern Rubies that must rely on
     # Open4 to get access to the standard output AND error.
     class Open_4 < MRI

data/lib/methadone/execution_strategy/rbx_open_4.rb

@@ -1,5 +1,7 @@
 module Methadone
   module ExecutionStrategy
+    # <b>Methadone Internal - treat as private</b>
+    #
     # For RBX; it throws a different exception when a command isn't found, so we override that here.
     class RBXOpen_4 < Open_4
       def exception_meaning_command_not_found

data/lib/methadone/exit_now.rb

@@ -1,4 +1,6 @@
 module Methadone
+  # Provides #exit_now! and #help_now!.  You might mix this into your business logic classes if they will
+  # need to exit the program with a human-readable error message.
   module ExitNow
     def self.included(k)
       k.extend(self)
@@ -9,11 +11,17 @@ module Methadone
     # +exit_code+:: exit status you'd like to exit with
     # +message+:: message to display to the user explaining the problem
     #
-    # Also can be used without an exit code like so:
+    # If +exit_code+ is a String and +message+ is omitted, +exit_code+ will be used as the message
+    # and the actual exit code will be 1.
     #
-    #     exit_now!("Oh noes!")
+    # === Examples
     #
-    # In this case, it's equivalent to <code>exit_now!(1,"Oh noes!")</code>.
+    #     exit_now!(4,"Oh noes!") 
+    #       # => exit app with status 4 and show the user "Oh noes!" on stderr
+    #     exit_now!("Oh noes!")   
+    #       # => exit app with status 1 and show the user "Oh noes!" on stderr
+    #     exit_now!(4)            
+    #       # => exit app with status 4 and dont' give the user a message (how rude of you)
     def exit_now!(exit_code,message=nil)
       if exit_code.kind_of?(String) && message.nil?
         raise Methadone::Error.new(1,exit_code)
@@ -21,5 +29,12 @@ module Methadone
         raise Methadone::Error.new(exit_code,message)
       end
     end
+
+    # Exit the program as if the user made an error invoking your app, providing
+    # them the message as well as printing the help.  This is useful if
+    # you have complex UI validation that can't be done by OptionParser.
+    def help_now!(message)
+      raise OptionParser::ParseError.new(message)
+    end
   end
 end

data/lib/methadone/main.rb

@@ -105,6 +105,10 @@ module Methadone
     #
     # The block can accept any parameters, and unparsed arguments
     # from the command line will be passed.
+    #
+    # *Note*: #go! will modify +ARGV+ so any unparsed arguments that you do *not* declare as arguments
+    # to #main will essentially be unavailable.  I consider this a bug, and it should be changed/fixed in
+    # a future version.
     # 
     # To run this method, call #go!
     def main(&block)
@@ -116,7 +120,7 @@ module Methadone
     # Configure the auto-handling of StandardError exceptions caught
     # from calling go!.
     #
-    # leak - if true, go! will *not* catch StandardError exceptions, but instead
+    # leak:: if true, go! will *not* catch StandardError exceptions, but instead
     #        allow them to bubble up.  If false, they will be caught and handled as normal.
     #        This does *not* affect Methadone::Error exceptions; those will NOT leak through.
     def leak_exceptions(leak)
@@ -187,16 +191,33 @@ module Methadone
     #
     # Since, most of the time, this is all you want to do,
     # this makes it more expedient to do so.  The key that is
-    # is set in #options will be a symbol of the option name, without
-    # the dashes.  Note that if you use multiple option names, a key
+    # is set in #options will be a symbol <i>and string</i> of the option name, without
+    # the leading dashes.  Note that if you use multiple option names, a key
     # will be generated for each.  Further, if you use the negatable form,
     # only the positive key will be set, e.g. for <tt>--[no-]verbose</tt>,
     # only <tt>:verbose</tt> will be set (to true or false).
+    #
+    # As an example, this declaration:
+    #
+    #     opts.on("-f VALUE", "--flag")
+    #
+    # And this command-line invocation:
+    #
+    #     $ my_app -f foo
+    #
+    # Will result in all of these forms returning the String "foo":
+    # * <tt>options['f']</tt>
+    # * <tt>options[:f]</tt>
+    # * <tt>options['flag']</tt>
+    # * <tt>options[:flag]</tt>
+    #
+    # Further, any one of those keys can be used to determine the default value for the option.
     def opts
       @option_parser
     end
 
-    # Calls <tt>opts.on</tt> with the given arguments
+    # Calls the +on+ method of #opts with the given arguments (see RDoc for #opts for the additional
+    # help provided).
     def on(*args,&block)
       opts.on(*args,&block)
     end
@@ -231,6 +252,9 @@ module Methadone
     # parsed from the command line.  When you put values in here, if you do so
     # *before* you've declared your command-line interface via #on, the value
     # will be used in the docstring to indicate it is the default.
+    # You can use either a String or a Symbol and, after #go! is called and
+    # the command-line is parsed, the values will be available as both
+    # a String and a Symbol.
     #
     # Example
     #
@@ -253,10 +277,10 @@ module Methadone
     # banner.  This also adds --version as an option to your app which,
     # when used, will act just like --help
     #
-    # version - the current version of your app.  Should almost always be
+    # version:: the current version of your app.  Should almost always be
     #           YourApp::VERSION, where the module YourApp should've been generated
     #           by the bootstrap script
-    # custom_message - if provided, customized the message shown next to --version
+    # custom_message:: if provided, customized the message shown next to --version
     def version(version,custom_message='Show help/version info')
       opts.version(version)
       opts.on("--version",custom_message) do 
@@ -341,6 +365,8 @@ module Methadone
       raise ex if ENV['DEBUG']
       logger.error ex.message unless no_message? ex
       ex.exit_code
+    rescue OptionParser::ParseError
+      raise
     rescue => ex
       raise ex if ENV['DEBUG']
       raise ex if @leak_exceptions
@@ -353,6 +379,8 @@ module Methadone
     end
   end
 
+  # <b>Methadone Internal - treat as private</b>
+  #
   # A proxy to OptionParser that intercepts #on
   # so that we can allow a simpler interface
   class OptionParserProxy < BasicObject

data/lib/methadone/process_status.rb

@@ -0,0 +1,45 @@
+module Methadone
+  # <b>Methadone Internal - treat as private</b>
+  #
+  # A wrapper/enhancement of Process::Status that handles coersion and expected
+  # nonzero statuses
+  class ProcessStatus
+
+    # The exit status, either directly from a Process::Status or derived from a non-Int value.
+    attr_reader :exitstatus
+
+    # Create the ProcessStatus with the given status.
+    #
+    # status:: if this responds to #exitstatus, that method is used to extract the exit code.  If it's
+    #          and Int, that is used as the exit code.  Otherwise,
+    #          it's truthiness is used: 0 for truthy, 1 for falsey.
+    # expected:: an Int or Array of Int representing the expected exit status, other than zero,
+    #            that represent "success".
+    def initialize(status,expected)
+      @exitstatus = derive_exitstatus(status)
+      @success = ([0] + Array(expected)).include?(@exitstatus)
+    end
+
+    # True if the exit status was a successul (i.e. expected) one.
+    def success?
+      @success
+    end
+
+  private
+
+    def derive_exitstatus(status)
+      status = if status.respond_to? :exitstatus
+                 status.exitstatus
+               else
+                 status
+               end
+      if status.kind_of? Fixnum
+        status
+      elsif status
+        0
+      else
+        1
+      end
+    end
+  end
+end

data/lib/methadone/sh.rb

@@ -2,11 +2,18 @@ if RUBY_PLATFORM == 'java'
   require 'java'
   require 'ostruct'
 elsif RUBY_VERSION =~ /^1.8/
+  begin
   require 'open4'
+  rescue LoadError
+    STDERR.puts "!! For Ruby #{RUBY_VERSION}, the open4 library must be installed"
+    raise
+  end
 else
   require 'open3'
 end
 
+require 'methadone/process_status'
+
 module Methadone
   # Module with various helper methods for executing external commands.
   # In most cases, you can use #sh to run commands and have decent logging
@@ -29,23 +36,23 @@ module Methadone
   #    sh! 'cp non_existent_file.txt /nowhere_good'
   #    # => same as above, EXCEPT, raises a Methadone::FailedCommandError
   #
-  #     sh 'cp foo.txt /tmp' do
-  #       # Behaves exactly as before, but this block is called after
-  #     end
+  #    sh 'cp foo.txt /tmp' do
+  #      # Behaves exactly as before, but this block is called after
+  #    end
   #
-  #     sh 'cp non_existent_file.txt /nowhere_good' do
-  #       # This block isn't called, since the command failed
-  #     end
+  #    sh 'cp non_existent_file.txt /nowhere_good' do
+  #      # This block isn't called, since the command failed
+  #    end
   #
-  #     sh 'ls -l /tmp/' do |stdout|
-  #       # stdout contains the output of the command
+  #    sh 'ls -l /tmp/' do |stdout|
+  #      # stdout contains the output of the command
+  #    end
+  #    sh 'ls -l /tmp/ /non_existent_dir' do |stdout,stderr|
+  #      # stdout contains the output of the command,
+  #      # stderr contains the standard error output.
   #     end
-  #     sh 'ls -l /tmp/ /non_existent_dir' do |stdout,stderr|
-  #       # stdout contains the output of the command,
-  #       # stderr contains the standard error output.
-  #      end
   #    
-  # == Handling remote execution
+  # == Handling process execution
   #
   # In order to work on as many Rubies as possible, this class defers the actual execution
   # to an execution strategy.  See #set_execution_strategy if you think you'd like to override
@@ -66,10 +73,15 @@ module Methadone
     # error output is logged at WARN.
     #
     # command:: the command to run
-    # block:: if provided, will be called if the command exited nonzero.  The block may take 0, 1, or 2 arguments.
-    #         The arguments provided are the standard output as a string and the standard error as a string,
+    # options:: options to control the call. Currently responds to:
+    #           +:expected+:: an Int or Array of Int representing error codes, <b>in addition to 0</b>, that are
+    #                         expected and therefore constitute success.  Useful for commands that don't use
+    #                         exit codes the way you'd like
+    # block:: if provided, will be called if the command exited nonzero.  The block may take 0, 1, 2, or 3 arguments.
+    #         The arguments provided are the standard output as a string, standard error as a string, and
+    #         the exitstatus as an Int.
     #         You should be safe to pass in a lambda instead of a block, as long as your
-    #         lambda doesn't take more than two arguments
+    #         lambda doesn't take more than three arguments
     #
     # Example
     #
@@ -82,22 +94,23 @@ module Methadone
     #     end
     #
     # Returns the exit status of the command.  Note that if the command doesn't exist, this returns 127.
-    def sh(command,&block)
+    def sh(command,options={},&block)
       sh_logger.debug("Executing '#{command}'")
 
       stdout,stderr,status = execution_strategy.run_command(command)
+      process_status = Methadone::ProcessStatus.new(status,options[:expected])
 
       sh_logger.warn("Error output of '#{command}': #{stderr}") unless stderr.strip.length == 0
 
-      if status.exitstatus != 0
+      if process_status.success?
+        sh_logger.debug("Output of '#{command}': #{stdout}") unless stdout.strip.length == 0
+        call_block(block,stdout,stderr,process_status.exitstatus) unless block.nil?
+      else
         sh_logger.info("Output of '#{command}': #{stdout}") unless stdout.strip.length == 0
         sh_logger.warn("Error running '#{command}'")
-      else
-        sh_logger.debug("Output of '#{command}': #{stdout}") unless stdout.strip.length == 0
-        call_block(block,stdout,stderr) unless block.nil?
       end
 
-      status.exitstatus
+      process_status.exitstatus
     rescue exception_meaning_command_not_found => ex
       sh_logger.error("Error running '#{command}': #{ex.message}")
       127
@@ -106,7 +119,8 @@ module Methadone
     # Run a command, throwing an exception if the command exited nonzero.
     # Otherwise, behaves exactly like #sh.
     #
-    # options - options hash, responding to:
+    # options:: options hash, responding to:
+    #           <tt>:expected</tt>:: same as for #sh
     #           <tt>:on_fail</tt>:: a custom error message.  This allows you to have your
     #                               app exit on shell command failures, but customize the error
     #                               message that they see.
@@ -120,8 +134,11 @@ module Methadone
     #     sh!("rsync foo bar", :on_fail => "Couldn't rsync, check log for details")
     #     # => if command fails, app exits and user sees: "error: Couldn't rsync, check log for details
     def sh!(command,options={},&block)
-      sh(command,&block).tap do |exitstatus|
-        raise Methadone::FailedCommandError.new(exitstatus,command,options[:on_fail]) if exitstatus != 0
+      sh(command,options,&block).tap do |exitstatus|
+        process_status = Methadone::ProcessStatus.new(exitstatus,options[:expected])
+        unless process_status.success?
+          raise Methadone::FailedCommandError.new(exitstatus,command,options[:on_fail]) 
+        end
       end
     end
 
@@ -138,8 +155,12 @@ module Methadone
     # Set the strategy to use for executing commands.  In general, you don't need to set this
     # since this module chooses an appropriate implementation based on your Ruby platform:
     #
-    # 1.8 Rubies, including 1.8, and REE:: Open4 is used via Methadone::ExecutionStrategy::Open_4
-    # Rubinius:: Open4 is used, but we handle things a bit differently; see Methadone::ExecutionStrategy::RBXOpen_4
+    # 1.8 Rubies, including 1.8, and REE:: Open4 is used via Methadone::ExecutionStrategy::Open_4. <b><tt>open4</tt> will not be
+    #                                      installed as a dependency</b>.  RubyGems doesn't allow conditional dependencies, 
+    #                                      so make sure that your app declares it as a dependency if you think you'll be 
+    #                                      running on 1.8 or REE.
+    # Rubinius:: Open4 is used, but we handle things a bit differently; see Methadone::ExecutionStrategy::RBXOpen_4.
+    #            Same warning on dependencies applies.
     # JRuby:: Use JVM calls to +Runtime+ via Methadone::ExecutionStrategy::JVM
     # Windows:: Currently no support for Windows
     # All others:: we use Open3 from the standard library, via Methadone::ExecutionStrategy::Open_3
@@ -176,15 +197,17 @@ module Methadone
     end
 
     # Safely call our block, even if the user passed in a lambda
-    def call_block(block,stdout,stderr)
+    def call_block(block,stdout,stderr,exitstatus)
       # blocks that take no arguments have arity -1.  Or 0.  Ugh.
       if block.arity > 0
         case block.arity
         when 1 
           block.call(stdout)
+        when 2
+          block.call(stdout,stderr)
         else
           # Let it fail for lambdas
-          block.call(stdout,stderr)
+          block.call(stdout,stderr,exitstatus)
         end
       else
         block.call

data/lib/methadone/version.rb

@@ -1,3 +1,3 @@
 module Methadone
-  VERSION = "1.0.0.rc5"
+  VERSION = "1.0.0.rc6"
 end