command-set 0.8.0

data/lib/command-set/interpreter.rb

@@ -0,0 +1,196 @@
+require 'logger'
+
+module Command
+  #This is the base interpreter class.  By itself it'll raise a bunch of
+  #NoMethodErrors.  
+  #
+  #Interpreters manage the Subject object(s) and CommandSet and process
+  #input.  
+  #
+  #Subclasses of BaseInterpreter (like TextInterpreter, for
+  #instance, must implement #cook_input(raw) that converts raw input (of 
+  #whatever form is appropriate to the interpreter) into CommandSetup
+  #objects.  Other methods can be overridden - especially consider
+  # #get_formatter, #prompt_user, and #assign_terms
+  class BaseInterpreter
+    attr_accessor :command_set, :out_io, :logger
+    attr_reader :subject
+
+    #:section: Client app methods
+
+    #Subject has an intentionally very tight interface (q.v.) the gist of
+    #which is that you can only assign to fields that commands require, and
+    #you can only access fields within a command that you declared that
+    #command required.  
+    def subject_template
+      raise "CommandSet unset!" if @command_set.nil?
+      return prep_subject(get_subject)
+    end
+
+    #Before running an interpreter on input, you must set the subject.
+    #Get a subject object by calling subject_template, assign it's fields,
+    #and then pass it into subject=
+    def subject= (subject)
+      begin
+        subject.get_image(subject_requirements())
+      rescue CommandException
+        prep_subject(subject)
+      end
+
+      subject.verify
+      @subject = subject
+    end
+
+    #Any options that the interpreter might have can be set by passing a
+    #hash to behavior to be merged with the defaults
+    def behavior(hash)
+      @behavior.merge!(hash)
+    end
+
+    def initialize
+      @command_set=nil
+      @sub_modes = []
+      @behavior = {
+        :screen_width => 76,
+        :warn_no_undo => true
+      }
+      @out_io = $stdout
+      @stop = false
+      @subject = nil
+      @logger = Logger.new($stderr)
+      @logger.level=Logger::FATAL
+      @undo_stack = UndoStack.new
+      @commands_pending = []
+      @pause_decks = Hash.new {|h,k| h[k]=[]}
+    end
+
+    #:section: Command behavior related method
+
+    #  Puts a CommandSet ahead of the current one for processing.  Useful for command
+    #  modes, like Cisco's IOS with configure modes, et al.
+    def push_mode(mode)
+      unless CommandSet === mode
+        raise RuntimeError, "Sub-modes must be CommandSets!" 
+      end
+
+      @sub_modes.push(mode)
+      return nil
+    end
+
+    #  The compliment to #push_mode.  Removes the most recent command set.
+    def pop_mode
+      @sub_modes.pop
+      return nil
+    end
+
+    #:section: Extension related methods
+
+    #If your interpreter needs extra fields in the subject, alter
+    #subject_requirements to return an array of those fields.
+    def subject_requirements
+      return [:undo_stack, :interpreter_behavior, 
+        :chain_of_command, :pause_decks]
+    end
+
+    def get_subject
+      return Subject.new
+    end
+
+    #This method sets up the fields in the subject required by the
+    #interpreter.
+    def prep_subject(subject)
+      @command_set.add_requirements(subject)
+      subject.required_fields(*subject_requirements())
+      subject.undo_stack = @undo_stack
+      subject.interpreter_behavior = @behavior
+      subject.chain_of_command = @commands_pending
+      subject.pause_decks = @pause_decks
+      return subject
+    end
+
+    #Gets the next command in the queue - related to DSL::Action#chain.
+    #You'll almost never want to override this method.
+    def next_command
+      setup = @commands_pending.shift
+      return setup.command_instance(current_command_set, build_subject)
+    end
+
+    #Present +message+ to the user, and get a response - usually yes or no.
+    #Non-interactive interpreters, or ones where that level of interaction
+    #is undesirable should not override this method, which returns "no".
+    def prompt_user(message)
+       "no"
+    end
+
+    #Process a single unit of input from the user.  Relies on cook input to
+    #convert +raw_input+ into a CommandSetup
+    def process_input(raw_input)
+      @commands_pending << cook_input(raw_input)
+
+      presenter = Results::Presenter.new
+      formatter = get_formatter
+      presenter.register_formatter(formatter)
+      collector = presenter.create_collector
+
+      begin
+        raise "Ack!  No OutputStandin in place!" unless $stdout.respond_to?(:add_dispatcher)
+        $stdout.add_dispatcher(collector)
+        until @commands_pending.empty?
+          cmd = next_command
+          if ( @behavior[:warn_no_undo] and not cmd.undoable? )
+            confirm = prompt_user("\"#{raw_input}\" cannot be undone.  Continue? ")
+            if not ["yes", "y", "sure", "i suppose", "okay"].include? confirm.strip.downcase
+              return
+            end
+          end
+          begin
+            execute(cmd, formatter, collector)
+          rescue CommandException => ce
+            ce.command = cmd
+            raise
+          rescue ResumeFrom => rf
+            deck = rf.pause_deck
+            @pause_decks[deck].push rf.setup
+            raise unless ResumeFromOnlyThis === rf
+          end
+        end
+      rescue ResumeFrom => rf
+        @pause_decks[deck] += @commands_pending
+      rescue CommandException => ce
+        ce.raw_input = raw_input
+        raise
+      ensure
+        $stdout.remove_dispatcher(collector)
+      end
+      presenter.done
+
+      @commands_pending.clear
+    end
+
+    #Gets the final Results::Formatter object to output to.  Override this
+    #if you won't be reporting output to the standard output.
+    def get_formatter
+      return Results::Formatter.new(::Command::raw_stdout)
+    end
+
+    protected
+
+    def execute(command, formatter, collector)
+      command.advise_formatter(formatter)
+      command.go(collector)
+      return nil
+    end
+
+    def current_command_set
+      return @command_set if @sub_modes.empty?
+      return @sub_modes.last
+    end
+
+    def build_subject
+      if @subject.nil?
+        subject=(subject_template())
+      end
+      return @subject
+    end
+  end
+end