command-set 0.9.2 → 0.10.0

data/lib/command-set/command.rb

@@ -1,5 +1,5 @@
 require 'command-set/arguments'
-require 'command-set/command-common'
+require 'command-set/structural'
 module Command
 
   #A thin wrapper on Array to maintain undo/redo state.
@@ -33,6 +33,7 @@ module Command
     end
   end
 
+=begin
   #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,
@@ -43,16 +44,25 @@ module Command
       @args_hash = args
       @terms = []
       @command = cmd
+      @execution_context = nil
     end
 
     attr_accessor :task_id, :command, :args_hash, :terms
 
+    def class_resolution(command_set, path, subject)
+      return command_set.process_terms(path, subject)
+    end
+
     def resolve_command_class(command_set, subject)
-      unless Class === @command && Command > @command
+      if @execution_context.nil? && Class === @command && Command > @command
+        @execution_context = TermProcessor.new(subject)
+      else
         command_path = @command
-        result = command_set.process_terms(command_path, subject)
-        @command = result.command_class
-        @args_hash = result.arg_hash.merge(@args_hash)
+        @execution_context = class_resolution(command_set, 
+                                              command_path, 
+                                              subject)
+        @command = @execution_context.command_class
+        @args_hash = @execution_context.arg_hash.merge(@args_hash)
         @terms = command_path
       end
 
@@ -61,15 +71,29 @@ module Command
 
     def command_instance(command_set, subject)
       command_class = resolve_command_class(command_set, subject)
-      command = command_class.new(subject, task_id)
+      command = command_class.new(@execution_context, task_id)
       command.consume_hash(@args_hash)
       return command
     end
   end
+=end
+
+  class AnchoredCommandSetup < CommandSetup
+    def initialize(command_set, cmd = [], args = {})
+      super(cmd, args)
+      @anchored_at = command_set
+    end
+
+    attr_accessor :anchored_at
+
+    def class_resolution(current_set)
+      @command_class = @anchored_at.find_command(@terms.dup)
+    end
+  end
 
   #An overworked exception class.  It captures details about the command
   #being interrupted as it propagates up the stack.
-  class ResumeFrom < ::Exception; 
+  class ResumeFrom < ::Exception 
     def initialize(pause_deck, msg = "")
       super(msg)
       @setup = CommandSetup.new
@@ -83,7 +107,7 @@ module Command
 
   module CommandClassMethods
     attr_reader :subject_requirements, :argument_list, 
-      :advice_block, :parent_arguments
+      :advice_block, :context
 
     def consume_terms(terms, subject, arg_hash)
       begin
@@ -123,27 +147,22 @@ module Command
     def optional_argument(arg, values=nil, &get_values)
       optional.argument(arg, values, &get_values)
     end
-
-    def factory
-      return self
-    end
   end
 
   class Command
     @name = "unnamed command"
-    @parent = nil
     @argument_list=[]
     @parent_arguments=[]
     @doc_text = nil
     @subject_requirements=[:chain_of_command]
     @defined = false
     @advice_block = proc {}
+    @context = []
 
     class << self
       alias_method :instance, :new
 
       attr_reader :name, :doc_text, :defined 
-      attr_accessor :parent
 
       def inherited(subclass)
         [ [:name, proc {name.dup}],
@@ -153,6 +172,7 @@ module Command
           [:subject_requirements, proc {subject_requirements.dup}],
           [:defined, proc {false}],
           [:advice_block, proc {advice_block.dup}],
+          [:context, proc {[]}]
         ].each do |var, prok|
           subclass.instance_variable_set("@#{var.to_s}", prok.call)
         end
@@ -163,6 +183,7 @@ module Command
         @argument_list = original.argument_list.dup
         @parent_arguments = original.parent_arguments.dup
         @subject_requirements = original.subject_requirements.dup
+        @context = []
       end
 
       #Establishes a subclass of Command.  This is important because commands are actually
@@ -172,17 +193,11 @@ module Command
       #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
-
+      def setup(new_name=nil, &block)
         command_class = Class.new(self)
         new_name = new_name.to_s
 
         command_class.instance_variable_set("@name", new_name)
-        command_class.instance_variable_set("@parent", parent)
 
         command_class.instance_eval &block
 
@@ -190,12 +205,16 @@ module Command
         return command_class
       end
 
-      def each_command(&block)
-        block.call(self)
+      def each_command(path, visitor)
+        visitor.arrive_at(path, self)
+      end
+
+      def parent_argument_list
+        @parent_arguments
       end
 
       def visit(terms, visitor)
-        result = visitor.arrive_at(terms, self)
+        visitor.arrive_at(terms, self)
 
         if(terms.empty?)
           return visitor.command_out_of_terms(self)
@@ -204,6 +223,8 @@ module Command
         end
       end
 
+      alias root_visit visit
+
       def single_consume(argument, arg_hash, subject, terms)
         arg_hash.merge! argument.consume(subject, terms)
       end
@@ -220,20 +241,20 @@ module Command
       def inspect
         arguments = argument_list.map{|arg| arg.name}
 
-        return "#<Class:#{"%#x" % self.object_id} - Command:#{path().join(" ")}(#{arguments.join(", ")})>"
+        return "#<Class:#{"%0#x" % self.object_id} - Command:#{name()}(#{arguments.join(", ")})>"
       end
 
-      def documentation(width, parent="")
+      def documentation(width, prefix=[])
         if @doc_text.nil?
-          return short_docs(width)
+          return short_docs(width, prefix)
         else
           return short_docs(width) + 
             ["\n"] + @doc_text.wrap(width)
         end
       end
 
-      def short_docs(width, parent="")
-        docs = [path]
+      def short_docs(width, prefix=[])
+        docs = prefix + [name]
         docs += argument_list.map do |arg|
           if arg.required?
             "<#{arg.name}>"
@@ -247,7 +268,7 @@ module Command
       end
 
       def create_argument_methods
-        names = (argument_list + parent_arguments).inject([]) do |list, arg|
+        names = argument_list.inject([]) do |list, arg|
           list + [*arg.names]
         end
 
@@ -263,6 +284,11 @@ module Command
           private(name.to_s + "=")
         end
       end
+
+      def push_context(part)
+        return unless Symbol === part
+        @context.unshift(part)
+      end
     end
 
     extend DSL::CommandDefinition
@@ -272,12 +298,19 @@ module Command
 
     class DontResume; end
 
-    def initialize(subject, resume=nil)
+    def initialize(execution_context, 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
+      @path = execution_context.command_path
+      @nesting = execution_context.set_nesting
+
+      @argument_list = self.class.argument_list.dup
+      @subject_requirements = self.class.subject_requirements.dup
+      resolve_parent_arguments
+
+      subject = execution_context.subject
+      context = execution_context.subject_context
+      @subject_image = subject.get_image(subject_requirements || [], context)
+
       @arg_hash = {}
       @should_undo = true
       @validation_problem = CommandException.new("No arguments provided!")
@@ -286,30 +319,67 @@ module Command
       @main_collector = nil
     end
 
-    attr_reader :arg_hash
+    def resolve_parent_arguments
+      missing = []
+      names = []
+      self.class.parent_argument_list.uniq.each do |name|
+        found = nil
+        @nesting.reverse.each do |set_nesting|
+          found = set_nesting.argument_list.find do |argument|
+            argument.names.include? name
+          end
+
+          unless found.nil?
+            @subject_requirements += found.subject_requirements
+            @argument_list << found
+            break
+          end
+        end
+        if found.nil?
+          missing << name
+        else
+          names += [*found.names]
+        end
+      end
+
+      unless missing.empty?
+        raise CommandError, 
+          "No parent has an argument named \"#{missing.join(", ")}\"" 
+      end
+
+      names.each do |name|
+        (class << self; self; end).instance_eval do
+          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
+      end
+    end
+
+    attr_reader :arg_hash, :path, :nesting
 
     def name
       self.class.name
     end
 
     def required_arguments
-      self.class.argument_list.find_all do |arg|
+      @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 + self.class.parent_arguments
+      @argument_list
     end
 
     def subject_requirements
-      self.class.subject_requirements
+      @subject_requirements
     end
 
     def inspect
@@ -318,27 +388,27 @@ module Command
     end
 
     def parent
-      self.class.parent
+      @nesting.last
     end
 
     def go(collector)
       return if @resume_from == DontResume
       unless self.respond_to? :execute
-        raise CommandException, "#{self.class.path}: command declared but no action defined" 
+        raise CommandException, "#{self.path}: command declared but no action defined" 
       end
 
       @main_collector = collector
       begin
         validate_arguments
-        verify_subject
+        verify_image
         execute
         join_undo
       rescue Interrupt
         puts "Command cancelled"
       rescue ResumeFrom => rf
         rf.setup.task_id = @last_completed_task
-        rf.setup.command = self.class
-        rf.setup.args_hash = arg_hash.dup
+        rf.setup.command_class = self.class
+        rf.setup.arg_hash = arg_hash.dup
         raise rf
       end
     end
@@ -347,11 +417,11 @@ module Command
       formatter.receive_advice(&self.class.advice_block)
     end
 
-    def verify_subject
+    def verify_image
       return if subject_requirements.nil?
       subject_requirements.each do |requirement|
         begin
-          if Subject::UndefinedField === @subject.send(requirement)
+          if Subject::UndefinedField === @subject_image.send(requirement)
             raise CommandException, "\"#{name}\" requires \"#{requirement.to_s}\" to be set"
           end
         rescue NameError => ne
@@ -374,7 +444,7 @@ module Command
 
       all_arguments.each do |argument|
         begin
-          @arg_hash.merge! argument.consume_hash(@subject, args_hash)
+          @arg_hash.merge! argument.consume_hash(@subject_image, args_hash)
         rescue ArgumentInvalidException => aie
           wrong_values.merge! aie.pairs
         rescue OutOfArgumentsException

data/lib/command-set/dsl.rb

@@ -21,6 +21,7 @@ Action:: utility functions within the command action block
       #the new commands.
       def include_commands(set, *commands)
         new_commands = set.command_list
+        options = Hash === commands.first ? commands.shift : {}
 
         commands.map!{|c| c.to_s}
         unless commands.empty?
@@ -29,13 +30,25 @@ Action:: utility functions within the command action block
           end
         end
 
+        unless new_commands.empty?
+          @included_sets << [set, options]
+        end
+
+        if new_commands.has_key?(nil)
+          apply_root_blocks(set.root_blocks)
+        end
+
         new_commands.each_pair do|name, command|
+          next if name.nil?
           if(CommandSet === @command_list[name])
             next unless CommandSet === command
             @command_list[name].include_commands(command)
           else
             @command_list[name] = command.clone
-            @command_list[name].parent=self
+          end
+          unless(options[:context].nil?)
+            @command_list[name] = ContextBoundary.new(@command_list[name], 
+                                                     options[:context])
           end
         end
       end
@@ -88,7 +101,6 @@ Action:: utility functions within the command action block
         if Class === name_or_command_class && Command > name_or_command_class
           if block.nil?
             command = name_or_command_class.dup
-            command.parent = self
             name = command.name
           else
             name = name_or_nil.to_s
@@ -104,7 +116,7 @@ Action:: utility functions within the command action block
           else
             raise RuntimeError, "#{name_or_command_class} is neither a Command class nor a name!"
           end
-          command = Command.setup(self, name, &block)
+          command = Command.setup(name, &block)
         end
 
         @command_list[name] = command
@@ -121,7 +133,7 @@ Action:: utility functions within the command action block
         if (@command_list.has_key? name) && (CommandSet === @command_list[name])
           command = @command_list[name]
         else
-          command = CommandSet.new(self, name)
+          command = CommandSet.new(name)
           @command_list[name] = command
         end
 
@@ -129,11 +141,14 @@ Action:: utility functions within the command action block
         #paths_update(command, name)
       end
 
-      #Occasionally it makes sense for a subcommand to do something when
-      #invoked on it's own.  Define that command using root_command as you
-      #would a normal command
+      #When the behavior of a includeable command set should alter the root
+      #command of another command set, use root_command to wrap the command
+      #definition methods - loose command definition stuff will apply to the
+      #command as is, but won't be updated into including sets.
+      #
+      #As a for instance, take a look at StndCmds::Mode
       def root_command(&block)
-        command(nil, &block)
+        apply_root_blocks([block])
       end
 
       #This is the method that makes DSL::CommandSetDefinition available.
@@ -141,6 +156,10 @@ Action:: utility functions within the command action block
       def define_commands(&block)
         instance_eval(&block)
       end
+
+      def subject_defaults(&block)
+        @subject_defaults = proc &block
+      end
     end
 
     #The meta-programmatic machinery to create arguments quickly.  Includes
@@ -366,7 +385,7 @@ Action:: utility functions within the command action block
       def subject_methods(*methods)
         @subject_requirements += [*methods]
       end
-
+      alias subject_method subject_methods
 
       #Creates a parent argument reference: an argument that references an
       #argument from a subcommand.  This lets a subcommand collect the
@@ -377,18 +396,7 @@ Action:: utility functions within the command action block
       #the mode is started.
       def parent_argument(name)
         name = name.to_s
-        search_in = parent
-        until (search_in = search_in.parent()).nil? do
-          found = parent.argument_list.find do |argument|
-            argument.names.include? name
-          end
-          unless found.nil?
-            arg = found
-            @parent_arguments << found
-            return
-          end
-        end
-        raise CommandError, "No parent has an argument named \"#{name}\""
+        @parent_arguments << name.to_s
       end
 
       def parent_arguments(*names)
@@ -397,7 +405,6 @@ Action:: utility functions within the command action block
         end
       end
 
-
       #The core of the Command.  Define a block that performs the command.
       #Within it, you can treat your arguments as readable private attributes 
       #and call methods from DSL::Action
@@ -518,7 +525,7 @@ Action:: utility functions within the command action block
       #This is how you'll access the Command::Subject object that's the
       #interface of every command to the program state.
       def subject
-        @subject
+        @subject_image
       end
 
       #:section: Pause and Resume
@@ -561,30 +568,32 @@ Action:: utility functions within the command action block
       #will cause that command to be invoked before returning control to the
       #user.
       def chain(*args)
-        setup = CommandSetup.new
-        setup.args_hash = Hash === args.last ? args.pop : {}
-        setup.command = 
-          if args.length == 1
-            args = args[0]
-            case args
-            when Array
-              args
-            when String
-              [args]
-            when Symbol
-              [args.to_s]
-            when Class
-              args
-            else
-              raise CommandException, "Can't chain #{args.inspect}"
-            end
+        anchor = CommandSet === args.first ? args.shift : self.parent
+        setup = AnchoredCommandSetup.new(anchor)
+        setup.arg_hash = Hash === args.last ? args.pop : {}
+
+        if args.length == 1
+          args = args[0]
+          case args
+          when Array
+            setup.terms = args
+          when String
+            setup.terms = [args]
+          when Symbol
+            setup.terms = [args.to_s]
+          when Class
+            setup.command_class = args
           else
-            if args.find{|arg| not (String === arg or Symbol === arg)}
-              raise CommandException, "Can't chain #{args.inspect}"
-            else
-              args.map{|arg| arg.to_s}
-            end
+            raise CommandException, "Can't chain #{args.inspect}"
           end
+        else
+          if args.find{|arg| not (String === arg or Symbol === arg)}
+            raise CommandException, "Can't chain #{args.inspect}"
+          else
+            setup.terms = args.map{|arg| arg.to_s}
+          end
+        end
+
         subject.chain_of_command.push(setup)
       end