process_builder 1.1.0

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+html/

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,24 @@
+PATH
+  remote: .
+  specs:
+    process_builder (1.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  process_builder!
+  rspec

data/README.rdoc

@@ -0,0 +1,34 @@
+= ProcessBuilder
+
+Simple object-oriented wrapper around Ruby's Process.spawn and Open3 library.
+
+ProcessBuilder allows you to build a process description which can then be
+used to spawn and interact with an external process.
+
+== Usage
+
+  require 'process_builder'
+
+  # Build a process description with the ProcessBuilder.build method.
+  process = ProcessBuilder.build('oggenc', 'track01.cdda.wav') do |builder|
+    # The builder object passed to this block has methods for setting various
+    # attributes of the process. See the RDoc for full details.
+    builder.environment['LOG_DIR'] = '/var/log'
+    builder.directory = "#{ENV['HOME']}/Music"
+  end
+
+  # Once the process description is built there are a variety of ways
+  # to spawn the process. One way is to call spawn:
+  pid = process.spawn
+  Process.wait(pid)
+
+  # Another way is to use any of the popen or capture methods defined by Open3:
+  stdin, stdout, stderr, wait_thread = process.popen3
+  status = wait_thread.value
+  stdin.close; stdout.close; stderr.close
+
+  # or in block form:
+  process.popen3 do |stdin, stdout, stderr, wait_thread|
+    status = wait_thread.value
+  end
+

data/Rakefile

@@ -0,0 +1,13 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rdoc/task'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.title = 'Process Builder'
+end
+

data/lib/process_builder.rb

@@ -0,0 +1,217 @@
+require 'pathname'
+require 'open3'
+
+# Object-oriented wrapper around Process.spawn and the Open3 library.
+# ProcessBuilder is an immutable description of a process and its various
+# attributes. ProcessBuilder objects are created with the
+# ProcessBuilder.build method, and after having been created can be used
+# to spawn the process in various ways, such as #spawn or #popen3.
+#
+# See the descriptions of the methods of this class for further details,
+# and the documentation for Process.spawn and Open3 for full details of
+# the arguments that each understands.
+class ProcessBuilder
+  VERSION = '1.1.0'
+
+  # The command and arguments passed to Process.spawn
+  attr_reader :command_line
+
+  # Working directory for the process. Corresponds to the :chdir option of
+  # Process.spawn
+  attr_reader :directory
+
+  # Hash representing environment variables for the process. Passed as the
+  # optional [env] argument of Process.spawn.
+  attr_reader :environment
+
+  # If true, clear environment variables, other than specified explicitly
+  # in environment.
+  attr_reader :unsetenv_others
+  alias unsetenv_others? unsetenv_others
+
+  # Process group, corresponding to the :pgroup option of Process.spawn.
+  attr_reader :pgroup
+
+  # Hash specifying IO redirection for the child process, corresponding to
+  # the redirection options of Process.spawn. Generally not used if using any
+  # of the Open3 mechanisms for spawning the process.
+  attr_reader :redirection
+
+  # File descriptor inheritance, corresponding to the :close_others option of
+  # Process.spawn.
+  attr_reader :close_others
+
+  # umask for the child process, corresponding to the :umask option of
+  # Process.spawn.
+  attr_reader :umask
+
+  # Hash specifying resource limits. Process.spawn expects resource limits to
+  # be specified as options in the form :rlimit_resourcename, where
+  # resourcename is one of the resources understood by Process.setrlimit,
+  # such as :rlimit_core for example.
+  # The keys of this Hash will be used to construct the options, so setting
+  # \rlimit[:core] would result in an option named :rlimit_core.
+  attr_reader :rlimit
+
+  # Build a new process description using the given args as the process
+  # command line. If a block is given, this method will yield a mutable
+  # ProcessBuilder::Builder object to it so that the block can specify the
+  # attributes of the process. The object returned by this method, however,
+  # is an immutable (and frozen) instance of ProcessBuilder.
+  def self.build(*args, &block)
+    new(*args, &block)
+  end
+
+  # Build a new process description copied from the given other ProcessBuilder.
+  # Like the build method, this method yields to the given block to allow for
+  # customization of the process attributes.
+  def self.copy(other)
+    raise ArgumentError unless other.is_a?(ProcessBuilder)
+    if block_given?
+      builder = Builder.new(other)
+      if block_given?
+        yield builder
+      end
+      new(builder)
+    else
+      new(other)
+    end
+  end
+
+  def initialize(*args)
+    if args.size == 1 && args.first.is_a?(ProcessBuilder)
+      self.copy_fields(args.first)
+    else
+      @command_line = array_copy(args)
+      @environment = Hash.new
+      @redirection = Hash.new
+      @rlimit = Hash.new
+      if block_given?
+        builder = Builder.new(self)
+        yield builder
+        self.copy_fields(builder)
+      end
+    end
+    self.freeze
+  end
+
+  def initialize_copy(other)
+    super
+    self.copy_fields(other)
+  end
+
+  # Spawn the process described by this ProcessBuilder using Process.spawn.
+  # Returns the PID of the spawned process.
+  def spawn
+    Process.spawn(*spawn_args)
+  end
+
+  # Spawn the process described by this ProcessBuilder using Open3.popen2.
+  def popen2(&block)
+    Open3.popen2(*spawn_args, &block)
+  end
+
+  # Spawn the process described by this ProcessBuilder using Open3.popen2e.
+  def popen2e(&block)
+    Open3.popen2e(*spawn_args, &block)
+  end
+
+  # Spawn the process described by this ProcessBuilder using Open3.popen3.
+  def popen3(&block)
+    Open3.popen3(*spawn_args, &block)
+  end
+
+  # Execute the process described by this ProcessBuilder using Open3.capture2.
+  # The argument to this method is used as the :stdin_data argument of
+  # Open3.capture2.
+  def capture2(stdin_data, &block)
+    args = self.spawn_args
+    args.last[:stdin_data] = stdin_data.to_s.dup
+    Open3.capture2(*args, &block)
+  end
+
+  # Execute the process described by this ProcessBuilder using Open3.capture3.
+  # The argument to this method is used as the :stdin_data argument of
+  # Open3.capture3.
+  def capture3(stdin_data, &block)
+    args = self.spawn_args
+    args.last[:stdin_data] = stdin_data.to_s.dup
+    Open3.capture3(*args, &block)
+  end
+
+  # Returns an array of arguments as understood by Process.spawn.
+  def spawn_args
+    result = Array.new
+    unless environment.empty?
+      result << environment
+    end
+    result.concat(command_line)
+    opts = Hash.new
+    opts[:chdir] = directory.to_s unless directory.nil?
+    opts[:pgroup] = pgroup unless pgroup.nil?
+    opts[:umask] = umask unless umask.nil?
+    opts[:unsetenv_others] = unsetenv_others unless unsetenv_others.nil?
+    opts[:close_others] = close_others unless close_others.nil?
+    rlimit.each do |key, value|
+      opts["rlimit_#{key}".to_sym] = value
+    end
+    redirection.each do |key, value|
+      opts[key] = value
+    end
+    result << opts
+    result
+  end
+
+protected
+
+  # :nodoc:
+  def copy_fields(other)
+    @command_line = array_copy(other.command_line)
+    @directory = Pathname(other.directory )if other.directory
+    @environment = hash_copy(other.environment)
+    @unsetenv_others = other.unsetenv_others
+    @pgroup = other.pgroup
+    @redirection = hash_copy(other.redirection)
+    @close_others = other.close_others
+    @umask = other.umask
+    @rlimit = hash_copy(other.rlimit)
+  end
+
+private
+
+  def copy_val(val)
+    case val
+    when NilClass, TrueClass, FalseClass, Numeric, Symbol
+      val
+    else
+      val.dup.freeze
+    end
+  end
+
+  def array_copy(array)
+    [array].flatten.compact.map { |arg|
+      copy_val(arg)
+    }
+  end
+
+  def hash_copy(hash)
+    hash ||= Hash.new
+    result = Hash.new
+    hash.each do |key, value|
+      result[key] = copy_val(value)
+    end
+    result
+  end
+
+  # Builder object that is passed to the block given to the ProcessBuilder.build
+  # and ProcessBuilder.copy methods. The Builder object has writable attributes
+  # allowing the block to customize the attributes of the process.
+  class Builder < ProcessBuilder
+    attr_writer :command_line, :directory, :environment, :pgroup,
+                :rlimit_resourcename, :umask, :close_others
+
+    def initialize(initial_state)
+      self.copy_fields(initial_state)
+    end
+  end
+end

data/process_builder.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "process_builder"
+
+Gem::Specification.new do |s|
+  s.name        = "process_builder"
+  s.version     = ProcessBuilder::VERSION
+  s.authors     = ["Jason Voegele"]
+  s.email       = ["jason@jvoegele.com"]
+  s.homepage    = "https://github.com/jvoegele/process_builder"
+  s.summary     = "Simple object-oriented wrapper around Process.spawn and Open3"
+
+  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_development_dependency "rspec"
+end

data/spec/process_builder_spec.rb

@@ -0,0 +1,156 @@
+require 'process_builder'
+
+describe ProcessBuilder do
+  context "build" do
+    it "returns a new ProcessBuilder object" do
+      p = ProcessBuilder.build
+      p.should be_kind_of(ProcessBuilder)
+    end
+
+    it "optionally takes command line arguments" do
+      p = ProcessBuilder.build('command', 'arg1', 'arg2')
+      p.command_line.should == %w[command arg1 arg2]
+    end
+
+    it "yields a ProcessBuilder::Builder object if given a block" do
+      yielded = false
+      process = ProcessBuilder.build do |p|
+        yielded = true
+        p.should be_kind_of(ProcessBuilder::Builder)
+      end
+      yielded.should be_true
+    end
+
+    it "copies the values set on the builder object in the block" do
+      process = ProcessBuilder.build('command', 'arg1') do |builder|
+        builder.command_line << 'arg2'
+        builder.directory = "#{ENV['HOME']}/fakedir"
+        builder.environment['ULTIMATE_ANSWER'] = 42
+        builder.environment['NILVAR'] = nil
+      end
+      process.command_line.should == %w[command arg1 arg2]
+      process.directory.should == Pathname("#{ENV['HOME']}/fakedir")
+      process.environment.should == {
+        'ULTIMATE_ANSWER' => 42,
+        'NILVAR' => nil
+      }
+    end
+  end
+
+  context "copy" do
+    let(:initializer) {
+      ->(builder) do
+        builder.directory = 'somedir'
+        builder.environment['SOMEVAR'] = 'someval'
+      end
+    }
+    it "copies all attributes of the other process builder" do
+      p1 = ProcessBuilder.build('command', 'arg1', &initializer)
+      p2 = ProcessBuilder.copy(p1) do |p|
+        p.directory = 'anotherdir'
+        p.environment['ANOTHERVAR'] = 'anotherval'
+      end
+      p2.command_line.should == %w[command arg1]
+      p2.directory.should == Pathname('anotherdir')
+      p2.environment.should == {
+        'SOMEVAR' => 'someval',
+        'ANOTHERVAR' => 'anotherval'
+      }
+    end
+  end
+
+  context "#spawn_args" do
+    let(:process) {
+      ProcessBuilder.build('command', 'arg1') do |p|
+        p.directory = 'somedir'
+        p.environment['SOMEVAR'] = 'someval'
+        p.pgroup = true
+        p.redirection[:err] = 'error.log'
+        p.umask = 42
+        p.rlimit['core'] = [0, 100]
+        p.rlimit[:nice] = 20
+      end
+    }
+
+    it "converts all attributes into arguments for Process.spawn" do
+      spawn_args = process.spawn_args
+      spawn_args.should == [
+        {'SOMEVAR' => 'someval'},
+        'command', 'arg1',
+        {
+          :chdir => 'somedir',
+          :pgroup => true,
+          :err => 'error.log',
+          :umask => 42,
+          :rlimit_core => [0, 100],
+          :rlimit_nice => 20
+        }
+      ]
+    end
+  end
+
+  it "can spawn a new process" do
+    p = ProcessBuilder.build('ruby', '--version') do |p|
+      p.redirection[:err] = :close
+    end
+    pid = p.spawn
+    pid.should be_kind_of(Integer)
+  end
+
+  context "popen" do
+    let(:process) {
+      ProcessBuilder.build('ruby', '--version')
+    }
+
+    it "supports popen2" do
+      stdin, stdout, wait_thread = process.popen2
+      stdin.should be_kind_of(IO)
+      stdout.should be_kind_of(IO)
+      wait_thread.should be_kind_of(Thread)
+      stdin.close
+      stdout.close
+
+      process.popen2 do |stdin, stdout, wait_thread|
+        stdin.should be_kind_of(IO)
+        stdout.should be_kind_of(IO)
+        wait_thread.should be_kind_of(Thread)
+      end
+    end
+
+    it "supports popen3" do
+      stdin, stdout, stderr, wait_thread = process.popen3
+      stdin.should be_kind_of(IO)
+      stdout.should be_kind_of(IO)
+      stderr.should be_kind_of(IO)
+      wait_thread.should be_kind_of(Thread)
+      stdin.close
+      stdout.close
+      stderr.close
+
+      process.popen3 do |stdin, stdout, stderr, wait_thread|
+        stdin.should be_kind_of(IO)
+        stdout.should be_kind_of(IO)
+        stderr.should be_kind_of(IO)
+        wait_thread.should be_kind_of(Thread)
+      end
+    end
+  end
+
+  context "capture" do
+    it "supports capture2" do
+      process = ProcessBuilder.build('ruby')
+      stdout_string, status = process.capture2("puts('Hello world!')")
+      stdout_string.should == "Hello world!\n"
+      status.should be_kind_of(Process::Status)
+    end
+
+    it "supports capture3" do
+      process = ProcessBuilder.build('ruby')
+      ruby_code = %Q{puts("Hello world!"); $stderr.puts("42")}
+      stdout_string, stderr_string, status = process.capture3(ruby_code)
+      stdout_string.should == "Hello world!\n"
+      stderr_string.should == "42\n"
+      status.should be_kind_of(Process::Status)
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: process_builder
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Jason Voegele
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70235751354520 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70235751354520
+description: 
+email:
+- jason@jvoegele.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.rdoc
+- Rakefile
+- lib/process_builder.rb
+- process_builder.gemspec
+- spec/process_builder_spec.rb
+homepage: https://github.com/jvoegele/process_builder
+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: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Simple object-oriented wrapper around Process.spawn and Open3
+test_files:
+- spec/process_builder_spec.rb