caliph 0.1.1 → 0.1.2

data/lib/caliph/command-line.rb

@@ -9,29 +9,30 @@ module Caliph
       attr_accessor :output_stream
     end
 
-    def initialize(executable, *options)
+    def initialize(executable = nil, *options)
       @output_stream = self.class.output_stream || $stderr
-      @executable = executable.to_s
+      @executable = executable.to_s unless executable.nil?
       @options = options
       @redirections = []
       @env = {}
+      @verbose = false
       yield self if block_given?
     end
 
-    attr_accessor :name, :executable, :options, :env, :output_stream
+    attr_accessor :name, :executable, :options, :env, :output_stream, :verbose
     attr_reader :redirections
 
     alias_method :command_environment, :env
 
+    def valid?
+      !@executable.nil?
+    end
+
     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
@@ -58,6 +59,8 @@ module Caliph
       self
     end
 
+    # Waits for the process to complete. If this takes longer that
+    # {consume_timeout},
     def redirect_from(path, stream)
       @redirections << "#{stream}<#{path}"
     end
@@ -82,104 +85,44 @@ module Caliph
       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
+    #:nocov:
+    #@deprecated (see: Shell)
     def run
-      report string_format + " ", false
-      result = execute
-      report "=> #{result.exit_code}"
-      report result.format_streams if verbose
-      return result
-    ensure
-      report "" if verbose
+      Caliph.new.run(self)
     end
 
-    # Fork a new process for the command, then terminate our process.
+    #@deprecated (see: Shell)
     def run_as_replacement
-      output_stream.puts "Ceding execution to: "
-      output_stream.puts string_format
-      Process.exec(command_environment, command)
+      Caliph.new.run_as_replacement(self)
     end
     alias replace_us run_as_replacement
 
-    # Run the command in the background.  The command can survive the caller.
+    #@deprecated (see: Shell)
     def run_detached
-      pid, out, err = spawn_process
-      Process.detach(pid)
-      return pid, out, err
+      Caliph.new.run_detached(self)
     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.
-    #
+    #@deprecated (see: Shell)
     def execute
-      collect_result(*spawn_process)
+      Caliph.new.execute(self)
     end
 
-    # Run the command in parallel with the parent process - will kill it if it
-    # outlasts us
+    #@deprecated (see: Shell)
     def run_in_background
-      pid, out, err = spawn_process
-      Process.detach(pid)
-      at_exit do
-        kill_process(pid)
-      end
-      return pid, out, err
+      Caliph.new.run_in_background(self)
     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
-
-
+    #@deprecated
     def succeeds?
       run.succeeded?
     end
 
+    #@deprecated
     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
-
-
+    #:nocov:
   end
-
-
 end

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

@@ -1,30 +1,55 @@
 module Caliph
+  # This is the Caliph handle on a run process - it can be used to send signals
+  # to running processes, wait for them to complete, get their exit status once
+  # they have, and watch their streams in either case.
   class CommandRunResult
-    def initialize(pid, command)
+    def initialize(pid, command, shell)
       @command = command
       @pid = pid
+      @shell = shell
 
       #####
       @process_status = nil
       @streams = {}
       @consume_timeout = nil
     end
-    attr_reader :process_status, :pid
+
+    attr_reader :process_status
+
+    attr_reader :pid, :command
     attr_accessor :consume_timeout, :streams
 
+    # Access the stdout of the process
     def stdout
       @streams[1]
     end
 
+    # Access the stderr of the process
     def stderr
       @streams[2]
     end
 
+    # @return [exit_code] the raw exit of the process
+    # @return [nil] the process is still running
     def exit_code
-      @process_status.exitstatus
+      if @process_status.nil?
+        return nil
+      else
+        @process_status.exitstatus
+      end
     end
     alias exit_status exit_code
 
+    # Check whether the process is still running
+    # @return [true] the process is still running
+    # @return [false] the process has completed
+    def running?
+      !@process_status.nil?
+    end
+
+    # Confirm that the process exited with a successful exit code (i.e. 0).
+    # This is pretty reliable, but many applications return bad exit statuses -
+    # 0 when they failed, usually.
     def succeeded?
       must_succeed!
       return true
@@ -32,11 +57,14 @@ module Caliph
       return false
     end
 
+    # Nicely formatted output of stdout and stderr - won't be intermixed, which
+    # may be different than what you'd see live in the shell
     def format_streams
       "stdout:#{stdout.nil? || stdout.empty? ? "[empty]\n" : "\n#{stdout}"}" +
       "stderr:#{stderr.nil? || stderr.empty? ? "[empty]\n" : "\n#{stderr}"}---"
     end
 
+    # Demands that the process succeed, or else raises and error
     def must_succeed!
       case exit_code
       when 0
@@ -46,6 +74,19 @@ module Caliph
       end
     end
 
+    # Stop a running process. Sends SIGINT by default which about like hitting
+    # Control-C.
+    # @param signal the Unix signal to send to the process
+    def kill(signal = nil)
+      Process.kill(signal || "INT", pid)
+    rescue Errno::ESRCH
+      warn "Couldn't find process #{pid} to kill it"
+    end
+
+    # Waits for the process to complete. If this takes longer that
+    # {consume_timeout}, output on the process's streams will be output via
+    # {Shell#report} - very useful when compilation or network transfers are
+    # taking a long time.
     def wait
       @accumulators = {}
       waits = {}
@@ -73,9 +114,9 @@ module Caliph
         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
+            @shell.report ""
+            @shell.report "Long running command output:"
+            @shell.report @buffered_echo.join
             @buffered_echo = nil
           end
         end
@@ -112,7 +153,7 @@ module Caliph
           begin
             while chunk = io.read_nonblock(4096)
               if @buffered_echo.nil?
-                @command.report chunk, false
+                @shell.report chunk, false
               else
                 @buffered_echo << chunk
               end

data/lib/caliph/shell.rb

@@ -0,0 +1,172 @@
+module Caliph
+  class Error < StandardError; end
+  class IncompleteCommand < Error; end
+  class InvalidCommand < Error; end
+
+  # Operates something like a command line shell, except from a Ruby object
+  # perspective.
+  #
+  # Basically, a Shell operates as your handle on creating, running and killing
+  # commands in Caliph.
+  #
+  class Shell
+    attr_accessor :verbose, :output_stream
+
+    def output_stream
+      @output_stream ||= $stderr
+    end
+
+    def verbose
+      @verbose ||= false
+    end
+
+    # Reports messages if verbose is true. Used internally to print messages
+    # about running commands
+    def report_verbose(message)
+      report(message) if verbose
+    end
+
+    # Prints information to {output_stream} which defaults to $stderr.
+    def report(message, newline=true)
+      output_stream.print(message + (newline ? "\n" : ""))
+    end
+
+    # Kill processes given a raw pid. In general, prefer
+    # {CommandRunResult#kill}
+    # @param pid the process id to kill
+    def kill_process(pid)
+      Process.kill("INT", pid)
+    rescue Errno::ESRCH
+      warn "Couldn't find process #{pid} to kill it"
+    end
+
+    def normalize_command_line(*args, &block)
+      command_line = nil
+      if args.empty? or args.first == nil
+        command_line = CommandLine.new
+      elsif args.all?{|arg| arg.is_a? String}
+        command_line = CommandLine.new(*args)
+      else
+        command_line = args.first
+      end
+      yield command_line if block_given?
+      #raise InvalidCommand, "not a command line: #{command_line.inspect}"
+      #unless command_line.is_a? CommandLine
+      raise IncompleteCommand, "cannot run #{command_line}" unless command_line.valid?
+      command_line
+    end
+    protected :normalize_command_line
+
+    # 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(command, pid, host_stdout, host_stderr)
+      result = CommandRunResult.new(pid, command, self)
+      result.streams = {1 => host_stdout, 2 => host_stderr}
+      return result
+    end
+
+    # Creates a process to run a command. Handles connecting pipes to stardard
+    # streams, launching the process and returning a pid for it.
+    # @return [pid, host_stdout, host_stderr] the process id and streams
+    #   associated with the child process
+    def spawn_process(command_line)
+      host_stdout, cmd_stdout = IO.pipe
+      host_stderr, cmd_stderr = IO.pipe
+
+      pid = Process.spawn(command_line.command_environment, command_line.command, :out => cmd_stdout, :err => cmd_stderr)
+      cmd_stdout.close
+      cmd_stderr.close
+
+      return pid, host_stdout, host_stderr
+    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.
+    #
+    def execute(command_line)
+      result = collect_result(command_line, *spawn_process(command_line))
+      result.wait
+      result
+    end
+
+    # @!group Running Commands
+    # 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 {#report}s some information to document that the
+    # command is running.  For a terser version, call {#execute} directly
+    #
+    # @!macro normalized
+    #   @yield [CommandLine] command about to be run (for configuration)
+    #   @return [CommandRunResult] used to refer to and inspect the resulting
+    #     process
+    #   @overload $0(&block)
+    #   @overload $0(cmd, &block)
+    #     @param [CommandLine] execute
+    #   @overload $0(*cmd_strings, &block)
+    #     @param [Array<String>] a set of strings to parse into a {CommandLine}
+    def run(*args, &block)
+      command_line = normalize_command_line(*args, &block)
+
+      report command_line.string_format + " ", false
+      result = execute(command_line)
+      report "=> #{result.exit_code}"
+      report_verbose result.format_streams
+      return result
+    ensure
+      report_verbose ""
+    end
+
+    # Completely replace the running process with a command. Good for setting
+    # up a command and then running it, without worrying about what happens
+    # after that. Uses `exec` under the hood.
+    # @macro normalized
+    # @example Using replace_us
+    #   # The last thing we'll ever do:
+    #   shell.run_as_replacement('echo', "Everything is okay")
+    #   # don't worry, we never get here.
+    #   shell.run("sudo", "shutdown -h now")
+    def run_as_replacement(*args, &block)
+      command_line = normalize_command_line(*args, &block)
+
+      report "Ceding execution to: "
+      report command_line.string_format
+      Process.exec(command_line.command_environment, command_line.command)
+    end
+    alias replace_us run_as_replacement
+
+    # Run the command in the background.  The command can survive the caller.
+    # Works, for instance, to kick off some long running processes that we
+    # don't care about. Note that this isn't quite full daemonization - we
+    # don't close the streams of the other process, or scrub its environment or
+    # anything.
+    # @macro normalized
+    def run_detached(*args, &block)
+      command_line = normalize_command_line(*args, &block)
+
+      pid, out, err = spawn_process(command_line)
+      Process.detach(pid)
+      return collect_result(command_line, pid, out, err)
+    end
+    alias spin_off run_detached
+
+    # Run the command in parallel with the parent process - will kill it if it
+    # outlasts us. Good for running e.g. a web server that we need to interact
+    # with, or the like, without cluttering the system with a bunch of zombies.
+    # @macro normalized
+    def run_in_background(*args, &block)
+      command_line = normalize_command_line(*args, &block)
+
+      pid, out, err = spawn_process(command_line)
+      Process.detach(pid)
+      at_exit do
+        kill_process(pid)
+      end
+      return collect_result(command_line, pid, out, err)
+    end
+    alias background run_in_background
+
+    # !@endgroup
+  end
+end

data/lib/caliph.rb

@@ -1,4 +1,13 @@
+module Caliph
+  # Returns an instance of the default {Shell}
+  # @todo add alternative shells - e.g. SSHShell
+  def self.new
+    Shell.new
+  end
+end
+
 require 'caliph/command-line'
 require 'caliph/command-chain'
 require 'caliph/command-line-dsl'
 require 'caliph/shell-escaped'
+require 'caliph/shell'

data/spec/command-line-dsl.rb

@@ -9,11 +9,11 @@ describe Caliph::CommandLineDSL do
     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"
+      expect(command).to be_an_instance_of(Caliph::WrappingChain)
+      expect(command.commands.size).to eq(2)
+      expect(command.commands[0]).to be_an_instance_of(Caliph::CommandLine)
+      expect(command.commands[1]).to be_an_instance_of(Caliph::CommandLine)
+      expect(command.command).to eq("sudo -- gem install bundler")
     end
   end
 
@@ -23,11 +23,11 @@ describe Caliph::CommandLineDSL do
     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"
+      expect(command).to be_an_instance_of(Caliph::PipelineChain)
+      expect(command.commands.size).to eq(2)
+      expect(command.commands[0]).to be_an_instance_of(Caliph::CommandLine)
+      expect(command.commands[1]).to be_an_instance_of(Caliph::CommandLine)
+      expect(command.command).to eq("cat /etc/passwd | grep root")
     end
   end
 
@@ -38,11 +38,11 @@ describe Caliph::CommandLineDSL do
     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 *"
+      expect(command).to be_an_instance_of(Caliph::PrereqChain)
+      expect(command.commands.size).to eq(2)
+      expect(command.commands[0]).to be_an_instance_of(Caliph::CommandLine)
+      expect(command.commands[1]).to be_an_instance_of(Caliph::CommandLine)
+      expect(command.command).to eq("cd /tmp/trash && rm -rf *")
     end
   end
 end

data/spec/command-line.rb

@@ -13,15 +13,15 @@ describe Caliph::CommandLine do
   end
 
   it "should have a name set" do
-    commandline.name.should == "echo"
+    expect(commandline.name).to eq("echo")
   end
 
   it "should produce a command string" do
-    commandline.command.should == "echo -n Some text"
+    expect(commandline.command).to eq("echo -n Some text")
   end
 
   it "should succeed" do
-    commandline.succeeds?.should be_true
+    expect(commandline.succeeds?).to be_truthy
   end
 
   it "should not complain about success" do
@@ -44,11 +44,11 @@ describe Caliph::CommandLine, "setting environment variables" do
   end
 
   it "should succeed" do
-    result.succeeded?.should be_true
+    expect(result.succeeded?).to be_truthy
   end
 
   it "should alter the command's environment variables" do
-    result.stdout.should =~ /TEST_ENV.*indubitably/
+    expect(result.stdout).to match(/TEST_ENV.*indubitably/)
   end
 
 end
@@ -64,24 +64,24 @@ describe Caliph::CommandLine, 'redirecting' do
 
   it 'should allow redirect stdout' do
     commandline.redirect_stdout('some_file')
-    result.should =~ /1>some_file$/
+    expect(result).to match(/1>some_file$/)
   end
 
   it 'should allow redirect stderr' do
     commandline.redirect_stderr('some_file')
-    result.should =~ /2>some_file$/
+    expect(result).to match(/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/
+    expect(result).to match(/\b1>stdout_file\b/)
+    expect(result).to match(/\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/
+    expect(result).to match(/\b1>output_file\b/)
+    expect(result).to match(/\b2>output_file\b/)
   end
 end
 
@@ -100,31 +100,29 @@ describe Caliph::PipelineChain do
   end
 
   it "should produce the right command" do
-    commandline.command.should == 'env | cat'
+    expect(commandline.command).to eq('env | cat')
   end
 
   it "should produce a runnable command with format_string" do
-    commandline.string_format.should == 'TEST_ENV=indubitably env | cat'
+    expect(commandline.string_format).to eq('TEST_ENV=indubitably env | cat')
   end
 
   it "should succeed" do
-    result.succeeded?.should be_true
+    expect(result.succeeded?).to be_truthy
   end
 
   it "should alter the command's environment variables" do
-    result.stdout.should =~ /TEST_ENV.*indubitably/
+    expect(result.stdout).to match(/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
+    expect(commandline.succeeds?).to eq(false)
   end
 
   it "should raise error if succeed demanded" do

data/spec_help/spec_helper.rb

@@ -1,11 +1,17 @@
+require "codeclimate-test-reporter"
+CodeClimate::TestReporter.start
+
 require 'rspec'
 require 'rspec/core/formatters/base_formatter'
 
+$:.unshift("./lib")
+
 require 'caliph'
-require 'cadre/rspec'
+require 'cadre/rspec3'
 
 RSpec.configure do |config|
+  config.backtrace_inclusion_patterns = []
   config.run_all_when_everything_filtered = true
-  config.add_formatter(Cadre::RSpec::NotifyOnCompleteFormatter)
-  config.add_formatter(Cadre::RSpec::QuickfixFormatter)
+  config.add_formatter(Cadre::RSpec3::NotifyOnCompleteFormatter)
+  config.add_formatter(Cadre::RSpec3::QuickfixFormatter)
 end