shells 0.1.23 → 0.2.0

data/lib/shells/shell_base/options.rb

@@ -0,0 +1,111 @@
+module Shells
+  class ShellBase
+
+    ##
+    # The options provided to this shell.
+    #
+    # This hash is read-only.
+    attr_accessor :options
+    private :options=
+
+    attr_accessor :orig_options
+    private :orig_options, :orig_options=
+
+    add_hook :on_after_run do |sh|
+      sh.instance_eval do
+        self.options = orig_options
+      end
+    end
+
+    ##
+    # Validates the options provided to the class.
+    #
+    # You should define this method in your subclass.
+    def validate_options #:doc:
+      warn "The validate_options() method is not defined on the #{self.class} class."
+    end
+    protected :validate_options
+
+
+    ##
+    # Initializes the shell with the supplied options.
+    #
+    # These options are common to all shells.
+    # +prompt+::
+    #       Defaults to "~~#".  Most special characters will be stripped.
+    # +retrieve_exit_code+::
+    #       Defaults to false. Can also be true.
+    # +on_non_zero_exit_code+::
+    #       Defaults to :ignore. Can also be :raise.
+    # +silence_timeout+::
+    #       Defaults to 0.
+    #       If greater than zero, will raise an error after waiting this many seconds for a prompt.
+    # +command_timeout+::
+    #       Defaults to 0.
+    #       If greater than zero, will raise an error after a command runs for this long without finishing.
+    # +unbuffered_input+::
+    #       Defaults to false.
+    #       If non-false, then input is sent one character at a time, otherwise input is sent in whole strings.
+    #       If set to :echo, then input is sent one character at a time and the character must be echoed back
+    #       from the shell before the next character will be sent.
+    #
+    # Please check the documentation for each shell class for specific shell options.
+    def initialize(options = {}, &block)
+
+      # cannot instantiate a ShellBase
+      raise NotImplementedError if self.class == Shells::ShellBase
+
+      raise ArgumentError, '\'options\' must be a hash.' unless options.is_a?(Hash)
+
+      self.options = {
+          prompt: '~~#',
+          retrieve_exit_code: false,
+          on_non_zero_exit_code: :ignore,
+          silence_timeout: 0,
+          command_timeout: 0,
+          unbuffered_input: false
+      }.merge( options.inject({}){ |m,(k,v)|  m[k.to_sym] = v; m } )
+
+      self.options[:prompt] = self.options[:prompt]
+                              .to_s.strip
+                              .gsub('!', '#')
+                              .gsub('$', '#')
+                              .gsub('\\', '.')
+                              .gsub('/', '.')
+                              .gsub('"', '-')
+                              .gsub('\'', '-')
+
+      self.options[:prompt] = '~~#' if self.options[:prompt] == ''
+
+      raise Shells::InvalidOption, ':on_non_zero_exit_code must be :ignore or :raise.' unless [:ignore, :raise].include?(self.options[:on_non_zero_exit_code])
+
+      validate_options
+      self.options.freeze   # no more changes to options now.
+      self.orig_options = self.options  # sort of, we might provide helpers (like +change_quit+)
+
+      run_hook :on_init
+
+      # allow for backwards compatibility.
+      if block_given?
+        run &block
+      end
+
+    end
+
+
+    ##
+    # Allows you to change the :quit option inside of a session.
+    #
+    # This is useful if you need to change the quit command for some reason.
+    # e.g. - Changing the command to "reboot".
+    #
+    # Returns the shell instance.
+    def change_quit(quit_command)
+      raise Shells::NotRunning unless running?
+      self.options = options.dup.merge( quit: quit_command ).freeze
+      self
+    end
+
+
+  end
+end

data/lib/shells/shell_base/output.rb

@@ -0,0 +1,217 @@
+module Shells
+  class ShellBase
+
+    # used when the buffer is pushed/popped.
+    attr_accessor :output_stack
+    private :output_stack, :output_stack=
+
+    ##
+    # Gets the STDOUT contents from the session.
+    attr_accessor :stdout
+    private :stdout=
+
+    ##
+    # Gets the STDERR contents from the session.
+    attr_accessor :stderr
+    private :stderr=
+
+    ##
+    # Gets all of the output contents from the session.
+    attr_accessor :output
+    private :output=
+
+    ##
+    # Gets the last time output was received from the shell.
+    attr_accessor :last_output
+    protected :last_output
+    private :last_output=
+
+    ##
+    # The character string we are expecting to be echoed back from the shell.
+    attr_accessor :wait_for_output
+    private :wait_for_output, :wait_for_output
+
+    add_hook :on_before_run do |sh|
+      sh.instance_eval do
+        self.output_stack = []
+        self.stdout = ''
+        self.stderr = ''
+        self.output = ''
+        self.last_output = Time.now
+        self.wait_for_output = false
+      end
+    end
+
+    add_hook :on_after_run do |sh|
+      sh.instance_eval do
+        self.output_stack = nil
+        self.last_output = nil
+        self.wait_for_output = false
+      end
+    end
+
+    private
+
+    def strip_ansi_escape(data)
+      data
+          .gsub(/\e\[(\d+;?)*[ABCDEFGHfu]/, "\n")   #   any of the "set cursor position" CSI commands.
+          .gsub(/\e\[=?(\d+;?)*[A-Za-z]/,'')        #   \e[#;#;#A or \e[=#;#;#A  basically all the CSI commands except ...
+          .gsub(/\e\[(\d+;"[^"]+";?)+p/, '')        #   \e[#;"A"p
+          .gsub(/\e[NOc]./,'?')                     #   any of the alternate character set commands.
+          .gsub(/\e[P_\]^X][^\e\a]*(\a|(\e\\))/,'') #   any string command
+          .gsub(/[\x00\x08\x0B\x0C\x0E-\x1F]/, '')  #   any non-printable characters (notice \x0A (LF) and \x0D (CR) are left as is).
+          .gsub("\t", ' ')                          #   turn tabs into spaces.
+    end
+
+    def reduce_newlines(data)
+      data.gsub("\r\n", "\n").gsub(" \r", "").gsub("\r", "")
+    end
+
+    def append_stdout(data, &block)
+      # Combined output gets the prompts,
+      # but stdout will be without prompts.
+      data = reduce_newlines data
+      for_stdout = if (pos = (data =~ prompt_match))
+                     data[0...pos]
+                   else
+                     data
+                   end
+
+      sync do
+        self.stdout += for_stdout
+        self.output += data
+        self.wait_for_output = false
+      end
+
+      if block_given?
+        result = block.call(for_stdout, :stdout)
+        if result && result.is_a?(String)
+          queue_input(result + line_ending)
+        end
+      end
+    end
+
+    def append_stderr(data, &block)
+      data = reduce_newlines data
+
+      sync do
+        self.stderr += data
+        self.output += data
+      end
+
+      if block_given?
+        result = block.call(data, :stderr)
+        if result && result.is_a?(String)
+          queue_input(result + line_ending)
+        end
+      end
+    end
+
+
+    protected
+
+    ##
+    # Sets the block to call when data is received.
+    #
+    # If no block is provided, then the shell will simply log all output from the program.
+    # If a block is provided, it will be passed the data as it is received.  If the block
+    # returns a string, then that string will be sent to the shell.
+    #
+    # This method is called internally in the +exec+ method, but there may be legitimate use
+    # cases outside of that method as well.
+    def buffer_output(&block) #:doc:
+      raise Shells::NotRunning unless running?
+      block ||= Proc.new { }
+      stdout_received do |data|
+        self.last_output = Time.now
+        append_stdout strip_ansi_escape(data), &block
+      end
+      stderr_received do |data|
+        self.last_output = Time.now
+        append_stderr strip_ansi_escape(data), &block
+      end
+    end
+
+    ##
+    # Executes the code block with a local output buffer, merging the local buffer into the parent buffer upon completion.
+    def merge_local_buffer(&block) #:doc:
+      push_buffer
+      begin
+        yield
+      ensure
+        pop_merge_buffer
+      end
+    end
+
+    ##
+    # Executes the code block with a local output buffer, discarding the local buffer upon completion.
+    def discard_local_buffer(&block) #:doc:
+      push_buffer
+      begin
+        yield
+      ensure
+        pop_discard_buffer
+      end
+    end
+
+    private
+
+    ##
+    # Pushes the buffers for output capture.
+    #
+    # This method is called internally in the +exec+ method, but there may be legitimate use
+    # cases outside of that method as well.
+    def push_buffer
+      raise Shells::NotRunning unless running?
+      # push the buffer so we can get the output of a command.
+      debug 'Pushing buffer >>'
+      sync do
+        output_stack.push [ stdout, stderr, output ]
+        self.stdout = ''
+        self.stderr = ''
+        self.output = ''
+      end
+    end
+
+    ##
+    # Pops the buffers and merges the captured output.
+    #
+    # This method is called internally in the +exec+ method, but there may be legitimate use
+    # cases outside of that method as well.
+    def pop_merge_buffer
+      raise Shells::NotRunning unless running?
+      # almost a standard pop, however we want to merge history with current.
+      debug 'Merging buffer <<'
+      sync do
+        hist_stdout, hist_stderr, hist_output = (output_stack.pop || [])
+        if hist_stdout
+          self.stdout = hist_stdout + stdout
+        end
+        if hist_stderr
+          self.stderr = hist_stderr + stderr
+        end
+        if hist_output
+          self.output = hist_output + output
+        end
+      end
+    end
+
+    ##
+    # Pops the buffers and discards the captured output.
+    #
+    # This method is used internally in the +get_exit_code+ method, but there may be legitimate use
+    # cases outside of that method as well.
+    def pop_discard_buffer
+      raise Shells::NotRunning unless running?
+      # a standard pop discarding current data and retrieving the history.
+      debug 'Discarding buffer <<'
+      sync do
+        hist_stdout, hist_stderr, hist_output = (output_stack.pop || [])
+        self.stdout = hist_stdout || ''
+        self.stderr = hist_stderr || ''
+        self.output = hist_output || ''
+      end
+    end
+
+  end
+end

data/lib/shells/shell_base/prompt.rb

@@ -0,0 +1,141 @@
+module Shells
+  class ShellBase
+
+    private
+
+    def prompt_match
+      @prompt_match
+    end
+
+    def prompt_match=(value)
+      # allow for trailing spaces or tabs, but no other whitespace.
+      @prompt_match =
+          if value.nil?
+            nil
+          elsif value.is_a?(::Regexp)
+            value
+          else
+            /#{regex_escape value.to_s}[ \t]*$/
+          end
+    end
+
+    add_hook :on_before_run do |sh|
+      sh.instance_eval do
+        self.prompt_match = options[:prompt]
+      end
+    end
+
+    add_hook :on_after_run do |sh|
+      sh.instance_eval do
+        self.prompt_match = nil
+      end
+    end
+
+    protected
+
+    ##
+    # Waits for the prompt to appear at the end of the output.
+    #
+    # Once the prompt appears, new input can be sent to the shell.
+    # This is automatically called in +exec+ so you would only need
+    # to call it directly if you were sending data manually to the
+    # shell.
+    #
+    # This method is used internally in the +exec+ method, but there may be legitimate use cases
+    # outside of that method as well.
+    def wait_for_prompt(silence_timeout = nil, command_timeout = nil, timeout_error = true) #:doc:
+      raise Shells::NotRunning unless running?
+
+      silence_timeout ||= options[:silence_timeout]
+      command_timeout ||= options[:command_timeout]
+
+      # when did we send a NL and how many have we sent while waiting for output?
+      nudged_at = nil
+      nudge_count = 0
+
+      silence_timeout = silence_timeout.to_s.to_f unless silence_timeout.is_a?(Numeric)
+      nudge_seconds =
+          if silence_timeout > 0
+            (silence_timeout / 3.0)  # we want to nudge twice before officially timing out.
+          else
+            0
+          end
+
+      # if there is a limit for the command timeout, then set the absolute timeout for the loop.
+      command_timeout = command_timeout.to_s.to_f unless command_timeout.is_a?(Numeric)
+      timeout =
+          if command_timeout > 0
+            Time.now + command_timeout
+          else
+            nil
+          end
+
+      # loop until the output matches the prompt regex.
+      # if something gets output async server side, the silence timeout will be handy in getting the shell to reappear.
+      # a match while waiting for output is invalid, so by requiring that flag to be false this should work with
+      # unbuffered input as well.
+      until output =~ prompt_match && !wait_for_output
+        # hint that we need to let another thread run.
+        Thread.pass
+
+        last_response = last_output
+
+        # Do we need to nudge the shell?
+        if nudge_seconds > 0 && (Time.now - last_response) > nudge_seconds
+          nudge_count = (nudged_at.nil? || nudged_at < last_response) ? 1 : (nudge_count + 1)
+
+          # Have we previously nudged the shell?
+          if nudge_count > 2  # we timeout on the third nudge.
+            raise Shells::SilenceTimeout if timeout_error
+            debug ' > silence timeout'
+            return false
+          else
+            nudged_at = Time.now
+
+            queue_input line_ending
+
+            # wait a bit longer...
+            self.last_output = nudged_at
+          end
+        end
+
+        # honor the absolute timeout.
+        if timeout && Time.now > timeout
+          raise Shells::CommandTimeout if timeout_error
+          debug ' > command timeout'
+          return false
+        end
+      end
+
+      # make sure there is a newline before the prompt, just to keep everything clean.
+      pos = (output =~ prompt_match)
+      if output[pos - 1] != "\n"
+        # no newline before prompt, fix that.
+        self.output = output[0...pos] + "\n" + output[pos..-1]
+      end
+
+      # make sure there is a newline at the end of STDOUT content buffer.
+      if stdout[-1] != "\n"
+        # no newline at end, fix that.
+        self.stdout += "\n"
+      end
+
+      true
+    end
+
+    ##
+    # Sets the prompt to the value temporarily for execution of the code block.
+    def temporary_prompt(prompt) #:doc:
+      raise Shells::NotRunning unless running?
+      old_prompt = prompt_match
+      begin
+        self.prompt_match = prompt
+        yield if block_given?
+      ensure
+        self.prompt_match = old_prompt
+      end
+    end
+
+
+  end
+end