backticks 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b5b80eef1129c850eb5fc8ffb3dc816dcd7853d2
-  data.tar.gz: e49b51b178cf49bdcb0c73dc0e77f44a0a1951cc
+  metadata.gz: 8093e055335a1040855c560d8c94d9fb7a5cecd1
+  data.tar.gz: 2145905dfafbc820072d832f789b65d7c99b5638
 SHA512:
-  metadata.gz: 3e267a2020567274d2335bc848421de16736cd9aa370d103b5c561474f9a85a8851909cda40f114b298d59ad583336f66e3caf017e29c63f7711f53b56a82a14
-  data.tar.gz: 728b478ae95cc2676fbf64c22809f4815e11a3b0b50031c7fb002eda006893309f56cb8201e4079e2046c806580f43bd43defc95723ce7834f81620a62e8e289
+  metadata.gz: fc987a7287c7662a5d9207eeebf429b74ead2b15c7ebaccfab73763ba73650b4197ef81cfc3654472bbf1bf818d56168b2e6d22994432502dd8defea1e75f1e8
+  data.tar.gz: d1aa0d1ae781ebed53753562d6c1799e091d7a91fad42f442a8c589efab60501af35618e9052a9bf86513b65f60b4691b5f3fc4c2a19f8991b3c4862b9d1f79c

data/README.md

@@ -1,9 +1,28 @@
 # Backticks
 
 Backticks is an intuitive OOP wrapper for invoking command-line processes and
-interacting with them. It uses PTYs
+interacting with them. It improves on Ruby's built-in invocation methods in a
+few ways:
+  - Uses [pseudoterminals](https://en.wikipedia.org/wiki/Pseudoterminal) for unbuffered I/O
+  - Captures input as well as output
+  - Intuitive API that accepts CLI parameters as Ruby positional and keyword args
 
-By default, processes that you invoke
+If you want to write a record/playback application for the terminal, or write
+functional tests that verify your program's output in real time, Backticks is
+exactly what you've been looking for!
+
+For an example of the intuitive API, let's consider how we list a bunch of
+files or search for some text with Backticks:
+
+```ruby
+# invokes "ls -l -R"
+Backticks.run 'ls', l:true, R:true
+
+# invokes "grep -H --context=2 --regexp=needle haystack.txt"
+Backticks.run 'grep', {H:true, context:2, regexp:'needle'}, 'haystack.txt'
+```
+
+Notice how running commands feels like a plain old Ruby method call.
 
 ## Installation
 
@@ -26,22 +45,23 @@ Or install it yourself as:
 ```ruby
 require 'backticks'
 
-# The lazy way; provides no CLI sugar, but benefits from unbuffered output.
-# Many Unix utilities produce colorized output when stdout is a TTY; be
-# prepared to handle escape codes in the output.
+# The lazy way; provides no CLI sugar, but benefits from unbuffered output,
+# and allows you to override Ruby's built-in backticks method.
 shell = Object.new ; shell.extend(Backticks::Ext)
 shell.instance_eval do
   puts `ls -l`
   raise 'Oh no!' unless $?.success?
 end
+# The just-as-lazy but less-magical way.
+Backticks.system('ls -l') || raise('Oh no!')
 
-# The easy way.
-output = Backticks.command('ls', R:true, '*.rb')
+# The easy way. Uses default options; returns the command's output as a String.
+output = Backticks.run('ls', R:true, '*.rb')
 puts "Exit status #{$?.to_i}. Output:"
 puts output
 
-# The hard way; allows customization such as interactive mode, which proxies
-# the child process's stdin, stdout and stderr to the parent process.
+# The hard way. Allows customized behavior; returns a Command object that
+# allows you to interact with the running command.
 command = Backticks::Runner.new(interactive:true).command('ls', R:true, '*.rb')
 command.join
 puts "Exit status: #{command.status.to_i}. Output:"
@@ -50,17 +70,48 @@ puts command.captured_output
 
 ### Buffering
 
-By default, Backticks allocates a pseudo-TTY for stdout and two Unix pipes for
-stderr/stdin; this captures stdout in real-time, but stderr and
-stdin are subject to unavoidable Unix pipe buffering.
+By default, Backticks allocates a pseudo-TTY for stdin/stdout and a Unix pipe
+for stderr; this captures the program's output and the user's input in realtime,
+but stderr is buffered according to the whim of the kernel's pipe subsystem.
+
+To use pipes for all I/O streams, enable buffering on the Runner:
+
+```ruby
+# at initialize-time
+r = Backticks::Runner.new(buffered:true)
+
+# or later on
+r.buffered = false
+```
+
+### Interactivity
+
+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
+with the child process even as its input and output are captured for later use.
+
+If the child process will use raw input, you need to set the parent's console
+accordingly:
+
+```ruby
+require 'io/console'
+# In IRB, call raw! on same line as command; IRB prompt uses raw I/O
+STDOUT.raw! ; Backticks::Runner.new(interactive:true).command('vi').join
+```
+
+### Literally Overriding Ruby's Backticks
 
-To use pipes for all io streams, enable buffering when you construct your
-Runner:
+It's a terrible idea, but you can use this gem to change the behavior of
+backticks system-wide by mixing it into Kernel.
 
 ```ruby
-Backticks::Runner.new(buffered:true)
+require 'backticks'
+include Backticks::Ext
+`echo Ruby lets me shoot myself in the foot`
 ```
 
+If you do this, I will hunt you down and scoff at you. You have been warned!
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/backticks.rb

@@ -5,19 +5,32 @@ require_relative 'backticks/runner'
 require_relative 'backticks/ext'
 
 module Backticks
-  # Run a command.
+  # Run a command; return a Command object that can be used to interact with
+  # the running process. Method parameters are passed through to the Runner.
   #
+  # @see Backticks::Runner#command
   # @return [Backticks::Command] a running command
-  def self.new(*argv)
-    Backticks::Runner.new.command(*argv)
+  def self.new(*cmd)
+    Backticks::Runner.new.command(*cmd)
   end
 
-  # Run a command and return its stdout.
+  # Run a command; return its stdout.
   #
+  # @param [String] cmd
   # @return [String] the command's output
-  def self.command(*argv)
-    command = self.new(*argv)
+  def self.run(*cmd)
+    command = self.new(*cmd)
     command.join
     command.captured_output
   end
+
+  # Run a command; return its success or failure.
+  #
+  # @param [String] cmd
+  # @return [Boolean] true if the command succeeded; false otherwise
+  def self.system(*cmd)
+    command = self.new(*cmd)
+    command.join
+    $?.success?
+  end
 end

data/lib/backticks/cli.rb

@@ -73,27 +73,35 @@ module Backticks
       def self.options(**opts)
         flags = []
 
-        # Transform opts into golang flags-style command line parameters;
+        # Transform opts into getopt-style command line parameters;
         # append them to the command.
         opts.each do |kw, arg|
           if kw.length == 1
-            if arg == true
-              # true: boolean flag
-              flags << "-#{kw}"
-            elsif arg
-              # truthey: option that has a value
-              flags << "-#{kw}" << arg.to_s
-            else
-              # falsey: omit boolean flag
-            end
+            # short-form option e.g. "-a" or "-x hello"
+            pre='-'
+            eql=' '
           else
+            # long-form option e.g. "--ask" or "--extra=hello"
             kw = kw.to_s.gsub('_','-')
+            pre='--'
+            eql='='
+          end
+
+          # options can be single- or multi-valued; normalize the processing
+          # of both by "upconverting" single options to an array or values.
+          if arg.kind_of?(Array)
+            values = arg
+          else
+            values = [arg]
+          end
+
+          values.each do |arg|
             if arg == true
               # true: boolean flag
-              flags << "--#{kw}"
+              flags << "#{pre}#{kw}"
             elsif arg
               # truthey: option that has a value
-              flags << "--#{kw}=#{arg}"
+              flags << "#{pre}#{kw}#{eql}#{arg}"
             else
               # falsey: omit boolean flag
             end

data/lib/backticks/command.rb

@@ -24,20 +24,21 @@ module Backticks
     attr_reader :captured_input, :captured_output, :captured_error, :status
 
     # Watch a running command.
-    def initialize(pid, stdin, stdout, stderr, interactive:false)
+    def initialize(pid, stdin, stdout, stderr)
       @pid = pid
       @stdin = stdin
       @stdout = stdout
       @stderr = stderr
-      @interactive = interactive
-
-      stdin.close unless @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
 
+    def interactive?
+      !@stdin.nil?
+    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`;
@@ -45,6 +46,8 @@ module Backticks
     #
     # @param [Float,Integer] limit number of seconds to wait before returning
     def join(limit=nil)
+      return self if @status # preserve idempotency
+
       if limit
         tf = Time.now + limit
       else
@@ -76,7 +79,7 @@ module Backticks
     # @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
+      streams << STDIN if interactive?
 
       if limit
         tf = Time.now + limit
@@ -103,7 +106,7 @@ module Backticks
         data = @stdout.readpartial(CHUNK) rescue nil
         if data
           @captured_output << data
-          STDOUT.write(data) if @interactive
+          STDOUT.write(data) if interactive?
           fresh_output = data
         end
       end
@@ -113,14 +116,17 @@ module Backticks
         data = @stderr.readpartial(CHUNK) rescue nil
         if data
           @captured_error << data
-          STDERR.write(data) if @interactive
+          STDERR.write(data) if interactive?
+          fresh_error = data
         end
       end
-      fresh_output
+
+      # return freshly-captured text(if any)
+      fresh_output || fresh_error
     rescue Interrupt
       # Proxy Ctrl+C to the child
       (Process.kill('INT', @pid) rescue nil) if @interactive
       raise
     end
   end
-end
+end

data/lib/backticks/ext.rb

@@ -1,7 +1,7 @@
 module Backticks
   module Ext
-    def `(str)
-      Backticks.command(str)
+    def `(cmd)
+      Backticks.run(cmd)
     end
   end
-end
+end

data/lib/backticks/runner.rb

@@ -33,10 +33,10 @@ module Backticks
 
     # Create an instance of Runner.
     # @param [#parameters] cli object used to convert Ruby method parameters into command-line parameters
-    def initialize(cli:Backticks::CLI::Getopt)
-      @interactive = false
-      @buffered = false
+    def initialize(buffered:false, cli:Backticks::CLI::Getopt, interactive:false)
+      @buffered = buffered
       @cli = cli
+      @interactive = interactive
     end
 
     # Run a command whose parameters are expressed using some Rubyish sugar.
@@ -56,9 +56,8 @@ module Backticks
     #
     # @example Run docker-compose with complex parameters
     #   command('docker-compose', {file: 'joe.yml'}, 'up', {d:true}, 'mysvc')
-    def command(*args)
+    def run(*args)
       argv = @cli.parameters(*args)
-
       if self.buffered
         run_buffered(argv)
       else
@@ -66,6 +65,8 @@ module Backticks
       end
     end
 
+    alias command run
+
     # Run a command. Use a pty to capture the unbuffered output.
     #
     # @param [Array] argv command to run; argv[0] is program name and the
@@ -73,14 +74,18 @@ module Backticks
     # @return [Command] the running command
     private def run_unbuffered(argv)
       stdout, stdout_w = PTY.open
-      stdin_r, stdin = IO.pipe
-      stderr, stderr_w = IO.pipe
+      stdin_r, stdin = PTY.open
+      stderr, stderr_w = PTY.open
       pid = spawn(*argv, in: stdin_r, out: stdout_w, err: stderr_w)
       stdin_r.close
       stdout_w.close
       stderr_w.close
+      unless @interactive
+        stdin.close
+        stdin = nil
+      end
 
-      Command.new(pid, stdin, stdout, stderr, interactive:@interactive)
+      Command.new(pid, stdin, stdout, stderr)
     end
 
     # Run a command. Perform no translation or substitution. Use a pipe
@@ -92,8 +97,12 @@ module Backticks
     # @return [Command] the running command
     private def run_buffered(argv)
       stdin, stdout, stderr, thr = Open3.popen3(*argv)
+      unless @interactive
+        stdin.close
+        stdin = nil
+      end
 
-      Command.new(thr.pid, stdin, stdout, stderr, interactive:@interactive)
+      Command.new(thr.pid, stdin, stdout, stderr)
     end
   end
-end
+end

data/lib/backticks/version.rb

@@ -1,3 +1,3 @@
 module Backticks
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backticks
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-24 00:00:00.000000000 Z
+date: 2016-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler