command-set 0.8.0

data/lib/command-set/arguments.rb

@@ -0,0 +1,547 @@
+require 'command-set/dsl'
+
+module Command
+  #An Argument has a name and a value.  They're used to to validate input, provide input prompts (like
+  #tab-completion or pop-up menus.
+  class Argument
+
+    #Used for new Argument subclasses to register the types they can be based on, and the explicit names of the
+    # arguments
+    def self.register(shorthand, type=nil)
+      DSL::Argument::register_argument(self, shorthand, type)
+    end
+
+    def initialize(name)
+      @name = name.to_s
+      @value = nil
+    end
+
+    attr_reader :name, :value
+
+    #Provides a list of completion options based on a string prefix and the subject
+    #The completion should be an array of completion options.  If the completions have a common
+    #prefix, completion will enter it for the user.  As a clever trick for providing hints:
+    #  [ "This is a hint", "" ]
+    def complete(prefix, subject)
+      raise NotImplementedError, "complete not implemented in #{self.class.name}"
+    end
+
+    #Validates the input string against the type of the argument.  Returns true if the input is valid, or else
+    #false
+    def validate(term, subject)
+      raise NotImplementedError, "validate not implemented in #{self.class.name}"
+    end
+
+    #Pulls strings from an ordered list of inputs and provides the parsed data to the host command
+    #Returns the parsed data or raises ArgumentInvalidException
+    def consume(subject, arguments)
+      term = arguments.shift
+      unless validate(term, subject)
+	raise ArgumentInvalidException, {@name => term}
+      end
+      return {@name => parse(subject, term)}
+    end
+
+    def consume_hash(subject, hash)
+      unless((term = hash[@name]).nil?)
+        if validate(term, subject)
+          return {@name => parse(subject, term)}
+        else
+          raise ArgumentInvalidException, {@name => term}
+        end
+      end
+      return {}
+    end
+
+    def check_present(keys)
+      unless keys.include?(@name)
+        raise OutOfArgumentsException, "Missing argument: #@name!"
+      end
+    end
+
+    #Used for completion, to skip along terms and arguments until we're at a place where completion begins.
+    #Both the terms and arguments arrays are modified by this method, so a number of clever tricks can be played
+    #to make completion work.
+    def match_terms(subject, terms, arguments)
+      arguments.shift
+      validate(terms.shift, subject)
+    end
+
+    #Used in completion to recognize that some arguments can be skipped
+    def omittable?
+      false
+    end
+
+    #Used in validation to require some arguments, and allow others to be optional
+    def required?
+      true
+    end
+
+    #Returns the parsed data equivalent of the string input
+    def parse(subject, term)
+      return term
+    end
+  end
+
+  class ArgumentDecorator < Argument
+    def self.register(name)
+      DSL::Argument::register_decorator(self, name)
+    end
+
+    class << self
+      alias register_as register
+    end
+
+    def self.decoration(&block)
+      @decor = block
+    end
+
+    def self.decor
+      @decor
+    end
+
+    def decor
+      self.class.decor
+    end
+
+    def initialize(up)
+      @wrapping_decorator = up
+    end
+
+    def embed_argument(argument)
+      @wrapping_decorator.embed_argument(decorate(argument))
+    end
+
+    def decorate(argument)
+      block = decor
+      (class << argument; self; end).class_eval &block
+      return argument
+    end
+  end
+
+  class NumberArgument < Argument
+    register "number", Range
+
+    def initialize(name, range=nil)
+      super(name)
+      @range = range
+    end
+
+    attr_accessor :range
+
+    def complete(prefix, subject)
+      return [] unless validate(prefix, subject)
+      return [prefix]
+    end
+
+    def validate(term, subject)
+      value = parse(subject, term)
+      return false if not range.nil? and not range.include?(value) 
+      return true if %r{^0(\D.*)?} =~ term
+      return value != 0
+    end
+
+    def parse(subject, term)
+      @value = term.to_i
+    end
+  end
+
+  class RegexpArgument < Argument
+    register "regexp", Regexp
+    register "regex"
+
+    def initialize(name, regex)
+      @name = name
+      @regex = regex
+    end
+
+    def complete(prefix, subject)
+      return [prefix]
+    end
+
+    def validate(term, subject)
+      return @regex =~ term
+    end
+  end
+
+  class FileArgument < Argument
+    register "file"
+    Defaults = { 
+      :prune_patterns => [/^\./],
+      :dirs => [ENV['PWD']],
+      :acceptor => proc do |path|
+        return (File.exists?(path) and not File.directory?(path))
+      end
+    }
+
+    def initialize(name, options={})
+      super(name)
+      if Hash === options
+        @options = Defaults.merge(options)
+        @acceptor = @options[:acceptor]
+      elsif Proc === options
+        @options = Defaults.dup
+        @acceptor = options
+      else
+        raise "File argument needs hash or proc!"
+      end
+    end
+
+    def complete(prefix, subject)
+      list = []
+      search_path = @options[:dirs].dup
+      match = %r{^#{Regexp.escape(prefix)}.*}
+      infix = "" 
+
+      if( not (m = %r{^/([^/]*)$}.match(prefix)).nil? )
+	infix = "/"
+	search_path = ["/"]
+	match = /^#{m[1]}.*/
+      elsif( not (m = %r{^/(.*/)([^/]*)$}.match(prefix)).nil? )
+	infix = "/#{m[1]}"
+	match = /^#{m[2]}.*/
+	search_path = [infix]
+      elsif( %r{/$} =~ prefix )
+	infix = prefix
+	search_path.map! {|path| File.join(path, prefix)}
+	match = /.*/
+      elsif( %r{/} =~ prefix )
+	infix = File.dirname(prefix) + "/"
+	search_path.map! {|path| File.join(path, infix)}
+	match = %r{^#{Regexp.escape(File.basename(prefix))}.*}
+      end
+
+      search_path.each do |dir|
+	begin 
+	  Dir.foreach(dir) do |path|
+	    catch(:bad_path) do
+	      next unless match =~ path
+
+	      @options[:prune_patterns].each do |pat|
+		if pat =~ path
+		  throw :bad_path 
+		end
+	      end
+
+	      candidate = File.join(dir,path)
+	      if(File.file?(candidate))
+		throw :bad_path unless @acceptor[candidate]
+	      end
+
+	      if(File.directory?(candidate))
+		path += "/"
+	      end
+
+	      list << infix + path
+	    end
+	  end
+	rescue Errno::ENOENT
+	  next
+	end
+      end
+
+      if(list.length == 1 && list[0] =~ /\/$/)
+	list << list[0] + "."
+      end
+
+      list
+    end
+
+    def validate(term, subject)
+      if(%r{^/} =~ term)
+	return @acceptor[term]
+      end
+
+      @options[:dirs].each do |dir|
+	path = File.join(dir, term)
+	if(File.exists?(path))
+	  return @acceptor[path]
+	end
+      end
+
+      return @acceptor[File.join(@options[:dirs].first, term)]
+    end
+  end
+
+  class FiddlyArgument < Argument
+    def initialize(name, &block)
+      super(name)
+
+      (class << self; self; end).class_eval &block
+    end
+
+    def self.completion(&block)
+      raise TypeError unless block.arity == 2
+      define_method :complete, &block
+    end
+
+
+    def self.validation(&block)
+      raise TypeError unless block.arity == 2
+      define_method :validate, &block
+    end
+
+    def self.parser(&block)
+      raise TypeError unless block.arity == 2
+      define_method :parse, &block
+    end
+  end
+
+  class ArrayArgument < Argument
+    register "array", Array
+    register "choose"
+
+    def initialize(name, array)
+      super(name)
+      @options = array
+    end
+
+    def complete(prefix, subject)
+      return @options.grep(%r{^#{prefix}.*})
+    end
+
+    def validate(term, subject)
+      return @options.include?(term)
+    end
+  end
+
+  class StringArgument < Argument
+    register "string", String
+    register "any"
+
+    def initialize(name, string)
+      super(name)
+      @description = string
+    end
+
+    def complete(prefix, subject)
+      return [@description, ""]
+    end
+
+    def validate(term, subject)
+      return true
+    end
+  end
+
+  class ProcArgument < Argument
+    register "proc", Proc
+
+    def initialize(name, prok)
+      raise TypeError, "Block not arity 2: #{prok.arity}" unless prok.arity == 2
+      super(name)
+      @process = proc &prok
+    end
+
+    def complete(prefix, subject)
+      return @process.call(prefix, subject)
+    end
+
+    def validate(term, subject)
+      return @process.call(term, subject).include?(term)
+    end
+  end
+
+  class NoValidateProcArgument < ProcArgument
+    register "nonvalidating_proc"
+
+    def validate(term, subject)
+      return true
+    end
+  end
+
+  #Most common decorator.  Tags a argument as omitable.  Otherwise, the
+  #interpreter will return an error to the user if they leave out an
+  #argument.  Optional arguments that aren't provided are set to nil.
+  class Optional < ArgumentDecorator
+    register_as "optional"
+
+    decoration do
+      def required?
+        false
+      end
+    end
+  end
+
+  #Indicated that the name of the argument has to appear on the command line
+  #before it will be recognized.  Useful for optional or alternating arguments
+  class Named < ArgumentDecorator
+    register_as "named"
+
+    decoration do
+      alias_method(:old_consume, :consume)
+      alias_method(:old_complete, :complete)
+      alias_method(:old_match_terms, :match_terms)
+      def consume(subject, arguments)
+        if arguments.first == @name
+          arguments.shift
+          return old_consume(subject,arguments)
+        else
+          raise ArgumentInvalidException, "Name \"#{@name}\" required."
+        end
+      end
+
+      def match_terms(subject, terms, arguments)
+        if terms.first == @name.to_s
+          terms.shift
+        else
+          old_match_terms(subject, terms, arguments)
+        end
+      end
+
+      def complete(prefix, subject)
+        if %r{^#{prefix.to_s}.*} =~ @name.to_s
+          return [@name.to_s]
+        else
+          return old_complete(prefix, subject)
+        end
+      end
+    end
+  end
+
+
+  class MultiArgument < Argument
+    register "multiword"
+
+    def initialize(name, block)
+      raise TypeError, "Block arity is #{prok.arity}, not 2" unless block.arity == 2
+      super(name)
+      @process = proc &block
+    end
+
+    def complete(prefix, subject)
+      return @process[[*prefix], subject]
+    end
+
+    def validate(terms, subject)
+      return (not @process[[*terms], subject].empty?)
+    end
+
+    def consume(subject, arguments)
+      value = []
+      until arguments.empty? do
+	trying = arguments.shift
+	if(validate(value + [trying], subject))
+	  value << trying
+	else
+	  arguments.unshift(trying)
+	  break
+	end
+      end
+      return {@name => value}
+    end
+
+    def omittable?
+      true
+    end
+
+    def match_terms(subject, terms, arguments)
+      validated = validate(terms.first, subject)
+      if(validated)
+	terms.shift
+      else
+	arguments.shift
+      end
+      return true
+    end
+  end
+
+  #Allows several arguments to share a position.  Pass a block to the
+  #"decorator" method with the argument declarations inside.  The first
+  #argument that can parse the input will be assigned - others will get nil.
+  class AlternatingArgument < ArgumentDecorator
+    register "alternating"
+    register "multi"
+# initialize(embed_in){ yield if block_given? }
+    def initialize(embed_in, &block)
+      super(embed_in)
+      @names = []
+      @sub_arguments = []
+      self.instance_eval &block
+      @wrapping_decorator.embed_argument(self)
+    end
+
+    def name(name = nil)
+      if name.nil?
+        return @names
+      else
+        name = name.to_s
+        @names << name
+        @name = name
+      end
+    end
+
+    def complete(prefix, subject)
+      return sub_arguments.inject([]) do |list, sub_arg|
+        list.concat sub_arg.complete(prefix, subject)
+      end
+    end
+
+    def validate(term, subject)
+      begin
+        first_catch(term, subject)
+        return true
+      rescue CommandError
+        return false
+      end
+    end
+
+    def consume(subject, arguments)
+      term = arguments.first
+      catcher = first_catch(term, subject)
+      result = catcher.consume(subject, arguments)
+      @value = catcher.value
+      return result.merge({@name => result[catcher.name]})
+    end
+
+    #If a hash is used for arguments that includes more than one of alternating argument's sub-arguments, the behavior is undefined
+    def consume_hash(subject, hash)
+      begin
+        return super(subject, hash)
+      rescue OutOfArgumentsException; end
+      @sub_arguments.each do |arg|
+        unless hash[arg.name].nil?
+          result = arg.consume_hash(subject, hash)
+          return result.merge({@name => result[arg.name]})
+        end
+      end
+      raise OutOfArgumentsException, "Missing argument: #@name!"
+    end
+
+    def match_terms(subject, terms, arguments)
+      first_catch(terms.first, subject).match_terms(subject, terms, arguments)
+    end
+
+    def omittable?
+      return sub_arguments.inject(false) do |can_omit, sub_arg|
+        can_omit || sub_arg.omittable?
+      end
+    end
+
+    def parse(subject, term)
+      catcher = first_catch(term, subject)
+      return catcher.parse(subject, term)
+    end
+
+    def embed_argument(arg)
+      @names << arg.name
+      @sub_arguments << optional.decorate(arg)
+    end
+    private
+
+    attr_reader :sub_arguments
+
+    def first_catch(term, subject)
+      catcher = sub_arguments.find do |sub_arg|
+        sub_arg.validate(term, subject)
+      end
+
+      if catcher.nil? 
+	raise ArgumentInvalidException, {@name => term}
+      end
+
+      return catcher
+    end
+
+    include DSL::Argument
+  end
+end