repl_runner 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 05eaef051153f7d7b06f9c68c4933a0955d58e6b
+  data.tar.gz: a371ba6c53712e73296da79c69c3f604fa7c841e
+SHA512:
+  metadata.gz: 7d406e33b664960f9af50c4aea6a6ba3ebfbf3d848193f18732aad7c340f6d3e11c9125786b0b70fddcd72b482f57f90e2a432d6d6d7ea63c879b7739bc2a1a2
+  data.tar.gz: ecaee16aaf62250a286ffb4cf1e0deeda8cbecdaabb7d1b8015a537c6f89e1f68fe067ca2df8e6eefa9e72c5115012a2071db34601b149629ced825dc317a7bb

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

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

data/LICENSE

@@ -0,0 +1 @@
+MIT Yo

data/README.md

@@ -0,0 +1,80 @@
+# REPL Runner
+
+Drive irb, bash, or another REPL like environment programatically.
+
+## Why?
+
+I needed to be able to run `rails console` commands programatically for testing buildpacks with [Hatchet](http://github.com/heroku/hatchet).
+
+## How?
+
+Ruby includes the PTY library for creating and running [pseudo terminals](http://en.wikipediaorg/wiki/Pseudo_terminal). Unfortunately opening up a remote `irb` or `rails console` session and driving it without deadlocking your process is fairly maddeningly difficult. This library provides a safe abstraction for running commands and parsing the inputs from the outputs.
+
+## Shouldn't this be Called TerminalRunner?
+
+Well technically it should be called Pseudo Terminal Runner, but ReplRunner just has a certain ring to it.
+
+## Install
+
+In your gemfile add:
+
+```
+gem 'repl_runner'
+```
+
+Then run `$ bundle install`.
+
+## Use
+
+To open a remote rails console on heroku with the heroku toolbelt installed, you could drive it like this:
+
+```
+ReplRunner.new(:rails_console, "heroku run rails console -a testapp").run do |repl|
+  repl.run('a = 1 + 1')         {|result| assert_match '2', result }
+  repl.run('"hello" + "world"') {|result| assert_match 'helloworld', result }
+  repl.run("a * 'foo'")         {|result| assert_match 'foofoo', result}
+end
+```
+
+The first argument `:rails_console` tells ReplReader what type of a session we are going to open up. The second `"heroku run rails console -a testapp"` is the command we want to use to start our psuedo remote terminal.
+
+You can then call `run` on this and pass in a block. The block yields to a `MultiRepl` instance that can take the command `run` along with arguments to pass into the command line such as `'1+1'`
+
+All outputs will be strings. Commands wait for all commands to finish before returning anything, this is why you supply the `run` command with a block. When the command is done the block will be executed and the result of the command passed to it. This helps us parse the results much more effectively. If you need an immediate return, it's possible but I wouldn't recommend it. As a result I've left that functionality out for now.
+
+Also note that you will get the entire return including any prompts if you run an `irb` session locally with `.9.3` you might see a result like this:
+
+```
+$ irb
+1.9.3p392 :001 > 1 + 1
+ => 2
+```
+
+So when you run this via ReplRunner you will get a result string like this
+
+```
+ReplRunner.new(:irb) do |repl|
+  repl.run('1 + 1') {|result| puts result }
+end
+" => 2\r\r\n"
+```
+
+Note: if you don't pass in a second parameter i.e. only pass in `:irb` that exact command will be used to start your session.
+
+## Configure
+
+By default ReplRunner knows how to run `:rails_console`, `:bash`, and `:irb`. You can over-write existing defaults by re-defining them. You can register more custom commands you want like this:
+
+```ruby
+ReplRunner.register_commands(:rails_console, :irb)  do |config|
+  config.terminate_command "exit"          # the command you use to end the 'rails console'
+  config.startup_timeout 60                # seconds to boot
+  config.return_char "\n"                  # the character that submits the command
+  config.sync_stdout "STDOUT.sync = true"  # force REPL to not buffer standard out
+end
+```
+
+## License
+
+MIT (The Georgia Tech of the North) License. Do whatever you want with this code: I'm not liable or responsible for anything.
+

data/Rakefile

@@ -0,0 +1,17 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require 'rake'
+require 'rake/testtask'
+
+task :default => [:test]
+
+test_task = Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+STDOUT.sync = true

data/lib/repl_runner.rb

@@ -0,0 +1,75 @@
+# stdlib
+require 'timeout'
+require 'pty'
+
+# gems
+require 'active_support/core_ext/object/blank'
+
+class ReplRunner
+  attr_accessor :command, :repl
+
+  class NoResults < StandardError
+    def initialize(command, string)
+      msg = "No result found for command: #{command.inspect} in output: #{string.inspect}"
+      super(msg)
+    end
+  end
+
+  class UnregisteredCommand < StandardError
+    def initialize(cmd_type)
+      msg = "Cannot find registered command type: #{cmd_type.inspect}"
+      super(msg)
+    end
+  end
+
+  def initialize(cmd_type, command = nil, options = {})
+    command  = cmd_type.to_s if command.nil?
+    cmd_type = cmd_type.chomp.gsub(/\s/, '_').to_sym if cmd_type.is_a?(String)
+    @command = command
+    @repl    = nil
+    @config  = known_configs[cmd_type]
+    raise UnregisteredCommand.new(cmd_type) unless @config
+    @options = options
+  end
+
+  def known_configs
+    self.class.known_configs
+  end
+
+  class << self
+    def known_configs
+      @known_configs ||= {}
+    end
+
+    def register_command(*commands, &block)
+      config = Config.new(commands)
+      commands.each do |command|
+        known_configs[command] = config
+      end
+      yield config
+    end
+    alias :register_commands :register_command
+  end
+
+  def start
+    @repl = MultiRepl.new(command, @config.to_options.merge(@options))
+  end
+
+  def close
+    repl.close
+  end
+
+  def run(&block)
+    repl = start
+    yield repl
+    repl.execute
+  ensure
+    close if repl
+  end
+end
+
+require 'repl_runner/pty_party'
+require 'repl_runner/multi_command_parser'
+require 'repl_runner/multi_repl'
+require 'repl_runner/config'
+require 'repl_runner/default_config'

data/lib/repl_runner/config.rb

@@ -0,0 +1,34 @@
+class ReplRunner
+  class Config
+    attr_accessor :commands
+
+    def initialize(*commands)
+      @commands = commands
+    end
+
+    def terminate_command(command)
+      @terminate_command = command
+    end
+
+    def startup_timeout(command)
+      @startup_timeout = command
+    end
+
+    def return_char(char)
+      @return_char = char
+    end
+
+    def sync_stdout(string)
+      @sync_stdout = string
+    end
+
+    def to_options
+      {
+        terminate_command:  @terminate_command,
+        startup_timeout:    @startup_timeout,
+        return_char:        @return_char,
+        sync_stdout:        @sync_stdout
+      }
+    end
+  end
+end

data/lib/repl_runner/default_config.rb

@@ -0,0 +1,13 @@
+ReplRunner.register_command(:rails_console, :irb)  do |config|
+  config.terminate_command "exit"          # the command you use to end the 'rails console'
+  config.startup_timeout 60                # seconds to boot
+  config.return_char "\n"                  # the character that submits the command
+  config.sync_stdout "STDOUT.sync = true"  # force REPL to not buffer standard out
+end
+
+ReplRunner.register_command(:bash, :sh)  do |config|
+  config.terminate_command "exit"          # the command you use to end the 'bash' session
+  config.startup_timeout 60                # seconds to boot
+  config.return_char "\n"                  # the character that submits the command
+  config.sync_stdout nil                   # not needed
+end

data/lib/repl_runner/multi_command_parser.rb

@@ -0,0 +1,34 @@
+class ReplRunner
+  class MultiCommandParser
+    attr_accessor :commands, :raw
+
+    def initialize(commands, terminate_command = nil)
+      @commands          = commands
+      @terminate_command = terminate_command
+      @raw               = ""
+    end
+
+    def command_to_regex(command)
+      /#{Regexp.quote(command)}\r*\n+/
+    end
+
+    def parse(string)
+      self.raw    = string.dup
+      @parsed_result = []
+
+      # remove terminate command
+      string = string.gsub(command_to_regex(@terminate_command), '') if @terminate_command
+      # attack the string from the end
+      commands.reverse.each do |command|
+        regex  = command_to_regex(command)
+        result_array = string.split(regex)
+        @parsed_result << result_array.pop
+        raise NoResults.new(command, raw) if @parsed_result.last.blank?
+        string = result_array.join('')
+      end
+
+      @parsed_result.reverse!
+      return @parsed_result
+    end
+  end
+end

data/lib/repl_runner/multi_repl.rb

@@ -0,0 +1,80 @@
+class ReplRunner
+  # Takes in a command, to start a REPL session with PTY
+  # builds up a list of commands we want to run in our REPL
+  # executes them all at a time, reads in the result and returns results
+  # back to blocks
+  class MultiRepl
+    class UnexpectedExit < StandardError
+    end
+
+    DEFAULT_STARTUP_TIMEOUT = 60
+    DEFAULT_RETURN_CHAR     = "\n"
+
+    attr_accessor :command
+
+    def initialize(command, options = {})
+      @command_parser    = options[:command_parser]    || MultiCommandParser
+      @return_char       = options[:return_char]       || DEFAULT_RETURN_CHAR
+      @startup_timeout   = options[:startup_timeout]   || DEFAULT_STARTUP_TIMEOUT
+      @terminate_command = options[:terminate_command] or raise "must set default `terminate_command`"
+      @stync_stdout      = options[:sync_stdout]
+
+      @command  = command
+      @commands = []
+      @jobs     = []
+    end
+
+    def pty
+      @pty ||= PtyParty.new(command)
+    end
+
+    def run(command, &block)
+      @commands << command
+      @jobs     << (block || Proc.new {|result| })
+    end
+
+    def write(command)
+      pty.write("#{command}#{@return_char}")
+    end
+
+    def alive?
+      !!::Process.kill(0, pty.pid) rescue false # kill zero will return the status of the proceess without killing it
+    end
+
+    def dead?
+      !alive?
+    end
+
+    def read
+      raise UnexpectedExit, "Repl: '#{@command}' exited unexpectedly" if dead?
+      @output = pty.read(@startup_timeout)
+    end
+
+    def parse_results
+      @parsed_results ||= @command_parser.new(@commands, @terminate_command).parse(read)
+    end
+
+    def close
+      pty.close
+    end
+
+    def execute
+      write(@sync_stdout) if @sync_stdout
+
+      @commands.each do |command|
+        write(command)
+      end
+
+      write(@terminate_command)
+
+
+      output_array = parse_results
+
+      @jobs.each_with_index do |job, index|
+        job.call(output_array[index])
+      end
+    rescue NoResults => e
+      raise e, "Booting up REPL with command: #{command.inspect} \n#{e.message}"
+    end
+  end
+end

data/lib/repl_runner/pty_party.rb

@@ -0,0 +1,51 @@
+class ReplRunner
+  class PtyParty
+    attr_accessor :input, :output, :pid
+    TIMEOUT = 1
+
+    def initialize(command)
+      @output, @input, @pid = PTY.spawn(command)
+    end
+
+    def write(cmd)
+      input.write(cmd)
+    rescue Errno::EIO => e
+      raise e, "#{e.message} | trying to write '#{cmd}'"
+    end
+
+    def run(cmd, timeout = TIMEOUT)
+      write(cmd)
+      return read(timeout)
+    end
+
+    def close(timeout = TIMEOUT)
+      Timeout::timeout(timeout) do
+        input.close
+        output.close
+      end
+    rescue Timeout::Error
+      # do nothing
+    ensure
+      Process.kill('TERM', pid)   if pid.present?
+    end
+
+    # There be dragons - (You're playing with process deadlock)
+    #
+    # We want to read the whole output of the command
+    # First pull all contents from stdout (except we don't know how many there are)
+    # So we have to go until our process deadlocks, then we timeout and return the string
+    #
+    def read(timeout = TIMEOUT, str = "")
+      while true
+        Timeout::timeout(timeout) do
+          str << output.readline
+          break if output.eof?
+        end
+      end
+
+      return str
+    rescue Timeout::Error, EOFError, Errno::EIO
+      return str
+    end
+  end
+end

data/lib/repl_runner/version.rb

@@ -0,0 +1,3 @@
+class ReplRunner
+  VERSION = "0.0.1"
+end

data/repl_runner.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/repl_runner/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Richard Schneeman"]
+  gem.email         = ["richard@heroku.com"]
+  gem.description   = %q{ Programatically drive REPL like interfaces, irb, bash, etc. }
+  gem.summary       = %q{ Run your REPL like interfaces like never before}
+  gem.homepage      = "https://github.com/schneems/repl_runner"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "repl_runner"
+  gem.require_paths = ["lib"]
+  gem.version       = ReplRunner::VERSION
+  gem.license       = 'MIT' # the Georgia Tech of the North
+
+  gem.add_dependency "activesupport"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "mocha"
+end

data/test/config_test.rb

@@ -0,0 +1,28 @@
+require 'test_helper'
+
+class ConfigTest < Test::Unit::TestCase
+
+  def setup
+   @hash = {terminate_command: "exitYoSelf",
+            startup_timeout:   99,
+            return_char:       "poof",
+            sync_stdout:       "NSync"}
+  end
+
+  def test_config
+    config = ReplRunner::Config.new(:irb, :rails_console)
+    config.terminate_command @hash[:terminate_command]
+    assert_equal @hash[:terminate_command], config.to_options[:terminate_command]
+
+    config.startup_timeout @hash[:startup_timeout]
+    assert_equal @hash[:startup_timeout], config.to_options[:startup_timeout]
+
+    config.return_char @hash[:return_char]
+    assert_equal @hash[:return_char], config.to_options[:return_char]
+
+    config.sync_stdout @hash[:sync_stdout]
+    assert_equal @hash[:sync_stdout], config.to_options[:sync_stdout]
+
+    assert_equal @hash, config.to_options
+  end
+end

data/test/multi_command_parser_test.rb

@@ -0,0 +1,12 @@
+require 'test_helper'
+
+class MultiCommandParserTest < Test::Unit::TestCase
+  def test_removes_command_from_string
+    hash = {commands: ["1+1", "'hello' + 'world'"],
+            string:   "1+1\r\n => 2 \r\n'hello' + 'world'\r\n => \"helloworld\" \r\n",
+            expect:   [" => 2 \r\n", " => \"helloworld\" \r\n"]
+            }
+    cp = ReplRunner::MultiCommandParser.new(hash[:commands])
+    assert_equal hash[:expect], cp.parse(hash[:string])
+  end
+end

data/test/multi_repl_test.rb

@@ -0,0 +1,13 @@
+require 'test_helper'
+
+class MultiReplTest < Test::Unit::TestCase
+  def test_local_irb_stream
+    repl = ReplRunner::MultiRepl.new('irb', terminate_command: 'exit')
+    repl.run('111+111')           {|r| assert_match '222', r }
+    repl.run("'hello' + 'world'") {|r| assert_match 'helloworld', r }
+    repl.run("a = 'foo'")
+    repl.run("b = 'bar'")         {} # test empty block doesn't throw exceptions
+    repl.run("a * 5")             {|r| assert_match 'foofoofoofoofoo', r }
+    repl.execute
+  end
+end

data/test/pty_party_test.rb

@@ -0,0 +1,18 @@
+require 'test_helper'
+
+class StreamExecTest < Test::Unit::TestCase
+  def test_local_irb_stream
+    repl  = ReplRunner::PtyParty.new("irb")
+    repl.run("STDOUT.sync = true\n")
+    assert_equal "1+1\r\n => 2 \r\n", repl.run("1+1\n")
+    assert_equal "'hello' + 'world'\r\n => \"helloworld\" \r\n", repl.run("'hello' + 'world'\n")
+  end
+
+  def test_multi_command_read
+    repl  = ReplRunner::PtyParty.new("irb")
+    repl.write("STDOUT.sync = true\n")
+    repl.write("1+1\n")
+    repl.write("exit\n")
+    assert_equal "STDOUT.sync = true\r\n1+1\r\nexit\r\n2.0.0-p0 :001 > STDOUT.sync = true\r\n => true \r\n2.0.0-p0 :002 > 1+1\r\n => 2 \r\n2.0.0-p0 :003 > exit\r\n", repl.read
+  end
+end

data/test/repl_runner_test.rb

@@ -0,0 +1,40 @@
+require 'test_helper'
+
+class ReplRunnerTest < Test::Unit::TestCase
+  def test_local_irb_stream
+    ReplRunner.new(:irb).run do |repl|
+      repl.run('111+111')           {|r| assert_match '222', r }
+      repl.run("'hello' + 'world'") {|r| assert_match 'helloworld', r }
+      repl.run("a = 'foo'")
+      repl.run("b = 'bar'")         {} # test empty block doesn't throw exceptions
+      repl.run("a * 5")             {|r| assert_match 'foofoofoofoofoo', r }
+    end
+  end
+
+  def test_ensure_exit
+    assert_raise(ReplRunner::NoResults) do
+      ReplRunner.new(:irb, "irb -r ./test/require/never-boots.rb", startup_timeout: 2).run do |repl|
+        repl.run('111+111') {|r| }
+      end
+    end
+  end
+
+  def test_bash
+    ReplRunner.new(:bash).run do |repl|
+      repl.run('ls') {|r| assert_match /Gemfile/, r}
+    end
+  end
+
+  def test_unknown_command
+    assert_raise ReplRunner::UnregisteredCommand do
+      ReplRunner.new(:zootsuite)
+    end
+  end
+
+  def test_heroku
+    # ReplRunner.new('rails console', "heroku run rails console -a test-app-1372231309-0734751").run do |repl|
+    #   repl.run("'foo' * 5")          {|r| assert_match /foofoofoofoofoo/, r }
+    #   repl.run("'hello ' + 'world'") {|r| assert_match /hello world/, r }
+    # end
+  end
+end

data/test/require/never-boots.rb

@@ -0,0 +1,5 @@
+# require this file while booting up IRB, and it will never return
+
+while true
+  sleep 1
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+Bundler.require
+
+
+require 'repl_runner'
+require 'test/unit'
+require "mocha/setup"
+
+
+def assert_tests_run
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: repl_runner
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Richard Schneeman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  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: ' Programatically drive REPL like interfaces, irb, bash, etc. '
+email:
+- richard@heroku.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/repl_runner.rb
+- lib/repl_runner/config.rb
+- lib/repl_runner/default_config.rb
+- lib/repl_runner/multi_command_parser.rb
+- lib/repl_runner/multi_repl.rb
+- lib/repl_runner/pty_party.rb
+- lib/repl_runner/version.rb
+- repl_runner.gemspec
+- test/config_test.rb
+- test/multi_command_parser_test.rb
+- test/multi_repl_test.rb
+- test/pty_party_test.rb
+- test/repl_runner_test.rb
+- test/require/never-boots.rb
+- test/test_helper.rb
+homepage: https://github.com/schneems/repl_runner
+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.0.2
+signing_key: 
+specification_version: 4
+summary: Run your REPL like interfaces like never before
+test_files:
+- test/config_test.rb
+- test/multi_command_parser_test.rb
+- test/multi_repl_test.rb
+- test/pty_party_test.rb
+- test/repl_runner_test.rb
+- test/require/never-boots.rb
+- test/test_helper.rb