backticks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4c09ea76ce613d4920ab0f2f0102fa56eb0ddc86
+  data.tar.gz: 013d631b062d46df861787bf64107cf802fe4580
+SHA512:
+  metadata.gz: 4d05727a43ef3634d734eef36990cf8915072da01ccca1e57993a58b83fc5af2d638366e3d3c9fbe123d7aa99b0e03a9239a79cc178589cb1b0c6d411fab7421
+  data.tar.gz: 60dba8be758e0ca850c573882ce14ed3da1200f9a6cb62020b2a9b92e2590b7acb396fd6b2914572b5337d7c9b92c559aa2f429158e203beff3c682ff6e80abf

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in backticks.gemspec
+gemspec

data/README.md

@@ -0,0 +1,63 @@
+# Backticks
+
+Backticks is an intuitive OOP wrapper for invoking command-line processes and
+interacting with them. It uses PTYs
+
+By default, processes that you invoke
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'backticks'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install backticks
+
+## Usage
+
+```ruby
+require 'backticks'
+
+# The easy way
+output = Backticks.command('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.
+command = Backticks::Runner.new(interactive:true).command('ls', R:true, '*.rb')
+command.join
+puts "Exit status: #{command.status.to_i}. Output:"
+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.
+
+To use pipes for all io streams, enable buffering when you construct your
+Runner:
+
+```ruby
+Backticks::Runner.new(buffered:true)
+```
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/xeger/backticks. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/backticks.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'backticks/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "backticks"
+  spec.version       = Backticks::VERSION
+  spec.authors       = ["Tony Spataro"]
+  spec.email         = ["xeger@xeger.net"]
+
+  spec.summary       = %q{Intuitive OOP wrapper for command-line processes}
+  spec.description   = %q{Captures processes' stdout, stderr and (optionally) stdin; uses PTY to avoid buffering.}
+  spec.homepage      = "https://github.com/xeger/backticks"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "backticks"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/backticks.rb

@@ -0,0 +1,22 @@
+require "backticks/version"
+require "backticks/cli"
+require "backticks/command"
+require "backticks/runner"
+
+module Backticks
+  # Run a command.
+  #
+  # @return [Backticks::Command] a running command
+  def self.new(*argv)
+    Backticks::Runner.new.command(*argv)
+  end
+
+  # Run a command and return its stdout.
+  #
+  # @return [String] the command's output
+  def self.command(*argv)
+    command = self.new(*argv)
+    command.join
+    command.captured_output
+  end
+end

data/lib/backticks/cli.rb

@@ -0,0 +1,107 @@
+module Backticks
+  module CLI
+    # Command-line parameter generator that relies on traditional *nix getopt
+    # conventions. Getopt doesn't know about GNU conventions such as short and
+    # long options; it doesn't know about abbreviations; it doesn't know about
+    # conventions such as `--X` vs. `--no-X` or `-d` vs. `-D`.
+    #
+    # Although Getopt is simple, it has the tremendous advantage of being
+    # compatible with a wide range of other schemes including GNU getopt-long,
+    # 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.
+      #
+      # 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
+      #
+      # @return [Array] list of String words and options
+      #
+      # @example recursively find all text files
+      #   parameters('ls', l:true, R:true, '*.txt') => 'ls -l -R *.txt
+      #
+      # @example install your favorite gem
+      #   parameters('gem', 'install', no_document:true, 'backticks')
+      def self.parameters(*cmd)
+        argv = []
+
+        cmd.each do |item|
+          case item
+          when Array
+            # list of words to append to argv
+            argv.concat(item.map { |e| e.to_s })
+          when Hash
+            # list of options to convert to CLI parameters
+            argv.concat(options(item))
+          else
+            # single word to append to argv
+            argv << item.to_s
+          end
+        end
+
+        argv
+      end
+
+      # Translate Ruby method parameters 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
+      #   - Ruby trollop gem
+      #   - Golang flags package
+      #
+      # This method accepts an unbounded set of keyword arguments (i.e. you can
+      # pass it _any_ valid Ruby symbol as a kwarg). Each kwarg has a
+      # value; the key/value pair is translated into a CLI option using the
+      # following heuristic:
+      #   1) Snake-case keys are hyphenated, e.g. :no_foo => "--no-foo"
+      #   2) boolean values indicate a CLI flag; true includes the flag, false or nil omits it
+      #   3) all other values indicate a CLI option that has a value.
+      #   4) single character keys are passed as short options; {X: V} becomes "-X V"
+      #   5) multi-character keys are passed as long options; {Xxx: V} becomes "--XXX=V"
+      #
+      # The generic translator doesn't know about short vs. long option names,
+      # abbreviations, or the GNU "X vs. no-X" convention, so it does not
+      # produce the most idiomatic or compact command line for a given program;
+      # its output is, however, almost always valid for utilities that use
+      # Unix-like parameters.
+      #
+      # @return [Array] list of String command-line options
+      def self.options(**opts)
+        flags = []
+
+        # Transform opts into golang flags-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
+          else
+            kw = kw.to_s.gsub('_','-')
+            if arg == true
+              # true: boolean flag
+              flags << "--#{kw}"
+            elsif arg
+              # truthey: option that has a value
+              flags << "--#{kw}=#{arg}"
+            else
+              # falsey: omit boolean flag
+            end
+          end
+        end
+
+        flags
+      end
+    end
+  end
+end

data/lib/backticks/command.rb

@@ -0,0 +1,124 @@
+module Backticks
+  # Represents a running process; provides mechanisms for capturing the process's
+  # output, passing input, waiting for the process to end, and learning its
+  # exitstatus.
+  #
+  # 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
+
+    # Number of bytes to read from the command in one "chunk".
+    CHUNK = 1_024
+
+    # @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, :status
+
+    # Watch a running command.
+    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
+
+    # 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.
+    #
+    # @param [Float,Integer] limit number of seconds to wait before returning
+    def join(limit=nil)
+      if limit
+        tf = Time.now + limit
+      else
+        tf = FOREVER
+      end
+
+      until (t = Time.now) >= tf
+        capture(tf - t)
+        res = Process.waitpid(@pid, Process::WNOHANG)
+        if res
+          @status = $?
+          return self
+        end
+      end
+
+      return nil
+    end
+
+    # Block until one of the following happens:
+    #  - 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)
+    #
+    # 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
+
+      if limit
+        tf = Time.now + limit
+      else
+        tf = FOREVER
+      end
+
+      ready, _, _ = IO.select(streams, [], [], 1)
+
+      # proxy STDIN to child's stdin
+      if ready && ready.include?(STDIN)
+        input = STDIN.readpartial(CHUNK) rescue nil
+        @captured_input << input
+        if input
+          @stdin.write(input)
+        else
+          # our own STDIN got closed; proxy this fact to the child
+          @stdin.close
+        end
+      end
+
+      # capture child's stdout and maybe proxy to STDOUT
+      if ready && ready.include?(@stdout)
+        data = @stdout.readpartial(CHUNK) rescue nil
+        if data
+          @captured_output << data
+          STDOUT.write(data) if @interactive
+          fresh_output = data
+        end
+      end
+
+      # capture child's stderr and maybe proxy to STDERR
+      if ready && ready.include?(@stderr)
+        data = @stderr.readpartial(CHUNK) rescue nil
+        if data
+          @captured_error << data
+          STDERR.write(data) if @interactive
+        end
+      end
+      fresh_output
+    rescue Interrupt
+      # Proxy Ctrl+C to the child
+      (Process.kill('INT', @pid) rescue nil) if @interactive
+      raise
+    end
+  end
+end

data/lib/backticks/runner.rb

@@ -0,0 +1,93 @@
+require 'pty'
+
+module Backticks
+  # An easy-to-use interface for invoking commands and capturing their output.
+  # Instances of Runner can be interactive, which prints the command's output
+  # to the terminal and also allows the user to interact with the command.
+  # They can also be unbuffered, which uses a pseudo-tty to capture the
+  # command's output with no delay or
+  class Runner
+    # If true, commands will have their stdio streams tied to the parent
+    # 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!
+    #
+    # @return [Boolean]
+    attr_accessor :interactive
+
+    # If true, commands will be invoked with a pseudo-TTY for stdout in order
+    # to capture output as it is generated instead of waiting for pipe buffers
+    # to fill.
+    #
+    # @return [Boolean]
+    attr_accessor :buffered
+
+    # Create an instance of Runner.
+    # @param [#parameters] cli object ysed to convert Ruby method parameters into command-line parameters
+    def initialize(cli:Backticks::CLI::Getopt)
+      @interactive = false
+      @buffered = false
+      @cli = cli
+    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
+    # objects are appended to argv as "bare" words; Hashes are translated to
+    # command-line options and then appended to argv.
+    #
+    # The
+    #
+    # @return [Command] the running command
+    #
+    # @example Run docker-compose with complex parameters
+    #   command('docker-compose', {file: 'joe.yml'}, 'up', {d:true}, 'mysvc')
+    #
+    # @see #options for information on Hash-to-flag translation
+    def command(*cmd)
+      argv = @cli.parameters(*cmd)
+
+      if self.buffered
+        run_buffered(argv)
+      else
+        run_unbuffered(argv)
+      end
+    end
+
+    # 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)
+      stdout, stdout_w = PTY.open
+      stdin_r, stdin = IO.pipe
+      stderr, stderr_w = IO.pipe
+      pid = spawn(*argv, in: stdin_r, out: stdout_w, err: stderr_w)
+      stdin_r.close
+      stdout_w.close
+      stderr_w.close
+
+      Command.new(pid, stdin, stdout, stderr, interactive:@interactive)
+    end
+
+    # Run a command. Perform no translation or substitution. Use a pipe
+    # to read the output, which may be buffered by the OS. Return the program's
+    # exit status and stdout.
+    #
+    # @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)
+      stdin, stdout, stderr, thr = Open3.popen3(*argv)
+
+      Command.new(thr.pid, stdin, stdout, stderr, interactive:@interactive)
+    end
+  end
+end

data/lib/backticks/version.rb

@@ -0,0 +1,3 @@
+module Backticks
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: backticks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tony Spataro
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-12-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Captures processes' stdout, stderr and (optionally) stdin; uses PTY to
+  avoid buffering.
+email:
+- xeger@xeger.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- README.md
+- Rakefile
+- backticks.gemspec
+- bin/console
+- bin/setup
+- lib/backticks.rb
+- lib/backticks/cli.rb
+- lib/backticks/command.rb
+- lib/backticks/runner.rb
+- lib/backticks/version.rb
+homepage: https://github.com/xeger/backticks
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Intuitive OOP wrapper for command-line processes
+test_files: []