scmd 2.0.0 → 2.1.1

data/.gitignore

@@ -1,11 +1,10 @@
 *.gem
 *.log
 *.rbc
+.rbx/
 .bundle
 .config
 .yardoc
-.rvmrc
-.rbenv-version
 Gemfile.lock
 InstalledFiles
 _yardoc

data/Gemfile

@@ -1,7 +1,5 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
-# Specify your gem's dependencies in scmd.gemspec
 gemspec
 
-gem 'bundler', '~>1.1'
-gem 'rake',    '~>0.9.2'
+gem 'rake'

data/{LICENSE → LICENSE.txt}

@@ -1,4 +1,4 @@
-Copyright (c) 2012 <TODO: copyright holders>
+Copyright (c) 2012-Present Kelly Redding, Collin Redding
 
 MIT License
 

data/README.md

@@ -1,20 +1,6 @@
 # Scmd
 
-Wrapper to `open4` for running system commands.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'scmd'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install scmd
+Build and run system commands.  Scmd uses `posix-spawn` to fork child processes to run the commands.
 
 ## Usage
 
@@ -38,6 +24,30 @@ Run it:
 cmd.run
 ```
 
+**OR**, async run it:
+
+```ruby
+cmd.start
+cmd.running? # => true
+cmd.pid      #=> 12345
+
+# do other stuff...
+cmd.wait # indefinitely until cmd exits
+```
+
+**OR**, async run it with a timeout:
+
+```ruby
+cmd.start
+
+begin
+  cmd.wait(10)
+rescue Scmd::Timeout => err
+  cmd.stop # attempt to stop the cmd nicely, kill if doesn't stop in time
+  cmd.kill # just kill the cmd now
+end
+```
+
 Results:
 
 ```ruby
@@ -84,6 +94,20 @@ Raise an exception if not successful with `run!`:
 Scmd.new("cd /path/that/does/not/exist").run! #=> Scmd::Command::Failure
 ```
 
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'scmd'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install scmd
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,8 +1 @@
-#!/usr/bin/env rake
-
-require 'assert/rake_tasks'
-Assert::RakeTasks.install
-
 require 'bundler/gem_tasks'
-
-task :default => :build

data/lib/scmd.rb

@@ -1,3 +1,4 @@
+require 'scmd/version'
 require 'scmd/command'
 
 module Scmd

data/lib/scmd/command.rb

@@ -1,10 +1,10 @@
+require 'posix-spawn'
+
 # Scmd::Command is a base wrapper for handling system commands. Initialize it
 # with with a string specifying the command to execute.  You can then run the
 # command and inspect its results.  It can be used as is, or inherited from to
 # create a more custom command wrapper.
 
-require 'posix-spawn'
-
 module Scmd
 
   class RunError < ::RuntimeError
@@ -14,19 +14,80 @@ module Scmd
     end
   end
 
+  TimeoutError = Class.new(::RuntimeError)
+
   class Command
+    WAIT_INTERVAL = 0.1 # seconds
+    STOP_TIMEOUT  = 3   # seconds
+    RunData = Class.new(Struct.new(:pid, :stdin, :stdout, :stderr))
 
     attr_reader :cmd_str
     attr_reader :pid, :exitstatus, :stdout, :stderr
 
     def initialize(cmd_str)
       @cmd_str = cmd_str
-      reset_results
+      setup
     end
 
-    def reset_results
-      @pid = @exitstatus = nil
-      @stdout = @stderr = ''
+    def run(input=nil)
+      run!(input) rescue RunError
+      self
+    end
+
+    def run!(input=nil)
+      called_from = caller
+
+      begin
+        start(input)
+      ensure
+        wait # indefinitely until cmd is done running
+        raise RunError.new(@stderr, called_from) if !success?
+      end
+
+      self
+    end
+
+    def start(input=nil)
+      setup
+      @run_data = RunData.new(*POSIX::Spawn::popen4(@cmd_str))
+      @pid = @run_data.pid.to_i
+      if !input.nil?
+        [*input].each{|line| @run_data.stdin.puts line.to_s}
+        @run_data.stdin.close
+      end
+    end
+
+    def wait(timeout=nil)
+      return if !running?
+
+      pidnum, pidstatus = wait_for_exit(timeout)
+      @stdout     += @run_data.stdout.read.strip
+      @stderr     += @run_data.stderr.read.strip
+      @exitstatus  = pidstatus.exitstatus || pidstatus.termsig
+
+      teardown
+    end
+
+    def stop(timeout=nil)
+      return if !running?
+
+      send_term
+      begin
+        wait(timeout || STOP_TIMEOUT)
+      rescue TimeoutError => err
+        kill
+      end
+    end
+
+    def kill
+      return if !running?
+
+      send_kill
+      wait # indefinitely until cmd is killed
+    end
+
+    def running?
+      !@run_data.nil?
     end
 
     def success?
@@ -44,40 +105,50 @@ module Scmd
       " @exitstatus=#{@exitstatus.inspect}>"
     end
 
-    def run(input=nil)
-      run!(input) rescue RunError
-      self
+    private
+
+    def wait_for_exit(timeout)
+      if timeout.nil?
+        ::Process::waitpid2(@run_data.pid)
+      else
+        timeout_time = Time.now + timeout
+        pid, status = nil, nil
+        while pid.nil? &&  Time.now < timeout_time
+          sleep WAIT_INTERVAL
+          pid, status = ::Process.waitpid2(@run_data.pid, ::Process::WNOHANG)
+          pid = nil if pid == 0 # may happen on jruby
+        end
+        raise(TimeoutError, "`#{@cmd_str}` timed out (#{timeout}s).") if pid.nil?
+        [pid, status]
+      end
     end
 
-    def run!(input=nil)
-      called_from = caller
+    def setup
+      @pid = @exitstatus = @run_data = nil
+      @stdout = @stderr = ''
+    end
 
-      begin
-        pid, stdin, stdout, stderr = POSIX::Spawn::popen4(@cmd_str)
-        if !input.nil?
-          [*input].each{|line| stdin.puts line.to_s}
-          stdin.close
-        end
-        @pid     = pid.to_i
-        @stdout += stdout.read.strip
-        @stderr += stderr.read.strip
-      rescue Errno::ENOENT => err
-        @exitstatus = -1
-        @stderr     = err.message
-      ensure
-        [stdin, stdout, stderr].each{|io| io.close if !io.closed?}
-        ::Process::waitpid(pid)
+    def teardown
+      [@run_data.stdin, @run_data.stdout, @run_data.stderr].each do |io|
+        io.close if !io.closed?
+      end
+      @run_data = nil
+      true
+    end
 
-        # `$?` is a thread-safe predefined variable that returns the exit status
-        # of the last child process to terminate:
-        # http://phrogz.net/ProgrammingRuby/language.html#predefinedvariables
-        @exitstatus ||= $?.exitstatus
+    def send_term
+      send_signal 'TERM'
+    end
 
-        raise RunError.new(@stderr, called_from) if !success?
-      end
+    def send_kill
+      send_signal 'KILL'
+    end
 
-      self
+    def send_signal(sig)
+      return if !running?
+      ::Process.kill sig, @run_data.pid
     end
 
   end
+
 end

data/lib/scmd/version.rb

@@ -1,3 +1,3 @@
 module Scmd
-  VERSION = "2.0.0"
+  VERSION = "2.1.1"
 end

data/scmd.gemspec

@@ -1,19 +1,20 @@
 # -*- encoding: utf-8 -*-
-require File.expand_path('../lib/scmd/version', __FILE__)
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "scmd/version"
 
 Gem::Specification.new do |gem|
   gem.name        = "scmd"
   gem.version     = Scmd::VERSION
-  gem.description = %q{Build and run system commands.}
-  gem.summary     = %q{Build and run system commands.}
-
   gem.authors     = ["Kelly Redding", "Collin Redding"]
   gem.email       = ["kelly@kellyredding.com", "collin.redding@me.com"]
+  gem.description = %q{Build and run system commands.}
+  gem.summary     = %q{Build and run system commands.}
   gem.homepage    = "http://github.com/redding/scmd"
 
-  gem.files         = `git ls-files`.split("\n")
-  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
   gem.add_development_dependency("assert")

data/test/helper.rb

@@ -1,5 +1,5 @@
-# this file is automatically required in when you require 'assert' in your tests
-# put test helpers here
+# this file is automatically required when you run `assert`
+# put any test helpers here
 
 # add root dir to the load path
 $LOAD_PATH.unshift(File.expand_path("../..", __FILE__))

data/test/{command_tests.rb → unit/command_tests.rb}

@@ -13,6 +13,9 @@ module Scmd
 
     should have_readers :cmd_str, :pid, :exitstatus, :stdout, :stderr
     should have_instance_methods :run, :run!
+    should have_instance_methods :start, :wait, :stop, :kill
+    should have_instance_methods :running?, :success?
+
 
     should "know and return its cmd string" do
       assert_equal "echo hi", subject.cmd_str
@@ -53,7 +56,7 @@ module Scmd
 
       assert_kind_of Scmd::RunError, err
       assert_includes 'No such file or directory', err.message
-      assert_includes 'test/command_tests.rb:', err.backtrace.first
+      assert_includes 'test/unit/command_tests.rb:', err.backtrace.first
     end
 
     should "return itself on `run`, `run!`" do
@@ -62,6 +65,42 @@ module Scmd
       assert_equal @failure_cmd, @failure_cmd.run
     end
 
+    should "start and be running until `wait` is called and the cmd exits" do
+      cmd = Command.new("sleep .1")
+      assert_not cmd.running?
+
+      cmd.start
+      assert cmd.running?
+      assert_not_nil cmd.pid
+
+      cmd.wait
+      assert_not cmd.running?
+    end
+
+    should "do nothing and return when told to wait but not running" do
+      assert_not subject.running?
+      assert_nil subject.pid
+
+      subject.wait
+      assert_nil subject.pid
+    end
+
+    should "do nothing and return when told to stop but not running" do
+      assert_not subject.running?
+      assert_nil subject.pid
+
+      subject.stop
+      assert_nil subject.pid
+    end
+
+    should "do nothing and return when told to kill but not running" do
+      assert_not subject.running?
+      assert_nil subject.pid
+
+      subject.kill
+      assert_nil subject.pid
+    end
+
   end
 
   class InputTests < CommandTests
@@ -88,4 +127,44 @@ module Scmd
 
   end
 
+  class LongRunningTests < CommandTests
+    desc "that is long running"
+    setup do
+      @long_cmd = Command.new("sleep .3 && echo hi")
+    end
+
+    should "not timeout if wait timeout is longer than cmd time" do
+      assert_nothing_raised do
+        @long_cmd.start
+        @long_cmd.wait(1)
+      end
+      assert @long_cmd.success?
+      assert_equal 'hi', @long_cmd.stdout
+    end
+
+    should "timeout if wait timeout is shorter than cmd time" do
+      assert_raises(TimeoutError) do
+        @long_cmd.start
+        @long_cmd.wait(0.1)
+      end
+      assert_not @long_cmd.success?
+      assert_empty @long_cmd.stdout
+    end
+
+    should "be stoppable" do
+      @long_cmd.start
+      @long_cmd.stop
+
+      assert_not @long_cmd.running?
+    end
+
+    should "be killable" do
+      @long_cmd.start
+      @long_cmd.kill
+
+      assert_not @long_cmd.running?
+    end
+
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: scmd
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 9
   prerelease: 
   segments: 
   - 2
-  - 0
-  - 0
-  version: 2.0.0
+  - 1
+  - 1
+  version: 2.1.1
 platform: ruby
 authors: 
 - Kelly Redding
@@ -16,11 +16,12 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-11-08 00:00:00 Z
+date: 2013-03-12 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: assert
   prerelease: false
+  type: :development
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -30,11 +31,11 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: posix-spawn
   prerelease: false
+  type: :runtime
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -44,7 +45,6 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :runtime
   version_requirements: *id002
 description: Build and run system commands.
 email: 
@@ -59,17 +59,16 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
-- LICENSE
+- LICENSE.txt
 - README.md
 - Rakefile
 - lib/scmd.rb
 - lib/scmd/command.rb
 - lib/scmd/version.rb
 - scmd.gemspec
-- test/command_tests.rb
 - test/helper.rb
-- test/irb.rb
-- test/scmd_tests.rb
+- test/unit/command_tests.rb
+- test/unit/scmd_tests.rb
 homepage: http://github.com/redding/scmd
 licenses: []
 
@@ -99,13 +98,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Build and run system commands.
 test_files: 
-- test/command_tests.rb
 - test/helper.rb
-- test/irb.rb
-- test/scmd_tests.rb
-has_rdoc: 
+- test/unit/command_tests.rb
+- test/unit/scmd_tests.rb

data/test/irb.rb

@@ -1,9 +0,0 @@
-require 'assert/setup'
-
-# this file is required in when the 'irb' rake test is run.
-# b/c 'assert/setup' is required above, the test helper will be
-# required in as well.
-
-# put any IRB setup code here
-
-require 'scmd'