s0nspark-choice 0.1.4

data/lib/choice.rb

@@ -0,0 +1,155 @@
+$:.unshift File.dirname(__FILE__)
+require 'choice/option'
+require 'choice/parser'
+require 'choice/writer'
+require 'choice/lazyhash'
+
+#
+# Usage of this module is lovingly detailed in the README file.
+#
+module Choice 
+  extend self
+
+  # The main method, which defines the options
+  def options(hash = {}, &block)
+    # if we are passing in a hash to define our options, use that straight
+    options_from_hash(hash) unless hash.empty?
+
+    # Setup all instance variables
+    reset! if hash.empty?
+    @@args ||= ARGV
+    
+    # Eval the passed block to define the options.
+    instance_eval(&block) if block_given?
+
+    # Parse what we've got.
+    parse unless parsed?
+  end
+
+  # Set options from a hash, shorthand style
+  def options_from_hash(options_hash)
+    options_hash.each do |name, definition|
+      option = Option.new
+      definition.each do |key, value| 
+        Array(value).each { |hit| option.send(key, hit) }
+      end
+      @@options << [name.to_s, option]
+    end
+  end
+
+  # Returns a hash representing options passed in via the command line.
+  def choices
+    @@choices
+  end
+
+  # Defines an option.
+  def option(opt, options = {}, &block)
+    # Notice: options is maintained as an array of arrays, the first element
+    # the option name and the second the option object.
+    @@options << [opt.to_s, Option.new(options, &block)]
+  end
+  
+  # Separators are text displayed by --help within the options block.
+  def separator(str)
+    # We store separators as simple strings in the options array to maintain 
+    # order.  They are ignored by the parser.
+    @@options << str
+  end
+  
+  # Define the banner, header, footer methods.  All are just getters/setters
+  # of class variables.
+  %w[banner header footer].each do |method|
+    define_method(method) do |string|
+      variable = "@@#{method}"
+      return class_variable_get(variable) if string.nil?
+      val = class_variable_get(variable) || ''
+      class_variable_set(variable, val << string)
+    end
+  end
+
+  
+  # Parse the provided args against the defined options.
+  def parse #:nodoc:
+    # Do nothing if options are not defined.
+    return unless @@options.size > 0
+
+    # Show help if it's anywhere in the argument list.
+    if @@args.include?('--help') or @@args.include?('-h')
+      help
+    else
+      begin
+        # Delegate parsing to our parser class, passing it our defined 
+        # options and the passed arguments.
+        @@choices = LazyHash.new(Parser.parse(@@options, @@args))
+      rescue Choice::Parser::ParseError
+        # If we get an expected exception, show the help file.
+        help
+      end
+    end
+  end
+  
+  # Did we already parse the arguments?
+  def parsed? #:nodoc:
+    @@choices ||= false
+  end
+  
+  # Print the help screen by calling our Writer object
+  def help #:nodoc:
+    Writer.help( { :banner => @@banner, :header => @@header, 
+                   :options => @@options, :footer => @@footer }, 
+                   output_to, exit_on_help? )
+  end
+  
+  # Set the args, potentially to something other than ARGV.
+  def args=(args) #:nodoc:
+    @@args = args.dup.map { |a| a + '' }
+    parse if parsed?
+  end
+
+  # Return the args.
+  def args #:nodoc:
+    @@args
+  end
+  
+  # Returns the arguments that follow an argument
+  def args_of(opt)
+    args_of_opt = []
+    
+    # Return an array of the arguments between opt and the next option,
+    # which all start with "-"
+    @@args.slice(@@args.index(opt)+1, @@args.length).select do |arg|
+      if arg[0].chr != "-"
+        args_of_opt << arg
+      else
+        break
+      end
+    end
+    args_of_opt
+  end
+  
+  # You can choose to not kill the script after the help screen is printed.
+  def dont_exit_on_help=(val) #:nodoc:
+    @@exit = true
+  end
+  
+  # Do we want to exit on help?
+  def exit_on_help? #:nodoc:
+    @@exit rescue false
+  end
+  
+  # If we want to write to somewhere other than STDOUT.
+  def output_to(target = nil) #:nodoc:
+    @@output_to ||= STDOUT
+    return @@output_to if target.nil?
+    @@output_to = target
+  end
+  
+  # Reset all the class variables.
+  def reset! #:nodoc:
+    @@args    = false
+    @@banner  = false
+    @@header  = Array.new
+    @@options = Array.new
+    @@footer  = Array.new
+  end
+end

data/lib/choice/lazyhash.rb

@@ -0,0 +1,67 @@
+module Choice
+ 
+  # This class lets us get away with really bad, horrible, lazy hash accessing.
+  # Like so:
+  #   hash = LazyHash.new
+  #   hash[:someplace] = "somewhere"
+  #   puts hash[:someplace]
+  #   puts hash['someplace']
+  #   puts hash.someplace
+  #
+  # If you'd like, you can pass in a current hash when initializing to convert
+  # it into a lazyhash.  Or you can use the .to_lazyhash method attached to the 
+  # Hash object (evil!).
+  class LazyHash < Hash 
+    
+    # Keep the old methods around.
+    alias_method :old_store, :store
+    alias_method :old_fetch, :fetch
+    
+    # You can pass in a normal hash to convert it to a LazyHash.
+    def initialize(hash = nil)
+      hash.each { |key, value| self[key] = value } if !hash.nil? && hash.is_a?(Hash)
+    end
+
+    # Wrapper for []
+    def store(key, value)
+      self[key] = value
+    end
+    
+    # Wrapper for []=
+    def fetch(key)
+      self[key]
+    end
+
+    # Store every key as a string.
+    def []=(key, value)
+      key = key.to_s if key.is_a? Symbol
+      self.old_store(key, value)
+    end
+    
+    # Every key is stored as a string.  Like a normal hash, nil is returned if
+    # the key does not exist.
+    def [](key)
+      key = key.to_s if key.is_a? Symbol
+      self.old_fetch(key) rescue return nil
+    end
+
+    # You can use hash.something or hash.something = 'thing' since this is
+    # truly a lazy hash.
+    def method_missing(meth, *args)
+      meth = meth.to_s
+      if meth =~ /=/
+        self[meth.sub('=','')] = args.first
+      else
+        self[meth]
+      end
+    end
+    
+  end
+end
+
+# Really ugly, horrible, extremely fun hack.
+class Hash #:nodoc: 
+  def to_lazyhash
+    return Choice::LazyHash.new(self) 
+  end
+end

data/lib/choice/option.rb

@@ -0,0 +1,90 @@
+module Choice
+  
+  # The Option class parses and stores all the information about a specific
+  # option.
+  class Option #:nodoc: all
+
+    # Since we define getters/setters on the fly, we need a white list of
+    # which to accept.  Here's the list.
+    CHOICES = %w[short long desc default filter action cast validate valid]
+
+    # You can instantiate an option on its own or by passing it a name and
+    # a block.  If you give it a block, it will eval() the block and set itself
+    # up nicely.
+    def initialize(options = {}, &block)
+      # Here we store the definitions this option contains, to make to_a and
+      # to_h easier.
+      @choices = []      
+
+      # If we got a block, eval it and set everything up.
+      instance_eval(&block) if block_given?      
+
+      # Is this option required?
+      @required = options[:required] || false
+      @choices << 'required'
+    end
+       
+    # This is the catch all for the getter/setter choices defined in CHOICES.
+    # It also gives us choice? methods.
+    def method_missing(method, *args, &block)
+      # Get the name of the choice we want, as a class variable string.
+      var = "@#{method.to_s.sub('?','')}"
+
+      # To string, for regex purposes.
+      method = method.to_s
+      
+      # Don't let in any choices not defined in our white list array.
+      raise ParseError, "I don't know `#{method}'" unless CHOICES.include? method.sub('?','')
+      
+      # If we're asking a question, give an answer.  Like 'short?'.
+      return !!instance_variable_get(var) if method =~ /\?/ 
+      
+      # If we were called with no arguments, we want a get.
+      return instance_variable_get(var) unless args[0] || block_given?
+      
+      # If we were given a block or an argument, save it.
+      instance_variable_set(var, args[0]) if args[0]
+      instance_variable_set(var, block) if block_given?
+      
+      # Add the choice to the @choices array if we're setting it for the first
+      # time.
+      @choices << method if args[0] || block_given? unless @choices.index(method)
+    end
+    
+    # The desc method is slightly special: it stores itself as an array and
+    # each subsequent call adds to that array, rather than overwriting it.
+    # This is so we can do multi-line descriptions easily.
+    def desc(string = nil)
+      return @desc if string.nil?
+
+      @desc ||= []
+      @desc.push(string)
+
+      # Only add to @choices array if it's not already present.
+      @choices << 'desc' unless @choices.index('desc')
+    end
+    
+    # Simple, desc question method.
+    def desc?() !!@desc end
+
+    # Returns Option converted to an array.
+    def to_a
+      @choices.inject([]) do |array, choice|
+        return array unless @choices.include? choice
+        array + [instance_variable_get("@#{choice}")]
+      end
+    end
+    
+    # Returns Option converted to a hash.
+    def to_h
+      @choices.inject({}) do |hash, choice|
+        return hash unless @choices.include? choice
+        hash.merge choice => instance_variable_get("@#{choice}") 
+      end
+    end
+    
+    # In case someone tries to use a method we don't know about in their 
+    # option block.
+    class ParseError < Exception; end    
+  end
+end

data/lib/choice/parser.rb

@@ -0,0 +1,227 @@
+module Choice
+  
+  # The parser takes our option definitions and our arguments and produces
+  # a hash of values.
+  module Parser #:nodoc: all
+    extend self
+    
+    # What method to call on an object for each given 'cast' value.
+    CAST_METHODS = { Integer => :to_i, String => :to_s, Float => :to_f,
+                     Symbol => :to_sym }
+    
+    # Perhaps this method does too much.  It is, however, a parser.
+    # You pass it an array of arrays, the first element of each element being
+    # the option's name and the second element being a hash of the option's
+    # info.  You also pass in your current arguments, so it knows what to
+    # check against.
+    def parse(options, args)
+      # Return empty hash if the parsing adventure would be fruitless.
+      return {} if options.nil? || !options || args.nil? || !args.is_a?(Array)
+      
+      # If we are passed an array, make the best of it by converting it
+      # to a hash.
+      options = options.inject({}) do |hash, value|
+        value.is_a?(Array) ? hash.merge(value.first => value[1]) : hash
+      end if options.is_a? Array
+      
+      # Define local hashes we're going to use.  choices is where we store
+      # the actual values we've pulled from the argument list.
+      hashes, longs, required, validators, choices, arrayed = {}, {}, {}, {}, {}, {}
+      hard_required = {}
+
+      # We can define these on the fly because they are all so similar.
+      params = %w[short cast filter action default valid]
+      params.each { |param| hashes["#{param}s"] = {} }
+
+      # Inspect each option and move its info into our local hashes.
+      options.each do |name, obj|
+        name = name.to_s
+
+        # Only take hashes or hash-like duck objects.
+        raise HashExpectedForOption unless obj.respond_to? :to_h
+        obj = obj.to_h 
+
+        # Is this option required?
+        hard_required[name] = true if obj['required']
+
+        # Set the local hashes if the value exists on this option object.
+        params.each { |param| hashes["#{param}s"][name] = obj[param] if obj[param] }
+        
+        # If there is a validate statement, make it a regex or proc.
+        validators[name] = make_validation(obj['validate']) if obj['validate']
+        
+        # Parse the long option. If it contains a =, figure out if the 
+        # argument is required or optional.  Optional arguments are formed
+        # like [=ARG], whereas required are just ARG (in --long=ARG style).
+        if obj['long'] && obj['long'] =~ /(=|\[| )/
+          # Save the separator we used, as we're gonna need it, then split
+          sep = $1
+          option, *argument = obj['long'].split(sep)
+
+          # The actual name of the long switch
+          longs[name] = option
+
+          # Preserve the original argument, as it may contain [ or =,
+          # by joining with the character we split on.  Add a [ in front if
+          # we split on that.
+          argument = (sep == '[' ? '[' : '') << Array(argument).join(sep)
+
+          # Do we expect multiple arguments which get turned into an array?
+          arrayed[name] = true if argument =~ /^\[?=?\*(.+)\]?$/
+         
+          # Is this long required or optional?
+          required[name] = true unless argument =~ /^\[=?\*?(.+)\]$/
+        elsif obj['long']
+          # We can't have a long as a switch when valid is set -- die.
+          raise ArgumentRequiredWithValid if obj['valid']
+
+          # Set without any checking if it's just --long
+          longs[name] = obj['long']
+        end
+
+        # If we were given a list of valid arguments with 'valid,' this option
+        # is definitely required.
+        required[name] = true if obj['valid']
+      end
+
+      # Go through the arguments and try to figure out whom they belong to
+      # at this point.
+      args.each_with_index do |arg, i|
+        if hashes['shorts'].value?(arg)
+          # Set the value to the next element in the args array since
+          # this is a short.
+          value = args[i+1]
+
+          # If the next element doesn't exist or starts with a -, make this
+          # value true.
+          value = true if !value || value =~ /^-/
+
+          # Add this value to the choices hash with the key of the option's
+          # name.  If we expect an array, tack this argument on.
+          name = hashes['shorts'].index(arg)
+          if arrayed[name]
+            choices[name] ||= []
+            choices[name]  += arrayize_arguments(name, args[i+1..-1])
+          else
+            choices[name] = value
+          end
+
+        elsif /^(--[^=]+)=?/ =~ arg && longs.value?($1)
+          # The joke here is we always accept both --long=VALUE and --long VALUE.
+          
+          # Grab values from --long=VALUE format
+          if arg =~ /=/ && longs.value?((longed = arg.split('=')).first)
+            name  = longs.index(longed.shift)
+            value = longed * '='
+            # For the arrayed options.
+            potential_args = args[i+1..-1]
+          else
+            # Grab value otherwise if not in --long=VALUE format.  Assume --long VALUE.
+            name = longs.index(arg)
+            # Value is nil if we don't have a = and the next argument is no good
+            value = args[i+1] =~ /^-/ ? nil : args[i+1] 
+            # For the arrayed options.
+            potential_args = args[i+2..-1]
+          end
+
+          # If we expect an array, tack this argument on.
+          if arrayed[name] && !value.nil?
+            # If this is arrayed and the value isn't nil, set it.
+            choices[name] ||= []
+            choices[name] << value
+            choices[name] += arrayize_arguments(name, potential_args)
+          else
+            # If we set the value to nil, that means nothing was set and we
+            # need to set the value to true.  We'll find out later if that's 
+            # acceptable or not.
+            choices[name] = value.nil? ? true : value
+          end
+
+        else
+          # If we're here, we have no idea what the passed argument is.  Die.
+          raise UnknownOption if arg =~ /^-/
+        end
+      end
+
+      # Okay, we got all the choices.  Now go through and run any filters or
+      # whatever on them.
+      choices.each do |name, value|
+        # Check to make sure we have all the required arguments.
+        raise ArgumentRequired if required[name] && value === true
+
+        # Validate the argument if we need to, against a regexp or a block.
+        if validators[name]
+          if validators[name].is_a?(Regexp) && validators[name] =~ value 
+          elsif validators[name].is_a?(Proc) && validators[name].call(value)
+          else raise ArgumentValidationFails 
+          end
+        end
+
+        # Make sure the argument is valid
+        raise InvalidArgument unless value.to_a.all? { |v| hashes['valids'][name].include?(v) } if hashes['valids'][name] 
+        
+        # Cast the argument using the method defined in the constant hash.
+        value = value.send(CAST_METHODS[hashes['casts'][name]]) if hashes['casts'].include?(name)
+        
+        # Run the value through a filter and re-set it with the return.
+        value = hashes['filters'][name].call(value) if hashes['filters'].include?(name)
+
+        # Run an action block if there is one associated.
+        hashes['actions'][name].call(value) if hashes['actions'].include?(name)
+        
+        # Now that we've done all that, re-set the element of the choice hash
+        # with the (potentially) new value.
+        choices[name] = value
+      end
+      
+      # Die if we're missing any required arguments
+      hard_required.each do |name, value|
+        raise ArgumentRequired unless choices[name]
+      end
+
+      # Home stretch.  Go through all the defaults defined and if a choice
+      # does not exist in our choices hash, set its value to the requested
+      # default.
+      hashes['defaults'].each do |name, value|
+        choices[name] = value unless choices[name]
+      end
+      
+      # Return the choices hash.
+      choices
+    end
+
+  private
+    # Turns trailing command line arguments into an array for an arrayed value
+    def arrayize_arguments(name, args)
+      # Go through trailing arguments and suck them in if they don't seem
+      # to have an owner.
+      array = []
+      potential_args = args.dup 
+      until (arg = potential_args.shift) =~ /^-/ || arg.nil?
+        array << arg
+      end
+      array
+    end
+    
+    def make_validation(validation)
+      case validation
+        when Proc then
+          validation
+        when Regexp, String then 
+          Regexp.new(validation.to_s)
+        else 
+          raise ValidateExpectsRegexpOrBlock
+      end
+    end
+    
+    # All the possible exceptions this module can raise.
+    class ParseError < Exception; end
+    class HashExpectedForOption < Exception; end
+    class UnknownOption < ParseError; end      
+    class ArgumentRequired < ParseError; end
+    class ValidateExpectsRegexpOrBlock < ParseError; end
+    class ArgumentValidationFails < ParseError; end
+    class InvalidArgument < ParseError; end
+    class ArgumentRequiredWithValid < ParseError; end
+  end
+end