system_run 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd6598275fe6de6a8b62779ad1ad194634552787
-  data.tar.gz: 6323869c240f230dc367ca83183c74fc6e10e283
+  metadata.gz: 82b98b36722d6fefa40acc60c9e71a3e88c4917a
+  data.tar.gz: 42d53eaffdc0d376a6541d8e6398c8fde8e0e6ed
 SHA512:
-  metadata.gz: 7476d1f83a81b930acf77623d1b0c523fa5f1b009dfc1d8262779ae06acc2a19d570f6fcdbb1e1e6f11d70e083766058714c3c3ce12bfb23e6ef14af28faea1f
-  data.tar.gz: 72740f36a260b1cea5a683d85fab6468c3d8da0e2d104e276f7e3b1a276af344898fdc747af98f3567acbe0b799af5ef89b5275717fbcede002d4af3aacaa4a6
+  metadata.gz: 805bb4f14de0dd05d69833a367452c891f5439cea6078602bc3d136f65c99ecd38dbf1e10301005b36e1849003e513e368cba3a7eb92a87906202a7a46b32532
+  data.tar.gz: f79a1e1ed744aea047fdc737a0d086bfaaea857286ddaca287b0b3e28cd4b562cf4eded8fba549ee9c4cbc90257396553879cc7aca2f5fc9c364cdd78a2d54b7

data/README.md

@@ -8,12 +8,19 @@ a timeout occurs and other options that are forwarded to `spawn` as-is.
 
 ## Examples
 
+System.run will by default capture stderr and stdout separately and return
+them as strings along with the process exit state.
+
 ```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"]
+```
 
+You can also only pick just one by specifiying the `capture` keyword argument.
+
+```ruby
 # only capture stdout.
 System.run program, capture: :out
 # => [#<Process::Status: pid 20421 exit 0>, "hello"]
@@ -21,18 +28,36 @@ System.run program, capture: :out
 # only capture stderr.
 System.run program, capture: :err
 # => [#<Process::Status: pid 20458 exit 0>, "world"]
+```
+
+Sometimes, it is also useful to capture both stdout _and_ stderr simultaneously.
+Bear in mind, however, that stdout is buffered and thus might not appear if the
+process dies before the buffer is flushed.
 
+```ruby
 # 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"]
+```
+
+You can also specify a timeout interval after which System.run will kill
+the process.
 
+```ruby
 # 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"]
+```
 
+If outright killing the process is too harsh for you, or you want to do some
+extra things like logging the timeout, you can specify a callable object that
+will get called when the timeout expires. This callable will receive one argument,
+the process id of the spawned child.
+
+```ruby
 # 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
@@ -41,16 +66,33 @@ System.run program, timeout: 2, capture: :both, on_timeout: ->(pid) do
 end
 # ...
 # => [#<Process::Status: pid 20519 SIGTERM (signal 15)>, "this can only end badly"]
+```
 
+You can temporarily set some environment variables that will be accessible to
+the child process. Keys and values will be converted to string by System.run
+for you, don't worry about that.
+
+```ruby
 # 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"]
+```
+
+You can also specify the directory which shall be the working directory
+for the child process.
 
+```ruby
 # set working dir.
 System.run program, capture: :out, cwd: Dir.tmpdir
 # => [#<Process::Status: pid 20545 exit 0>, "/tmp"]
+```
+
+If the output is too large to be loaded into memory or you want to keep the
+output, you can specify a file–or for default capture, two files–that
+System.run should write to. System.run will rewind the file after writing.
 
+```ruby
 # redirect to file (File or Tempfile or descendants)
 program = %q{ruby -e "STDOUT.print 'hello'; STDERR.print 'world'"}
 out = Tempfile.new 'out'
@@ -61,16 +103,24 @@ out.read
 # => "hello"
 err.read
 # => "world"
+```
 
+You can specify all options the same as when working with strings, System.run doesn't care.
+
+```ruby
 # 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 also supply text to be used as input for the child process by passing
+the corresponding file object as `in` keyword parameter.
 
-# you can specify some file to be used as stdin. this option is passed
-# directly to Kernel.spawn.
+```ruby
+# the in: 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

data/system_run.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name             = "system_run"
-  s.version          = "1.0.2"
+  s.version          = "1.0.3"
   s.platform         = Gem::Platform::RUBY
   s.license          = "MIT"
   s.summary          = "Tiny wrapper for running commands. Inspired by systemu."

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: system_run
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Sonja Biedermann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-09 00:00:00.000000000 Z
+date: 2017-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec