methadone 0.5.1 → 1.0.0.rc1

data/.gitignore

@@ -7,3 +7,4 @@ html
 tmp
 results.html
 coverage
+*.rbc

data/Gemfile

@@ -1,4 +1,5 @@
 source "http://rubygems.org"
 
+gem 'open4', :platform => :ruby_18
 # Specify your gem's dependencies in methadone.gemspec
 gemspec

data/README.rdoc

@@ -12,6 +12,7 @@ Currently, this library is under development and has the following to offer:
 
 * Bootstrapping a new CLI app
 * Lightweight DSL to structure your bin file
+* Simple wrapper for running external commands with good logging
 * Utility Classes
   * Methadone::CLILogger - a logger subclass that sends messages to standard error standard out as appropriate
   * Methadone::CLILogging - a module that, when included in any class, provides easy access to a shared logger
@@ -22,7 +23,18 @@ Currently, this library is under development and has the following to offer:
 * {Source on Github}[http://github.com/davetron5000/methadone]
 * RDoc[http://rdoc.info/github/davetron5000/methadone/master/frames]
 
-== Bootstrapping
+== Platforms
+
+* Works completely on:
+  * MRI Ruby 1.9.2
+  * MRI Ruby 1.9.3
+  * MRI Ruby Head
+  * MRI Ruby 1.8.7
+  * RBX
+  * REE
+* For JRuby, everything works but aruba; aruba just doesn't work on JRuby for some reason, though this library *is* being used in production under JRuby 1.6.6
+
+== Bootstrapping a new CLI App
 
 The +methadone+ command-line app will bootstrap a new command-line app, setting up a proper gem structure, unit tests, and cucumber-based tests with aruba:
 
@@ -112,6 +124,52 @@ don't accept options, <tt>[options]</tt> won't appear in the help.  The names of
 will appear in proper order and <tt>:optional</tt> ones will be in square brackets.  You don't have to 
 touch a thing.
 
+== Wrapper for running external commands with good logging
+
+While backtick and <tt>%x[]</tt> are nice for compact, bash-like scripting, they have some failings:
+
+* You have to check the return value via <tt>$?</tt>
+* You have no access to the standard error
+* You really want to log: the command, the output, and the error so that for cron-like tasks, you can sort out what happened
+
+Enter Methadone::SH
+
+    include Methadone::SH
+
+    sh 'cp foo.txt /tmp'
+    # => logs the command to DEBUG, executes the command, logs its output to DEBUG and its
+    #    error output to WARN, returns 0
+    
+    sh 'cp non_existent_file.txt /nowhere_good'
+    # => logs the command to DEBUG, executes thecommand, logs its output to INFO and
+    #    its error output to WARN, returns the nonzero exit status of the underlying command
+    
+    sh! 'cp non_existent_file.txt /nowhere_good'
+    # => same as above, EXCEPT, raises a Methadone::FailedCommandError
+
+With this, you can easily script external commands in *almost* as expedient a fashion as with +bash+, however you get sensible logging along the way.  By default, this uses the logger provided by Methadone::CLILogging (which is *not* mixed in when you mix in Methadone::SH).  If you want to use a different logger, or don't want to mix in Methadone::CLILogging, simply call +set_sh_logger+ with your preferred logger.
+
+But that's not all!  You can run code when the command succeed by passing a block:
+
+    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
+
+The <tt>sh!</tt> form works this way as well.  The block form is also how you can access the standard output or error of the command that ran.  Simply have your block accept one or two aguments:
+
+    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
+
+This isn't a replacement for Open3 or ChildProcess, but a way to easily "do the right thing" for most cases.
 
 == Utility Classes
 

data/Rakefile

@@ -15,7 +15,7 @@ Rake::TestTask.new do |t|
   t.libs << "lib"
   t.libs << "test"
   t.ruby_opts << "-rrubygems"
-  t.test_files = FileList['test/test_*.rb']
+  t.test_files = FileList['test/test_*.rb'] + FileList['test/execution_strategy/test_*.rb']
 end
 
 desc 'build rdoc'
@@ -43,5 +43,5 @@ Cucumber::Rake::Task.new('features:wip') do |t|
 end
 
 CLEAN << "coverage"
-
+CLOBBER << FileList['**/*.rbc']
 task :default => [:test, :features]

data/bin/methadone

@@ -8,6 +8,7 @@ require 'methadone/cli'
 include FileUtils
 include Methadone::Main
 include Methadone::CLI
+include Methadone::SH
 
 main do |app_name|
   check_and_prepare_basedir!(app_name,options[:force])
@@ -20,7 +21,7 @@ main do |app_name|
 
   chdir File.dirname(app_name)
 
-  %x[bundle gem #{gemname}]
+  sh! "bundle gem #{gemname}"
 
   chdir gemname
 
@@ -50,11 +51,12 @@ main do |app_name|
   copy_file "features/step_definitions/executable_steps.rb", :as => "#{gemname}_steps.rb"
   copy_file "bin/executable", :as => gemname, :executable => true, :binding => binding
 
+  gem_variable = File.open("#{gemname}.gemspec") { |x| x.read }.match(/(\w+)\.executables/)[1]
   add_to_file "#{gemname}.gemspec", [
-    "  s.add_development_dependency('rdoc')",
-    "  s.add_development_dependency('aruba')",
-    "  s.add_development_dependency('rake','~> 0.9.2')",
-    "  s.add_dependency('methadone')",
+    "  #{gem_variable}.add_development_dependency('rdoc')",
+    "  #{gem_variable}.add_development_dependency('aruba')",
+    "  #{gem_variable}.add_development_dependency('rake','~> 0.9.2')",
+    "  #{gem_variable}.add_dependency('methadone')",
   ], :before => /^end\s*$/
 end
 

data/features/bootstrap.feature

@@ -35,6 +35,7 @@ Feature: Bootstrap a new command-line app
     And the file "tmp/newgem/newgem.gemspec" should match /add_development_dependency\('rdoc'/
     And the file "tmp/newgem/newgem.gemspec" should match /add_development_dependency\('rake','~> 0.9.2'/
     And the file "tmp/newgem/newgem.gemspec" should match /add_dependency\('methadone'/
+    And the file "tmp/newgem/newgem.gemspec" should use the same block variable throughout
     Given I cd to "tmp/newgem"
     And my app's name is "newgem"
     When I successfully run `bin/newgem --help` with "lib" in the library path

data/features/step_definitions/bootstrap_steps.rb

@@ -10,6 +10,15 @@ Given /^my app's name is "([^"]*)"$/ do |app_name|
   @app_name = app_name
 end
 
+Then /^the file "([^"]*)" should use the same block variable throughout$/ do |file|
+  prep_for_fs_check do
+    content = IO.read(file)
+    from_bundler = content.match(/(\w+)\.authors/)[1]
+    added_by_methadone = content.match(/(\w+).add_development_dependency\('rdoc'/)[1]
+    from_bundler.should == added_by_methadone
+  end
+end
+
 Then /^the stderr should match \/([^\/]*)\/$/ do |expected|
   assert_matching_output(expected, all_stderr)
 end

data/features/step_definitions/version_steps.rb

@@ -1,4 +1,4 @@
 When /^I successfully run `([^`]*)` with "([^"]*)" in the library path$/ do |command,dir|
-  ENV["RUBYOPT"] = "-I" + File.join(Dir.pwd,ARUBA_DIR,'tmp','newgem',dir)
+  ENV["RUBYOPT"] = (ENV["RUBYOPT"] || '') + " -I" + File.join(Dir.pwd,ARUBA_DIR,'tmp','newgem',dir)
   step %(I successfully run `#{command}`)
 end

data/features/support/env.rb

@@ -9,13 +9,18 @@ Before do
   @puts = true
   @aruba_timeout_seconds = 60
   @original_rubylib = ENV['RUBYLIB']
+  @original_rubyopt = ENV['RUBYOPT']
 
   # We want to use, hopefully, the methadone from this codebase and not
   # the gem, so we put it in the RUBYLIB
   ENV['RUBYLIB'] = File.join(PROJECT_ROOT,'lib') + File::PATH_SEPARATOR + ENV['RUBYLIB'].to_s
+
+  # We need -rubygems here so that 1.8-style rubies work AND travis-ci doesn't barf with it in the shebang line
+  ENV['RUBYOPT'] = (ENV['RUBYOPT'] || '') + ' -rubygems'
 end
 
 After do
   # Put back how it was
   ENV['RUBYLIB'] = @original_rubylib
+  ENV['RUBYOPT'] = @original_rubyopt
 end

data/features/version.feature

@@ -1,4 +1,3 @@
-@wip
 Feature: The version should show up in the banner by default
   As a developer
   I should be able to have the current gem version in the banner

data/lib/methadone.rb

@@ -3,4 +3,11 @@ require 'methadone/cli_logger'
 require 'methadone/cli_logging'
 require 'methadone/main'
 require 'methadone/error'
+require 'methadone/execution_strategy/base'
+require 'methadone/execution_strategy/mri'
+require 'methadone/execution_strategy/open_3'
+require 'methadone/execution_strategy/open_4'
+require 'methadone/execution_strategy/rbx_open_4'
+require 'methadone/execution_strategy/jvm'
+require 'methadone/sh'
 # Note: DO NOT require cli.rb OR cucumber.rb here

data/lib/methadone/error.rb

@@ -9,4 +9,16 @@ module Methadone
       @exit_code = exit_code
     end
   end
+
+  # Thrown by certain methods when an externally-called command exits nonzero
+  class FailedCommandError < Error
+
+    # The command that caused the failure
+    attr_reader :command
+
+    def initialize(exit_code,command)
+      super(exit_code,"Command '#{command}' exited #{exit_code}")
+      @command = command
+    end
+  end
 end

data/lib/methadone/execution_strategy/base.rb

@@ -0,0 +1,37 @@
+module Methadone
+  # Module to contain ExecutionStrategy implementations.
+  # To build your own simply implement two methods:
+  #
+  # <tt>exception_meaning_command_not_found</tt>:: return the class that, if caught, means that the underlying command
+  #                                                couldn't be found.  This is needed because currently impelmentations
+  #                                                throw an exception, but they don't all throw the same one.
+  module ExecutionStrategy
+    # Base for any ExecutionStrategy implementation.  Currently, this is nothing more than an interface
+    # specification.
+    class Base
+      # Executes the command and returns the results back.
+      # This should do no logging or other logic other than to execute the command
+      # and return the required results.
+      #
+      # command:: the command-line to run, as a String
+      #
+      # Returns an array of size 3:
+      # <tt>[0]</tt>:: The standard output of the command as a String, never nil
+      # <tt>[1]</tt>:: The standard error output of the command as a String, never nil
+      # <tt>[2]</tt>:: A Process::Status-like objects that responds to <tt>exitstatus</tt> which returns
+      #                the exit code of the command (e.g. 0 for success).
+      def run_command(command)
+        subclass_must_impelment!
+      end
+
+      # Returns the class that, if caught by calling #run_command, represents the underlying command
+      # not existing.  For example, in MRI Ruby, if you try to execute a non-existent command,
+      # you get a Errno::ENOENT.
+      def exception_meaning_command_not_found
+        subclass_must_impelment!
+      end
+    protected
+      def subclass_must_impelment!; raise "subclass must implement"; end
+    end
+  end
+end

data/lib/methadone/execution_strategy/jvm.rb

@@ -0,0 +1,30 @@
+module Methadone
+  module ExecutionStrategy
+    # Methadone::ExecutionStrategy for the JVM that uses JVM classes to run the command and get its results.
+    class JVM < Base
+      def run_command(command)
+        process = java.lang.Runtime.get_runtime.exec(command)
+        process.get_output_stream.close
+        stdout = input_stream_to_string(process.get_input_stream)
+        stderr = input_stream_to_string(process.get_error_stream)
+        exitstatus = process.wait_for
+        [stdout.chomp,stderr.chomp,OpenStruct.new(:exitstatus => exitstatus)]
+      end
+
+      def exception_meaning_command_not_found
+        NativeException
+      end
+
+    private
+      def input_stream_to_string(is)
+        ''.tap do |string|
+          ch = is.read
+          while ch != -1
+            string << ch
+            ch = is.read
+          end
+        end
+      end
+    end
+  end
+end

data/lib/methadone/execution_strategy/mri.rb

@@ -0,0 +1,14 @@
+module Methadone
+  module ExecutionStrategy
+    # Base strategy for MRI rubies.
+    class MRI < Base
+      def run_command(command)
+        raise "subclass must implement"
+      end
+
+      def exception_meaning_command_not_found
+        Errno::ENOENT
+      end
+    end
+  end
+end

data/lib/methadone/execution_strategy/open_3.rb

@@ -0,0 +1,11 @@
+module Methadone
+  module ExecutionStrategy
+    # Implementation for modern Rubies that uses the built-in Open3 library
+    class Open_3 < MRI
+      def run_command(command)
+        stdout,stderr,status = Open3.capture3(command)
+        [stdout.chomp,stderr.chomp,status]
+      end
+    end
+  end
+end

data/lib/methadone/execution_strategy/open_4.rb

@@ -0,0 +1,16 @@
+module Methadone
+  module ExecutionStrategy
+    # ExecutionStrategy for non-modern Rubies that must rely on
+    # Open4 to get access to the standard output AND error.
+    class Open_4 < MRI
+      def run_command(command)
+        pid, stdin_io, stdout_io, stderr_io = Open4::popen4(command)
+        stdin_io.close
+        stdout = stdout_io.read
+        stderr = stderr_io.read
+        _ , status = Process::waitpid2(pid)
+        [stdout.chomp,stderr.chomp,status]
+      end
+    end
+  end
+end

data/lib/methadone/execution_strategy/rbx_open_4.rb

@@ -0,0 +1,10 @@
+module Methadone
+  module ExecutionStrategy
+    # 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
+        Errno::EINVAL
+      end
+    end
+  end
+end

data/lib/methadone/sh.rb

@@ -0,0 +1,143 @@
+if RUBY_PLATFORM == 'java'
+  require 'java'
+  require 'ostruct'
+elsif RUBY_VERSION =~ /^1.8/
+  require 'open4'
+else
+  require 'open3'
+end
+
+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
+  # done.  You will likely use this in a class that also mixes-in
+  # Methadone::CLILogging.  If you *don't*, you must provide a logger
+  # via #set_sh_logger.
+  #
+  # 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
+  # that, or just want to know how it works.
+  #
+  # This is not intended to be a complete replacement for Open3, but instead of make common cases
+  # and good practice easy to accomplish.
+  module SH
+    # Run a shell command, capturing and logging its output.
+    # If the command completed successfully, it's output is logged at DEBUG.
+    # If not, its output as logged at INFO.  In either case, its
+    # 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,
+    #         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
+    #
+    # Example
+    #
+    #     sh "cp foo /tmp"
+    #     sh "ls /tmp" do |stdout|
+    #       # stdout contains the output of ls /tmp
+    #     end
+    #     sh "ls -l /tmp foobar" do |stdout,stderr|
+    #       # ...
+    #     end
+    #
+    # Returns the exit status of the command.  Note that if the command doesn't exist, this returns 127.
+    def sh(command,&block)
+      sh_logger.debug("Executing '#{command}'")
+
+      stdout,stderr,status = execution_strategy.run_command(command)
+
+      sh_logger.warn("Error output of '#{command}': #{stderr}") unless stderr.strip.length == 0
+
+      if status.exitstatus != 0
+        sh_logger.info("Output of '#{command}': #{stdout}")
+        sh_logger.warn("Error running '#{command}'")
+      else
+        sh_logger.debug("Output of '#{command}': #{stdout}") 
+        call_block(block,stdout,stderr) unless block.nil?
+      end
+
+      status.exitstatus
+    rescue exception_meaning_command_not_found => ex
+      sh_logger.error("Error running '#{command}': #{ex.message}")
+      127
+    end
+
+    # Run a command, throwing an exception if the command exited nonzero.
+    # Otherwise, behaves exactly like #sh.
+    #
+    # Raises Methadone::FailedCommandError if the command exited nonzero.
+    def sh!(command,&block)
+      sh(command,&block).tap do |exitstatus|
+        raise Methadone::FailedCommandError.new(exitstatus,command) if exitstatus != 0
+      end
+    end
+
+    # Override the default logger (which is the one provided by CLILogging).
+    # You would do this if you want a custom logger or you aren't mixing-in
+    # CLILogging.
+    #
+    # Note that this method is *not* called <tt>sh_logger=</tt> to avoid annoying situations
+    # where Ruby thinks you are setting a local variable
+    def set_sh_logger(logger)
+      @sh_logger = logger
+    end
+
+    # 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
+    # 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
+    #
+    # See Methadone::ExecutionStrategy::Base for how to implement your own.
+    def set_execution_strategy(strategy)
+      @execution_strategy = strategy
+    end
+
+  private 
+
+    def exception_meaning_command_not_found
+      execution_strategy.exception_meaning_command_not_found
+    end
+
+    def self.default_execution_strategy_class
+      if RUBY_PLATFORM == 'java'
+        Methadone::ExecutionStrategy::JVM
+      elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx'
+        Methadone::ExecutionStrategy::RBXOpen_4
+      elsif RUBY_VERSION =~ /^1.8/
+        Methadone::ExecutionStrategy::Open_4
+      else
+        Methadone::ExecutionStrategy::Open_3
+      end
+    end
+
+    def execution_strategy
+      @execution_strategy ||= SH.default_execution_strategy_class.new 
+    end
+
+    def sh_logger
+      @sh_logger ||= self.logger
+    end
+
+    # Safely call our block, even if the user passed in a lambda
+    def call_block(block,stdout,stderr)
+      # blocks that take no arguments have arity -1.  Or 0.  Ugh.
+      if block.arity > 0
+        case block.arity
+        when 1 
+          block.call(stdout)
+        else
+          # Let it fail for lambdas
+          block.call(stdout,stderr)
+        end
+      else
+        block.call
+      end
+    end
+  end
+end