command-set 0.8.0

data/lib/command-set/command.rb

@@ -0,0 +1,456 @@
+require 'command-set/arguments'
+module Command
+
+  #A thin wrapper on Array to maintain undo/redo state.
+  class UndoStack
+    def initialize()
+      @stack = []
+      @now = 0
+    end
+
+    def add(cmd)
+      @stack.slice!(0,@now)
+      @now=0
+      @stack.unshift(cmd)
+    end
+
+    def get_undo
+      if @now > (@stack.length - 1) or @stack.length == 0
+        raise CommandException, "No more commands to undo" 
+      end
+      cmd = @stack[@now]
+      @now+=1
+      return cmd
+    end  
+
+    def get_redo
+      if @now <= 0
+        raise CommandException, "Can't redo"
+      end
+      @now-=1
+      return @stack[@now]
+    end
+  end
+
+  #An abstraction of the lifecycle of a command.  Allows invocations to be
+  #postponed temporarily, or for the command to be instantiated and still
+  #passed around.  Client code should almost never need to see this class,
+  #so the methods aren't individually documented.
+  class CommandSetup
+    def initialize(cmd = [], args = {})
+      @task_id = nil
+      @args_hash = args
+      @terms = []
+      @command = cmd
+    end
+
+    attr_accessor :task_id, :command, :args_hash, :terms
+
+    def resolve_command_class(command_set)
+      if Class === @command && Command > @command
+        return @command
+      end
+
+      command_path = @command
+      @command,terms = command_set.find_command(*command_path)
+
+      if CommandSet === @command
+        if (cmd = @command.get_root).nil?
+          raise CommandException, "Incomplete command #{command_path.join(" ")}"
+        else
+          terms = [@command]
+          @command = cmd
+        end
+      end
+
+      @terms = terms
+
+      return @command
+    end
+
+    def assign_terms(cmd)
+      terms = @terms.dup
+      cmd.each_consumer do |consumer|
+        terms = consumer[terms]
+      end
+
+      cmd.consume_hash(@args_hash)
+    end
+
+    def command_instance(command_set, subject)
+      command_class = resolve_command_class(command_set)
+      command = command_class.new(subject, task_id)
+      assign_terms(command)
+      return command
+    end
+  end
+
+  #An overworked exception class.  It captures details about the command
+  #being interrupted as it propagates up the stack.
+  class ResumeFrom < ::Exception; 
+    def initialize(pause_deck = nil, msg = "")
+      super(msg)
+      @setup = CommandSetup.new
+      @pause_deck = pause_deck
+    end
+
+    attr_reader :setup, :pause_deck
+  end
+
+  class ResumeFromOnlyThis < ResumeFrom; end
+
+  class Command
+    @name = "unnamed command"
+    @parent = nil
+    @argument_list=[]
+    @doc_text = nil
+    @subject_requirements=[:chain_of_command]
+    @defined = false
+    @advice_block = proc {}
+    class << self
+      alias_method :instance, :new
+
+      attr_reader :name, :argument_list
+      alias_method :required_argument_list, :argument_list 
+      alias_method :optional_argument_list, :argument_list 
+      attr_reader :doc_text, :subject_requirements, :defined, :advice_block
+      attr_accessor :parent
+
+      def inherited(subclass)
+        subclass.instance_variable_set("@name", name.dup)
+        subclass.instance_variable_set("@argument_list", argument_list.dup )
+        subclass.instance_variable_set("@doc_text", doc_text.dup) unless doc_text.nil?
+        subclass.instance_variable_set("@subject_requirements", subject_requirements.dup)
+        subclass.instance_variable_set("@defined", false)
+        subclass.instance_variable_set("@advice_block", advice_block.dup)
+      end
+
+      #Establishes a subclass of Command.  This is important because commands are actually
+      #classes in CommandSet; their instances are specific executions of the command, which 
+      #allows for undo's, and history management.
+      #The block will get run in the context of the new class, allowing you to quickly 
+      #define the class completely.
+      #
+      #For examples, see Command::StandardCommands
+      def setup(parent, new_name=nil, &block)
+
+        unless parent.nil? or CommandSet === parent
+          raise RuntimeError, "Command parents must be CommandSets or nil"
+        end
+
+        command_class = Class.new(self)
+        new_name = new_name.to_s
+        #Of interest: klass.instance_eval { def method } creates klass::method
+        #but klass.class_eval { def method } creates klass#method
+
+        command_class.instance_variable_set("@name", new_name)
+        command_class.instance_variable_set("@parent", parent)
+
+        command_class.instance_eval &block
+
+        command_class.defined
+        return command_class
+      end
+
+      def defined
+        @defined = true
+      end
+
+      def defined?
+        return @defined
+      end
+
+      def inspect
+        arguments = []
+        [required_argument_list, optional_argument_list].each do |list|
+          next if list.nil?
+          list.each do |argument|
+            arguments << argument.name
+          end
+        end
+        return "#<Class:#{self.object_id} - Command:#{path().join(" ")}(#{arguments.join(", ")})>"
+      end
+
+      def path
+        if @parent.nil?
+          [@name]
+        else
+          @parent.path + [@name]
+        end
+      end
+
+      def documentation(width, parent="")
+        if @doc_text.nil?
+          return short_docs(width)
+        else
+          return short_docs(width) + 
+            ["\n"] + @doc_text.wrap(width)
+        end
+      end
+
+      def short_docs(width, parent="")
+        docs = ((parent.empty? ? [name]:[parent, name]) + required_argument_list.map do |arg|
+          "<#{arg.name}> "
+        end + optional_argument_list.map do |arg|
+          "[<#{arg.name}>]"
+        end).join(" ")
+
+        return docs.wrap(width)
+      end
+
+      def add_requirements(subject)
+        subject.required_fields(*(@subject_requirements.uniq))
+      end
+
+      def completion_list(terms, prefix, subject)
+        arguments = argument_list.dup
+
+        until(terms.empty? or arguments.empty?) do
+          arguments.first.match_terms(subject, terms, arguments)
+        end
+
+        completion = []
+        arguments.each do |handler|
+          completion += handler.complete(prefix, subject)
+          break unless handler.omittable?
+        end 
+        return completion
+      end
+
+      def create_argument_methods(name)
+        define_method(name) do
+          @arg_hash[name]
+        end
+        private(name)
+
+        define_method(name.to_s + "=") do |value|
+          @arg_hash[name] = value
+        end
+        private(name.to_s + "=")
+      end
+
+      def embed_argument(arg)
+        names = [*arg.name]
+
+        names.each do |name|
+          create_argument_methods(name)
+        end
+
+        unless argument_list.last.nil? or argument_list.last.required?
+          if arg.required?
+            raise NoMethodError, "Can't define required arguments after optionals"
+          end
+        end
+
+        argument_list << arg
+      end
+
+      def optional_argument(arg, values=nil, &get_values)
+        optional.argument(arg, values, &get_values)
+      end
+
+      def optional_arguments(name, &block)
+        optional.multiword_argument(name, block)
+      end
+
+      def no_more_required_arguments(*args) #:nodoc:
+        raise NoMethodError, "Can't define required arguments after optionals"
+      end
+      private :no_more_required_arguments
+
+      def stop_requireds #:nodoc:
+        class << self
+          alias_method :argument, :no_more_required_arguments
+          def stop_requireds
+          end
+        end
+      end
+      private :stop_requireds
+    end
+
+    extend DSL::CommandDefinition
+    extend DSL::Argument
+    include DSL::Action
+
+    def initialize(subject, resume=nil)
+      raise CommandException, "#{@name}: unrecognized command" unless self.class.defined?
+      fields = subject_requirements || []
+      @subject = subject.get_image(fields)
+      @puts_box = nil
+      @puts_lock = Mutex.new
+      @arg_hash = {}
+      @should_undo = true
+      @validation_problem = CommandException.new("No arguments provided!")
+      @last_completed_task = nil
+      @resume_from = resume
+      @main_collector = collector
+    end
+
+    attr_reader :arg_hash
+
+    def name
+      self.class.name
+    end
+
+    def required_arguments
+      self.class.argument_list.find_all do |arg|
+        arg.required?
+      end
+    end
+
+    def optional_arguments
+      self.class.argument_list.find_all do |arg|
+        not arg.required?
+      end
+    end
+
+    def all_arguments
+      self.class.argument_list
+    end
+
+    def subject_requirements
+      self.class.subject_requirements
+    end
+
+    def inspect
+      name = self.class.name
+      return "#<Command:#{name}>:#{self.object_id} #{@arg_hash.inspect}"
+    end
+
+    def parent
+      self.class.parent
+    end
+
+    def go(collector)
+      unless self.respond_to? :execute
+        raise CommandException, "#{@name}: command declared but no action defined" 
+      end
+
+      @main_collector = collector
+      begin
+        validate_arguments
+        verify_subject
+        execute
+        join_undo
+      rescue Interrupt
+        puts "Command cancelled"
+      rescue ResumeFrom => rf
+        rf.setup.task_id = @last_completed_task
+        raise rf
+      end
+    end
+
+    def advise_formatter(formatter)
+      formatter.receive_advice(&self.class.advice_block)
+    end
+
+    def verify_subject
+      return if subject_requirements.nil?
+      subject_requirements.each do |requirement|
+        begin
+          if Subject::UndefinedField === @subject.send(requirement)
+            raise CommandException, "\"#{name}\" requires \"#{requirement.to_s}\" to be set"
+          end
+        rescue NameError => ne
+          raise CommandException, "\"#{name}\" requires subject to include \"#{requirement.to_s}\""
+        end
+      end
+    end
+
+    def consume_hash(args_hash)
+      allowed_arguments = all_arguments.inject([]) do |allowed, argument|
+        allowed += [*argument.name]
+      end
+
+      wrong_values = {}
+      required_names = []
+
+      args_hash.keys.each do |name|
+        args_hash[name.to_s] = args_hash[name]
+      end
+
+      all_arguments.each do |argument|
+        begin
+          @arg_hash.merge! argument.consume_hash(@subject, args_hash)
+        rescue ArgumentInvalidException => aie
+          wrong_values.merge! aie.pairs
+        rescue OutOfArgumentsException
+          required_names += ([*argument.name].find_all {|name| not @arg_hash.has_key?(name)})
+        end
+      end
+
+      wrong_names = @arg_hash.keys - allowed_arguments
+
+      unless wrong_values.empty?
+        aie = ArgumentInvalidException.new(wrong_values)
+        @validation_problem = aie
+        raise aie
+      end
+
+      unless wrong_names.empty?
+        aue = ArgumentUnrecognizedException.new("Unrecognized arguments: #{wrong_names.join(", ")}")
+        @validation_problem = aue
+        raise aue
+      end
+
+      unless required_names.empty?
+        ooae = OutOfArgumentsException.new("Missing arguments: #{required_names.join(", ")}")
+        @validation_problem = ooae
+        raise ooae
+      end
+
+      @validation_problem = nil
+    end
+
+    def yield_consumer(argument, &block)
+      blk = proc(&block)
+      consumer = proc do |args|
+        raise TypeError, "#{args.inspect} isn't an Array!" unless Array === args
+        begin
+          if args.empty?
+            raise OutOfArgumentsException, "argument #{argument.inspect} required!"
+          end
+          @arg_hash.merge! argument.consume(@subject, args)
+          return args
+        rescue ArgumentInvalidException => aie
+          @validation_problem = aie
+          raise
+        end
+      end
+      blk[consumer]
+    end
+
+    def each_consumer(&block)
+      begin
+        all_arguments.each do |argument|
+          yield_consumer(argument, &block)
+        end
+      rescue OutOfArgumentsException
+      end
+      @validation_problem = nil
+    end
+
+    def undoable?
+      return false
+    end
+
+    def join_undo
+      if(undoable? && @should_undo && subject.undo_stack != nil) 
+        subject.undo_stack.add(self)
+      end
+      return nil
+    end
+
+    def collector
+    end
+
+    def validate_arguments
+      raise @validation_problem if Exception === @validation_problem
+      required_arguments.each do |argument|
+        argument.check_present(@arg_hash.keys)
+      end
+    end
+  end
+end
+
+