execute_shell 0.0.5 → 1.0.0

data/Gemfile

@@ -1,13 +1,3 @@
 source "http://rubygems.org"
 
-group :rake do
-  gem 'rake_tasks', '~> 0.0.1'
-end
-
-group :test do
-  gem 'Platform',       '~> 0.4.0', :require => 'platform'
-  gem 'open4',          '~> 1.0.1'
-  gem 'win32-open3-19', '~> 0.0.1', :require => 'open3'
-
-  gem 'app_mode', '~> 1.0.0'
-end
+gemspec

data/Gemfile.lock

@@ -1,20 +1,24 @@
+PATH
+  remote: .
+  specs:
+    execute_shell (1.0.0)
+      Platform (~> 0.4.0)
+      open4 (~> 1.0.1)
+      win32-open3-19 (~> 0.0.1)
+
 GEM
   remote: http://rubygems.org/
   specs:
     Platform (0.4.0)
-    app_mode (1.0.1)
     open4 (1.0.1)
-    rake (0.8.7)
-    rake_tasks (0.0.4)
-      rake (~> 0.8.7)
+    rake_tasks (2.0.5)
+    test_unit_helper (0.0.1)
     win32-open3-19 (0.0.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  Platform (~> 0.4.0)
-  app_mode (~> 1.0.0)
-  open4 (~> 1.0.1)
-  rake_tasks (~> 0.0.1)
-  win32-open3-19 (~> 0.0.1)
+  execute_shell!
+  rake_tasks (~> 2.0.5)
+  test_unit_helper (~> 0.0.1)

data/README

@@ -20,24 +20,43 @@ in the octagon with a pig.
 
 == Usage
 
-1. Include the ExecuteShell module in your class or module:
+1. Simply call ExecuteShell.run as needed:
 
-    include ExecuteShell
+    result = ExecuteShell.run('ls ~')
 
-2. Call a shell command:
+   result will be a ShellResult object containing information
+   regarding the executed command.
 
-    success, output = shell('ls ~')
+   Available methods include:
+
+    out ...... Standard out.
+    err ...... Standard error.
+    success? . Whether the command was executed successfully.
+    to_s ..... Standard out and standard error concatenated.
+
+2. If you wish to simply get a single success, output, or error value back,
+   you may use calls such as:
+
+    ExecuteShell.run_success?('ls ~')
+    ExecuteShell.run_out('ls ~')
+    ExecuteShell.run_err('ls ~')
+    ExecuteShell.run_to_s('ls ~')
+
+   These may be chained together and will be returned in an array in the order
+   they are specified:
+
+    ExecuteShell.run_out_err('ls ~')
+    ExecuteShell.run_to_s_success_out('ls ~')
+    ExecuteShell.run_err_out_success('ls ~')
 
 == Additional Notes
 
-* The shell method has a second optional parameter, which is a path.
+* The run method has a second optional parameter, which is a path.
   If specified, the working directory will be changed to this path prior
   to executing the shell command. It will be set back to the original
   working directory before returning to the calling function.
 
-* Success will be false under two conditions. One is if there is any output
-  to stderr. The other is if an exception is raised. In either case, the
-  information is returned in the output.
+* Success is based on the content of the err attribute of ShellResult.
 
 == Additional Documentation
 
@@ -45,4 +64,6 @@ in the octagon with a pig.
 
 == License
 
-ExecuteShell is released under the GPLv3 license.
+ExecuteShell is released under the {LGPLv3 license}[link:../../license/lgpl].
+
+link:../../license/lgplv3-88x31.png

data/execute_shell.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name    = 'execute_shell'
-  s.version = '0.0.5'
+  s.version = '1.0.0'
 
   s.summary     = 'Cross-platform shell commands.'
   s.description = %Q{
@@ -13,20 +13,20 @@ in the octagon with a pig.
   s.email    = 'tthetoad@gmail.com'
   s.homepage = 'http://www.bitbucket.org/ToadJamb/gems_execute_shell'
 
-  s.license = 'GPLv3'
+  s.license = 'LGPLv3'
 
-  s.extra_rdoc_files << 'README'
+  s.extra_rdoc_files = Dir['README', 'license/*']
 
   s.require_paths = ['lib']
-  s.files = Dir['lib/**/*.rb', '*']
+  s.files = Dir['*', 'lib/**/*.rb', 'license/*']
   s.test_files = Dir['test/**/*.rb']
 
   s.add_dependency 'Platform',       '~> 0.4.0'
   s.add_dependency 'open4',          '~> 1.0.1'
   s.add_dependency 'win32-open3-19', '~> 0.0.1'
-  s.add_dependency 'app_mode',       '~> 1.0.0'
 
-  s.add_development_dependency 'rake_tasks', '~> 0.0.1'
+  s.add_development_dependency 'rake_tasks',       '~> 2.0.5'
+  s.add_development_dependency 'test_unit_helper', '~> 0.0.1'
 
   s.has_rdoc = true
 end

data/lib/execute_shell.rb

@@ -1,8 +1,45 @@
+#--
+################################################################################
+#                      Copyright (C) 2011 Travis Herrick                       #
+################################################################################
+#                                                                              #
+#                                 \v^V,^!v\^/                                  #
+#                                 ~%       %~                                  #
+#                                 {  _   _  }                                  #
+#                                 (  *   -  )                                  #
+#                                 |    /    |                                  #
+#                                  \   _,  /                                   #
+#                                   \__.__/                                    #
+#                                                                              #
+################################################################################
+# This program is free software: you can redistribute it                       #
+# and/or modify it under the terms of the GNU Lesser General Public License    #
+# as published by the Free Software Foundation,                                #
+# either version 3 of the License, or (at your option) any later version.      #
+################################################################################
+# This program is distributed in the hope that it will be useful,              #
+# but WITHOUT ANY WARRANTY;                                                    #
+# without even the implied warranty of MERCHANTABILITY                         #
+# or FITNESS FOR A PARTICULAR PURPOSE.                                         #
+# See the GNU Lesser General Public License for more details.                  #
+#                                                                              #
+# You should have received a copy of the GNU Lesser General Public License     #
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.        #
+################################################################################
+#++
+
 gem_name = File.basename(__FILE__, '.rb')
 
-require 'app_mode'
 require 'platform'
-require 'open4' if [:linux].include?(Platform::IMPL)
-require 'open3' if [:mingw].include?(Platform::IMPL)
 
+case Platform::IMPL
+  when :linux
+    require 'open4'
+  when :mingw
+    require 'open3'
+end
+
+require_relative File.join(gem_name, 'shell_result')
 require_relative File.join(gem_name, gem_name)
+
+ExecuteShell.raise_not_implemented(gem_name) unless ExecuteShell.supported?

data/lib/execute_shell/execute_shell.rb

@@ -15,62 +15,50 @@
 #                                                                              #
 ################################################################################
 # This program is free software: you can redistribute it                       #
-# and/or modify it under the terms of the GNU General Public License           #
+# and/or modify it under the terms of the GNU Lesser General Public License    #
 # as published by the Free Software Foundation,                                #
 # either version 3 of the License, or (at your option) any later version.      #
-#                                                                              #
-# Commercial licensing may be available for a fee under a different license.   #
 ################################################################################
 # This program is distributed in the hope that it will be useful,              #
 # but WITHOUT ANY WARRANTY;                                                    #
 # without even the implied warranty of MERCHANTABILITY                         #
 # or FITNESS FOR A PARTICULAR PURPOSE.                                         #
-# See the GNU General Public License for more details.                         #
+# See the GNU Lesser General Public License for more details.                  #
 #                                                                              #
-# You should have received a copy of the GNU General Public License            #
+# You should have received a copy of the GNU Lesser General Public License     #
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.        #
 ################################################################################
 #++
 
 # Contains methods for returning output from console commands.
-module ExecuteShell
-  # Indicates the mode that ExecuteShell is running in.
-  ExecuteShellMode = StateManager.new(:production)
-
-  # Returns output from a console command.
-  # ==== Input
-  # [command : String] The command to be run.
-  # [path : String : Dir.getwd] The path to use for the command.
-  # ==== Output
-  # [Boolean] Whether the shell execution was successful.
-  #
-  #          This is determined in two ways.
-  #          The first is if anything is sent to stderr.
-  #          The second is whether any exceptions occurred.
-  #
-  # [String] The output from the shell command.
-  #
-  #          This will include any messages sent to stderr,
-  #          as well as those sent to stdout.
-  #          Any exceptions are included in this return value, as well.
-  def shell(command, path = Dir.getwd)
-    raise_not_implemented(__method__) unless
-      [:linux, :mingw].include?(Platform::IMPL)
-
-    out = ''
-    err = ''
-    success = nil
-
-    path ||= Dir.getwd
-
-    begin
-      STDOUT.puts command if ExecuteShellMode.development
+class ExecuteShell
+  class << self
+    # Raises an error indicating that the class/method/feature is not supported.
+    # ==== Input
+    # [text : String] The class/method/feature that isnot supported.
+    def raise_not_implemented(text)
+      raise NotImplementedError,
+        "#{text} has not been implemented for #{Platform::IMPL}."
+    end
+
+    # Returns output from a console command.
+    # ==== Input
+    # [command : String] The command to be run.
+    # [path : String : Dir.getwd] The path to use for the command.
+    # ==== Output
+    # [ShellResult] A ShellResult object that contains information
+    #               regarding the output, errors, and success.
+    def run(command, path = File.expand_path(Dir.getwd))
+      raise_not_implemented(__method__) unless supported?
+
+      out = ''
+      err = ''
 
       block = case Platform::IMPL
         when :mingw
           lambda {
             # Run the command and wait for it to execute.
-            result = Open3::popen3('cmd') do |std_in, std_out, std_err, thread|
+            Open3::popen3('cmd') do |std_in, std_out, std_err, thread|
               # Set up the command.
               std_in.puts command
 
@@ -85,7 +73,7 @@ module ExecuteShell
         when :linux
           lambda {
             # Run the command and wait for it to execute.
-            result = Open4::popen4('bash') do |pid, std_in, std_out, std_err|
+            Open4::popen4('bash') do |pid, std_in, std_out, std_err|
               # Set up the command.
               std_in.puts command
 
@@ -99,93 +87,159 @@ module ExecuteShell
           }
       end
 
-      wrap_success, wrap_out = wrap_path(path, block)
-
-      # Success is determined by lack of error text.
-      success = err.empty?
+      wrap_path path, block
 
-      # Remove all the extra stuff that the cmd prompt adds.
-      if Platform::IMPL == :mingw
-        out.gsub!(/\n\n#{path.gsub(%r[/], '\\\\\\')}>\Z/, '')
+      out = ShellResult.cleanup(command, path, out)
 
-        # replace contains the command line prompt
-        # and the command up to the first space.
-        replace = path.gsub(%r[/], '\\\\\\')
-        replace += '>'
-        replace += command[0..(command.index(/ /) || 0) - 1]
-
-        # Remove the header portion of the text.
-        # This includes the Microsoft 'banner' text
-        # that consumes the first two lines.
-        out = out.gsub(/\A.+#{replace}.*?$/m, '').strip
-      end
+      return ShellResult.new(out, err)
+    end
 
-      # Set the error flag and notify the user if anything went wrong.
-      out = (out + "\n" + err).strip unless success
-      out += wrap_out.strip unless wrap_success
+    # Indicates whether the specified operating system is supported.
+    # ==== Input
+    # [os : Symbol,String : Platform::IMPL] The operating system to check for.
+    # ==== Output
+    # [Boolean] A boolean value indicating whether the system is supported.
+    # ==== Examples
+    #  ExecuteShell.supported?         #=> true
+    #  ExecuteShell.supported?(:linux) #=> true
+    #  ExecuteShell.supported?(:my_os) #=> false
+    def supported?(os = Platform::IMPL)
+      supported_systems.include? os.to_sym
+    end
 
-      # Include the wrapper's success flag in the resulting success flag.
-      success = success && wrap_success
-    rescue Exception => exc
-      # Format exception messages.
-      success = false
-      out += format_error(exc)
+    # Returns an array of the supported systems as returned by Platform::IMPL.
+    # ==== Output
+    # [Array] The supported operating systems.
+    # ==== Examples
+    #  ExecuteShell.supported_systems #=> [:linux, :mingw]
+    def supported_systems
+      [:linux, :mingw]
     end
 
-    return success, out
-  end
+    # Allows method calls such as run_success? or run_err_out.
+    # ==== Input
+    # [method : Symbol] The missing method that is being called.
+    # [*args : Array] Arguments that were passed to the method.
+    # [&block : Block] The block passed to the method.
+    # ==== Output
+    # The output depends on the method called.
+    #
+    # This method supports any method that starts with "run_" and
+    # combines methods available from a ShellResult object.
+    #
+    # For example, the following are all valid calls:
+    #  ExecuteShell.run_success? "echo 'hi'"
+    #  ExecuteShell.run_success "echo 'hi'"
+    #  ExecuteShell.run_success_err_out "echo 'hi'"
+    #  ExecuteShell.run_out_to_s_err "echo 'hi'"
+    #
+    # If only one method name is provided, that value will be returned alone.
+    #
+    # If more than one method name is provided, the results will be returned
+    # in an array listing the results in the order specified in the method call.
+    def method_missing(method, *args, &block)
+      return super unless method.to_s =~ /^run_/
+
+      # Execute the command.
+      shell_result = run(*args)
+
+      # Get a list of the requested result values.
+      method_list = method.to_s.sub(/^run_/, '').split('_')
+
+      results = []
+      skip = nil
+
+      # Loop through the methods, building an array of result values.
+      method_list.each_with_index do |item, i|
+        # Skip to the next one if two methods have already been combined.
+        # i.e. 'to_s'
+        if skip
+          skip = false
+          next
+        end
+
+        item += '?' if item == 'success'
+
+        if item == 'to'
+          item += "_#{method_list[i + 1]}"
+          skip = true
+        end
+
+        results << shell_result.send(item.to_sym)
+      end
 
-  ############################################################################
-  private
-  ############################################################################
-
-  # Formats error messages.
-  # ==== Input
-  # [exception : Exception] The error that was raised.
-  # ==== Output
-  # [String] The error information in a readable format.
-  def format_error(exception)
-    error_format = '%s: %s%s'
-    error_format % [exception.class, exception.message,
-      ExecuteShellMode.development ? "\n#{exception.backtrace.join("\n")}" : '']
-  end
+      # Return the result(s) in an appropriate way.
+      return case results.length
+        when 0; nil
+        when 1; results[0]
+        else; results
+      end
+    end
 
-  # Raises a NotImplementedError.
-  # ==== Input
-  # [method : String] The method that does not have
-  #                   an implementation for the current platform.
-  def raise_not_implemented(method)
-    raise NotImplementedError,
-      "#{method} " +
-      "has not been implemented for #{Platform::IMPL}."
-  end
+    # Indicates that this class will respond to
+    # calls such as run_success? or run_err_out.
+    # ==== Input
+    # [method : Symbol] The method that is being checked.
+    # [include_private : Boolean] Whether to include private methods
+    #                             in the search.
+    # ==== Output
+    # [Boolean] Indicates whether the class responds to the specified method.
+    # ==== Examples
+    #  a #=> b
+    def respond_to_missing?(method, include_private)
+      return super unless method.to_s =~ /^run_/
+
+      method_list = method.to_s.sub(/^run_/, '').split('_')
+
+      skip = nil
+
+      shell_result = ShellResult.new('', '')
+
+      # Loop through the methods, checking the validity of each.
+      method_list.each_with_index do |item, i|
+        # Skip to the next one if two methods have already been combined.
+        # i.e. 'to_s'
+        if skip
+          skip = false
+          next
+        end
+
+        item += '?' if item == 'success'
+
+        if item == 'to'
+          item += "_#{method_list[i + 1]}"
+          skip = true
+        end
+
+        # Return false if the ShellResult object does not respond to the method.
+        return false unless shell_result.respond_to?(item.to_sym)
+      end
 
-  # Runs a block of code by changing the path first.
-  # ==== Input
-  # [path : String] The path to change to prior to running the block.
-  # [block : Proc] The code block to execute.
-  # [*args : Array] Any other parameters
-  #                 that will be passed on to <tt>block</tt>.
-  # ==== Output
-  # [Boolean] Indicates whether the block was executed successfully.
-  # [String] Any error messages from trapped errors.
-  def wrap_path(path, block, *args)
-    path ||= File.expand_path(Dir.getwd)
-    original = File.expand_path(Dir.getwd)
-    out = nil
-
-    STDOUT.puts path if ExecuteShellMode.development
-
-    begin
-      Dir.chdir path unless path == original
-      block.call(*args)
-    rescue Exception => exc
-      # Format exception messages.
-      out = format_error(exc)
-    ensure
-      Dir.chdir original unless path == original
+      return true
     end
 
-    return out.nil?, out
+    ########################################################################
+    private
+    ########################################################################
+
+    # Runs a block of code by changing the path first.
+    # ==== Input
+    # [path : String] The path to change to prior to running the block.
+    # [block : Proc] The code block to execute.
+    # [*args : Array] Any other parameters
+    #                 that will be passed on to <tt>block</tt>.
+    # ==== Output
+    # [String] Any error messages from trapped errors.
+    def wrap_path(path, block, *args)
+      path ||= File.expand_path(Dir.getwd)
+      original = File.expand_path(Dir.getwd)
+
+      begin
+        Dir.chdir path unless path == original
+        block.call(*args)
+      ensure
+        Dir.chdir original unless path == original
+      end
+    end
   end
 end