command-set 0.8.0

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

@@ -0,0 +1,243 @@
+module Command
+  module StandardCommand
+    class Resume < Command
+      @name = "resume"
+      optional.argument :deck, "Resume from name"
+
+      doesnt_undo
+
+      subject_methods :chain_of_command, :pause_decks
+
+      action do
+        subject.chain_of_command.insert(0, *(subject.pause_decks[deck]))
+      end
+      defined
+    end
+
+    class Quit < Command
+      @name = "quit"
+      subject_methods :interpreter
+
+      doesnt_undo
+
+      action do
+        subject.interpreter.stop
+      end
+      defined
+    end
+  end
+
+  #This is a collection of useful commands that are often useful to add to
+  #DSL::CommandSetDefinition#include_commands
+  #
+  #For instance
+  #
+  # set = CommandSet::define_commands do
+  #   include_commands Command::StandardCommands::Quit
+  #   include_commands Command::StandardCommands::Undo
+  #   include_commands Command::StandardCommands::Help
+  # end
+  #
+  #Some notes: 
+  #
+  #0. Resume is usually handy for use in +chain+ calls, not as something to
+  #   present for the user to access directly.  It resumes paused commands.
+  #0. Mode is useful in subcommands.  Including it lets the user use the
+  #   subcommand by itself to switch into a mode where that subcommand is
+  #   the root command set.  Then "exit" lets them leave and return to the
+  #   regular set.  Consider IOS's config mode, for instance. 
+  #0. Set is useful for allowing the user to update program settings on the
+  #   fly.  It assumes a set of nested hashes that represent the settings.
+  #   It functions as you'd (hopefully) expect.  +set+ +optionname+ returns
+  #   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
+
+	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
+    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
+
+      command(:exit) do
+	subject_methods :interpreter
+	doesnt_undo
+
+	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
+  end
+end

data/lib/command-set/subject.rb

@@ -0,0 +1,91 @@
+module Command
+  #This object represents the subject of a command set.  To expose parts of
+  #the application to the command set, commands should call subject_methods
+  #with the names of methods it expects to use.  
+  #
+  #Furthermore, Subject maintains the state of the command set, which helps
+  #put all of the logic in the Command objects by letting them maintain
+  #state in one place
+  #
+  #Subjects are very picky about their fields.  The motivation here is to
+  #fail fast.  Commands can't access fields they don't declare with
+  #DSL::CommandDefinition#subject_methods, and the interpreter will fail
+  #fast unless the required fields have been assigned.
+  #
+  #Finally, Commands can't set fields - but the fields are the same for each
+  #command, so they can change the fields.  For drastic changes, try
+  #Array#replace or Hash#replace
+  class Subject
+    class UndefinedField; end
+    Undefined = UndefinedField.new
+
+    def required_fields(*field_names)
+      field_names.map! {|name| name.to_s}
+      field_names -= instance_variables.map {|var| var.sub(/^@/, "")}
+      field_names.each do |field|
+	add_accessor(field)
+      end
+    end
+
+    def verify
+      missing = instance_variables.find_all do |var| 
+	UndefinedField === instance_variable_get(var)
+      end
+      unless missing.empty?
+	raise RuntimeError, "Undefined fields: #{missing.join(", ")}" 
+      end	
+      return nil
+    end
+
+    def get_image(with_fields)
+      image = SubjectImage.new
+      missing_fields = []
+      with_fields.each do |field|
+        begin 
+          field = field.to_s
+          value = instance_variable_get("@#{field}")
+          image.add_field(field, value)
+        rescue NameError
+          missing_fields << field
+        end
+      end
+      unless missing_fields.empty? 
+        raise CommandException, "Subject is missing fields: #{missing_fields.join(", ")}"
+      end
+      image
+    end
+
+    protected
+    def add_accessor(name)
+      self.instance_variable_set("@#{name}", Undefined)
+      meta = class << self; self; end
+
+    meta.instance_eval do
+
+      define_method("#{name}=") do |value|
+	return instance_variable_set("@#{name}", value)
+      end
+    end
+  end
+end
+
+#This is the object type that's actually passed to a command.  It's
+#populated using the subject_methods that the command declared, using values
+#from the application Subject.
+class SubjectImage
+
+  #You shouldn't really need to ever call this - it's used by the
+  #interpreter to set up the image before it's passed to the command
+  def add_field(name, value)
+    meta = class << self; self; end
+
+  meta.instance_eval do
+    define_method("#{name}") do
+      return value
+    end
+  end
+end
+end  
+
+
+end

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

@@ -0,0 +1,171 @@
+require 'readline'
+require 'command-set'
+require 'dl/import'
+require 'logger'
+require 'command-set/interpreter'
+
+#This really locks text-interpreter down to Linux, maybe Unix-like
+#platforms, I'm thinking.  A more flexible way of doing this would rock,
+#regardless of length.
+module Readline
+  extend DL::Importable
+  dlload "/lib/libreadline.so"
+  RLLB = symbol("rl_line_buffer")
+  def self.line_buffer
+    p = RLLB.ptr
+    if p.nil?
+      return p
+    else
+      return p.to_s
+    end
+  end
+end
+
+module Command
+   class TextInterpreter < BaseInterpreter
+     def initialize
+       super
+       @complete_line = false
+       @behavior.merge!(
+         :prompt => [/(?:: )?$/, "> "]
+       )
+     end
+
+     attr_accessor :complete_line
+
+     def go
+       if @command_set.nil? or @subject.nil?
+         raise "command_set or subject unset!"
+       end
+
+       Readline.completion_proc = lambda do |prefix|
+         parsed_input = Readline.line_buffer.split(" ")
+         unless prefix.empty?
+           parsed_input.pop
+         end
+
+         list = current_command_set.completion_list(parsed_input, 
+                                                    prefix, build_subject)
+         list
+       end
+
+       @stop = false
+
+       begin
+         line = Readline.readline(get_prompt, true)
+         next if line.empty?
+         process_line(line)
+       rescue Interrupt
+         puts "Interrupt: please use \"quit\""
+       rescue CommandException => ce
+         @out_io.puts "Error: " + ce.message
+         @out_io.puts ce.backtrace if @behavior[:debug_commands]
+         logger.warn ce.message
+         ce.backtrace.each do |line|
+           logger.debug line
+         end
+
+       rescue Exception => e
+         @out_io.puts "Exception: " + e.message
+         @out_io.puts e.backtrace.join("\n") if @behavior[:debug_commands]
+         logger.warn e.message
+         e.backtrace.each do |line|
+           logger.debug line
+         end
+         puts "Waiting for return"
+         $stdin.gets
+         @stop = true
+       end until @stop
+     end
+
+     def cook_input(line)
+       line = split_line(line)
+       if(@complete_line)
+         new_line = []
+         line.each do |word|
+           word = complete(word, new_line)
+           new_line << word
+         end
+         line = new_line
+       end
+       return CommandSetup.new(line)
+     end
+
+     def assign_terms(cmd)
+       terms = super
+       unless terms.empty?
+         puts "(Discarding extraneous: #{terms.join(" ")}"
+       end
+     end
+
+     alias single_command process_input
+     alias process_line process_input
+
+     def complete(word, line)
+       list = current_command_set.completion_list(line, word, build_subject)
+
+       if list.length == 0
+         raise CommandException, "Unrecognized: #{word}"
+       end
+
+       return word if list[-1].empty?
+
+       if list.length == 1
+         return list[0]
+       else
+         raise CommandException, "Ambiguous: #{word}"
+       end
+     end
+
+     def split_line(line)
+       line_array = []
+       scanner = StringScanner.new(line)
+
+       until scanner.eos?
+         scanner.scan(/\s*/)
+         quote = scanner.scan(/['"]/)
+         unless quote.nil?
+           line_array << ""
+           until scanner.eos?
+             line_array.last << scanner.scan(/[^#{quote}\\]*/)
+             stopped_by = scanner.scan(/[#{quote}\\]/)
+             break unless stopped_by == '\\'
+             line_array.last << scanner.getch
+           end
+         else
+           line_array << ""
+           until scanner.eos?
+             line_array.last << scanner.scan(/[^\s\\]*/)
+             stopped_by = scanner.scan(/[\s\\]/)
+             break unless stopped_by == '\\'
+             line_array.last << scanner.getch
+           end
+         end
+       end
+
+       return line_array
+     end
+
+     def get_formatter
+       return Results::TextFormatter.new(::Command::raw_stdout)
+     end
+
+     def get_prompt
+       prompt = ""
+
+       prompt.sub!(*(@command_set.prompt))
+       @sub_modes.each do |mode|
+         prompt.sub!(*(mode.prompt))
+       end
+       prompt.sub!(*(@behavior[:prompt]))
+     end
+
+     def stop
+       @stop = true
+     end
+
+     def prompt_user(message)
+       Readline.readline(message)
+     end
+   end
+end

data/lib/command-set.rb

@@ -0,0 +1,3 @@
+require 'command-set/command'
+require 'command-set/command-set'
+require 'command-set/text-interpreter'

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.4
+specification_version: 1
+name: command-set
+version: !ruby/object:Gem::Version 
+  version: 0.8.0
+date: 2007-11-27 00:00:00 -08:00
+summary: Framework for interactive programs focused around a DSL for commands
+require_paths: 
+- lib
+email: judson@redfivellc.com
+homepage: 
+rubyforge_project: 
+description: CommandSet is a interactive program framework.  Its focus is a DSL for defining commands, much like Rake or RSpec.  The actual interpreter is left as an open question, although a default readline based terminal interpreter is included, it could very well be adapted to interact with CGI or a GUI.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: Another tidy package brought to you by Judson
+authors: 
+- Judson Lester
+files: 
+- lib/command-set.rb
+- lib/command-set
+- lib/command-set/command-set.rb
+- lib/command-set/arguments.rb
+- lib/command-set/og.rb
+- lib/command-set/text-interpreter.rb
+- lib/command-set/subject.rb
+- lib/command-set/result-list.rb
+- lib/command-set/dsl.rb
+- lib/command-set/command.rb
+- lib/command-set/interpreter.rb
+- lib/command-set/standard-commands.rb
+- lib/command-set/results.rb
+- lib/command-set/quick-interpreter.rb
+- lib/command-set/batch-interpreter.rb
+- doc/README
+- doc/Specifications
+- doc/argumentDSL
+test_files: []
+
+rdoc_options: 
+- --diagram
+- --inline-source
+- --main
+- Command
+- --title
+- command-set-0.8.0 RDoc
+extra_rdoc_files: 
+- doc/README
+- doc/Specifications
+- doc/argumentDSL
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+