backticks 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b155f73a14fe3ee0afa0d26a7e72187cca00a7b3
-  data.tar.gz: 403f3296c832847f3ba8cde407f7bf2e75ba7a29
+  metadata.gz: 156e6dd6cd59ca1201a48b9679e1f6151caf6b43
+  data.tar.gz: 225c905201c500af8cde4a7561490befaf797caa
 SHA512:
-  metadata.gz: ae13cb81eabdee1ae6e8ee49688aa9224bb3764c3376e759bf71ff5b184a2de2dc5e4bb9752caf6457be5c0cb82d1bcec18c6b28972da09d26c087246f730faf
-  data.tar.gz: bb8367fb27bf005dd592b6eaaff7532ae3e9663423007c640d1b01c288367af6f0c3b102e488de4f3fa8c145da9e954ac855456cf67dfa2ac2ec9c9887cd3793
+  metadata.gz: b7230c03f69e71a6aeadb1cd0f3d43f0a12ad166231d0aecaea8c9c41bf8373e3cb5e3fbdfaf8ddb08be35c4e0632404edafb4b9de36e55213e6166f19134a1d
+  data.tar.gz: bb4bfa7199f80179fba4147379667b9e4e80ad2b8d3208e4d072953aaffbc2d42e4c1c8f52ce46059bec9c0b978600c3661b0650c23f2b7330da1fac7d9ddd8f

data/.rspec

@@ -1,2 +1,4 @@
 --format documentation
 --color
+--order random
+--require spec_helper

data/.travis.yml

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

data/Gemfile

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

data/README.md

@@ -3,6 +3,8 @@
 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
@@ -59,7 +61,7 @@ puts output
 
 # 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 = Backticks::Runner.new(interactive:true).run('ls', R:true, '*.rb')
 command.join
 puts "Exit status: #{command.status.to_i}. Output:"
 puts command.captured_output
@@ -93,7 +95,7 @@ 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
+STDOUT.raw! ; Backticks::Runner.new(interactive:true).run('vi').join
 ```
 
 ### Literally Overriding Ruby's Backticks

data/backticks.gemspec

@@ -19,6 +19,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.required_ruby_version = Gem::Requirement.new("~> 2.0")
+
   spec.add_development_dependency 'bundler', '~> 1.10'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec'

data/lib/backticks.rb

@@ -5,31 +5,38 @@ require_relative 'backticks/runner'
 require_relative 'backticks/ext'
 
 module Backticks
-  # Run a command; return a Command object that can be used to interact with
-  # the running process.
+  # Run a command with default invocation options; return a Command object that
+  # can be used to interact with the running process.
   #
-  # @param [String] cmd
+  # @param [Array] sugar list of command words and options
   # @return [Backticks::Command] a running command
-  def self.new(cmd)
-    Backticks::Runner.new.command(cmd)
+  # @see Backticks::Runner#run for a better description of sugar
+  # @see Backticks::Runner for more control over process invocation
+  def self.new(*sugar)
+    Backticks::Runner.new.run(*sugar)
   end
 
-  # Run a command; return its stdout.
+  # Run a command with default invocation options; wait for to exit, then return
+  # its output. Populate $? with the command's status before returning.
   #
-  # @param [String] cmd
+  # @param [Array] sugar list of command words and options
   # @return [String] the command's output
-  def self.run(cmd)
-    command = self.new(*cmd)
+  # @see Backticks::Runner#run for a better description of sugar
+  # @see Backticks::Runner for more control over process invocation
+  def self.run(*sugar)
+    command = self.new(*sugar)
     command.join
     command.captured_output
   end
 
-  # Run a command; return its success or failure.
+  # Run a command; return whether it succeeded or failed.
   #
-  # @param [String] cmd
+  # @param [Array] sugar list of command words and options
   # @return [Boolean] true if the command succeeded; false otherwise
-  def self.system(*cmd)
-    command = self.new(*cmd)
+  # @see Backticks::Runner#run for a better description of sugar
+  # @see Backticks::Runner for more control over process invocation
+  def self.system(*sugar)
+    command = self.new(*sugar)
     command.join
     $?.success?
   end

data/lib/backticks/cli.rb

@@ -10,14 +10,14 @@ module Backticks
     # golang flags, and most Java utilities. It's a great choice of default
     # CLI.
     module Getopt
-      # Translate a series of positional and keyword arguments into command-line
-      # line parameters consisting of words and options.
+      # Translate a series Ruby positional and keyword arguments into command-
+      # parameters consisting of words and options.
       #
       # Each positional argument can be a Hash, an Array, or another object.
       # They are handled as follows:
       #  - Hash is translated to a sequence of options; see #options
       #  - Array is appended to the command line as a sequence of words
-      #  - other objects are turned into a strong with #to_s and appended to the command line as a single word
+      #  - other objects are turned into a string with #to_s and appended to the command line as a single word
       #
       # @return [Array] list of String words and options
       #
@@ -26,10 +26,10 @@ module Backticks
       #
       # @example install your favorite gem
       #   parameters('gem', 'install', no_document:true, 'backticks')
-      def self.parameters(*cmd)
+      def self.parameters(*sugar)
         argv = []
 
-        cmd.each do |item|
+        sugar.each do |item|
           case item
           when Array
             # list of words to append to argv
@@ -46,7 +46,7 @@ module Backticks
         argv
       end
 
-      # Translate Ruby method parameters into command-line parameters using a
+      # Translate Ruby keyword arguments into command-line parameters using a
       # notation that is compatible with traditional Unix getopt. Command lines
       # generated by this method are also mostly compatible with the following:
       #   - GNU getopt
@@ -70,12 +70,12 @@ module Backticks
       # Unix-like parameters.
       #
       # @return [Array] list of String command-line options
-      def self.options(**opts)
+      def self.options(kwargs={})
         flags = []
 
         # Transform opts into golang flags-style command line parameters;
         # append them to the command.
-        opts.each do |kw, arg|
+        kwargs.each do |kw, arg|
           if kw.length == 1
             if arg == true
               # true: boolean flag
@@ -104,4 +104,4 @@ module Backticks
       end
     end
   end
-end
+end

data/lib/backticks/command.rb

@@ -46,6 +46,8 @@ module Backticks
     #
     # @param [Float,Integer] limit number of seconds to wait before returning
     def join(limit=nil)
+      return self if @status
+
       if limit
         tf = Time.now + limit
       else

data/lib/backticks/runner.rb

@@ -33,10 +33,22 @@ module Backticks
 
     # Create an instance of Runner.
     # @param [#parameters] cli object used to convert Ruby method parameters into command-line parameters
-    def initialize(buffered:false, cli:Backticks::CLI::Getopt, interactive:false)
-      @buffered = buffered
-      @cli = cli
-      @interactive = interactive
+    def initialize(options={})
+      options = {
+        :buffered => false,
+        :cli => Backticks::CLI::Getopt,
+        :interactive => false,
+      }.merge(options)
+
+      @buffered = options[:buffered]
+      @cli = options[:cli]
+      @interactive = options[:interactive]
+    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.
@@ -50,15 +62,23 @@ module Backticks
     #
     # @see Backticks::CLI::Getopt for option-Hash format information
     #
-    # @param [Array] args list of command words and options
+    # @param [Array] sugar list of command words and options
     #
     # @return [Command] the running command
     #
     # @example Run docker-compose with complex parameters
-    #   command('docker-compose', {file: 'joe.yml'}, 'up', {d:true}, 'mysvc')
-    def command(*args)
-      argv = @cli.parameters(*args)
+    #   run('docker-compose', {file: 'joe.yml'}, 'up', {d:true}, 'mysvc')
+    def run(*sugar)
+      run_without_sugar(@cli.parameters(*sugar))
+    end
 
+    # Run a command whose argv is specified in the same manner as Kernel#exec,
+    # with no Rubyish sugar.
+    #
+    # @param [Array] argv command to run; argv[0] is program name and the
+    #   remaining elements are parameters and flags
+    # @return [Command] the running command
+    def run_without_sugar(argv)
       if self.buffered
         run_buffered(argv)
       else

data/lib/backticks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backticks
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-11 00:00:00.000000000 Z
+date: 2016-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -85,9 +85,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="