backticks 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8093e055335a1040855c560d8c94d9fb7a5cecd1
-  data.tar.gz: 2145905dfafbc820072d832f789b65d7c99b5638
+  metadata.gz: b155f73a14fe3ee0afa0d26a7e72187cca00a7b3
+  data.tar.gz: 403f3296c832847f3ba8cde407f7bf2e75ba7a29
 SHA512:
-  metadata.gz: fc987a7287c7662a5d9207eeebf429b74ead2b15c7ebaccfab73763ba73650b4197ef81cfc3654472bbf1bf818d56168b2e6d22994432502dd8defea1e75f1e8
-  data.tar.gz: d1aa0d1ae781ebed53753562d6c1799e091d7a91fad42f442a8c589efab60501af35618e9052a9bf86513b65f60b4691b5f3fc4c2a19f8991b3c4862b9d1f79c
+  metadata.gz: ae13cb81eabdee1ae6e8ee49688aa9224bb3764c3376e759bf71ff5b184a2de2dc5e4bb9752caf6457be5c0cb82d1bcec18c6b28972da09d26c087246f730faf
+  data.tar.gz: bb8367fb27bf005dd592b6eaaff7532ae3e9663423007c640d1b01c288367af6f0c3b102e488de4f3fa8c145da9e954ac855456cf67dfa2ac2ec9c9887cd3793

data/README.md

@@ -1,28 +1,25 @@
-# Backticks
+# Introduction
 
-Backticks is an intuitive OOP wrapper for invoking command-line processes and
-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
+Backticks is a powerful, intuitive OOP wrapper for invoking command-line processes and
+interacting with them.
 
-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!
+"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
 
-For an example of the intuitive API, let's consider how we list a bunch of
-files or search for some text with Backticks:
+"Intuitive" comes from a DSL that lets you provide command-line arguments as if they were
+Ruby method arguments:
 
-```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'
+```
+Backticks.run 'ls', R:true, ignore_backups:true, hide:'.git'
+Backticks.run 'cp' {f:true}, '*.rb', '/mnt/awesome'
 ```
 
-Notice how running commands feels like a plain old Ruby method call.
+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!
 
 ## Installation
 

data/lib/backticks.rb

@@ -6,19 +6,19 @@ require_relative 'backticks/ext'
 
 module Backticks
   # 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.
+  # the running process.
   #
-  # @see Backticks::Runner#command
+  # @param [String] cmd
   # @return [Backticks::Command] a running command
-  def self.new(*cmd)
-    Backticks::Runner.new.command(*cmd)
+  def self.new(cmd)
+    Backticks::Runner.new.command(cmd)
   end
 
   # Run a command; return its stdout.
   #
   # @param [String] cmd
   # @return [String] the command's output
-  def self.run(*cmd)
+  def self.run(cmd)
     command = self.new(*cmd)
     command.join
     command.captured_output

data/lib/backticks/cli.rb

@@ -73,35 +73,27 @@ module Backticks
       def self.options(**opts)
         flags = []
 
-        # Transform opts into getopt-style command line parameters;
+        # Transform opts into golang flags-style command line parameters;
         # append them to the command.
         opts.each do |kw, arg|
           if kw.length == 1
-            # short-form option e.g. "-a" or "-x hello"
-            pre='-'
-            eql=' '
+            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
           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 << "#{pre}#{kw}"
+              flags << "--#{kw}"
             elsif arg
               # truthey: option that has a value
-              flags << "#{pre}#{kw}#{eql}#{arg}"
+              flags << "--#{kw}=#{arg}"
             else
               # falsey: omit boolean flag
             end

data/lib/backticks/command.rb

@@ -46,8 +46,6 @@ 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
@@ -77,7 +75,8 @@ module Backticks
     #
     # @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)
+    private
+    def capture(limit=nil)
       streams = [@stdout, @stderr]
       streams << STDIN if interactive?
 
@@ -117,12 +116,9 @@ module Backticks
         if data
           @captured_error << data
           STDERR.write(data) if interactive?
-          fresh_error = data
         end
       end
-
-      # return freshly-captured text(if any)
-      fresh_output || fresh_error
+      fresh_output
     rescue Interrupt
       # Proxy Ctrl+C to the child
       (Process.kill('INT', @pid) rescue nil) if @interactive

data/lib/backticks/runner.rb

@@ -56,8 +56,9 @@ module Backticks
     #
     # @example Run docker-compose with complex parameters
     #   command('docker-compose', {file: 'joe.yml'}, 'up', {d:true}, 'mysvc')
-    def run(*args)
+    def command(*args)
       argv = @cli.parameters(*args)
+
       if self.buffered
         run_buffered(argv)
       else
@@ -65,14 +66,13 @@ 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
     #   remaining elements are parameters and flags
     # @return [Command] the running command
-    private def run_unbuffered(argv)
+    private
+    def run_unbuffered(argv)
       stdout, stdout_w = PTY.open
       stdin_r, stdin = PTY.open
       stderr, stderr_w = PTY.open
@@ -95,7 +95,7 @@ module Backticks
     # @param [Array] argv command to run; argv[0] is program name and the
     #   remaining elements are command-line arguments.
     # @return [Command] the running command
-    private def run_buffered(argv)
+    def run_buffered(argv)
       stdin, stdout, stderr, thr = Open3.popen3(*argv)
       unless @interactive
         stdin.close

data/lib/backticks/version.rb

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

metadata

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