system_run 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c6bd63c23713abf1d6a2ce4c456048e313fd7a3
-  data.tar.gz: 304ba5539f1f046ad9eb73bcc0d139fda00b27e0
+  metadata.gz: cd6598275fe6de6a8b62779ad1ad194634552787
+  data.tar.gz: 6323869c240f230dc367ca83183c74fc6e10e283
 SHA512:
-  metadata.gz: 107eafe0bccfa161b5450977034a1b860bf6f9a73c3db07726c902ad23e260e7616001f1caf045fb2a0e53d9f15f3cc7a678f48c2121af1bb13a080831213057
-  data.tar.gz: 07d0a846819655436dcbbac434d28d48031f1038725a823266d1d02ecb8a8b0fc82fc51bdc58cd26641313ae5db6d9a03da5419c3ddc3d3a6affcc66200840b2
+  metadata.gz: 7476d1f83a81b930acf77623d1b0c523fa5f1b009dfc1d8262779ae06acc2a19d570f6fcdbb1e1e6f11d70e083766058714c3c3ce12bfb23e6ef14af28faea1f
+  data.tar.gz: 72740f36a260b1cea5a683d85fab6468c3d8da0e2d104e276f7e3b1a276af344898fdc747af98f3567acbe0b799af5ef89b5275717fbcede002d4af3aacaa4a6

data/README.md

@@ -1,3 +1,78 @@
 # system_run
-Tiny wrapper for running commands.
-Inspired by systemu.
+Tiny wrapper for running commands. Inspired by systemu.
+
+System.run is a wrapper for making subprocess-spawning more ergonomic. It uses
+Ruby's `Kernel.spawn` internally and supports setting a timeout, environment
+variables, a working directory, files for redirecting, a custom action for when
+a timeout occurs and other options that are forwarded to `spawn` as-is.
+
+## Examples
+
+```ruby
+# capture both stderr and stdout, but separately.
+program = %q{ruby -e "STDOUT.print 'hello'; STDERR.print 'world'"}
+System.run program
+# => [#<Process::Status: pid 20407 exit 0>, "hello", "world"]
+
+# only capture stdout.
+System.run program, capture: :out
+# => [#<Process::Status: pid 20421 exit 0>, "hello"]
+
+# only capture stderr.
+System.run program, capture: :err
+# => [#<Process::Status: pid 20458 exit 0>, "world"]
+
+# capture both stdout and stderr into the same string.
+# stdout is buffered, stderr is not!
+System.run program, capture: :both
+# => [#<Process::Status: pid 20464 exit 0>, "worldhello"]
+
+# kill (send signal 9) process after the specified time.
+program = %q{ruby -e "STDERR.print 'this can only end badly'; loop { sleep 1 }"}
+System.run program, timeout: 2, capture: :both
+# ...
+# => [#<Process::Status: pid 20507 SIGKILL (signal 9)>, "this can only end badly"]
+
+# override default action with sending SIGTERM and setting a control variable.
+state = :everything_is_great
+System.run program, timeout: 2, capture: :both, on_timeout: ->(pid) do
+  state = :oh_no
+  Process.kill 15, pid
+end
+# ...
+# => [#<Process::Status: pid 20519 SIGTERM (signal 15)>, "this can only end badly"]
+
+# set some environment variable.
+program = %{ruby -e "STDERR.print ENV['hello']; STDOUT.print Dir.pwd"}
+System.run program, capture: :err, env: {'hello' => 2}
+# => [#<Process::Status: pid 20540 exit 0>, "2"]
+
+# set working dir.
+System.run program, capture: :out, cwd: Dir.tmpdir
+# => [#<Process::Status: pid 20545 exit 0>, "/tmp"]
+
+# redirect to file (File or Tempfile or descendants)
+program = %q{ruby -e "STDOUT.print 'hello'; STDERR.print 'world'"}
+out = Tempfile.new 'out'
+err = Tempfile.new 'err'
+System.run program, file: [out, err]
+# => #<Process::Status: pid 20553 exit 0>
+out.read
+# => "hello"
+err.read
+# => "world"
+
+# everything works the same!
+out = Tempfile.new 'out'
+System.run program, file: out, capture: :both
+# => #<Process::Status: pid 20591 exit 0>
+out.read
+# => "worldhello"
+
+# you can specify some file to be used as stdin. this option is passed
+# directly to Kernel.spawn.
+input = Tempfile.new.tap { |f| f.write('system_run'); f.rewind }
+echo = %q{ruby -e "print STDIN.gets"}
+System.run echo, in: input, capture: :out
+# => [#<Process::Status: pid 20605 exit 0>, "system_run"]
+```

data/spec/system_run_spec.rb

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+$:.push '../lib'
+require 'rspec'
+require 'system_run'
+
+RSpec.describe System, ".run" do
+  context "basic capturing of output" do
+    program = %q{ruby -e "STDOUT.print 'hello'; STDERR.print 'world'"}
+
+    it "can capture stdout and stderr separately" do
+      status, stdout, stderr = System.run program
+
+      expect(status.exitstatus).to eq 0
+      expect(stdout).to eq('hello')
+      expect(stderr).to eq('world')
+    end
+
+    it "can discard stderr" do
+      status, stdout = System.run program, capture: :out
+      expect(status.exitstatus).to eq 0
+      expect(stdout).to eq('hello')
+    end
+
+    it "can discard stdout, too" do
+      status, stderr = System.run program, capture: :err
+      expect(status.exitstatus).to eq 0
+      expect(stderr).to eq('world')
+    end
+
+    it "can merge both streams into one" do
+      status, all = System.run program, capture: :both
+      expect(status.exitstatus).to eq(0)
+      expect(all).to eq('worldhello')
+    end
+  end
+
+  context "setting a timeout on subprocess" do
+    program = %q{ruby -e "STDERR.print 'this can only end badly'; loop { sleep 2 }"}
+
+    it "will timeout after n seconds, preserving output so-far, and kill process" do
+      status, all = System.run program, timeout: 2, capture: :both
+
+      expect(status.signaled?).to be true
+      expect(status.termsig).to eq 9
+      expect(all).to eq('this can only end badly')
+    end
+
+    it "will timeout after n seconds and execute a custom action" do
+      state = :ok
+      status, all = System.run program, timeout: 2, capture: :both, on_timeout: ->(pid) do
+        state = :err
+        Process.kill 15, pid
+      end
+
+      expect(state).to eq(:err)
+      expect(status.signaled?).to be true
+      expect(status.termsig).to eq 15
+      expect(all).to eq('this can only end badly')
+    end
+  end
+
+  context "setting environment variables and changing directory prior to executing" do
+    program = %{ruby -e "STDERR.print ENV['hello']; STDOUT.print Dir.pwd"}
+
+    it "can set environment variables" do
+      status, stderr = System.run program, capture: :err, env: {'hello' => 2}
+
+      expect(status.exitstatus).to eq(0)
+      expect(stderr).to eq('2')
+    end
+
+    it "can switch working directory" do
+      status, stdout = System.run program, capture: :out, cwd: Dir.tmpdir
+
+      expect(status.exitstatus).to eq(0)
+      expect(stdout).to eq(Dir.tmpdir)
+    end
+  end
+
+  context "reading and writing to files" do
+    program = %q{ruby -e "STDOUT.print 'hello'; STDERR.print 'world'"}
+
+    it "can redirect output to files" do
+      out = Tempfile.new 'out'
+      err = Tempfile.new 'err'
+
+      status = System.run program, file: [out, err]
+
+      expect(status.exitstatus).to eq(0)
+      expect(out.read).to eq('hello')
+      expect(err.read).to eq('world')
+
+      [out, err].each { |f| f.close; f.unlink }
+    end
+
+    it "works the same as with string, e.g. merging streams" do
+      out = Tempfile.new 'out'
+
+      status = System.run program, file: out, capture: :both
+
+      expect(status.exitstatus).to eq(0)
+      expect(out.read).to eq('worldhello')
+      out.close; out.unlink
+    end
+
+    it "can read input provided in a file" do
+      input = Tempfile.new.tap { |f| f.write('system_run'); f.rewind }
+
+      echo = %q{ruby -e "print STDIN.gets"}
+      status, out = System.run echo, in: input, capture: :out
+
+      expect(status.exitstatus).to eq(0)
+      expect(out).to eq('system_run')
+    end
+  end
+end

data/system_run.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name             = "system_run"
-  s.version          = "1.0.1"
+  s.version          = "1.0.2"
   s.platform         = Gem::Platform::RUBY
   s.license          = "MIT"
   s.summary          = "Tiny wrapper for running commands. Inspired by systemu."
@@ -10,9 +10,10 @@ Gem::Specification.new do |s|
   s.files            = Dir['lib/**/*,spec/*}'] + %w(LICENSE Rakefile system_run.gemspec README.md)
   s.require_path     = 'lib'
   s.extra_rdoc_files = ['README.md']
-  s.test_files       = []
+  s.test_files       = Dir['spec/system_run_spec*.rb']
 
   s.required_ruby_version = '>=2.3.0'
+  s.add_development_dependency 'rspec', '~>3.0'
 
   s.authors          = ['Sonja Biedermann']
 

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: system_run
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Sonja Biedermann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-07 00:00:00.000000000 Z
-dependencies: []
+date: 2017-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: see https://github.com/biederfrau/system_run
 email: s.bdrmnn@gmail.com
 executables: []
@@ -20,6 +34,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- spec/system_run_spec.rb
 - system_run.gemspec
 homepage: https://github.com/biederfrau/system_run
 licenses:
@@ -45,4 +60,5 @@ rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Tiny wrapper for running commands. Inspired by systemu.
-test_files: []
+test_files:
+- spec/system_run_spec.rb