caliph 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2b0f24364e478c354208e04a309d201339ebaa57
+  data.tar.gz: 1de70f9e8bb89ee483b7d28ffbcbb76d10428687
+SHA512:
+  metadata.gz: 94590b96bf71222807e9b9c96c3a5ea52cd89a826191169608d02603879edb3bc02948bea3f92e97fdf0366baedcf1ad1403c0a6248f857ee79051ffaa24de13
+  data.tar.gz: 255d5824af358a59fdfb92b8798bd62015f81cfe9f242d51e9f1ac9c0318c50bfa9ae20dd9bce372567eea5775927db1e48c947daabbd4f0cd84f60cf8c80e6f

data/lib/caliph.rb

@@ -0,0 +1,4 @@
+require 'caliph/command-line'
+require 'caliph/command-chain'
+require 'caliph/command-line-dsl'
+require 'caliph/shell-escaped'

data/lib/caliph/command-chain.rb

@@ -0,0 +1,58 @@
+require 'caliph/define-op'
+
+module Caliph
+  class CommandChain < CommandLine
+    include DefineOp
+
+    def initialize
+      @commands = []
+      @command_environment = {}
+      super(nil)
+    end
+
+    attr_reader :commands
+
+    def add(cmd)
+      yield cmd if block_given?
+      @commands << cmd
+      self
+    end
+
+    #Honestly this is sub-optimal - biggest driver for considering the
+    #mini-shell approach here.
+    def command_environment
+      @command_environment = @commands.reverse.inject(@command_environment) do |env, command|
+        env.merge(command.command_environment)
+      end
+    end
+
+    def name
+      @name || @commands.last.name
+    end
+  end
+
+  class WrappingChain < CommandChain
+    define_op('-')
+
+    def command
+      @commands.map{|cmd| cmd.command}.join(" -- ")
+    end
+  end
+
+  class PrereqChain < CommandChain
+    define_op('&')
+
+    def command
+      @commands.map{|cmd| cmd.command}.join(" && ")
+    end
+  end
+
+  class PipelineChain < CommandChain
+    define_op('|')
+
+    def command
+      @commands.map{|cmd| cmd.command}.join(" | ")
+    end
+  end
+end
+

data/lib/caliph/command-line-dsl.rb

@@ -0,0 +1,11 @@
+module Caliph
+  module CommandLineDSL
+    def cmd(*args, &block)
+      CommandLine.new(*args, &block)
+    end
+
+    def escaped_command(*args, &block)
+      ShellEscaped.new(CommandLine.new(*args, &block))
+    end
+  end
+end

data/lib/caliph/command-line.rb

@@ -0,0 +1,185 @@
+require 'caliph/define-op'
+require 'caliph/command-run-result'
+
+module Caliph
+  class CommandLine
+    include DefineOp
+
+    class << self
+      attr_accessor :output_stream
+    end
+
+    def initialize(executable, *options)
+      @output_stream = self.class.output_stream || $stderr
+      @executable = executable.to_s
+      @options = options
+      @redirections = []
+      @env = {}
+      yield self if block_given?
+    end
+
+    attr_accessor :name, :executable, :options, :env, :output_stream
+    attr_reader :redirections
+
+    alias_method :command_environment, :env
+
+    def set_env(name, value)
+      command_environment[name] = value
+      return self
+    end
+
+    def verbose
+      #::Rake.verbose && ::Rake.verbose != ::Rake::FileUtilsExt::DEFAULT
+    end
+
+    def name
+      @name || executable
+    end
+
+    # The command as a string, including arguments and options
+    def command
+      ([executable] + options_composition + @redirections).join(" ")
+    end
+
+    # The command as a string, including arguments and options, plus prefixed
+    # environment variables.
+    def string_format
+      (command_environment.map do |key, value|
+        [key, value].join("=")
+      end + [command]).join(" ")
+    end
+
+    def options_composition
+      options
+    end
+
+    def redirect_to(stream, path)
+      @redirections << "#{stream}>#{path}"
+      self
+    end
+
+    def redirect_from(path, stream)
+      @redirections << "#{stream}<#{path}"
+    end
+
+    def copy_stream_to(from, to)
+      @redirections << "#{from}>&#{to}"
+    end
+
+    def redirect_stdout(path)
+      redirect_to(1, path)
+    end
+
+    def redirect_stderr(path)
+      redirect_to(2, path)
+    end
+
+    def redirect_stdin(path)
+      redirect_from(path, 0)
+    end
+
+    def redirect_both(path)
+      redirect_stdout(path).redirect_stderr(path)
+    end
+
+    # Run the command, wait for termination, and collect the results.
+    # Returns an instance of CommandRunResult that contains the output
+    # and exit code of the command.
+    #
+    # This version adds some information to STDOUT to document that the
+    # command is running.  For a terser version, call #execute directly
+    def run
+      report string_format + " ", false
+      result = execute
+      report "=> #{result.exit_code}"
+      report result.format_streams if verbose
+      return result
+    ensure
+      report "" if verbose
+    end
+
+    # Fork a new process for the command, then terminate our process.
+    def run_as_replacement
+      output_stream.puts "Ceding execution to: "
+      output_stream.puts string_format
+      Process.exec(command_environment, command)
+    end
+    alias replace_us run_as_replacement
+
+    # Run the command in the background.  The command can survive the caller.
+    def run_detached
+      pid, out, err = spawn_process
+      Process.detach(pid)
+      return pid, out, err
+    end
+    alias spin_off run_detached
+
+    # Run the command, wait for termination, and collect the results.
+    # Returns an instance of CommandRunResult that contains the output
+    # and exit code of the command.
+    #
+    def execute
+      collect_result(*spawn_process)
+    end
+
+    # Run the command in parallel with the parent process - will kill it if it
+    # outlasts us
+    def run_in_background
+      pid, out, err = spawn_process
+      Process.detach(pid)
+      at_exit do
+        kill_process(pid)
+      end
+      return pid, out, err
+    end
+    alias background run_in_background
+
+    # Given a process ID for a running command and a pair of stdout/stdin
+    # streams, records the results of the command and returns them in a
+    # CommandRunResult instance.
+    def collect_result(pid, host_stdout, host_stderr)
+      result = CommandRunResult.new(pid, self)
+      result.streams = {1 => host_stdout, 2 => host_stderr}
+      result.wait
+      return result
+    end
+
+
+    def kill_process(pid)
+      Process.kill("INT", pid)
+    end
+
+    def complete(pid, out, err)
+      kill_process(pid)
+      collect_result(pid, out, err)
+    end
+
+    def report(message, newline=true)
+      output_stream.print(message + (newline ? "\n" : ""))
+    end
+
+
+    def succeeds?
+      run.succeeded?
+    end
+
+    def must_succeed!
+      run.must_succeed!
+    end
+
+    def spawn_process
+      host_stdout, cmd_stdout = IO.pipe
+      host_stderr, cmd_stderr = IO.pipe
+
+      pid = Process.spawn(command_environment, command, :out => cmd_stdout, :err => cmd_stderr)
+      cmd_stdout.close
+      cmd_stderr.close
+
+      return pid, host_stdout, host_stderr
+    end
+
+
+  end
+
+
+end

data/lib/caliph/command-run-result.rb

@@ -0,0 +1,129 @@
+module Caliph
+  class CommandRunResult
+    def initialize(pid, command)
+      @command = command
+      @pid = pid
+
+      #####
+      @process_status = nil
+      @streams = {}
+      @consume_timeout = nil
+    end
+    attr_reader :process_status, :pid
+    attr_accessor :consume_timeout, :streams
+
+    def stdout
+      @streams[1]
+    end
+
+    def stderr
+      @streams[2]
+    end
+
+    def exit_code
+      @process_status.exitstatus
+    end
+    alias exit_status exit_code
+
+    def succeeded?
+      must_succeed!
+      return true
+    rescue
+      return false
+    end
+
+    def format_streams
+      "stdout:#{stdout.nil? || stdout.empty? ? "[empty]\n" : "\n#{stdout}"}" +
+      "stderr:#{stderr.nil? || stderr.empty? ? "[empty]\n" : "\n#{stderr}"}---"
+    end
+
+    def must_succeed!
+      case exit_code
+      when 0
+        return exit_code
+      else
+        fail "Command #{@command.inspect} failed with exit status #{exit_code}: \n#{format_streams}"
+      end
+    end
+
+    def wait
+      @accumulators = {}
+      waits = {}
+      @buffered_echo = []
+
+      ioes = streams.values
+      ioes.each do |io|
+        @accumulators[io] = []
+        waits[io] = 3
+      end
+      begin_echoing = Time.now + (@consume_timeout || 3)
+
+      @live_ioes = ioes.dup
+
+      until @live_ioes.empty? do
+        newpid, @process_status = Process.waitpid2(pid, Process::WNOHANG)
+
+        unless @process_status.nil?
+          consume_buffers(@live_ioes)
+          break
+        end
+
+        timeout = 0
+
+        if !@buffered_echo.nil?
+          timeout = begin_echoing - Time.now
+          if timeout < 0
+            @command.report ""
+            @command.report "Long running command output:"
+            @command.report @buffered_echo.join
+            @buffered_echo = nil
+          end
+        end
+
+        if timeout > 0
+          result = IO::select(@live_ioes, [], @live_ioes, timeout)
+        else
+          result = IO::select(@live_ioes, [], @live_ioes, 1)
+        end
+
+        unless result.nil? #timeout
+          readable, _writeable, errored = *result
+          unless errored.empty?
+            raise "Error on IO: #{errored.inspect}"
+          end
+
+          consume_buffers(readable)
+        end
+      end
+
+      if @process_status.nil?
+        newpid, @process_status = Process.waitpid2(pid)
+      end
+
+      ioes.each do |io|
+        io.close
+      end
+      @streams = Hash[ioes.each_with_index.map{|io, index| [index + 1, @accumulators[io].join]}]
+    end
+
+    def consume_buffers(readable)
+      if not(readable.nil? or readable.empty?)
+        readable.each do |io|
+          begin
+            while chunk = io.read_nonblock(4096)
+              if @buffered_echo.nil?
+                @command.report chunk, false
+              else
+                @buffered_echo << chunk
+              end
+              @accumulators[io] <<  chunk
+            end
+          rescue IO::WaitReadable => ex
+          rescue EOFError => ex
+            @live_ioes.delete(io)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/caliph/define-op.rb

@@ -0,0 +1,29 @@
+module Caliph
+  module DefineOp
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def define_chain_op(opname, klass)
+        define_method(opname) do |other|
+          unless CommandLine === other
+            other = CommandLine.new(*[*other])
+          end
+          chain = nil
+          if klass === self
+            chain = self
+          else
+            chain = klass.new
+            chain.add(self)
+          end
+          chain.add(other)
+        end
+      end
+
+      def define_op(opname)
+        CommandLine.define_chain_op(opname, self)
+      end
+    end
+  end
+end

data/lib/caliph/shell-escaped.rb

@@ -0,0 +1,25 @@
+require 'caliph/command-line'
+
+module Caliph
+  class ShellEscaped < CommandLine
+    def initialize(cmd)
+      @escaped = cmd
+    end
+
+    def command
+      "'" + @escaped.string_format.gsub(/'/,"\'") + "'"
+    end
+
+    def command_environment
+      {}
+    end
+
+    def name
+      @name || @escaped.name
+    end
+
+    def to_s
+      command
+    end
+  end
+end

data/lib/caliph/testing/mock-command-line.rb

@@ -0,0 +1,67 @@
+require 'caliph/command-line'
+
+module Caliph
+  class MockCommandResult < CommandRunResult
+    def self.create(*args)
+      if args.length == 1
+        args = [args[0], {1 => ""}]
+      end
+
+      if String == args[1]
+        args[1] = {1 => args[1]}
+      end
+
+      return self.new(*args)
+    end
+
+    def initialize(code, streams)
+      @streams = streams
+      @exit_code = code
+    end
+
+    attr_reader :exit_code, :streams
+
+    alias exit_status exit_code
+  end
+
+  class CommandLine
+    def self.execute(*args)
+      fail "Command line executed in specs without 'expect_command' or 'expect_some_commands'"
+    end
+  end
+
+  module CommandLineExampleGroup
+    include CommandLineDSL
+    module MockingExecute
+      def execute
+        Caliph::CommandLine.execute(command)
+      end
+    end
+
+
+    def self.included(group)
+      group.before :each do
+        @original_execute = Caliph::CommandLine.instance_method(:execute)
+        unless MockingExecute > Caliph::CommandLine
+          Caliph::CommandLine.send(:include, MockingExecute)
+        end
+        Caliph::CommandLine.send(:remove_method, :execute)
+      end
+
+      group.after :each do
+        Caliph::CommandLine.send(:define_method, :execute, @original_execute)
+      end
+    end
+
+    #Registers indifference as to exactly what commands get called
+    def expect_some_commands
+      Caliph::CommandLine.should_receive(:execute).any_number_of_times.and_return(MockCommandResult.create(0))
+    end
+
+    #Registers an expectation about a command being run - expectations are
+    #ordered
+    def expect_command(cmd, *result)
+      Caliph::CommandLine.should_receive(:execute, :expected_from => caller(1)[0]).with(cmd).ordered.and_return(MockCommandResult.create(*result))
+    end
+  end
+end

data/lib/caliph/testing/record-commands.rb

@@ -0,0 +1,38 @@
+require 'caliph/command-line'
+
+module Caliph
+  class CommandLine
+    @@commands = []
+    alias original_execute execute
+
+    def execute
+      result = original_execute
+      @@commands << [command, result]
+      return result
+    end
+
+    class << self
+      attr_accessor :command_recording_path
+
+      def command_recording_path
+        @command_recording_path ||= ENV['CALIPH_CMDREC']
+      end
+
+      def emit_recording
+        io = $stderr
+        if command_recording_path
+          io = File.open(command_recording_path, "w")
+        else
+          io.puts "Set CALIPH_CMDREC to write to a path"
+        end
+        @@commands.each do |pair|
+          io.puts "[/#{pair[0]}/, #{[pair[1].exit_code, pair[1].streams].inspect}]"
+        end
+      end
+    end
+  end
+end
+
+at_exit do
+  Caliph::CommandLine.emit_recording
+end

data/spec/command-chain.rb

@@ -0,0 +1,9 @@
+require 'caliph'
+
+describe Caliph::CommandChain do
+
+  it "should initialize" do
+    Caliph::CommandChain.new
+  end
+
+end

data/spec/command-line-dsl.rb

@@ -0,0 +1,48 @@
+require 'caliph/command-line-dsl'
+
+describe Caliph::CommandLineDSL do
+  include described_class
+
+  describe "using the - operator" do
+    let :command do
+      cmd("sudo") - ["gem", "install", "bundler"]
+    end
+
+    it "should define commands" do
+      command.should be_an_instance_of(Caliph::WrappingChain)
+      command.should have(2).commands
+      command.commands[0].should be_an_instance_of(Caliph::CommandLine)
+      command.commands[1].should be_an_instance_of(Caliph::CommandLine)
+      command.command.should == "sudo -- gem install bundler"
+    end
+  end
+
+  describe "using the | operator" do
+    let :command do
+      cmd("cat", "/etc/passwd") | ["grep", "root"]
+    end
+
+    it "should define commands" do
+      command.should be_an_instance_of(Caliph::PipelineChain)
+      command.should have(2).commands
+      command.commands[0].should be_an_instance_of(Caliph::CommandLine)
+      command.commands[1].should be_an_instance_of(Caliph::CommandLine)
+      command.command.should == "cat /etc/passwd | grep root"
+    end
+  end
+
+  describe "using the & operator" do
+    let :command do
+      p method(:cmd).source_location
+      cmd("cd", "/tmp/trash") & %w{rm -rf *}
+    end
+
+    it "should define commands" do
+      command.should be_an_instance_of(Caliph::PrereqChain)
+      command.should have(2).commands
+      command.commands[0].should be_an_instance_of(Caliph::CommandLine)
+      command.commands[1].should be_an_instance_of(Caliph::CommandLine)
+      command.command.should == "cd /tmp/trash && rm -rf *"
+    end
+  end
+end

data/spec/command-line.rb

@@ -0,0 +1,135 @@
+require 'caliph'
+require 'caliph/testing/mock-command-line'
+
+require 'caliph/testing/record-commands'
+
+Caliph::CommandLine.command_recording_path = "/dev/null"
+
+describe Caliph::CommandLine do
+  let :commandline do
+    Caliph::CommandLine.new('echo', "-n") do |cmd|
+      cmd.options << "Some text"
+    end
+  end
+
+  it "should have a name set" do
+    commandline.name.should == "echo"
+  end
+
+  it "should produce a command string" do
+    commandline.command.should == "echo -n Some text"
+  end
+
+  it "should succeed" do
+    commandline.succeeds?.should be_true
+  end
+
+  it "should not complain about success" do
+    expect do
+      commandline.must_succeed!
+    end.to_not raise_error
+  end
+
+end
+
+describe Caliph::CommandLine, "setting environment variables" do
+  let :commandline do
+    Caliph::CommandLine.new("env") do |cmd|
+      cmd.env["TEST_ENV"] = "indubitably"
+    end
+  end
+
+  let :result do
+    commandline.run
+  end
+
+  it "should succeed" do
+    result.succeeded?.should be_true
+  end
+
+  it "should alter the command's environment variables" do
+    result.stdout.should =~ /TEST_ENV.*indubitably/
+  end
+
+end
+
+describe Caliph::CommandLine, 'redirecting' do
+  let :commandline do
+    Caliph::CommandLine.new("env")
+  end
+
+  let :result do
+    commandline.string_format
+  end
+
+  it 'should allow redirect stdout' do
+    commandline.redirect_stdout('some_file')
+    result.should =~ /1>some_file$/
+  end
+
+  it 'should allow redirect stderr' do
+    commandline.redirect_stderr('some_file')
+    result.should =~ /2>some_file$/
+  end
+
+  it 'should allow chain redirects' do
+    commandline.redirect_stdout('stdout_file').redirect_stderr('stderr_file')
+    result.should =~ /\b1>stdout_file\b/
+    result.should =~ /\b2>stderr_file\b/
+  end
+
+  it 'should redirect both' do
+    commandline.redirect_both('output_file')
+    result.should =~ /\b1>output_file\b/
+    result.should =~ /\b2>output_file\b/
+  end
+end
+
+describe Caliph::PipelineChain do
+  let :commandline do
+    Caliph::PipelineChain.new do |chain|
+      chain.add Caliph::CommandLine.new("env")
+      chain.add Caliph::CommandLine.new("cat") do |cmd|
+        cmd.env["TEST_ENV"] = "indubitably"
+      end
+    end
+  end
+
+  let :result do
+    commandline.run
+  end
+
+  it "should produce the right command" do
+    commandline.command.should == 'env | cat'
+  end
+
+  it "should produce a runnable command with format_string" do
+    commandline.string_format.should == 'TEST_ENV=indubitably env | cat'
+  end
+
+  it "should succeed" do
+    result.succeeded?.should be_true
+  end
+
+  it "should alter the command's environment variables" do
+    result.stdout.should =~ /TEST_ENV.*indubitably/
+  end
+end
+
+
+
+describe Caliph::CommandLine, "that fails" do
+  let :commandline do
+    Caliph::CommandLine.new("false")
+  end
+
+  it "should not succeed" do
+    commandline.succeeds?.should == false
+  end
+
+  it "should raise error if succeed demanded" do
+    expect do
+      commandline.must_succeed
+    end.to raise_error
+  end
+end

data/spec_help/gem_test_suite.rb

@@ -0,0 +1,17 @@
+puts Dir::pwd
+require 'test/unit'
+begin
+  require 'spec'
+rescue LoadError
+  false
+end
+
+class RSpecTest < Test::Unit::TestCase
+  def test_that_rspec_is_available
+    assert_nothing_raised("\n\n *  RSpec isn't available - please run: gem install rspec  *\n\n"){ ::Spec }
+  end
+
+  def test_that_specs_pass
+    assert(system(*%w{spec -f e -p **/*.rb spec}),"\n\n *  Specs failed  *\n\n")
+  end
+end

data/spec_help/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rspec'
+require 'rspec/core/formatters/base_formatter'
+
+require 'caliph'
+require 'cadre/rspec'
+
+RSpec.configure do |config|
+  config.run_all_when_everything_filtered = true
+  config.add_formatter(Cadre::RSpec::NotifyOnCompleteFormatter)
+  config.add_formatter(Cadre::RSpec::QuickfixFormatter)
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: caliph
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Evan Dorn
+- Judson Lester
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-12 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      TDD-suitable Ruby tool for generating command-line commands via an OOP interface.
+email:
+- evan@lrdesign.com
+- judson@lrdesign.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/caliph.rb
+- lib/caliph/command-chain.rb
+- lib/caliph/command-line-dsl.rb
+- lib/caliph/command-line.rb
+- lib/caliph/command-run-result.rb
+- lib/caliph/define-op.rb
+- lib/caliph/shell-escaped.rb
+- lib/caliph/testing/mock-command-line.rb
+- lib/caliph/testing/record-commands.rb
+- spec/command-chain.rb
+- spec/command-line-dsl.rb
+- spec/command-line.rb
+- spec_help/gem_test_suite.rb
+- spec_help/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --inline-source
+- --main
+- doc/README
+- --title
+- caliph-0.1.0 Documentation
+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: caliph
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: TDD-suitable Ruby tool for generating command-line commands via an OOP interface.
+test_files:
+- spec_help/gem_test_suite.rb