popen4 0.1.2

data/CHANGES

@@ -0,0 +1,7 @@
+== 0.1.1 - 12-Jun-2006
+* Fixed Bug 4742 
+  - open3.so Open4 fails to return Process::Status on Windows 2000.
+  - Thanks to Park Heesob!
+  
+== 0.1.0 - 10-Jun-2006
+* Initial release

data/LICENSE

@@ -0,0 +1,71 @@
+== POpen4 License
+
+POpen4 is copyright John-Mason P. Shackelford (john-mason@shackelford.org) 
+and made available under the terms of Ruby's license, included below for your 
+convenience.
+
+== win32-open3 License
+
+The the win32-open3 library may be included in this distribution of POpen4. If
+so, POpen4 users must also comply with the terms of its license. Park Heesob and 
+Daniel Berger hold the copyright on most of the win32-open3 code which also 
+happens to be licensed under the same terms as Ruby. 
+
+== Ruby's License
+
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see the file GPL), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/README.rdoc

@@ -0,0 +1,50 @@
+== Description
+POpen4 provides the Rubyist a single API across platforms for executing a 
+command in a child process with handles on stdout, stderr, stdin streams as well 
+as access to the process ID and exit status. It does very little other than to 
+provide an easy way to use either Ara Howard's Open4 library or the win32-popen3 
+library by Park Heesob and Daniel Berger depending on your platform and without
+having to code around the slight differences in their APIs. 
+
+Consider this my first attempt at a response to 
+{Daniel's request}[http://groups.google.com/group/comp.lang.ruby/msg/44ba016610fa8878]
+for a consensus on the API back in 2005.
+
+It is my hope that this project will be shortly absorbed or replaced with a 
+better solution. POpen4 offers very little in the way of features or 
+flexibility, but it does work across platforms without extra coding.
+== Notes
+Rather than adopting either Open4's API or win32-open3's (they differ in several
+respects, but most obviously in the order in which streams are passed to the 
+block) I am proposing a third API for couple of reasons. First, Open4 passes the
+PID first and win32-open3 passes stdin neither of which seem to me to be the 
+streams we are most likely to use when we don't need all four. POpen4 passes
+stdout and stderr first so that when the others are not required we can omit
+them from the block. Second, I thought it best to break everybody's code rather
+than to be a drop in replacement on one platform and be a surprise on another.
+No surprises--it's a new API on either platform.
+
+== Installation
+
+   $ gem install --remote --include-dependencies POpen4
+   
+Presently POpen4 ships in four platform specific gems:
+
+  POpen4-0.1.0-unix.gem
+  POpen4-0.1.0-win32-1.8.2-VC7.gem
+  POpen4-0.1.0-win32-1.8.4-VC6.gem
+  POpen4-0.1.0-win32-source.gem
+
+Users of Linux, Unix, BSD, etc., will want the unix package. Ara's Open4 gem
+is a dependency. Users of the Ruby One-Click Installer (OCI) will want to select
+the gem appropriate their version of Ruby. The real issue here is compiler 
+version. The wrong version will SEGFAULT due to some incompatibility somewhere
+in the VC++ compiler or libraries (which I really wish we could resolve, 
+but oh well). Others using a Windows platform but not the OCI will want to 
+compile from source using last of these gems. Be sure to have your environment 
+set up for doing a build before running <tt>gem install POpen4</tt>.
+
+== Acknowledgements
+Ara Howard, Park Heesob, Daniel Berger and others have done the real work. Many 
+thanks to them for the many hours they have poured into sharing their work with 
+the Ruby community at large.

data/Rakefile

@@ -0,0 +1,131 @@
+require 'rubygems'
+require 'rubygems/user_interaction'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+PROJECT_VERSION = "0.1.1"
+
+task :default => [:test]
+
+# Test --------------------------------------------------------------------
+
+desc "Run the unit tests"
+task :test do
+  Rake::TestTask.new("test") do |t|
+    t.libs << "tests"
+    t.pattern = 'tests/*_test.rb'
+    t.verbose = true
+  end
+end
+
+# Documentation -----------------------------------------------------------
+desc "Generate RDoc"
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = "POpen4 -- Open4 cross-platform"
+  rdoc.options << '--main' << 'README'
+  rdoc.rdoc_files.include('README', 'LICENSE', 'CHANGES')
+  rdoc.rdoc_files.include('lib/**/*.rb', 'doc/**/*.rdoc').exclude('lib/open3.rb')
+}
+
+# GEM Packaging -----------------------------------------------------------
+
+POPEN4_GENERIC = FileList["{tests,lib}/popen4*.rb"].add('*').to_a
+
+# -- WIN32 1.8.2 ----------------
+
+spec = Gem::Specification.new do |s|
+  s.name          = "POpen4"
+  s.version       = PROJECT_VERSION
+  s.author        = "John-Mason P. Shackelford"
+  s.email         = "john-mason@shackelford.org"
+  s.platform      = 'win32-1.8.2-VC7'
+  s.summary       = "Open4 cross-platform"
+  s.files         = POPEN4_GENERIC + FileList['lib/1.8.2*/*', 'lib/open3.rb'].to_a
+  s.require_path  = "lib"
+  s.autorequire   = "popen4.rb"
+  s.has_rdoc      = true
+  s.add_dependency("Platform",   ">= 0.4.0")    
+end
+
+task :package => [:test]
+Rake::GemPackageTask.new( spec ) do |pkg|
+  pkg.gem_spec = spec
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+# -- WIN32 1.8.4 ----------------
+
+spec = Gem::Specification.new do |s|
+  s.name          = "POpen4"
+  s.version       = PROJECT_VERSION
+  s.author        = "John-Mason P. Shackelford"
+  s.email         = "john-mason@shackelford.org"
+  s.platform      = 'win32-1.8.4-VC6'
+  s.summary       = "Open4 cross-platform"
+  s.files         = POPEN4_GENERIC + FileList['lib/1.8.4*/*', 'lib/open3.rb'].to_a
+  s.require_path  = "lib"
+  s.autorequire   = "popen4.rb"
+  s.has_rdoc      = true
+  s.add_dependency("Platform",   ">= 0.4.0")    
+end
+
+task :package => [:test]
+Rake::GemPackageTask.new( spec ) do |pkg|
+  pkg.gem_spec = spec
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+# -- WIN32 src-only ----------------
+
+spec = Gem::Specification.new do |s|
+  s.name          = "POpen4"
+  s.version       = PROJECT_VERSION
+  s.author        = "John-Mason P. Shackelford"
+  s.email         = "john-mason@shackelford.org"
+  s.platform      = 'win32-source'
+  s.summary       = "Open4 cross-platform"
+  s.files         = POPEN4_GENERIC + FileList['{ext}/**/*','lib/open3.rb'].to_a
+  s.require_path  = "lib"
+  s.autorequire   = "popen4.rb"
+  s.has_rdoc      = true
+  s.add_dependency("Platform",   ">= 0.4.0")
+  s.extensions << 'ext/win32-open3/extconf.rb'   
+end
+
+task :package => [:test]
+Rake::GemPackageTask.new( spec ) do |pkg|
+  pkg.gem_spec = spec
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+# -- Unix / OS X / BSD / Linux ----------------
+
+spec = Gem::Specification.new do |s|
+  s.name          = "POpen4"
+  s.version       = PROJECT_VERSION
+  s.author        = "John-Mason P. Shackelford"
+  s.email         = "john-mason@shackelford.org"
+  s.platform      = 'unix'
+  s.summary       = "Open4 cross-platform"
+  s.files         = POPEN4_GENERIC 
+  s.require_path  = "lib"
+  s.autorequire   = "popen4.rb"
+  s.has_rdoc      = true
+  s.add_dependency("Platform",   ">= 0.4.0")
+  s.add_dependency("open4",     ">= 0.4.0")  
+end
+
+task :package => [:test]
+Rake::GemPackageTask.new( spec ) do |pkg|
+  pkg.gem_spec = spec
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+
+

data/lib/popen4.rb

@@ -0,0 +1,100 @@
+require 'rubygems'
+require 'platform'
+#require_gem 'Platform', '>= 0.4.0'
+
+case Platform::OS
+  
+# win32/popen4 yields stdin, stdout, stderr and pid, respectively
+when :win32
+  
+  require File.join( File.dirname( __FILE__ ), 'open3')    
+  
+  # POpen4 provides the Rubyist a single API across platforms for executing a 
+  # command in a child process with handles on stdout, stderr, and stdin streams 
+  # as well as access to the process ID and exit status.
+  #
+  # Consider the following example (borrowed from Open4):
+  # 
+  #   require 'rubygems'
+  #   require 'popen4'
+  #   
+  #   status =
+  #     POpen4::popen4("cmd") do |stdout, stderr, stdin, pid|
+  #       stdin.puts "echo hello world!"
+  #       stdin.puts "echo ERROR! 1>&2"
+  #       stdin.puts "exit"
+  #       stdin.close
+  #   
+  #       puts "pid        : #{ pid }"
+  #       puts "stdout     : #{ stdout.read.strip }"
+  #       puts "stderr     : #{ stderr.read.strip }"
+  #     end
+  #   
+  #   puts "status     : #{ status.inspect }"
+  #   puts "exitstatus : #{ status.exitstatus }"
+  #
+  module POpen4    
+    # Starts a new process and hands IO objects representing the subprocess 
+    # stdout, stderr, stdin streams and the pid (respectively) to the block 
+    # supplied. If the command could not be started, return nil.
+    # 
+    # The mode argument may be set to t[ext] or b[inary] and is used only on
+    # Windows platforms.
+    # 
+    # The stdin stream and/or pid may be omitted from the block parameter list
+    # if they are not required.
+    def self.popen4(command, mode = "t") # :yields: stdout, stderr, stdin, pid
+      
+      err_output = nil      
+      status = Open4.popen4(command, mode) do |stdin,stdout,stderr,pid|
+        yield stdout, stderr, stdin, pid
+        
+        # On windows we will always get an exit status of 3 unless
+        # we read to the end of the streams so we do this on all platforms
+        # so that our behavior is always the same.
+        stdout.read unless stdout.eof?
+        
+        # On windows executing a non existent command does not raise an error
+        # (as in unix) so on unix we return nil instead of a status object and
+        # on windows we try to determine if we couldn't start the command and
+        # return nil instead of the Process::Status object.
+        stderr.rewind
+        err_output = stderr.read
+      end
+      
+      if status.exitstatus == 1 && 
+        err_output.match(/is not recognized as an internal or external command/)
+        return nil
+      end
+      
+      return status
+    end # def
+  end # module
+  
+  
+else # unix popen4 yields pid, stdin, stdout and stderr, respectively
+  # :enddoc:
+  require 'open4'
+  module POpen4
+    def self.popen4(command, mode = "t")
+      begin
+        return status = Open4.popen4(command) do |pid,stdin,stdout,stderr|
+          yield stdout, stderr, stdin, pid
+          # On windows we will always get an exit status of 3 unless
+          # we read to the end of the streams so we do this on all platforms
+          # so that our behavior is always the same.
+          stdout.read unless stdout.eof?
+          stderr.read unless stderr.eof?
+        end
+      rescue Errno::ENOENT => e
+        # On windows executing a non existent command does not raise an error
+        # (as in unix) so on unix we return nil instead of a status object and
+        # on windows we try to determine if we couldn't start the command and
+        # return nil instead of the Process::Status object.
+        return nil
+      end
+    end #def    
+  end #module
+  
+end 
+

data/tests/popen4_test.rb

@@ -0,0 +1,79 @@
+$: << File.join( File.dirname( __FILE__ ), '../lib/')
+
+require 'test/unit'
+require 'popen4'
+
+require 'rubygems'
+require_gem 'Platform', '>= 0.4.0'
+
+class POpen4Test < Test::Unit::TestCase
+  
+  case Platform::OS
+    when :win32
+      CMD_SHELL     = "cmd"
+      CMD_STDERR    = "ruby -e \"$stderr.puts 'ruby'\""
+      CMD_EXIT      = "ruby -e \"$stdout.puts 'ruby'; exit 1\""
+    else # unix
+      CMD_SHELL     = "sh"
+      CMD_STDERR    = "ruby -e '$stderr.puts \"ruby\"'"
+      CMD_EXIT      = "ruby -e '$stdout.puts \"ruby\"; exit 1'"
+  end 
+  CMD_GOOD      = "ruby --version"
+  CMD_BAD       = CMD_GOOD.reverse
+  
+  def test_popen4_block_good_cmd      
+    assert_nothing_raised do
+      POpen4.popen4(CMD_GOOD){ |pout, perr, pin, pid| }
+    end
+  end
+  
+  def test_popen4_block_bad_cmd      
+    status = nil
+    assert_nothing_raised do
+      status = POpen4.popen4(CMD_BAD){ |pout, perr, pin, pid| }
+    end
+    assert_nil status
+  end
+  
+  def test_popen4_block_status   
+    status = POpen4.popen4(CMD_GOOD) do |pout, perr, pin, pid|
+      assert_kind_of(IO, pin)
+      assert_kind_of(IO, pout)
+      assert_kind_of(IO, perr)
+      assert_kind_of(Fixnum, pid)
+    end      
+    assert_kind_of Process::Status, status
+  end
+  
+  def test_open4_block_read_stdout
+    status = POpen4.popen4(CMD_GOOD) do |pout, perr|
+      assert_match(/ruby \d\.\d\.\d/, pout.gets)
+    end      
+    assert_equal 0, status.exitstatus
+  end
+  
+  def test_open4_block_read_stderr
+    status = POpen4.popen4(CMD_STDERR) do |pout, perr|
+      assert_match "ruby", perr.gets
+    end      
+    assert_equal 0, status.exitstatus
+  end
+  
+  def test_open4_block_exitstatus
+    status = POpen4.popen4(CMD_EXIT) do |pout, perr|
+      assert_match "ruby", pout.gets
+    end      
+    assert_kind_of Process::Status, status
+    assert_equal 1, status.exitstatus
+  end
+  
+  def test_open4_block_write_stdin
+    status = POpen4.popen4(CMD_SHELL) do |pout, perr, pin|
+      pin.puts CMD_GOOD
+      pin.puts "exit"
+      pin.close
+      assert_match(/ruby \d\.\d\.\d/, pout.readlines.join)
+    end      
+    assert_equal 0, status.exitstatus  
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: popen4
+version: !ruby/object:Gem::Version 
+  version: 0.1.2
+platform: ruby
+authors: 
+- John-Mason P. Shackelford
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-03 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: Platform
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: open4
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.0
+    version: 
+description: POpen4 provides the Rubyist a single API across platforms for executing a command in a child process with handles on stdout, stderr, stdin streams as well as access to the process ID and exit status.
+email: john-mason@shackelford.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGES
+- LICENSE
+- README.rdoc
+files: 
+- Rakefile
+- lib/popen4.rb
+- CHANGES
+- LICENSE
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/shairontoledo/popen4
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: Open4 cross-platform
+test_files: 
+- tests/popen4_test.rb