command-set 0.8.1 → 0.8.2

data/doc/argumentDSL

@@ -21,16 +21,17 @@ Decorator methods, and the classes they add:
 
 The shorthand argument methods are:
 
-+regexp_argument+:: RegexpArgument
-+multiword_argument+:: MultiArgument
++any_argument+:: StringArgument
 +array_argument+:: ArrayArgument
-+string_argument+:: StringArgument
++choose_argument+:: ArrayArgument
 +file_argument+:: FileArgument
-+any_argument+:: StringArgument
++multiword_argument+:: MultiArgument
 +nonvalidating_proc_argument+:: NoValidateProcArgument
 +number_argument+:: NumberArgument
-+choose_argument+:: ArrayArgument
 +proc_argument+:: ProcArgument
 +regex_argument+:: RegexpArgument
++regexp_argument+:: RegexpArgument
++rest_argument+:: RestOfLineArgument
++string_argument+:: StringArgument
 
 Don't forget about #alternating_argument and #argument itself!

data/lib/command-set/arguments.rb

@@ -119,6 +119,7 @@ module Command
     end
   end
 
+  #Input has to be a number, in the range passed to create the argument
   class NumberArgument < Argument
     register "number", Range
 
@@ -146,6 +147,7 @@ module Command
     end
   end
 
+  #Input must match the regular expression passed to create this Argument
   class RegexpArgument < Argument
     register "regexp", Regexp
     register "regex"
@@ -164,6 +166,7 @@ module Command
     end
   end
 
+  #File access. Completes paths, validates file options.
   class FileArgument < Argument
     register "file"
     Defaults = { 
@@ -174,6 +177,18 @@ module Command
       end
     }
 
+    #You create a FileArgument either with an optional  hash of options, or
+    #a block that evaluates whether or not a path is acceptable.
+    #
+    #The default options hash looks like:
+    #
+    # :prune_patterns => [/^\./],  #regexs of paths to eliminate from
+    #                              #completion
+    # :dirs => [ENV['PWD']],       #essentially the PATH env variable
+    # :acceptor => proc do |path|  #Is a good path?
+    #   return (File.exists?(path) and not File.directory?(path))
+    # end                          #The default wants existent non-dirs
+    #
     def initialize(name, options={})
       super(name)
       options ||= {}
@@ -264,6 +279,9 @@ module Command
     end
   end
 
+  #Using FiddlyArguments is sometimes unavoidable, but it kind of stinks.
+  #You assign blocks that validate, complete and parse the input.  You're 
+  #probably better off subclassing Argument.
   class FiddlyArgument < Argument
     def initialize(name, &block)
       super(name)
@@ -288,6 +306,7 @@ module Command
     end
   end
 
+  #Created with an array of options to choose from
   class ArrayArgument < Argument
     register "array", Array
     register "choose"
@@ -306,6 +325,7 @@ module Command
     end
   end
 
+  #Liberally accepts any string as input
   class StringArgument < Argument
     register "string", String
     register "any"
@@ -324,6 +344,8 @@ module Command
     end
   end
 
+  #Consumes the rest of the line as a space separated string.
+  #Useful for commands with sentences as their arguments.
   class RestOfLineArgument < StringArgument
     register "rest"
 
@@ -337,6 +359,14 @@ module Command
     end
   end
 
+  #Created with a two argument block, a proc_argument validates it's input
+  #by passing it to the block.  It also uses the block to validate.
+  #
+  #As a result, the block should return a list of acceptable completions,
+  #given a prefix and the current subject.
+  #
+  #Ideally, use proc_arguments to prototype new argument types before
+  #creating whole classes for them.
   class ProcArgument < Argument
     register "proc", Proc
 
@@ -355,6 +385,7 @@ module Command
     end
   end
 
+  #Like ProcArgument, but performs to validation on the input.
   class NoValidateProcArgument < ProcArgument
     register "nonvalidating_proc"
 
@@ -413,6 +444,9 @@ module Command
   end
 
 
+  #Consumes multiple words as dictated by the block used to create the
+  #argument.  A little complex, but powerful.  For use, see
+  #StandardCommands::Set
   class MultiArgument < Argument
     register "multiword"
 

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

@@ -165,9 +165,9 @@ module Command
       #creating the command set.  You can even call
       #DSL::CommandSetDefinition#define_commands on the set that's returned
       #in order to add one-off commands or fold in other command sets.
-      def require_commands(file, mod, cmd_path=[])
+      def require_commands(mod, file, cmd_path=[])
         set = self.new
-        set.require_commands(file, mod, cmd_path)
+        set.require_commands(mod, file, cmd_path)
         return set
       end
     end

data/lib/command-set/dsl.rb

@@ -45,8 +45,8 @@ Action:: utility functions within the command action block
       #+define_commands+ on a specific Module, pick out a specific
       #subcommand (by passing a path), and then including specific commands
       #from it.
-      def require_commands(file, module_name, path = [], *commands)
-        require file
+      def require_commands(module_name, file = nil, path = [], *commands)
+        require file rescue nil
         module_path = module_name.to_s.split("::")
         mod = Object
         module_path.each do |part|
@@ -258,7 +258,7 @@ Action:: utility functions within the command action block
       #module's documentation.  Also useful if you want to document your own
       #argument class' contributions.  Try something like:
       #
-      #  > ruby -r"lib/command-set/arguments.rb" -e "Command::DSL::Argument::document"
+      #  > ruby -r"lib/command-set/arguments.rb" -e "puts Command::DSL::Argument::document"
       def self.document
         docs = <<-EOD 
         There are two kinds of methods available for #{self.name}.  
@@ -289,7 +289,7 @@ Action:: utility functions within the command action block
 
         EOD
 
-        @@shorthand_map.each_pair do |method, klass|
+        @@shorthand_map.to_a.sort.each do |method, klass|
           docs += "+#{method}+:: #{klass.name.sub("Command::","")}\n"
         end
 
@@ -301,7 +301,7 @@ Action:: utility functions within the command action block
         indent = /^\s+/.match(docs)[0]
         docs.gsub!(/^#{indent}/, "")
 
-        puts docs
+        return docs
       end
 
       def self.argument_typemap #:nodoc:

data/lib/command-set/standard-commands.rb

@@ -26,7 +26,237 @@ module Command
       defined
     end
   end
+end
+
+module StdCmd
+  module Help
+    @@set = nil
+    def self.define_commands
+      return @@set ||= Command::CommandSet.define_commands do
+        command("help") do
+          optional.multiword_argument(:terms) do |terms,subject|
+            prefix = terms.pop
+            subject.command_set.completion_list(terms, prefix, subject)
+          end
+
+          subject_methods :interpreter_behavior, :command_set
+
+          action do
+            width = (subject.interpreter_behavior)[:screen_width]
+            puts
+            if(terms.nil? || terms.empty?)
+              subject.command_set.documentation(width).each do |docline|
+                puts docline
+              end
+            else
+              command,remains = subject.command_set.find_command(*terms)
+              docs = command.documentation(width)
+              docs.each do |docline|
+                puts docline
+              end
+            end
+            puts
+          end
+
+          doesnt_undo
+
+          document <<-EOH
+          Returns a hopefully helpful description of the command indicated
+        EOH
+        end
+      end
+    end
+  end
+
+  #Resume is very rarely used in user-facing command sets, but can be
+  #handy to chain in as a synthetic command
+  module Resume
+    @@set = nil
+    def self.define_commands
+      return @@set ||= Command::CommandSet.define_commands do
+        command Command::StandardCommand::Resume
+      end 
+    end
 
+  end
+
+  module Quit
+    @@set = nil
+    def self.define_commands
+      return @@set ||= Command::CommandSet.define_commands do
+        command Command::StandardCommand::Quit
+      end  
+    end
+
+  end
+
+  module Undo
+    @@set = nil
+    def self.define_commands
+      return @@set ||= Command::CommandSet.define_commands do
+        command("undo") do
+          doesnt_undo
+          action do
+            command=subject.undo_stack.get_undo
+            command.undo
+          end
+
+          subject_methods :undo_stack
+
+          document <<-EOH
+        Undoes the most recently used command, if possible.
+        EOH
+        end
+
+        command("redo") do
+          doesnt_undo
+          action do
+            command=subject.undo_stack.get_redo
+            command.execute
+          end
+
+          document <<-EOH
+        Redoes the most recently used command, if possible.
+        EOH
+        end
+      end  
+    end
+
+  end
+
+  module Mode
+    @@set = nil
+    def self.define_commands
+      return @@set ||= Command::CommandSet.define_commands do
+        root_command do
+          argument(Command::FiddlyArgument.new(:mode) do |argument|
+            argument.completion do |t,s|
+              []
+            end
+
+            argument.validation do |term,s|
+              Command::CommandSet === term
+            end
+          end)
+          subject_methods :interpreter
+          doesnt_undo
+
+          action do
+            subject.interpreter.push_mode(mode)
+          end
+        end
+
+        command(:exit) do
+          subject_methods :interpreter
+          doesnt_undo
+
+          action do
+            subject.interpreter.pop_mode
+          end
+        end
+      end  
+    end
+  end
+
+  module Set
+    @@set = nil
+    def self.define_commands
+      return @@set ||= Command::CommandSet.define_commands do
+        command(:set) do
+          optional.multiword_argument(:address) do |terms, subject|
+            last_word = terms.pop
+            hash = value_set(terms, subject)
+            if(Hash === hash)
+              return hash.keys.grep(%r{^#{last_word}.*})
+            else
+              return []
+            end
+          end
+
+          optional.argument(:value, "VALUE")
+
+          def value_set(terms, subject)
+            knobs = subject.knobs
+            return [] if knobs.nil?
+
+            terms.each do |term|
+              unless knobs.respond_to? :[]
+                raise Command::CommandError, "can't find settings under #{term}" 
+              end
+              knobs = knobs[term]
+            end
+
+            return knobs
+          end
+
+          define_method :value_set do |terms, subject|
+            self.class.value_set(terms, subject)
+          end
+
+          subject_methods :knobs
+
+          #TODO: This is a big mess in here
+          #AFAICT, there should be an address, followed by an optional name
+          #followed by an optional value...
+
+          action do
+            if address.nil?
+              dont_undo
+              puts subject.knobs.keys.sort.join("\n")
+              return
+            else
+              @knob_name = address.pop 
+              @knobs = value_set(address, subject)
+            end
+
+            if Hash === @knobs[@knob_name]
+              dont_undo 
+              puts @knobs[@knob_name].keys.sort.join("\n")
+              return
+            elsif @knobs.has_key? @knob_name
+              if value.nil?
+                dont_undo
+                puts "#@knob_name: #{@knobs[@knob_name].inspect}"
+              else
+                @original_value = @knobs[@knob_name]
+                @knobs[@knob_name]=value
+                #I'm only keeping this because I trust you meant something
+                #@knobs[@knob_name]=convert_value(@original_value, value)
+              end
+            end
+          end 
+
+          undo do
+            @knobs[@knob_name] = @original_value
+          end
+
+          document <<-EOH
+        Without arugments, lists the available variables.
+
+        With one argument, prints the value of the variable <name>.
+
+        Sets <name> to <value>.  Most settings should be obvious.  But 
+        some important ones probably won't be.  
+        EOH
+        end
+      end  
+    end
+  end
+
+  #Includes quit, undo/redo and help.
+  module Basics
+    @@set = nil
+    def self.define_commands
+      return @@set ||= Command::CommandSet.define_commands do
+        include_commands Quit
+        include_commands Undo
+        include_commands Help
+      end
+    end
+  end
+end
+
+module Command
   #This is a collection of useful commands that are often useful to add to
   #DSL::CommandSetDefinition#include_commands
   #
@@ -38,6 +268,14 @@ module Command
   #   include_commands Command::StandardCommands::Help
   # end
   #
+  #Or you could use Command::DSL::require_commands, like so
+  #
+  # set = CommandSet::define_commands do
+  #   require_commands "StdCmd::Quit", "command-set/standard_commands",
+  #   require_commands "StdCmd::Undo"
+  #   require_commands "StdCmd::Help"
+  # end
+  #
   #Some notes: 
   #
   #0. Resume is usually handy for use in +chain+ calls, not as something to
@@ -52,192 +290,16 @@ module Command
   #   the current value, +set+ +optionname+ +value+ sets the value of
   #   +optionname+
   module StandardCommands
-    help = CommandSet.define_commands do
-      command("help") do
-	optional.multiword_argument(:terms) do |terms,subject|
-	  prefix = terms.pop
-	  subject.command_set.completion_list(terms, prefix, subject)
-	end
-	
-	subject_methods :interpreter_behavior, :command_set
-
-	action do
-	  width = (subject.interpreter_behavior)[:screen_width]
-	  puts
-	  if(terms.nil? || terms.empty?)
-	    subject.command_set.documentation(width).each do |docline|
-              puts docline
-            end
-	  else
-	    command,remains = subject.command_set.find_command(*terms)
-	    docs = command.documentation(width)
-	    docs.each do |docline|
-	      puts docline
-	    end
-	  end
-	  puts
-	end
-	
-	doesnt_undo
-
-	document <<-EOH
-	  Returns a hopefully helpful description of the command indicated
-	EOH
-      end
-    end
-    Help = help
-
-    #Resume is very rarely used in user-facing command sets, but can be handy to chain in
-    #as a synthetic command
-    resume = CommandSet.define_commands do
-      command StandardCommand::Resume
-    end
-    Resume = resume
-
-    quit = CommandSet.define_commands do
-      command StandardCommand::Quit
-    end
-    Quit = quit
-
-    undo_redo = CommandSet.define_commands do
-      command("undo") do
-	doesnt_undo
-	action do
-	  command=subject.undo_stack.get_undo
-	  command.undo
-	end
+    Help = StdCmd::Help.define_commands()
 
-	subject_methods :undo_stack
+    Resume = StdCmd::Resume.define_commands()
 
-	document <<-EOH
-	Undoes the most recently used command, if possible.
-	EOH
-      end
-
-      command("redo") do
-	doesnt_undo
-	action do
-	  command=subject.undo_stack.get_redo
-	  command.execute
-	end
+    Quit = StdCmd::Quit.define_commands()
 
-	document <<-EOH
-	Redoes the most recently used command, if possible.
-	EOH
-      end
-    end
-    Undo = undo_redo
-
-    mode_exit = CommandSet.define_commands do
-      root_command do
-	argument(FiddlyArgument.new(:mode) do |argument|
-	  argument.completion do |t,s|
-	    []
-	  end
-
-	  argument.validation do |term,s|
-	    CommandSet === term
-	  end
-	end)
-	subject_methods :interpreter
-	doesnt_undo
-
-	action do
-	  subject.interpreter.push_mode(mode)
-	end
-      end
+    Undo = StdCmd::Undo.define_commands()
 
-      command(:exit) do
-	subject_methods :interpreter
-	doesnt_undo
+    Mode = StdCmd::Mode.define_commands()
 
-	action do
-	  subject.interpreter.pop_mode
-	end
-      end
-    end
-    Mode = mode_exit
-
-
-    set = CommandSet.define_commands do
-      command(:set) do
-	optional.multiword_argument(:address) do |terms, subject|
-	  last_word = terms.pop
-	  hash = value_set(terms, subject)
-	  if(Hash === hash)
-	    return hash.keys.grep(%r{^#{last_word}.*})
-	  else
-	    return []
-	  end
-	end
-
-	optional.argument(:value, "VALUE")
-
-	def value_set(terms, subject)
-	  knobs = subject.knobs
-	  return [] if knobs.nil?
-
-	  terms.each do |term|
-	    unless knobs.respond_to? :[]
-	      raise CommandError, "can't find settings under #{term}" 
-	    end
-	    knobs = knobs[term]
-	  end
-
-	  return knobs
-	end
-
-	define_method :value_set do |terms, subject|
-	  self.class.value_set(terms, subject)
-	end
-
-	subject_methods :knobs
-	
-	#TODO: This is a big mess in here
-	#AFAICT, there should be an address, followed by an optional name
-	#followed by an optional value...
-
-	action do
-	  if address.nil?
-	    dont_undo
-	    puts subject.knobs.keys.sort.join("\n")
-	    return
-	  else
-	    @knob_name = address.pop 
-	    @knobs = value_set(address, subject)
-	  end
-
-	  if Hash === @knobs[@knob_name]
-	    dont_undo 
-	    puts @knobs[@knob_name].keys.sort.join("\n")
-	    return
-	  elsif @knobs.has_key? @knob_name
-	    if value.nil?
-	      dont_undo
-	      puts "#@knob_name: #{@knobs[@knob_name].inspect}"
-	    else
-	      @original_value = @knobs[@knob_name]
-	      @knobs[@knob_name]=value
-	      #I'm only keeping this because I trust you meant something
-	      #@knobs[@knob_name]=convert_value(@original_value, value)
-	    end
-	  end
-	end 
-
-	undo do
-	  @knobs[@knob_name] = @original_value
-	end
-
-	document <<-EOH
-	Without arugments, lists the available variables.
-
-	With one argument, prints the value of the variable <name>.
-
-	Sets <name> to <value>.  Most settings should be obvious.  But 
-	some important ones probably won't be.  
-	EOH
-      end
-    end
-    Set = set
+    Set = StdCmd::Set.define_commands()
   end
 end

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: command-set
 version: !ruby/object:Gem::Version 
-  version: 0.8.1
+  version: 0.8.2
 date: 2007-12-13 00:00:00 -08:00
 summary: Framework for interactive programs focused around a DSL for commands
 require_paths: 
@@ -47,7 +47,6 @@ files:
 - doc/README
 - doc/Specifications
 - doc/argumentDSL
-- GUIDED_TOUR
 test_files: []
 
 rdoc_options: 
@@ -56,9 +55,9 @@ rdoc_options:
 - --main
 - Command
 - --title
-- command-set-0.8.1 RDoc
+- command-set-0.8.2 RDoc
 extra_rdoc_files: 
-- GUIDED_TOUR
+- doc/argumentDSL
 executables: []
 
 extensions: []

data/GUIDED_TOUR

@@ -1,24 +0,0 @@
-The quickest way to get a handle on what CommandSet can do for you is to
-look at the various pieces and get a handle on how they work together.
-
-The rough sketch is that you enumerate a series of commands, which you then 
-feed to an interpreter.  The interpreter will set you up with a template for 
-your porgram's subject, which you fill in with some defaults.  Then, give 
-the filled in subject back to the interpreter and let it run.
-
-Here's the appropriate places to get started:
-
-0. DSL (Read thoroughly - especially the sub modules)
-0. BaseInterpreter#subject_template
-0. BaseInterpreter#subject=
-0. TextInterpreter#go
-
-A couple of handy tricks can be found at
-
-0. BaseInterpreter#process_input
-0. StandardCommands
-0. QuickInterpreter
-
-More advanced stuff that worth learning once your app is off the ground:
-
-0. Results