command-set 0.8.0

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

@@ -0,0 +1,282 @@
+require 'strscan'
+require 'thread'
+require 'command-set/arguments'
+require 'command-set/command'
+require 'command-set/subject'
+require 'command-set/results'
+require 'command-set/dsl'
+
+
+#:stopdoc:
+class String
+  def wrap(width=80)
+    scanner = StringScanner.new(self)
+    result=[]
+
+    scanner.skip(/\s*/)
+
+    current_line = scanner.scan(/\S+/)
+
+    until scanner.eos?
+      scanner.skip(/\s*/)
+      word = scanner.scan(/\S+/)
+      next if word.nil?
+      if word.length > (width - current_line.length) 
+	result << current_line
+	current_line = word
+      else
+	current_line << (" " + word)
+      end
+    end
+
+    unless /^\s*$/ =~ current_line
+      result << current_line
+    end
+
+    return result
+  end
+end
+
+Command::wrap_stdout
+#Command::wrap_stderr
+
+#:startdoc:
+
+#Command::CommandSet is a tight little library that let's you clearly and
+#easily describe a set of commands for an interactive application.  The
+#command set can then be handed to one of a number of interpreters that will
+#facilitate interaction with the user.
+#
+#CommandSet has a number of pretty neat features:
+#- A command line text interpreter, with tab completion etc. compliments of
+#  readline.
+#
+#- A handy little DSL for describing commands and what they do.  There are
+#  other CLI engines that map to ruby methods, but frankly, I'm not sure
+#  that's the most useful mapping.  The CommandSet DSL lets you specify the
+#  type of commands, control how they tab complete, mark some arguments as
+#  optional, etc.  
+#
+#- Modularized commands.  The StandardCommands class is a good example.
+#  Basically, any time you have a command that might be generally
+#  applicable, you can compose it into another set, and cherrypick specific
+#  commands out.  For example:
+#  
+#    CommandSet.define_commands do
+#      command(:example) do |example|
+#        ...stuff...
+#      end
+#
+#      include(other_set)
+#      include(cluttered_set, :useful)
+#
+#      sub_command(:sub) do |sub|
+#        sub.include(yet_another_set)
+#      end
+#    end
+#
+#- Results processing.  Basically, any +puts+, +p+ or +print+ call in the
+#  context of a command will (instead of outputing directly to +$stdout+)
+#  instead fire events in Formatter objects.  The default behavior of which is
+#  ... to output directly to +STDOUT+.  The catch here is that that behavior can
+#  be changed, and the events can include the beginnings and ends of nesting
+#  lists, so you have this whole tree of results from your command execution
+#  that can be manipulated on it's way to the user.
+#  As a for instance, you can spin off threads to do processing of parts of
+#  a command, and be confidant that you'll be able to make sense of the
+#  output for the user.
+#
+#- Extensible Command, Argument, and BaseInterpreter make power
+#  functionality easy to add.  The modular design means that a CommandSet
+#  written for use with the TextInterpreter, can also be used to process the
+#  command line arguments to the program or passed to a batch interpreter.
+#  WebApp (a separate gem) uses this feature so that a web application
+#  automatically gets a command line version, for testing or administrator's
+#  convenience.
+#
+#:include: GUIDED_TOUR
+module Command
+  class CommandError < ScriptError; end
+  class CommandException < RuntimeError
+    def initialize(msg=nil)
+      super
+      @raw_input = nil
+      @command = nil
+    end
+
+    def message
+      if @command.nil?
+        if @raw_input.nil?
+          super
+        else
+          return @raw_input.inspect() +": "+ super
+        end
+      else
+        return @command.class.path.join(" ") +": "+ super
+      end
+    end
+
+    attr_accessor :raw_input, :command
+  end
+  class OutOfArgumentsException < CommandException; end
+  class ArgumentInvalidException < CommandException
+    def initialize(pairs)
+      @pairs = pairs.dup
+      super("Bad arguments: #{pairs.inspect}")
+    end
+
+    attr_reader :pairs
+  end
+  class ArgumentUnrecognizedException < CommandException; end
+
+  #This class packs up a set of commands, for presentation to an
+  #interpreter.  CommandSet objects are defined using methods from
+  #DSL::CommandSetDefinition
+  class CommandSet
+    def initialize(parent=nil, name="")
+      @parent = parent
+      @name = name
+      @command_list = Hash.new 
+      @subject_template = nil
+      @documentation = ""
+      @prompt = nil
+    end
+
+    attr_accessor :documentation, :parent
+
+    class << self
+      #The preferred way to use a CommandSet is to call CommandSet::define_commands with
+      #a block, and then call #command, #include_commands
+      #and #sub_command on it.
+      def define_commands(&block)
+	set = self.new
+	set.define_commands(&block)
+	return set
+      end
+    end
+
+    include DSL::CommandSetDefinition
+
+    #:section: Workhorse methods - not usually used by client code
+    #
+
+    def paths_update(command, name)
+      command.add_path(self, [], name)
+
+      @paths.each do |set, path|
+        command.add_path(set, path, name)
+      end
+    end
+
+    def get_root
+      command = @command_list[nil]
+    end
+
+    def prompt
+      if @prompt.nil?
+        if @name.empty?
+          return [/$/, ""]
+        else
+          return [/$/, "#@name : "]
+        end
+      else
+        return @prompt
+      end
+    end
+
+    def set_prompt(match, replace)
+      @prompt = [match, replace]
+    end
+
+    def add_requirements(subject)
+      @command_list.each_value do |command|
+	command.add_requirements subject
+      end
+      return subject
+    end
+
+    #Given a set of terms, returns a Command or CommandSet, plus an extraneous (probably argument) terms
+    def find_command(*terms)
+      if terms.empty?
+        return self,[] 
+      end
+
+      command_name = terms.shift
+
+      command = @command_list[command_name]
+
+      if Class === command && Command > command
+	if command.defined?
+	  return command,terms
+	else
+	  raise CommandError, "#{command_name}: unfinalized command: #{command.inspect}"
+	end
+      elsif CommandSet === command
+	return command.find_command(*terms)
+      elsif command.nil?
+        if @command_list[nil].nil?
+          raise CommandException, "Unknown command: #{command_name.inspect}"
+        else
+          return @command_list[nil], terms.unshift(command_name)
+        end
+      else
+	raise ScriptError, "Somehow a non-command made it's " +
+	  "way into the command registry. -- (#{command.inspect})"
+      end
+    end
+
+    def completion_list(terms, prefix, subject)
+      if terms.length == 0
+	list = @command_list.keys.grep(%r{^#{prefix}.*})
+	if @command_list.has_key?(nil)
+	  list += @command_list[nil].completion_list([], prefix, subject)
+	end
+	return list
+      end
+
+      begin
+	command,terms = find_command(*terms)
+	return command.completion_list(terms, prefix, subject)
+      rescue CommandException => ce
+	return []
+      end
+    end
+
+    def path
+      if @parent.nil?
+        return []
+      else
+        return @parent.path + [@name]
+      end
+    end
+
+    def documentation(width, parent="")
+      docs = ""
+      docs = @command_list.to_a.reject do |el|
+	el[0].nil?
+      end
+      
+      parent = [parent, @name].join(" ")
+      docs = docs.sort_by{|el| el[0]}.inject([]) do |doclist,cmd|
+	doclist += cmd[1].short_docs(width, parent)
+      end
+      
+      return docs
+    end
+
+    alias short_docs documentation
+
+    def instance(subject)
+      if @command_list.has_key?(nil)
+	return @command_list[nil].new(subject)
+      else
+	raise CommandException, "incomplete command"
+      end
+    end
+
+    def command_list
+      return @command_list.dup
+    end
+  end
+end
+