backticks 0.5.0 → 1.0.0rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8199c03291828b81d31df59a9e3341d20b13b27a
-  data.tar.gz: 5a4058b1ada73100e623660cf0c201f1aba3accb
+  metadata.gz: a446a43c0be0d08f7ad35f3f9a2fa7791f66229d
+  data.tar.gz: 2fc8f0e3176dae7628cb08225c63f95d97002e8f
 SHA512:
-  metadata.gz: 943ceaf445259b9c4fc67e94652fa5be8d613496abf198578842b81a97d5bb782d371bc5ac1b519c8143850fce1290a7f8e1245989c1a3cc71c76c4da237c279
-  data.tar.gz: 2c6ac11905c9a76836acb555d8819f74947fbf90fa42a0104bdb8823b2b3dff36d44bda9df56206cd9676ced6d5df65a24b201d1aa2d23295968e8d62b8f9c43
+  metadata.gz: 96d973bd4ef27a7bfcfecf7f8cb9e7ea0de2bb05f758aa42fb49c5438ba372230c5a77d07737da4e9492c0109533992ca9f1ad9ccf779fe442e7907d8bd5a7b7
+  data.tar.gz: 378d42242e3efbc5817c89266a34e620ca59ddfe6fc92411b56671fe5aa7104088a5f934235f8b1f9dbcb66c589ef71f8c1c1904f5a755074392317817c59172

data/README.md

@@ -81,9 +81,16 @@ r = Backticks::Runner.new(buffered:true)
 
 # or later on
 r.buffered = false
+
+# you can also specify invididual stream names to buffer
+r.buffered = [:stderr]
 ```
 
-### Interactivity
+When you read the `buffered` attribute of a Runner, it returns the list of
+stream names that are buffered; this means that even if you _write_ a boolean
+to this attribute, you will _read_ an Array of Symbol.
+
+### Interactivity and Real-Time Capture
 
 If you set `interactive:true` on the Runner, the console of the calling (Ruby)
 process is "tied" to the child's I/O streams, allowing the user to interact
@@ -98,6 +105,26 @@ require 'io/console'
 STDOUT.raw! ; Backticks::Runner.new(interactive:true).run('vi').join
 ```
 
+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,
+:stdout, :stderr) and a String with binary encoding that contains fresh
+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.
+
+Try loading the README in an editor with all of the vowels scrambled. Scroll
+around and notice how words change when they leave and enter the screen!
+
+```ruby
+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
+```
+
 ### Literally Overriding Ruby's Backticks
 
 It's a terrible idea, but you can use this gem to change the behavior of

data/lib/backticks/command.rb

@@ -20,12 +20,18 @@ module Backticks
     # @return [Integer] child process ID
     attr_reader :pid
 
-    # @return [String] all data captured (so far) from child's stdin/stdout/stderr
-    attr_reader :captured_input, :captured_output, :captured_error
-
     # @return [nil,Process::Status] result of command if it has ended; nil if still running
     attr_reader :status
 
+    # @return [String] all input that has been captured so far
+    attr_reader :captured_input
+
+    # @return [String] all output that has been captured so far
+    attr_reader :captured_output
+
+    # @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)
       @pid = pid
@@ -38,10 +44,23 @@ module Backticks
       @captured_error  = String.new.force_encoding(Encoding::BINARY)
     end
 
+    # @return [String]
+    def to_s
+      "#<Backticks::Command(@pid=#{pid},@status=#{@status || 'nil'})>"
+    end
+
     def interactive?
       !@stdin.nil?
     end
 
+    # Provide a callback to monitor input and output in real time.
+    # @yield
+    # @yieldparam
+    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`;
@@ -73,14 +92,13 @@ module Backticks
     #  - the command produces fresh output on stdout or stderr
     #  - the user passes some input to the command (if interactive)
     #  - the process exits
-    #  - the time limit elapses (if provided)
+    #  - the time limit elapses (if provided) OR 60 seconds pass
     #
     # Return up to CHUNK bytes of fresh output from the process, or return nil
     # if no fresh output was produced
     #
     # @param [Float,Integer] number of seconds to wait before returning nil
     # @return [String,nil] fresh bytes from stdout/stderr, or nil if no output
-    private
     def capture(limit=nil)
       streams = [@stdout, @stderr]
       streams << STDIN if interactive?
@@ -91,15 +109,19 @@ module Backticks
         tf = FOREVER
       end
 
-      ready, _, _ = IO.select(streams, [], [], 1)
+      ready, _, _ = IO.select(streams, [], [], 0)
 
       # proxy STDIN to child's stdin
       if ready && ready.include?(STDIN)
-        input = STDIN.readpartial(CHUNK) rescue nil
-        if input
-          @captured_input << input
-          @stdin.write(input)
+        data = STDIN.readpartial(CHUNK) rescue nil
+        if data
+          data = @tap.call(:stdin, data) if @tap
+          if data
+            @captured_input << data
+            @stdin.write(data)
+          end
         else
+          @tap.call(:stdin, nil) if @tap
           # our own STDIN got closed; proxy this fact to the child
           @stdin.close unless @stdin.closed?
         end
@@ -109,9 +131,12 @@ module Backticks
       if ready && ready.include?(@stdout)
         data = @stdout.readpartial(CHUNK) rescue nil
         if data
-          @captured_output << data
-          STDOUT.write(data) if interactive?
-          fresh_output = data
+          data = @tap.call(:stdout, data) if @tap
+          if data
+            @captured_output << data
+            STDOUT.write(data) if interactive?
+            fresh_output = data
+          end
         end
       end
 
@@ -119,8 +144,11 @@ module Backticks
       if ready && ready.include?(@stderr)
         data = @stderr.readpartial(CHUNK) rescue nil
         if data
-          @captured_error << data
-          STDERR.write(data) if interactive?
+          data = @tap.call(:stderr, data) if @tap
+          if data
+            @captured_error << data
+            STDERR.write(data) if interactive?
+          end
         end
       end
       fresh_output

data/lib/backticks/runner.rb

@@ -15,12 +15,8 @@ module Backticks
     # process so the user can view their output and send input to them.
     # Commands' output is still captured normally when they are interactive.
     #
-    # Note that interactivity doesn't work very well with unbuffered commands;
-    # we use pipes to connect to the command's stdio, and the OS forcibly
-    # buffers pipe I/O. If you want to send some input to your command, you
-    # may need to send a LOT of input before it receives any; the same problem
-    # applies to reading your command's output. If you set interactive to
-    # true, you usually want to set buffered to false!
+    # Note: if you set `interactive` to true, then stdin and stdout will be
+    # unbuffered regardless of how you have set `buffered`!
     #
     # @return [Boolean]
     attr_accessor :interactive
@@ -29,7 +25,10 @@ module Backticks
     # a pseudoterminal.
     #
     # This may be a Boolean, or it may be an Array of stream names from the
-    # set [:stdin, stdout, stderr].
+    # set [:stdin, :stdout, :stderr].
+    #
+    # Note: if you set `interactive` to true, then stdin and stdout will be
+    # unbuffered regardless of how you have set `buffered`!
     #
     # @return [Array] list of symbolic stream names
     attr_reader :buffered
@@ -66,12 +65,6 @@ module Backticks
       end
     end
 
-    # @deprecated
-    def command(*sugar)
-      warn 'Backticks::Runner#command is deprecated; please call #run instead'
-      run(*sugar)
-    end
-
     # Run a command whose parameters are expressed using some Rubyish sugar.
     # This method accepts an arbitrary number of positional parameters; each
     # parameter can be a Hash, an array, or a simple Object. Arrays and simple

data/lib/backticks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backticks
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0rc1
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-18 00:00:00.000000000 Z
+date: 2016-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -90,9 +90,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.4.5