README.md in process_helper-0.0.2 vs README.md in process_helper-0.0.3

- old
+ new

@@ -43,11 +43,23 @@ $ bundle Or install it yourself as: $ gem install process_helper + +Or, if you want to avoid a Gem/RubyGems dependency, you can copy the `process_helper.rb` file from the `lib` folder directly into your project and require it: + # from a ruby file: + require_relative 'process_helper' + + # from IRB: + require './process_helper' + + # or put the directory containing it on the load path: + $LOAD_PATH.unshift('.') + require '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: @@ -126,10 +138,31 @@ * `: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 +### `:timeout` (short form `:kill`) + +***WARNING! This option is beta and will be changed in a future release!*** + +Valid value is a float, e.g. `1.5`. Default value is nil/undefined. + +* Currently controls how long `process_helper` will wait to read from + a blocked IO stream before timing out (via [IO.select](http://ruby-doc.org/core-2.2.0/IO.html#method-c-select)). For example, invoking `cat` with no arguments, which by default will continue accepting input until killed. +* If undefined (default), there will be no timeout, and `process_helper` will hang if a process hangs while waiting to read from IO. + +***The following changes are planned for this option:*** + +* Add validation of value (enforced to be a float). +* Add ability for the timeout value to also kill long running processes which are ***not*** in blocked waiting on an IO stream read (i.e. kill process regardless of any IO state, not just via [IO.selects](http://ruby-doc.org/core-2.2.0/IO.html#method-c-select) timeout support). +* Have both types of timeouts raise different and unique exception classes. +* Possibly have different option names to allow different timeout values for the two types of timeouts. + +See [https://www.pivotaltracker.com/story/show/93303096](https://www.pivotaltracker.com/story/show/93303096) for more details. + + + ## 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. @@ -160,9 +193,13 @@ 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 + +## (Un)License + +`process_helper` is (un)licensed under the [unlicense](http://unlicense.org/). So, feel free to copy it into your project (it's usable as a single required file and module), use it, abuse it, do what you will, no attribution required. :) ## Resources Other Ruby Process tools/libraries