backticks 1.0.0rc1 → 1.0.0rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a446a43c0be0d08f7ad35f3f9a2fa7791f66229d
-  data.tar.gz: 2fc8f0e3176dae7628cb08225c63f95d97002e8f
+  metadata.gz: 51c5bc30064cde134337b459ec829f6099a65c21
+  data.tar.gz: 950628c7a317d251eca8bc29c89cf474259b2f63
 SHA512:
-  metadata.gz: 96d973bd4ef27a7bfcfecf7f8cb9e7ea0de2bb05f758aa42fb49c5438ba372230c5a77d07737da4e9492c0109533992ca9f1ad9ccf779fe442e7907d8bd5a7b7
-  data.tar.gz: 378d42242e3efbc5817c89266a34e620ca59ddfe6fc92411b56671fe5aa7104088a5f934235f8b1f9dbcb66c589ef71f8c1c1904f5a755074392317817c59172
+  metadata.gz: 6887deef8f9ce8f4c1c998951b135a78e567a6244eaa9b80cd132fbb22d7700bc1c64470b010cfe9cd91b10a4dcc9432cf0bd4b9a5df5fbc9d73e365217f9b66
+  data.tar.gz: cdb8c7c4e9d7776592921ca11c29c930c3d1687ecf82a0058ffc8088d14c0482fcec31dfac9fa56853807984834fd2d9c093cf0c5f82ab6898a58955eff695c7

data/.travis.yml

@@ -1,7 +1,8 @@
 sudo: false
 language: ruby
 rvm:
-- 1.9
+- 2.0
+- 2.1
 - 2.2
 before_install: gem install bundler -v '~> 1.10'
 script: bundle exec rake spec

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+1.0
+===

data/Gemfile

@@ -3,6 +3,11 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in backticks.gemspec
 gemspec
 
+group :development do
+  gem 'pry'
+  gem 'pry-byebug'
+end
+
 group :test do
   gem 'coveralls', require: false
 end

data/README.md

@@ -1,15 +1,14 @@
-# Introduction
+![Build Status](https://travis-ci.org/xeger/backticks.svg) [![Coverage Status](https://coveralls.io/repos/xeger/backticks/badge.svg?branch=master&service=github)](https://coveralls.io/github/xeger/backticks?branch=master) [![Docs](https://img.shields.io/badge/docs-rubydoc-blue.svg)](http://www.rubydoc.info/gems/backticks)
 
 Backticks is a powerful, intuitive OOP wrapper for invoking command-line processes and
 interacting with them.
 
-![Build Status](https://travis-ci.org/xeger/backticks.svg) [![Coverage Status](https://coveralls.io/repos/xeger/backticks/badge.svg?branch=master&service=github)](https://coveralls.io/github/xeger/backticks?branch=master)
-
 "Powerful" comes from features that make Backticks especially well suited for time-sensitive
 or record/playback applications:
   - Uses [pseudoterminals](https://en.wikipedia.org/wiki/Pseudoterminal) for realtime stdout/stdin
   - Captures input as well as output
   - Separates stdout from stderr
+  - Allows realtime monitoring and transformation of input/output
 
 "Intuitive" comes from a DSL that lets you provide command-line arguments as if they were
 Ruby method arguments:
@@ -105,6 +104,8 @@ require 'io/console'
 STDOUT.raw! ; Backticks::Runner.new(interactive:true).run('vi').join
 ```
 
+### Intercepting and Modifying I/O
+
 You can use the `Command#tap` method to intercept I/O streams in real time,
 with or without interactivity. To start the tap, pass a block to the method.
 Your block should accept two parameters: a Symbol stream name (:stdin,
@@ -112,14 +113,15 @@ Your block should accept two parameters: a Symbol stream name (:stdin,
 input or output.
 
 The result of your block is used to decide what to do with the input/output:
-nil means "discard" and a modified string is captured in place of the original.
+nil means "discard," any String means "use this in place of the original input
+or output.""
 
-Try loading the README in an editor with all of the vowels scrambled. Scroll
+Try loading `README.md` in an editor with all of the vowels scrambled. Scroll
 around and notice how words change when they leave and enter the screen!
 
 ```ruby
+vowels = 'aeiou'  
 STDOUT.raw! ; cmd = Backticks::Runner.new(interactive:true).run('vi', 'README.md') ; cmd.tap do |io, bytes|
-  vowels = 'aeiou'  
   bytes.gsub!(/[#{vowels}]/) { vowels[rand(vowels.size)] } if io == :stdout
   bytes
 end ; cmd.join ; nil

data/lib/backticks/command.rb

@@ -6,13 +6,11 @@ module Backticks
   # Interactive commands print their output to Ruby's STDOUT and STDERR
   # in realtime, and also pass input from Ruby's STDIN to the command's stdin.
   class Command
-    # Time value that is used internally when a user is willing to wait
-    # "forever" for the command.
-    #
-    # Using a definite time-value helps simplify the looping logic internally,
-    # but it does mean that this class will stop working in February of 2106.
-    # You have been warned!
-    FOREVER = Time.at(2**32-1).freeze
+    # Duration that we use when a caller is willing to wait "forever" for
+    # a command to finish. This means that `#join` is buggy when used with
+    # commands that take longer than a year to complete. You have been
+    # warned!
+    FOREVER = 86_400 * 365
 
     # Number of bytes to read from the command in one "chunk".
     CHUNK = 1_024
@@ -32,52 +30,71 @@ module Backticks
     # @return [String] all output to stderr that has been captured so far
     attr_reader :captured_error
 
-    # Watch a running command.
-    def initialize(pid, stdin, stdout, stderr)
+    # Watch a running command by taking ownership of the IO objects that
+    # are passed in.
+    #
+    # @param [Integer] pid
+    # @param [IO] stdin
+    # @param [IO] stdout
+    # @param [IO] stderr
+    def initialize(pid, stdin, stdout, stderr, interactive:false)
       @pid = pid
       @stdin = stdin
       @stdout = stdout
       @stderr = stderr
+      @interactive = !!interactive
 
       @captured_input  = String.new.force_encoding(Encoding::BINARY)
       @captured_output = String.new.force_encoding(Encoding::BINARY)
       @captured_error  = String.new.force_encoding(Encoding::BINARY)
     end
 
-    # @return [String]
+    # @return [String] a basic string representation of this command
     def to_s
       "#<Backticks::Command(@pid=#{pid},@status=#{@status || 'nil'})>"
     end
 
+    # @return [Boolean] true if this command is tied to STDIN/STDOUT
     def interactive?
-      !@stdin.nil?
+      @interactive
+    end
+
+    # Block until the command completes; return true if its status
+    # was zero, false if nonzero.
+    #
+    # @return [Boolean]
+    def success?
+      join
+      status.success?
     end
 
-    # Provide a callback to monitor input and output in real time.
+    # Provide a callback to monitor input and output in real time. This method
+    # saves a reference to block for later use; whenever the command generates
+    # output or receives input, the block is called back with the name of the
+    # stream on which I/O occurred and the actual data that was read or written.
     # @yield
-    # @yieldparam
+    # @yieldparam [Symbol] stream one of :stdin, :stdout or :stderr
+    # @yieldparam [String] data fresh input from the designated stream
     def tap(&block)
       raise StandardError.new("Tap is already set (#{@tap}); cannot set twice") if @tap && @tap != block
       @tap = block
     end
 
     # Block until the command exits, or until limit seconds have passed. If
-    # interactive is true, pass user input to the command and print its output
-    # to Ruby's output streams. If the time limit expires, return `nil`;
-    # otherwise, return self.
+    # interactive is true, proxy STDIN to the command and print its output
+    # to STDOUT. If the time limit expires, return `nil`; otherwise, return
+    # self.
+    #
+    # If the command has already exited when this method is called, return
+    # self immediately.
     #
     # @param [Float,Integer] limit number of seconds to wait before returning
-    def join(limit=nil)
+    def join(limit=FOREVER)
       return self if @status
 
-      if limit
-        tf = Time.now + limit
-      else
-        tf = FOREVER
-      end
-
+      tf = Time.now + limit
       until (t = Time.now) >= tf
-        capture(tf - t)
+        capture(tf-t)
         res = Process.waitpid(@pid, Process::WNOHANG)
         if res
           @status = $?
@@ -103,13 +120,7 @@ module Backticks
       streams = [@stdout, @stderr]
       streams << STDIN if interactive?
 
-      if limit
-        tf = Time.now + limit
-      else
-        tf = FOREVER
-      end
-
-      ready, _, _ = IO.select(streams, [], [], 0)
+      ready, _, _ = IO.select(streams, [], [], limit)
 
       # proxy STDIN to child's stdin
       if ready && ready.include?(STDIN)

data/lib/backticks/runner.rb

@@ -24,19 +24,23 @@ module Backticks
     # List of I/O streams that should be captured using a pipe instead of
     # a pseudoterminal.
     #
-    # This may be a Boolean, or it may be an Array of stream names from the
-    # set [:stdin, :stdout, :stderr].
+    # When read, this attribute is always an Array of stream names from the
+    # set `[:stdin, :stdout, :stderr]`.
     #
-    # Note: if you set `interactive` to true, then stdin and stdout will be
+    # **Note**: if you set `interactive` to true, then stdin and stdout are
     # unbuffered regardless of how you have set `buffered`!
     #
     # @return [Array] list of symbolic stream names
     attr_reader :buffered
 
+    # @return [String,nil] PWD for new child processes, default is Dir.pwd
+    attr_accessor :chdir
+
     # @return [#parameters] the CLI-translation object used by this runner
     attr_reader :cli
 
     # Create an instance of Runner.
+    #
     # @option [#include?,Boolean] buffered list of names; true/false for all/none
     # @option [#parameters] cli command-line parameter translator
     # @option [Boolean] interactive true to tie parent stdout/stdin to child
@@ -55,6 +59,13 @@ module Backticks
       self.interactive = options[:interactive]
     end
 
+    # Control which streams are buffered (i.e. use a pipe) and which are
+    # unbuffered (i.e. use a pseudo-TTY).
+    #
+    # If you pass a Boolean argument, it is converted to an Array; therefore,
+    # the reader for this attribute always returns a list even if you wrote
+    # a boolean value.
+    #
     # @param [Array,Boolean] buffered list of symbolic stream names; true/false for all/none
     def buffered=(b)
       @buffered = case b
@@ -109,7 +120,8 @@ module Backticks
         PTY.open
       end
 
-      pid = spawn(*argv, in: stdin_r, out: stdout_w, err: stderr_w)
+      dir = @chdir || Dir.pwd
+      pid = spawn(*argv, in: stdin_r, out: stdout_w, err: stderr_w, chdir: dir)
       stdin_r.close
       stdout_w.close
       stderr_w.close
@@ -118,7 +130,7 @@ module Backticks
         stdin = nil
       end
 
-      Command.new(pid, stdin, stdout, stderr)
+      Command.new(pid, stdin, stdout, stderr, interactive:interactive)
     end
   end
 end

data/lib/backticks/version.rb

@@ -1,3 +1,3 @@
 module Backticks
-  VERSION = "1.0.0rc1"
+  VERSION = "1.0.0rc2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backticks
 version: !ruby/object:Gem::Version
-  version: 1.0.0rc1
+  version: 1.0.0rc2
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-07-29 00:00:00.000000000 Z
+date: 2016-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -62,6 +62,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - README.md