process_helper 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 545dfa70d2c4398cb9e9a83bf98cd7541506d857
+  data.tar.gz: 7257372f2aa37bb3d2fd40c4b40cff450dfaee71
+SHA512:
+  metadata.gz: 6c0478bcbf1cf87ec7afbfc1b0e1394ecdabbdbe222f6b83bb09ede1e35abaaee6f6660c2a20a215fe3c9f4bac560e08bfa5ca28c6b0959ad146f21aaf7dc0b9
+  data.tar.gz: d2be7bb16ee0d16f3d6eee824e9c33747912af1427ef75f0859300ccc4b5f6daf087a1ef4c61dcd9a0b9a068a52f4f080095504d048d32118c3d4151b06f82a9

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.idea
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rubocop.yml

@@ -0,0 +1,29 @@
+---
+# https://github.com/bbatsov/rubocop/blob/master/config/default.yml
+Metrics/LineLength:
+  Max: 99
+
+Metrics/MethodLength:
+  CountComments: false  # count full line comments?
+  Max: 20
+
+Style/CaseIndentation:
+  IndentOneStep: true
+
+Style/FirstParameterIndentation:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/MultilineOperationIndentation:
+  Enabled: false
+
+Style/SpaceAroundEqualsInParameterDefault:
+  # compatibility with RubyMine defaults (apparently can't override?)
+  EnforcedStyle: space
+
+Style/TrailingComma:
+  # can't make this only apply to arrays and not params, so it's disabled
+  Enabled: false
+  #EnforcedStyleForMultiline: comma

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1

data/.travis.yml

@@ -0,0 +1,2 @@
+---
+sudo: false

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

data/README.md

@@ -0,0 +1,180 @@
+[![Travis-CI Build Status](https://travis-ci.org/thewoolleyman/process_helper.svg?branch=master)](https://travis-ci.org/thewoolleyman/process_helper)
+
+[Pivotal Tracker Project](https://www.pivotaltracker.com/n/projects/1117814)
+
+# process_helper
+
+Makes it easy to spawn Ruby sub-processes with guaranteed exit status handling, passing of lines to STDIN, and capturing of STDOUT and STDERR streams.
+
+## Goals
+
+* Always raise an exception on unexpected exit status (i.e. return code or `$!`)
+* Combine and interleave STDOUT and STDERR streams into STDOUT (using [Open3.popen2e](http://ruby-doc.org/stdlib-2.1.5/libdoc/open3/rdoc/Open3.html#method-c-popen2e)),
+  so you don't have to worry about how to capture the output of both streams.
+* Provide useful options for suppressing output and including output when an exception
+  is raised due to an unexpected exit status
+* Provide real-time streaming of combined STDOUT/STDERR streams in addition to returning full combined output as a string returned from the method and/or in the exception.  
+* Support passing multi-line input to the STDIN stream via arrays of strings.
+* Allow override of the expected exit status(es) (zero is expected by default)
+* Provide short forms of all options for terse, concise usage.
+
+## Non-Goals
+
+* Any explicit support for process forks, multiple threads, or anything other
+  than a single direct child process.
+* Any support for separate handling of STDOUT and STDERR streams
+
+## Why Yet Another Ruby Process Wrapper Library?
+
+There's many other libraries to make it easier to work with processes in Ruby (see the Resources section).  However, `process_helper` was created because none of them made it *easy* to run processes while meeting **all** of these requirements (redundant details are repeated above in Goals section):
+
+* Combine STDOUT/STDERR output streams ***interleaved chronologically as emitted***
+* Stream STDOUT/STDERR real-time ***while process is still running***, in addition to returning full output as a string and/or in an exception
+* Guarantee an exception is ***always raised*** on an unexpected exit status (and allow specification of ***multiple nonzero values*** as expected exit statuses)
+* Can be used ***very concisely***.  I.e. All behavior can be invoked via a single mixed-in module with single public method call using terse options with sensible defaults, no need to use IO streams directly or have any blocks or local variables declared.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'process_helper'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install process_helper
+
+## Usage
+
+`ProcessHelper` is a Ruby module you can include in any Ruby code,
+and then call `#process` to run a command, like this:
+
+```
+require 'process_helper'
+include ProcessHelper
+process('echo "Hello"')
+```
+
+By default, ProcessHelper will combine any STDERR and STDOUT, and output it to STDOUT,
+and also return it as the result of the `#process` method.
+
+## Options
+
+### `:expected_exit_status` (short form `:exp_st`)
+
+Expected Integer exit status, or array of expected Integer exit statuses.
+Default value is `[0]`.
+
+An exception will be raised by the `ProcessHelper#process` method if the
+actual exit status of the processed command is not (one of) the
+expected exit status(es).
+
+Here's an example of expecting a nonzero failure exit status which matches the actual exit status
+(the actual exit status of a failed `ls` command will be 1 on OSX, 2 on Linux):
+
+```
+# The following will NOT raise an exception:
+process('ls /does_not_exist', expected_exit_status: [1,2])
+```
+
+...but it **WILL** still print the output (in this case STDERR output from the failed `ls`
+command) to STDOUT:
+
+```
+ls: /does_not_exist: No such file or directory
+```
+
+Here's a second example of expecting a nonzero failure exit status but the command succeeds:
+
+```
+# The following WILL raise an exception:
+process('printf FAIL', expected_exit_status: 1)
+```
+
+Here's the output of the above example:
+
+```
+FAIL
+ProcessHelper::UnexpectedExitStatusError: Command succeeded but was expected to fail, pid 62974 exit 0 (expected [1]). Command: `printf FAIL`. Command Output: "FAIL"
+```
+
+### `:include_output_in_exception` (short form `:out_ex`)
+
+Boolean flag indicating whether output should be included in the message of the Exception (error)
+which will be raised by the `ProcessHelper#process` method if the command fails (has an unexpected exit status).
+
+Here's an example of a failing command:
+
+```
+process('ls /does_not_exist', include_output_in_exception: true)
+```
+
+Here's the exception generated by the above example.  Notice the "Command Output"
+with the *"...No such file or directory"* STDERR output of the failed command:
+
+```
+ProcessHelper::UnexpectedExitStatusError: Command failed, pid 64947 exit 1. Command: `ls /does_not_exist`. Command Output: "ls: /does_not_exist: No such file or directory
+"
+```
+
+### `:puts_output` (short form `:out`)
+
+Valid values are `:always`, `:error`, and `:never`.  Default value is `:always`.
+
+* `:always` will always print output to STDOUT
+* `:error` will only print output to STDOUT if command has an
+  error - i.e. non-zero or unexpected exit status
+* `:never` will never print output to STDOUT
+
+## Warnings if failure output will be suppressed based on options
+
+ProcessHelper will give you a warning if you pass a combination of options that would
+prevent **ANY** output from being printed or included in the Exception message if
+a command were to fail.
+
+For example, in this case there is no output, and the expected exit status includes
+the actual failure status which is returned, so the warning is printed, and the only
+place the output will be seen is in the return value of the `ProcessHelper#process` method:
+
+```
+> process('ls /does_not_exist', expected_exit_status: [1,2], puts_output: :never, include_output_in_exception: false)
+WARNING: Check your ProcessHelper options - :puts_output is :never, and :include_output_in_exception is false, so all error output will be suppressed if process fails.
+ => "ls: /does_not_exist: No such file or directory\n"
+ ```
+
+## Version
+
+You can see the version of ProcessHelper in the `ProcessHelper::VERSION` constant:
+
+```
+ProcessHelper::VERSION
+=> "0.0.1"
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/thewoolleyman/process_helper/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. If you are awesome, use `git rebase --interactive` to ensure
+   you have a single atomic commit on your branch.
+6. Create a new Pull Request
+
+## Resources
+
+Other Ruby Process tools/libraries
+
+* [open4](https://github.com/ahoward/open4) - a solid and useful library - the main thing I missed in it was easily combining real-time streaming interleaved STDOUT/STDERR streams
+* [open4 on ruby toolbox](https://www.ruby-toolbox.com/projects/open4) - see if there's some useful higher-level gem that depends on it and gives you functionality you may need
+* A great series of blog posts by Devver:
+  * [https://devver.wordpress.com/2009/06/30/a-dozen-or-so-ways-to-start-sub-processes-in-ruby-part-1/](https://devver.wordpress.com/2009/06/30/a-dozen-or-so-ways-to-start-sub-processes-in-ruby-part-1/)
+  * [https://devver.wordpress.com/2009/07/13/a-dozen-or-so-ways-to-start-sub-processes-in-ruby-part-2/](https://devver.wordpress.com/2009/07/13/a-dozen-or-so-ways-to-start-sub-processes-in-ruby-part-2/)
+  * [https://devver.wordpress.com/2009/10/12/ruby-subprocesses-part_3/](https://devver.wordpress.com/2009/10/12/ruby-subprocesses-part_3/)
+
+
+

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/process_helper/empty_command_error.rb

@@ -0,0 +1,5 @@
+# Error which is raised when a command is empty
+module ProcessHelper
+  class EmptyCommandError < RuntimeError
+  end
+end

data/lib/process_helper/invalid_options_error.rb

@@ -0,0 +1,5 @@
+# Error which is raised when options are invalid
+module ProcessHelper
+  class InvalidOptionsError < RuntimeError
+  end
+end

data/lib/process_helper/unexpected_exit_status_error.rb

@@ -0,0 +1,5 @@
+# Error which is raised when a command returns an unexpected exit status (return code)
+module ProcessHelper
+  class UnexpectedExitStatusError < RuntimeError
+  end
+end

data/lib/process_helper/unprocessed_input_error.rb

@@ -0,0 +1,5 @@
+# Error which is raised when command exists while input lines remain unprocessed
+module ProcessHelper
+  class UnprocessedInputError < RuntimeError
+  end
+end

data/lib/process_helper/version.rb

@@ -0,0 +1,4 @@
+# Library version
+module ProcessHelper
+  VERSION = '0.0.1'
+end

data/lib/process_helper.rb

@@ -0,0 +1,258 @@
+require_relative 'process_helper/version'
+require_relative 'process_helper/empty_command_error'
+require_relative 'process_helper/invalid_options_error'
+require_relative 'process_helper/unexpected_exit_status_error'
+require_relative 'process_helper/unprocessed_input_error'
+require 'open3'
+
+# Makes it easier to spawn ruby sub-processes with proper capturing of stdout and stderr streams.
+module ProcessHelper
+  def process(cmd, options = {})
+    cmd = cmd.to_s
+    fail ProcessHelper::EmptyCommandError, 'command must not be empty' if cmd.empty?
+    options = options.dup
+    options_processing(options)
+    Open3.popen2e(cmd) do |stdin, stdout_and_stderr, wait_thr|
+      always_puts_output = (options[:puts_output] == :always)
+      output = get_output(
+        stdin,
+        stdout_and_stderr,
+        options[:input_lines],
+        always_puts_output,
+        options[:timeout]
+      )
+      stdin.close
+      handle_exit_status(cmd, options, output, wait_thr)
+      output
+    end
+  end
+
+  private
+
+  def warn_if_output_may_be_suppressed_on_error(options)
+    return unless options[:puts_output] == :never
+
+    if options[:include_output_in_exception] == false
+      err_msg = 'WARNING: Check your ProcessHelper options - ' \
+        ':puts_output is :never, and :include_output_in_exception ' \
+        'is false, so all error output will be suppressed if process fails.'
+    else
+      err_msg = 'WARNING: Check your ProcessHelper options - ' \
+        ':puts_output is :never, ' \
+        'so all error output will be suppressed unless process ' \
+        "fails with an exit code other than #{options[:expected_exit_status]} " \
+        '(in which case exception will include output ' \
+        'because :include_output_in_exception is true)'
+    end
+    $stderr.puts(err_msg)
+  end
+
+  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+  # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
+  def get_output(stdin, stdout_and_stderr, original_input_lines, always_puts_output, timeout)
+    input_lines = original_input_lines.dup
+    input_lines_processed = 0
+    current_input_line_processed = false
+    output = ''
+    begin
+      while (output_line = readline_nonblock(stdout_and_stderr))
+        current_input_line_processed = true
+        puts output_line if always_puts_output
+        output += output_line
+        output_line = nil
+      end
+    rescue EOFError
+      input_lines_processed -= 1  if !original_input_lines.empty? && !current_input_line_processed
+      fail_unless_all_input_lines_processed(original_input_lines, input_lines_processed)
+    rescue IO::WaitReadable
+      if input_lines.empty?
+        result = IO.select([stdout_and_stderr], nil, nil, timeout)
+        retry unless result.nil?
+      else
+        current_input_line_processed = false
+        puts_input_line_to_stdin(stdin, input_lines)
+        input_lines_processed += 1
+        result = IO.select([stdout_and_stderr], nil, nil, timeout)
+        retry
+      end
+    end
+    output
+  end
+
+  def readline_nonblock(io)
+    buffer = ''
+    while (ch = io.read_nonblock(1))
+      buffer << ch
+      if ch == "\n"
+        result = buffer
+        return result
+      end
+    end
+  end
+
+  def fail_unless_all_input_lines_processed(original_input_lines, input_lines_processed)
+    unprocessed_input_lines = original_input_lines.length - input_lines_processed
+    msg = "Output stream closed with #{unprocessed_input_lines} " \
+    'input lines left unprocessed:' \
+    "#{original_input_lines[-(unprocessed_input_lines)..-1]}"
+    fail(
+      ProcessHelper::UnprocessedInputError,
+      msg
+    ) unless unprocessed_input_lines == 0
+  end
+
+  def puts_input_line_to_stdin(stdin, input_lines)
+    return if input_lines.empty?
+    input_line = input_lines.shift
+    stdin.puts(input_line)
+  end
+
+  def handle_exit_status(cmd, options, output, wait_thr)
+    expected_exit_status = options[:expected_exit_status]
+    exit_status = wait_thr.value
+    return if expected_exit_status.include?(exit_status.exitstatus)
+
+    exception_message = create_exception_message(cmd, exit_status, expected_exit_status)
+    if options[:include_output_in_exception]
+      exception_message += " Command Output: \"#{output}\""
+    end
+    puts_output_only_on_exception(options, output)
+    fail ProcessHelper::UnexpectedExitStatusError, exception_message
+  end
+
+  def create_exception_message(cmd, exit_status, expected_exit_status)
+    if expected_exit_status == [0]
+      result_msg = 'failed'
+      exit_status_msg = ''
+    elsif !expected_exit_status.include?(0)
+      result_msg = 'succeeded but was expected to fail'
+      exit_status_msg = " (expected #{expected_exit_status})"
+    else
+      result_msg = 'did not exit with one of the expected exit statuses'
+      exit_status_msg = " (expected #{expected_exit_status})"
+    end
+
+    "Command #{result_msg}, #{exit_status}#{exit_status_msg}. " \
+      "Command: `#{cmd}`."
+  end
+
+  def puts_output_only_on_exception(options, output)
+    return if options[:puts_output] == :always
+    puts output if options[:puts_output] == :error
+  end
+
+  def options_processing(options)
+    validate_long_vs_short_option_uniqueness(options)
+    convert_short_options(options)
+    set_option_defaults(options)
+    validate_option_values(options)
+    convert_scalar_expected_exit_status_to_array(options)
+    warn_if_output_may_be_suppressed_on_error(options)
+  end
+
+  # rubocop:disable Style/AccessorMethodName
+  def set_option_defaults(options)
+    options[:puts_output] = :always if options[:puts_output].nil?
+    options[:include_output_in_exception] = true if options[:include_output_in_exception].nil?
+    options[:expected_exit_status] = [0] if options[:expected_exit_status].nil?
+    options[:input_lines] = [] if options[:input_lines].nil?
+  end
+
+  def valid_option_pairs
+    pairs = [
+      %w(expected_exit_status exp_st),
+      %w(include_output_in_exception out_ex),
+      %w(input_lines in),
+      %w(puts_output out),
+      %w(timeout kill),
+    ]
+    pairs.each do |pair|
+      pair.each_with_index do |opt, index|
+        pair[index] = opt.to_sym
+      end
+    end
+  end
+
+  def valid_options
+    valid_option_pairs.flatten
+  end
+
+  def validate_long_vs_short_option_uniqueness(options)
+    invalid_options = (options.keys - valid_options)
+    fail(
+      ProcessHelper::InvalidOptionsError,
+      "Invalid option(s) '#{invalid_options.join(', ')}' given.  " \
+         "Valid options are: #{valid_options.join(', ')}") unless invalid_options.empty?
+    valid_option_pairs.each do |pair|
+      long_option_name, short_option_name = pair
+      both_long_and_short_option_specified =
+        options[long_option_name] && options[short_option_name]
+      next unless both_long_and_short_option_specified
+      fail(
+        ProcessHelper::InvalidOptionsError,
+        "Cannot specify both '#{long_option_name}' and '#{short_option_name}'")
+    end
+  end
+
+  def convert_short_options(options)
+    valid_option_pairs.each do |pair|
+      long, short = pair
+      options[long] = options.delete(short) unless options[short].nil?
+    end
+  end
+
+  def validate_option_values(options)
+    options.each do |option, value|
+      valid_option_pairs.each do |pair|
+        long_option_name, _ = pair
+        next unless option == long_option_name
+        validate_integer(pair, value) if option.to_s == 'expected_exit_status'
+        validate_boolean(pair, value) if option.to_s == 'include_output_in_exception'
+        validate_puts_output(pair, value) if option.to_s == 'puts_output'
+      end
+    end
+  end
+
+  def validate_integer(pair, value)
+    valid =
+      case
+        when value.is_a?(Integer)
+          true
+        when value.is_a?(Array) && value.all? { |v| v.is_a?(Integer) }
+          true
+        else
+          false
+      end
+
+    fail(
+      ProcessHelper::InvalidOptionsError,
+      "#{quote_and_join_pair(pair)} options must be an Integer or an array of Integers"
+    ) unless valid
+  end
+
+  def validate_boolean(pair, value)
+    fail(
+      ProcessHelper::InvalidOptionsError,
+      "#{quote_and_join_pair(pair)} options must be a boolean"
+    ) unless value == true || value == false
+  end
+
+  def validate_puts_output(pair, value)
+    valid_values = [:always, :error, :never]
+    fail(
+      ProcessHelper::InvalidOptionsError,
+      "#{quote_and_join_pair(pair)} options must be one of the following: " +
+        valid_values.map { |v| ":#{v}" }.join(', ')
+    ) unless valid_values.include?(value)
+  end
+
+  def quote_and_join_pair(pair)
+    pair.map { |o| "'#{o}'" }.join(',')
+  end
+
+  def convert_scalar_expected_exit_status_to_array(options)
+    return if options[:expected_exit_status].is_a?(Array)
+    options[:expected_exit_status] =
+      [options[:expected_exit_status]]
+  end
+end