executor 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in executor.gemspec
+gemspec

data/README.md

@@ -0,0 +1,42 @@
+# Executor
+
+Executor aims to provide a standard interface to work with binaries outside of ruby. It provides a standard implementation of the following requirements:
+
+* Capturing exit status and raising appropriate exception
+* Redirecting stderr  
+* Asynchronous callbacks
+* Logging of command output
+   
+## Options
+
+ * redirect_stderr - This will cause any stderr from a command to be merged to stdout 
+ * raise_exceptions - This will listen for the exit code of the executed process and raise an exception if non 0
+ * async - This is true by default if a block is given to Executor::command, async will create a new thread and execute the passed block upon completion of the process
+
+ * logger - This takes an instance of logger (or an instance that implements #info) 
+
+## Usage
+
+### Basic
+
+    require 'executor'
+    
+    Executor::command("echo 5")
+
+### With redirection
+
+    Executor::command("expr 5 / 0", :redirect_stderr => true)
+
+### With one-time configuration
+
+    Executor::configure(
+      :raise_exceptions => false
+    )
+
+    Executor::command("expr 5 / 0")
+
+## Special notes
+
+ * In async mode (when block given or via explicit configuration), an exception if caught will be returned to the callback
+
+credits: me, robgleeson@freenode

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/executor.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "executor/version"
+
+Gem::Specification.new do |s|
+  s.name        = "executor"
+  s.version     = Executor::VERSION
+  s.authors     = ["Thomas W. devol"]
+  s.email       = ["vajrapani666@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Execute system commands through a configurable interface}
+  s.description = %q{Execute system commands with exception handling and logging}
+
+  s.rubyforge_project = "executor"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "nullobject"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "em-spec"
+end

data/lib/executor.rb

@@ -0,0 +1,87 @@
+require "executor/version"
+require "nullobject"
+require "timeout"
+
+module Executor
+
+  ExecutorFailure = Class.new(StandardError)
+  CommandFailure = Class.new(ExecutorFailure) 
+  TimeoutFailure = Class.new(ExecutorFailure)
+
+  class << self
+    def method_missing(meth, *args, &block)
+      if Executor.respond_to?(meth, true)
+        Executor.send(meth, *args, &block)
+      else
+        super
+      end
+    end
+  end
+
+  class Executor
+    DEFAULTS = {
+      :redirect_stderr => false,
+      :raise_exceptions => true,
+      :async => false,
+      :logger => Null::Object.instance
+    }
+    class << self
+      attr_reader :config
+
+      def configure(config={})
+        @config = (@config || Executor::DEFAULTS).merge(config)
+      end 
+
+      def command(cmd, options={}, &block)
+        options = configure.dup.merge(options)
+        options[:logger].info "COMMAND: #{cmd}"
+        options[:async] ||= block_given?
+        raise ArgumentError.new("No block given for async command") if (options[:async] && !block_given?)
+
+        if options[:async]
+          handle_async(cmd, options, &block)
+        else
+          return handle_nonasync(cmd, options)
+        end
+      end
+
+      private
+
+      def handle_nonasync(cmd, options)
+          stmt = ["(#{cmd})"]
+          stmt << "2>&1" if @config[:redirect_stderr]
+          if options[:timeout]
+            Timeout::timeout(options[:timeout]) do
+              output = %x{#{stmt*" "}}
+            end
+          else
+            output = %x{#{stmt*" "}}
+          end
+          options[:logger].info "Non-async output for #{cmd}: #{output.inspect}"
+          return return_or_raise(cmd, $?.success?, output, options)
+      rescue Timeout::Error=>e
+        raise TimeoutFailure.new(e)
+      end
+
+      def handle_async(cmd, options, &block)
+          Thread.new do 
+            IO.popen(cmd) do |pipe|
+              output = pipe.read
+              options[:logger].info "Async output for #{cmd}: #{output.inspect}"
+              pipe.close
+              yield return_or_raise(cmd, $?.success?, output, options) rescue $!
+            end
+          end
+      end
+
+      def return_or_raise(cmd, success, output, options)
+        options[:logger].info "RETURN(#{cmd}): #{output}"
+        exception =  CommandFailure.new(%Q{Command "#{cmd}" failed with #{output}}) 
+        return output if success
+        return exception if options[:async]
+        raise exception if options[:raise_exceptions]
+        return output
+      end
+    end
+  end
+end

data/lib/executor/version.rb

@@ -0,0 +1,3 @@
+module Executor
+  VERSION = "0.0.1"
+end

data/spec/executor_spec.rb

@@ -0,0 +1,146 @@
+require 'spec_helper'
+require 'executor'
+require 'logger'
+
+describe Executor do
+  let (:failing_cmd) { "expr 5 / 0" }
+    context "exceptions" do
+      it "initializes" do
+        expect {
+          raise Executor::CommandFailure.new("foo")
+        }.to raise_exception(Executor::CommandFailure, "foo")
+      end
+    end
+    context ".return_or_raise" do
+
+      let(:cmd) { "echo test"}
+      let(:output) { "test output" }
+
+      let(:options) { {:raise_exceptions => true, :logger=>stub(:info=>nil)} }
+      it "returns output if successful" do
+        output = "test"
+        Executor.return_or_raise("echo test",true, output, options).should == output
+      end
+
+      it "raises exceptions when configured" do
+        expect {
+          Executor.return_or_raise(cmd, false, output, options)
+        }.to raise_exception(Executor::CommandFailure, /#{cmd}.*#{output}/)
+      end
+
+     it "returns an exception if async" do
+        Executor.return_or_raise(cmd, false, output, options.merge(:async=>true)).should be_an(Executor::CommandFailure)
+     end 
+    end
+    context ".command" do
+      context "instance configuration" do
+        it "overrides class-level config for a single command" do
+          Executor.configure(:raise_exceptions => false)
+          expect {
+            Executor.command(failing_cmd, :raise_exceptions=>true)
+          }.to raise_exception(Executor::CommandFailure)
+        end
+      end
+      context "async" do
+        before do
+          Executor.configure(
+            :raise_exceptions => true
+          )
+        end
+
+        it "uses a separate thread" do
+          i = 0
+          Executor.command("sleep 3 && echo 5") do |result|
+            i+=1 
+          end  
+          i.should == 0
+          sleep 5
+          i.should == 1
+        end
+
+        it "calls the block passed to it" do
+          block_called = Executor.command(failing_cmd) do |result|
+            true
+          end || false
+          block_called.should be_true
+        end
+        it "should raise an exception upon non zero exit" do
+          Executor.command(failing_cmd) do |result|
+            result.should be_kind_of Executor::CommandFailure
+          end
+        end
+        it "with explicit async config, raise exception if no block given" do
+          expect {
+            Executor.command(failing_cmd, :async=>true)
+          }.to raise_exception(ArgumentError)
+        end
+      end
+      context "redirection" do
+        before do
+          Executor.configure(
+            :redirect_stderr => true,
+            :raise_exceptions => false
+          )
+        end
+        it "redirects stderr" do
+          result = Executor.command(failing_cmd)
+          result.should =~ /expr: division by zero/
+        end
+      end
+      context "non-async" do 
+        before do
+          Executor.configure(
+            :raise_exceptions => true
+          )
+        end
+        it "should raise an exception upon non zero exit" do
+          expect {
+            Executor.command(failing_cmd)
+          }.to raise_exception(Executor::CommandFailure)
+        end
+      end
+    end
+    context "logging" do
+      it "should log errors" do
+        logger = Logger.new(StringIO.new)
+        logger.should_receive(:info).with(instance_of(String)).any_number_of_times
+        Executor.configure(
+          :logger => logger,
+          :raise_exceptions => false
+        )
+        Executor.command("expr 5 / 0")
+      end 
+    end
+    context "without options" do
+      it "should be able to execute 'echo x' " do
+        Executor.command(%Q{echo "x"}) 
+      end
+      it "should be able to execute sleep && echo " do
+        start = Time.now.to_i
+        Executor.command("sleep 2 && echo 'test'") do |result|
+          finish = Time.now.to_i
+          (finish-start).should be_greater_than(2)
+        end
+      end
+    end
+
+
+    describe "on the roadmap" do
+      pending "with eventmachine" do
+        it "uses em::popen"
+      end
+      pending "timeouts" do
+        it "should capture timeouts" do
+          expect {
+            Executor.command("sleep 5", :timeout=>2)
+          }.to raise_exception(Executor::TimeoutFailure)
+        end
+        it "should fail for timeout on async" do
+          Executor.command("sleep 5", :timeout => 2) do |result|
+            raise result
+          end
+          sleep 5
+        end
+      end
+    end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH << File.join(File.dirname(__FILE__),'..','lib')
+$LOAD_PATH << File.join(File.dirname(__FILE__))
+

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: executor
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Thomas W. devol
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-28 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nullobject
+  requirement: &70114217923400 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70114217923400
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70114217922980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70114217922980
+- !ruby/object:Gem::Dependency
+  name: em-spec
+  requirement: &70114217922560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70114217922560
+description: Execute system commands with exception handling and logging
+email:
+- vajrapani666@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- executor.gemspec
+- lib/executor.rb
+- lib/executor/version.rb
+- spec/executor_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: executor
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Execute system commands through a configurable interface
+test_files:
+- spec/executor_spec.rb
+- spec/spec_helper.rb