shell-executer 1.0.0

data/README

@@ -0,0 +1,61 @@
+= shell-executer
+
+Shell::Executer provides an easy and robust way to execute shell commands.
+The stdout and stderr data can be read completely after the execution or
+in chunks during the execution. If the data is processed in chunks this could
+be done by line or by char.
+
+Command execution is done utilizing open4[http://rubyforge.org/projects/codeforpeople/].
+
+by {Holger Kohnen}[http://www.holgerkohnen.de]
+
+== Download and Installation
+
+You can download shell-executer from here[http://rubyforge.org/projects/shell-executer/] or install it with the following command.
+
+ $ gem install shell-executer
+
+== License
+
+You may use, copy and redistribute this library under the same terms as Ruby itself (see http://www.ruby-lang.org/en/LICENSE.txt).
+
+== Usage
+ require 'shell/executer.rb'
+
+ # execute and read standard output
+ Shell.execute('echo hello').stdout # => "hello\n"
+
+ # execute and read error output
+ Shell.execute('echo >&2 error').stderr # => "error\n"
+
+ # execute and check if the command exited with success
+ Shell.execute('ls /tmp').success? # => true
+ Shell.execute('ls /not_existing').success? # => false
+
+ # execute and process every line of output with block
+ Shell.execute('echo hello; echo world') {|stdout| print stdout }
+ # => "hello\n"
+ # => "world\n"
+
+ # execute and process every char of output with block
+ Shell.execute('echo 42', :mode => :chars) {|stdout| puts stdout }
+ # => "4\n"
+ # => "2\n"
+
+ # execute and process every line of stdout or stderr
+ Shell.execute('echo hello; echo >&2 error') do |stdout, stderr|
+   if stdout
+     print 'OUT> %s' % stdout
+   else
+     print 'ERR> %s' % stderr
+   end
+ end
+ # => "OUT> hello\n"
+ # => "ERR> error\n"
+
+ # execute and throw an exception if the process exited without success
+ begin
+   Shell.execute!('ls /not_existing')
+ rescue RuntimeError => e
+   print e.message # <= prints stderr
+ end

data/Rakefile

@@ -0,0 +1,68 @@
+require 'rubygems'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+TITLE        = 'shell-executer'
+DESCRIPTION  = <<-EOS
+  Shell::Executer provides an easy and robust way to execute shell commands.
+  The stdout and stderr data can be read completly after the execution or
+  in chunks during the execution.
+EOS
+AUTHOR       = 'Holger Kohnen'
+AUTHOR_EMAIL = 'h.kohnen@gmail.com'
+GEM_VERSION  = '1.0.0'
+HOMEPAGE     = "http://#{TITLE}.rubyforge.org/"
+PROJECT_NAME = TITLE
+
+task :default => :test
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList[
+    'test/test*.rb'
+  ]
+  t.warning = true
+  t.verbose = false
+end
+
+desc 'Generate RDoc'
+Rake::RDocTask.new do |task|
+  task.main = 'README'
+  task.title = TITLE
+  task.rdoc_dir = 'doc'
+  task.options << "--line-numbers" << "--inline-source"
+  task.rdoc_files.include('README', 'lib/**/*.rb')
+end
+
+specification = Gem::Specification.new do |s|
+  s.name = TITLE
+  s.summary = DESCRIPTION
+  s.version = GEM_VERSION
+  s.author = AUTHOR
+  s.description = DESCRIPTION
+  s.homepage = HOMEPAGE
+  s.rubyforge_project = PROJECT_NAME
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README']
+  s.rdoc_options <<
+    '--title' << TITLE << '--main' << 'README' << '--line-numbers' << "--inline-source"
+
+  s.email = AUTHOR_EMAIL
+  s.files = FileList['{lib,test}/**/*.rb', '[A-Z]*$', 'Rakefile'].to_a
+  s.add_dependency('open4')
+  s.add_dependency('expectations')
+end
+Rake::GemPackageTask.new(specification) do |package|
+  package.need_zip = false
+  package.need_tar = false
+end
+
+desc "Upload RDoc to RubyForge"
+task :publish_rdoc do
+  Rake::Task[:rdoc].invoke
+  Rake::SshDirPublisher.new(
+    "holgerkohnen@rubyforge.org",
+    "/var/www/gforge-projects/#{PROJECT_NAME}", "doc").upload
+end

data/lib/shell/executer.rb

@@ -0,0 +1,132 @@
+require 'open4'
+
+module Shell
+
+  class << self
+    # Shorthand for Shell::Executer#execute. For +options+ see: Shell::Executer.new.
+    def execute(command, options={}, &block)
+      Executer.new(options).execute(command, &block)
+    end
+
+    # Shorthand for Shell::Executer#execute!. For +options+ see: Shell::Executer.new.
+    def execute!(command, options={}, &block)
+      Executer.new(options).execute!(command, &block)
+    end
+  end
+
+  class Executer
+    # Holds last executed commands standard output if executed without block.
+    attr_reader :stdout
+
+    # Holds last executed commands error output.
+    attr_reader :stderr
+
+    # Configuration options:
+    # * <tt>:mode</tt> - Specifies the output mode.
+    #   Can be <tt>:chars</tt> or <tt>:lines</tt>.
+    #   In lines-mode every line of the output is passed to the block.
+    #   In chars-mode every char of the output is passed to the block.
+    #   (default is: <tt>:lines</tt>)
+    def initialize(options={})
+      @options = {
+        :mode => :lines # :chars|:lines <- output mode
+      }.merge(options)
+
+      @reader = (@options[:mode] == :chars) ? proc {|s| s.getc } : proc {|s| s.gets }
+      @mutex = Mutex.new
+
+      @stdout = ''
+      @stderr = ''
+      @success = nil
+    end
+
+    # :call-seq: execute(command) -> Shell::Executer
+    #            execute(command) {|stdout| ...} -> Shell::Executer
+    #            execute(command) {|stdout, stderr| ...} -> Shell::Executer
+    #
+    # Executes <tt>command</tt> and returns after execution.
+    #
+    # In the first form(<tt>execute(command)</tt>) the +command+ ist executed
+    # and the +stdout+, +stderr+ and +success+ attributes are populated.
+    #
+    # In the second and third form the +stdout+ attribute is *not* populated. The +stdout+
+    # is passed to the specified block instead. The block is invoked for
+    # every char or line of output depending on the specified <tt>options</tt>.
+    #
+    # In the second form only the stdout is passed to the block.
+    #
+    # In the third form either stdout or stderr is filled. The opposite is allways nil.
+    #   # Prefix output of rsync
+    #   Shell::Executer.new.execute('rsync -avz /source/ /dest/') do |stdout, stderr|
+    #     if stderr
+    #       print 'ERR> ' + stderr
+    #     else
+    #       print 'OUT> ' + stdout
+    #     end
+    #   end
+    def execute(command, &block)
+      @stdout = ''
+      @stderr = ''
+      @success = nil
+
+      begin
+        threads = []
+        pid, stdin, stdout, stderr = Open4::popen4(command)
+        [[:stdout, stdout], [:stderr, stderr]].each do |type, stream|
+          threads << Thread.new(type, stream) do |type, stream|
+            Thread.current.abort_on_exception = true
+            while data = @reader.call(stream)
+              data = ((@options[:mode] == :chars) ? data.chr : data)
+              @mutex.synchronize do
+                if type == :stdout
+                  if block_given?
+                    if block.arity == 2
+                      yield data, nil
+                    else
+                      yield data
+                    end
+                  else
+                    @stdout += data
+                  end
+                else
+                  yield nil, data if block_given? && block.arity == 2
+                  @stderr += data
+                end
+              end
+            end
+          end
+        end
+
+        ignored, status = Process::waitpid2 pid
+        @success = (status.exitstatus == 0)
+
+      ensure
+        threads.each(&:join)
+        stdin.close if stdin
+        stdout.close if stdout
+        stderr.close if stderr
+      end
+
+      self
+    end
+
+    # :call-seq: execute!(command) -> Shell::Executer
+    #            execute!(command) {|stdout| ...} -> Shell::Executer
+    #            execute!(command) {|stdout, stderr| ...} -> Shell::Executer
+    #
+    # Same as execute, but throws <tt>RuntimeError</tt> containing stderr if <tt>command</tt>
+    # exited without success.
+    def execute!(command, &block)
+      execute(command, &block)
+      raise stderr unless success?
+      self
+    end
+
+    # Returns true if the last command was executed successfully.
+    def success?
+      @success
+    end
+
+  end
+
+end

data/test/test_executer.rb

@@ -0,0 +1,50 @@
+require 'expectations'
+require File.expand_path(File.join(File.dirname(__FILE__), '../lib/shell/executer.rb'))
+
+Expectations do
+
+  expect 'stdout' do
+    Shell::Executer.new.execute('echo stdout').stdout.strip
+  end
+
+  expect 'stderr' do
+    Shell::Executer.new.execute('echo >&2 stderr').stderr.strip
+  end
+
+  expect true do
+    Shell::Executer.new.execute('echo 42').success?
+  end
+
+  expect false do
+    Shell::Executer.new.execute('ls /does_not_exist').success?
+  end
+
+  expect RuntimeError do
+    Shell::Executer.new.execute!('ls /does_not_exist')
+  end
+
+  expect ["std\n", "out\n"] do
+    r = []
+    Shell::Executer.new.execute('echo std; echo out') do |stdout, stderr|
+      r << stdout
+    end
+    r
+  end
+
+  expect ["4", "2"] do
+    r = []
+    Shell::Executer.new(:mode => :chars).execute('echo -n 42') do |stdout, stderr|
+      r << stdout.strip
+    end
+    r
+  end
+
+  expect 'stdout' do
+    Shell.execute('echo stdout').stdout.strip
+  end
+
+  expect RuntimeError do
+    Shell.execute!('ls /does_not_exist')
+  end
+
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: shell-executer
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Holger Kohnen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-30 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: open4
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: expectations
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Shell::Executer provides an easy and robust way to execute shell commands. The stdout and stderr data can be read completly after the execution or in chunks during the execution.
+email: h.kohnen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/shell/executer.rb
+- test/test_executer.rb
+- Rakefile
+- README
+has_rdoc: true
+homepage: http://shell-executer.rubyforge.org/
+post_install_message: 
+rdoc_options: 
+- --title
+- shell-executer
+- --main
+- README
+- --line-numbers
+- --inline-source
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: shell-executer
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Shell::Executer provides an easy and robust way to execute shell commands. The stdout and stderr data can be read completly after the execution or in chunks during the execution.
+test_files: []
+