shells 0.1.23 → 0.2.0

data/lib/shells/shell_base/debug.rb

@@ -0,0 +1,37 @@
+module Shells
+  class ShellBase
+
+    ##
+    # Sets the code to be run when debug messages are processed.
+    #
+    # The code will receive the debug message as an argument.
+    #
+    #   on_debug do |msg|
+    #     puts msg
+    #   end
+    #
+    def self.on_debug(proc = nil, &block)
+      add_hook :on_debug, proc, &block
+    end
+
+    protected
+
+    ##
+    # Processes a debug message.
+    def self.debug(msg) #:doc:
+      run_static_hook :on_debug, msg
+    end
+
+    ##
+    # Processes a debug message for an instance.
+    #
+    # This is processed synchronously.
+    def debug(msg) #:doc:
+      if have_hook?(:on_debug)
+        sync { self.class.debug msg }
+      end
+    end
+
+
+  end
+end

data/lib/shells/shell_base/exec.rb

@@ -0,0 +1,175 @@
+module Shells
+  class ShellBase
+
+    ##
+    # Gets the exit code from the last command if it was retrieved.
+    attr_accessor :last_exit_code
+    private :last_exit_code=
+
+    add_hook :on_before_run do |sh|
+      sh.instance_eval do
+        self.last_exit_code = nil
+      end
+    end
+
+    add_hook :on_after_run do |sh|
+      sh.instance_eval do
+        self.last_exit_code = nil
+      end
+    end
+
+    ##
+    # Executes a command during the shell session.
+    #
+    # If called outside of the +new+ block, this will raise an error.
+    #
+    # The +command+ is the command to execute in the shell.
+    #
+    # The +options+ can be used to override the exit code behavior.
+    # In all cases, the :default option is the same as not providing the option and will cause +exec+
+    # to inherit the option from the shell's options.
+    #
+    # +retrieve_exit_code+::
+    #       This can be one of :default, true, or false.
+    # +on_non_zero_exit_code+::
+    #       This can be on ot :default, :ignore, or :raise.
+    # +silence_timeout+::
+    #       This can be :default or the number of seconds to wait in silence before timing out.
+    # +command_timeout+::
+    #       This can be :default or the maximum number of seconds to wait for a command to finish before timing out.
+    #
+    # If provided, the +block+ is a chunk of code that will be processed every time the
+    # shell receives output from the program.  If the block returns a string, the string
+    # will be sent to the shell.  This can be used to monitor processes or monitor and
+    # interact with processes.  The +block+ is optional.
+    #
+    #   shell.exec('sudo -p "password:" nginx restart') do |data,type|
+    #     return 'super-secret' if /password:$/.match(data)
+    #     nil
+    #   end
+    #
+    def exec(command, options = {}, &block)
+      raise Shells::NotRunning unless running?
+
+      options ||= {}
+      options = { timeout_error: true, get_output: true }.merge(options)
+      options = self.options.merge(options.inject({}) { |m,(k,v)| m[k.to_sym] = v; m })
+      options[:retrieve_exit_code] = self.options[:retrieve_exit_code] if options[:retrieve_exit_code] == :default
+      options[:on_non_zero_exit_code] = self.options[:on_non_zero_exit_code] unless [:raise, :ignore].include?(options[:on_non_zero_exit_code])
+      options[:silence_timeout] = self.options[:silence_timeout] if options[:silence_timeout] == :default
+      options[:command_timeout] = self.options[:command_timeout] if options[:command_timeout] == :default
+      options[:command_is_echoed] = true if options[:command_is_echoed].nil?
+      ret = ''
+
+      merge_local_buffer do
+        begin
+          # buffer while also passing data to the supplied block.
+          if block_given?
+            buffer_output(&block)
+          end
+
+          command = command.to_s
+
+          # send the command and wait for the prompt to return.
+          debug 'Queueing command: ' + command
+          queue_input command + line_ending
+          if wait_for_prompt(options[:silence_timeout], options[:command_timeout], options[:timeout_error])
+            # get the output of the command, minus the trailing prompt.
+            ret =
+                if options[:get_output]
+                  debug 'Reading output of command...'
+                  command_output command, options[:command_is_echoed]
+                else
+                  ''
+                end
+
+            if options[:retrieve_exit_code]
+              self.last_exit_code = get_exit_code
+              if options[:on_non_zero_exit_code] == :raise
+                raise NonZeroExitCode.new(last_exit_code) unless last_exit_code == 0 || last_exit_code == :undefined
+              end
+            else
+              self.last_exit_code = nil
+            end
+          else
+            # A timeout occurred and timeout_error was set to false.
+            self.last_exit_code = :timeout
+            ret = output
+          end
+
+        ensure
+          # return buffering to normal.
+          if block_given?
+            buffer_output
+          end
+
+        end
+      end
+
+      ret
+    end
+
+    ##
+    # Executes a command specifically for the exit code.
+    #
+    # Does not return the output of the command, only the exit code.
+    def exec_for_code(command, options = {}, &block)
+      options = (options || {}).merge(retrieve_exit_code: true, on_non_zero_exit_code: :ignore)
+      exec command, options, &block
+      last_exit_code
+    end
+
+    ##
+    # Executes a command ignoring any exit code.
+    #
+    # Returns the output of the command and does not even retrieve the exit code.
+    def exec_ignore_code(command, options = {}, &block)
+      options = (options || {}).merge(retrieve_exit_code: false, on_non_zero_exit_code: :ignore)
+      exec command, options, &block
+    end
+
+    protected
+
+    ##
+    # Gets the output from a command.
+    def command_output(command, expect_command = true)  #:doc:
+      # get everything except for the ending prompt.
+      ret =
+          if (prompt_pos = (output =~ prompt_match))
+            output[0...prompt_pos]
+          else
+            output
+          end
+
+      if expect_command
+        command_regex = command_match(command)
+
+        # Go until we run out of data or we find one of the possible command starts.
+        # Note that we EXPECT the command to the first line of the output from the command because we expect the
+        # shell to echo it back to us.
+        result_cmd,_,result_data = ret.partition("\n")
+        until result_data.to_s.strip == '' || result_cmd.strip =~ command_regex
+          result_cmd,_,result_data = result_data.partition("\n")
+        end
+
+        if result_cmd.nil? || !(result_cmd =~ command_regex)
+          STDERR.puts "SHELL WARNING: Failed to match #{command_regex.inspect}."
+        end
+
+        result_data
+      else
+        ret
+      end
+    end
+
+    private
+
+    def command_match(command)
+      p = regex_escape options[:prompt]
+      c = regex_escape command
+      /\A(?:#{p}\s*)?#{c}[ \t]*\z/
+    end
+
+
+  end
+end

data/lib/shells/shell_base/hooks.rb

@@ -0,0 +1,83 @@
+module Shells
+  class ShellBase
+
+    private
+
+    def self.hooks
+      @hooks ||= {}
+    end
+
+    def self.parent_hooks(name)
+      superclass.respond_to?(:all_hooks, true) ? superclass.send(:all_hooks, name) : []
+    end
+
+    def self.all_hooks(name)
+      parent_hooks(name) + (hooks[name] || [])
+    end
+
+    protected
+
+    ##
+    # Adds a hook method to the class.
+    #
+    # A hook method should return :break if it wants to cancel executing any other hook methods in the chain.
+    def self.add_hook(hook_name, proc = nil, &block) #:doc:
+      hooks[hook_name] ||= []
+
+      if proc.respond_to?(:call)
+        hooks[hook_name] << proc
+      elsif proc.is_a?(Symbol) || proc.is_a?(String)
+        if self.respond_to?(proc, true)
+          hooks[hook_name] << method(proc.to_sym)
+        end
+      elsif proc
+        raise ArgumentError, 'proc must respond to :call method or be the name of a static method in this class'
+      end
+
+      if block
+        hooks[hook_name] << block
+      end
+
+    end
+
+
+
+    ##
+    # Runs a hook statically.
+    #
+    # The arguments supplied are passed to the hook methods directly.
+    #
+    # Return false unless the hook was executed.  Returns :break if one of the hook methods returns :break.
+    def self.run_static_hook(hook_name, *args)
+      list = all_hooks(hook_name)
+      list.each do |hook|
+        result = hook.call(*args)
+        return :break if result == :break
+      end
+      list.any?
+    end
+
+    ##
+    # Runs a hook in the current shell instance.
+    #
+    # The hook method is passed the shell as the first argument then the arguments passed to this method.
+    #
+    # Return false unless the hook was executed.  Returns :break if one of the hook methods returns :break.
+    def run_hook(hook_name, *args)
+      list = self.class.all_hooks(hook_name)
+      shell = self
+      list.each do |hook|
+        result = hook.call(shell, *args)
+        return :break if result == :break
+      end
+      list.any?
+    end
+
+    ##
+    # Returns true if there are any hooks to run.
+    def have_hook?(hook_name)
+      self.class.all_hooks(hook_name).any?
+    end
+
+  end
+end

data/lib/shells/shell_base/input.rb

@@ -0,0 +1,50 @@
+module Shells
+  class ShellBase
+
+    attr_accessor :input_fifo
+    private :input_fifo, :input_fifo
+
+    add_hook :on_before_run do |sh|
+      sh.instance_eval do
+        self.input_fifo = []
+      end
+    end
+
+    add_hook :on_after_run do |sh|
+      sh.instance_eval do
+        self.input_fifo = nil
+      end
+    end
+
+    ##
+    # Defines the line ending used to terminate commands sent to the shell.
+    #
+    # The default is "\n".  If you need "\r\n", "\r", or some other value, simply override this function.
+    def line_ending
+      "\n"
+    end
+
+    protected
+
+    ##
+    # Adds input to be sent to the shell.
+    def queue_input(data) #:doc:
+      sync do
+        if options[:unbuffered_input]
+          data = data.chars
+          input_fifo.push *data
+        else
+          input_fifo.push data
+        end
+      end
+    end
+
+    private
+
+    def next_input
+      sync { input_fifo.shift }
+    end
+
+
+  end
+end

data/lib/shells/shell_base/interface.rb

@@ -0,0 +1,149 @@
+module Shells
+  class ShellBase
+
+    protected
+
+    ##
+    # Sets up the shell session.
+    #
+    # This method is called after connecting the shell before the session block is run.
+    #
+    # By default this method will wait for the prompt to appear in the output.
+    #
+    # If you need to set the prompt, you would want to do it here.
+    def setup #:doc:
+      setup_prompt
+    end
+
+    ##
+    # Sets up the prompt for the shell session.
+    #
+    # By default this method will wait for the prompt to appear in the output.
+    #
+    # If you need to set the prompt, you would want to do it here.
+    def setup_prompt #:doc:
+      wait_for_prompt 30, 30, true
+    end
+
+
+    ##
+    # Tears down the shell session.
+    #
+    # This method is called after the session block is run before disconnecting the shell.
+    #
+    # The default implementation simply sends the quit command to the shell and waits up to 1 second for a result.
+    #
+    # This method will be called even if an exception is raised during the session.
+    def teardown #:doc:
+      unless options[:quit].to_s.strip == ''
+        self.ignore_io_error = true
+        exec_ignore_code options[:quit], command_timeout: 1, timeout_error: false
+      end
+    end
+
+    ##
+    # Connects to the shell.
+    #
+    # You must define this method in your subclass.
+    def connect #:doc:
+      raise ::NotImplementedError
+    end
+
+    ##
+    # Disconnects from the shell.
+    #
+    # You must define this method in your subclass.
+    # This method will always be called, even if an exception occurs during the session.
+    def disconnect #:doc:
+      raise ::NotImplementedError
+    end
+
+    ##
+    # Determines if the shell is currently active.
+    #
+    # You must define this method in your subclass.
+    def active? #:doc:
+      raise ::NotImplementedError
+    end
+
+    ##
+    # Runs the IO loop on the shell while the block returns true.
+    #
+    # You must define this method in your subclass.
+    # It should block for as little time as necessary before yielding to the block.
+    def io_loop(&block) #:doc:
+      raise ::NotImplementedError
+    end
+
+    ##
+    # Sends data to the shell.
+    #
+    # You must define this method in your subclass.
+    #
+    # It is important that this method not be called directly outside of the +run+ method.
+    # Use +queue_input+ to send data to the shell so that it can be handled in a synchronous manner.
+    def send_data(data) #:doc:
+      raise ::NotImplementedError
+    end
+
+    ##
+    # Register a callback to run when stdout data is received.
+    #
+    # The block will be passed the data received.
+    #
+    # You must define this method in your subclass and it should set a hook to be called when data is received.
+    #
+    #   def stdout_received
+    #     @conn.on_stdout do |data|
+    #       yield data
+    #     end
+    #   end
+    #
+    def stdout_received(&block) #:doc:
+      raise ::NotImplementedError
+    end
+
+    ##
+    # Register a callback to run when stderr data is received.
+    #
+    # The block will be passed the data received.
+    #
+    # You must define this method in your subclass and it should set a hook to be called when data is received.
+    #
+    #   def stderr_received
+    #     @conn.on_stderr do |data|
+    #       yield data
+    #     end
+    #   end
+    #
+    def stderr_received(&block) #:doc:
+      raise ::NotImplementedError
+    end
+
+    ##
+    # Gets the exit code from the last command.
+    #
+    # You must define this method in your subclass to utilize exit codes.
+    def get_exit_code #:doc:
+      self.last_exit_code = :undefined
+    end
+
+    public
+
+    ##
+    # Reads from a file on the device.
+    def read_file(path)
+      nil
+    end
+
+    ##
+    # Writes to a file on the device.
+    def write_file(path, data)
+      false
+    end
+
+
+
+
+  end
+end