command-set 0.8.4 → 0.9.0

data/lib/command-set/dsl.rb

@@ -34,7 +34,7 @@ Action:: utility functions within the command action block
             next unless CommandSet === command
             @command_list[name].include_commands(command)
           else
-            @command_list[name] = command.dup
+            @command_list[name] = command.clone
             @command_list[name].parent=self
           end
         end
@@ -63,7 +63,7 @@ Action:: utility functions within the command action block
           raise RuntimeError,"#{set.inspect} isn't a CommandSet"
         end
 
-        set = set.find_command(*path).first
+        set = set.find_command(path)
 
         if CommandSet === set
           include_commands(set, *commands)
@@ -94,10 +94,12 @@ Action:: utility functions within the command action block
             name = name_or_nil.to_s
             command = name_or_command_class.setup(self, name, &block)
           end
+        elsif name_or_command_class.nil?
+          command = @command_list[nil]
+          command.instance_eval(&block)
+          return
         else
-          if name_or_command_class.nil?
-            name = nil
-          elsif String === name_or_command_class or Symbol === name_or_command_class
+          if String === name_or_command_class or Symbol === name_or_command_class
             name = name_or_command_class.to_s
           else
             raise RuntimeError, "#{name_or_command_class} is neither a Command class nor a name!"
@@ -141,67 +143,6 @@ Action:: utility functions within the command action block
       end
     end
 
-    #These are the methods made available by Command::setup, and thus by
-    #DSL::CommandSetDefinition#command
-    module CommandDefinition
-      #See Command::Subject.  If this command will make use of fields of the
-      #subject, it must declare them using subject_methods.  You're then
-      #guaranteed that the subject will either have those fields defined, or
-      #an error will be thrown at runtime.  Pass a list of symbols, as you
-      #would to Class#attribute
-      def subject_methods(*methods)
-        @subject_requirements += [*methods]
-      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
-      def action(&block)
-        define_method(:execute, &block)
-      end
-
-      #Commands should either define an undo block (that will reverse
-      #whatever their action did) or else call doesnt_undo - for things that
-      #don't change any state.  
-      #
-      #One particularly useful feature is that each invocation is it's own
-      #object, so you can set instance variables to save the old state if
-      #you want.
-      def undo(&block)
-        define_method(:undo, &block)
-        define_method(:undoable?) do
-          return true
-        end
-        subject_requirements << :undo_stack
-      end
-
-      #Lets the interpreter know that this command intentionally doesn't
-      #provide an undo block - that there's nothing to undo.  Use it for
-      #informational commands, primarily.  Commands that neither declare
-      #that they 'doesnt_undo' nor provide an undo block will raise a
-      #warning to the user whenever they're called.
-      def doesnt_undo
-        define_method(:undoable?) { return true }
-        define_method(:join_undo) {}
-      end
-
-      #Used to explain to the formatter subsystem how best to format your
-      #output.  It can sometimes be useful to output lots of data, and then
-      #use format_advice to eliminate and shuffle it around.
-      #
-      #For more information see Command::Formatter::FormatAdvisor
-      def format_advice(&block)
-        @advice_block = proc &block
-      end
-
-      #Every command should provide a little text to describe what it does.
-      #This will be nicely formatted on output, so feel free to use heredocs
-      #and indent so that it looks nice in the code.
-      def document(text)
-        @doc_text = text.gsub(%r{\s+}, " ").strip
-      end
-    end
-
     #The meta-programmatic machinery to create arguments quickly.  Includes
     #methods such that argument classes can register themselves into the DSL.
     #Much of this module is unfortunately obtuse - it's designed so that
@@ -227,14 +168,30 @@ Action:: utility functions within the command action block
     #
     #:include: doc/argumentDSL
     module Argument
-      #Sugar for creating an alternating argument.  Basically, an
-      #alternating argument is a series of arguments, any of which could be
-      #set.  They either need to be of distinct types, or use +named+ to
-      #distinguish between them.
-      def alternating_argument(name, &block)
-        arg = AlternatingArgument.new(self, &block)
-        arg.name(name)
-        embed_argument(arg)
+      class SubjectDeferral
+        def method_missing(name, *args, &block)
+          @deferred_calls << [name, args, block]
+          return self
+        end
+
+        def initialize
+          @deferred_calls = []
+        end
+
+        def subject_requirements
+          return [@deferred_calls.first.first]
+        end
+
+        def realize(subject)
+          return @deferred_calls.inject(subject) do |obj, call|
+            obj = obj.__send__(call[0], *call[1])
+            if call[2].nil?
+              obj
+            else
+              call[2].call(obj)
+            end
+          end
+        end
       end
 
       @@decorator_map={}
@@ -324,29 +281,15 @@ Action:: utility functions within the command action block
       #Don't look to closely at the source.  It does bad things.
       def create_decorator(&block)
         me = /:in `([^']*)/.match(caller(0)[0])[1]
-        decorator = @@decorator_map[me].allocate
-        decorator.extend DSL::Argument
-        embed_in = self
-        decorator.instance_eval do
-          initialize(embed_in, &block)
-        end
-        return decorator
+        return @@decorator_map[me].new(self, &block)
       end
 
       #This method functions analogously to create_decorator, except it
       #works for arguments, not decorators.  It's worth looking at as the
       #call signature for all +funky_argument+ style calls.
-      def special_argument(arg, values=nil, &get_values)
+      def special_argument(name, values=nil, &get_values)
         me = /:in `([^']*)/.match(caller(0)[0])[1]
-        name = nil
-        argument = nil
-        if(::Command::Argument === arg)
-          name = arg.name
-          argument = arg
-        else
-          name = arg
-          argument = @@shorthand_map[me].new(name, get_values||values)
-        end
+        argument = @@shorthand_map[me].new(name, get_values||values)
         return self.embed_argument(argument)
       end
 
@@ -354,20 +297,42 @@ Action:: utility functions within the command action block
       #be used - which means that you can explicitly create and argument and
       #embed it.  Otherwise, the values of +values+ or +get_values+ will be
       #used to create the argument
-      def argument(arg, values=nil, &get_values)
+      def argument(arg, *values, &get_values)
         name = nil
         argument = nil
         if(::Command::Argument === arg)
           name = arg.name
           argument = arg
+        elsif(Class === arg and ::Command::Argument > arg)
+          argument = arg.new(values[0], get_values||values[1])
         else
           name = arg
-          argument = create(name, get_values||values)
+          argument = create(name, get_values||values.first)
         end
 
         return self.embed_argument(argument)
       end
 
+      #Returns a SubjectDeferral  Ultimately, this allows you to reference
+      #and base an argument on a value in the subject.  Check this out:
+      #
+      #  number_argument :which_little_pig subject.pigs {|pigs| 1..pigs.length}
+      #
+      #When that argument is evaluated, the pigs (is_a? Array) field of 
+      #the subject will get turned into a range: from 1 to it's length.
+      def subject
+        return SubjectDeferral.new
+      end
+
+      #Sugar for creating an alternating argument.  Basically, an
+      #alternating argument is a series of arguments, any of which could be
+      #set.  They either need to be of distinct types, or use +named+ to
+      #distinguish between them.
+      def alternating_argument(name, &block)
+        arg = AlternatingArgument.new(self, &block)
+        arg.name(name)
+      end
+
       #The method used to instantiate arguments based on their values.
       #Searches all registered Argument classes, from children up, until one
       #admits to being able to create arguments based on the value.
@@ -386,6 +351,100 @@ Action:: utility functions within the command action block
       end
     end
 
+    #These are the methods made available by Command::setup, and thus by
+    #DSL::CommandSetDefinition#command
+    module CommandDefinition
+      include Argument
+
+      #See Command::Subject.  If this command will make use of fields of the
+      #subject, it must declare them using subject_methods.  You're then
+      #guaranteed that the subject will either have those fields defined, or
+      #an error will be thrown at runtime.  Pass a list of symbols, as you
+      #would to Class#attribute
+      def subject_methods(*methods)
+        @subject_requirements += [*methods]
+      end
+
+
+      #Creates a parent argument reference: an argument that references an
+      #argument from a subcommand.  This lets a subcommand collect the
+      #arguments common to its commands and do two things: make command line
+      #calls more natural (+box+ +grape_box+ +add+ +grapes+ instead of +box+
+      #+add+ +grape_box+ +grapes+) and also make modes more useful, since
+      #they can collect the arguments that would otherwise be repeated when
+      #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}\""
+      end
+
+      def parent_arguments(*names)
+        names.each do |name|
+          parent_argument(name)
+        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
+      def action(&block)
+        define_method(:execute, &block)
+      end
+
+      #Commands should either define an undo block (that will reverse
+      #whatever their action did) or else call doesnt_undo - for things that
+      #don't change any state.  
+      #
+      #One particularly useful feature is that each invocation is it's own
+      #object, so you can set instance variables to save the old state if
+      #you want.
+      def undo(&block)
+        define_method(:undo, &block)
+        define_method(:undoable?) do
+          return true
+        end
+        subject_requirements << :undo_stack
+      end
+
+      #Lets the interpreter know that this command intentionally doesn't
+      #provide an undo block - that there's nothing to undo.  Use it for
+      #informational commands, primarily.  Commands that neither declare
+      #that they 'doesnt_undo' nor provide an undo block will raise a
+      #warning to the user whenever they're called.
+      def doesnt_undo
+        define_method(:undoable?) { return true }
+        define_method(:join_undo) {}
+      end
+
+      #Used to explain to the formatter subsystem how best to format your
+      #output.  It can sometimes be useful to output lots of data, and then
+      #use format_advice to eliminate and shuffle it around.
+      #
+      #For more information see Command::Formatter::FormatAdvisor
+      def format_advice(&block)
+        @advice_block = proc &block
+      end
+
+      #Every command should provide a little text to describe what it does.
+      #This will be nicely formatted on output, so feel free to use heredocs
+      #and indent so that it looks nice in the code.
+      def document(text)
+        @doc_text = text.gsub(%r{\s+}, " ").strip
+      end
+    end
+
     #The DSL for formatting.  A lot of code will do just fine with the
     #Kernel#puts #that Results intercepts.  More involved output control
     #starts by including CommandSet::DSL::Formatting, and using
@@ -403,20 +462,20 @@ Action:: utility functions within the command action block
       #Tells the main collector to begin a list.  Subsequent output will be
       #gathered into that list.  For more, check out Results::Collector
       def begin_list(name, options={})
-        @main_collector.begin_list(name, options)
+        $stdout.relevant_collector.begin_list(name, options)
       end
 
       #Tells the main collector to end the current list.  For more, check out
       #Results::Collector
       def end_list  
-        @main_collector.end_list
+        $stdout.relevant_collector.end_list
       end
 
       #Clean way to create an item of output.  Allows for various options to
       #be added.  The normal output method (#puts, #p, #write...) are all
       #diverted within a command, and effectively create no-option items.
       def item(name, options={})
-        @main_collector.item(name, options)
+        $stdout.relevant_collector.item(name, options)
       end
 
       #This returns a new Results::Collector, which can allow for some very
@@ -425,7 +484,7 @@ Action:: utility functions within the command action block
       #multiple lists at once, for instance a status list (with hashmarks)
       #and results(with useful data) list.
       def sub_collector
-        @main_collector.dup
+        $stdout.relevant_collector.dup
       end
     end
 
@@ -499,10 +558,31 @@ Action:: utility functions within the command action block
       #Calling chain with either a command class or a command path allows
       #will cause that command to be invoked before returning control to the
       #user.
-      def chain(klass_or_path, args)
+      def chain(*args)
         setup = CommandSetup.new
-        setup.command = klass_or_path
-        setup.args_hash = args || {}
+        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
+          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
+          end
         subject.chain_of_command.push(setup)
       end
 

data/lib/command-set/interpreter.rb

@@ -79,7 +79,7 @@ module Command
         raise RuntimeError, "Sub-modes must be CommandSets!" 
       end
 
-      @sub_modes.push(mode)
+      @sub_modes.push([mode, mode.most_recent_args])
       return nil
     end
 
@@ -118,6 +118,7 @@ module Command
     #You'll almost never want to override this method.
     def next_command
       setup = @commands_pending.shift
+      setup.args_hash = default_arg_hash.merge(setup.args_hash)
       return setup.command_instance(current_command_set, build_subject)
     end
 
@@ -143,6 +144,9 @@ module Command
         $stdout.add_dispatcher(collector)
         until @commands_pending.empty?
           cmd = next_command
+          unless cmd.class.executeable?
+            raise CommandException, "incomplete command"
+          end
           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
@@ -187,9 +191,14 @@ module Command
       return nil
     end
 
+    def default_arg_hash
+      return {} if @sub_modes.empty?
+      return @sub_modes.last.last
+    end
+
     def current_command_set
       return @command_set if @sub_modes.empty?
-      return @sub_modes.last
+      return @sub_modes.last.first
     end
 
     def build_subject

data/lib/command-set/quick-interpreter.rb

@@ -70,7 +70,11 @@ module Command
 
     #Accepts it's input as multiple arguments for convenience
     def process_input(*words)
-      super(words)
+      if words.length == 1 and Array === words.first
+        super words.first
+      else
+        super(words)
+      end
     end
 
     #Always returns "yes" so that undo warnings can be ignored.
@@ -83,6 +87,10 @@ module Command
       CommandSetup.new(words)
     end
 
+    def complete_input(terms, word)
+      return current_command_set.completion_list(terms, word, build_subject)
+    end
+
     #See PermissiveSubject
     def get_subject
       return PermissiveSubject.new

data/lib/command-set/results.rb

@@ -92,6 +92,8 @@ module Command
     #Kernel -- Which usually makes sense, but IO has a bunch of methods that
     #Kernel defines to basically delegate to an IO.... I have a headache
     #now.
+    #It might just make sense to explicitly do the delegation, rather than
+    #use DelegateClass
     methods = IO.public_instance_methods(false)
     methods -= self.public_instance_methods(false)
     methods |= ['class']