choice 0.1.0

data/lib/choice.rb

@@ -0,0 +1,132 @@
+$:.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 
+  class <<self 
+    # The main method, which defines the options
+    def options(&block)
+      # Setup all instance variables
+      @@args    ||= false
+      @@banner  ||= false
+      @@header  ||= Array.new
+      @@options ||= Array.new
+      @@footer  ||= Array.new
+      
+      # Args can be overriden, but shouldn't be
+      self.args = @@args || ARGV
+      
+      # Eval the passed block to define the options.
+      instance_eval(&block)
+
+      # Parse what we've got.
+      parse
+    end
+  
+    # Returns a hash representing options passed in via the command line.
+    def choices
+      @@choices
+    end
+  
+    # Defines an option.
+    def option(opt, &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(&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')
+        self.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.
+          self.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
+    
+    # You can choose to not kill the script after the help screen is prtined.
+    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
+  
+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,104 @@
+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]
+
+    # 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(option = nil, &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.
+      self.instance_eval(&block) if block_given?      
+
+      # This might be going away in the future.  If you pass nothing but a 
+      # name, Option will try and guess what you want.
+      defaultize(option) unless option.nil?      
+    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 true if method =~ /\?/ && instance_variable_get(var)
+      return false 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
+    
+    # Might be going away soon.  Tries to make some guesses about what you
+    # want if you instantiated Option with a name and no block.
+    def defaultize(option)
+      option = option.to_s
+      short "-#{option[0..0].downcase}"
+      long "--#{option.downcase}=#{option.upcase}"
+    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?
+      return false if @desc.nil?
+      true
+    end
+    
+    # Returns Option converted to an array.
+    def to_a
+      array = []
+      @choices.each do |choice|
+        array << instance_variable_get("@#{choice}") if @choices.include? choice
+      end
+      array
+    end
+    
+    # Returns Option converted to a hash.
+    def to_h
+      hash = {}
+      @choices.each do |choice|
+        hash[choice] = instance_variable_get("@#{choice}") if @choices.include? choice
+      end
+      hash
+    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,145 @@
+module Choice
+  
+  # The parser takes our option definitions and our arguments and produces
+  # a hash of values.
+  module Parser #:nodoc: all
+    
+    # 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 self.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.
+      if options.is_a?(Array)
+        new_options = {}
+        options.each { |o| new_options[o[0]] = o[1] if o.is_a?(Array) }
+        options = new_options
+      end
+      
+      # 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 = {}, {}, {}, {}, {}
+
+      # We can define these on the fly because they are all so similar.
+      params = %w[short cast filter action default]
+      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.
+        if obj.respond_to?(:to_h)
+          obj = obj.to_h 
+        else
+          raise HashExpectedForOption
+        end
+
+        # 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, save it as a regex.
+        # If it's present but can't pull off a to_s (wtf?), raise an error.
+        if obj['validate'] && obj['validate'].respond_to?(:to_s)
+          validators[name] = Regexp.new(obj['validate'].to_s)
+        elsif obj['validate']
+          raise ValidateExpectsRegexp
+        end
+        
+        # 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'] =~ /=/
+          option, argument = obj['long'].split('=')
+          longs[name] = option
+          required[name] = true unless argument =~ /^\[(.+)\]$/
+        elsif obj['long']
+          # Set without any checking if it's just --long
+          longs[name] = obj['long']
+        end
+      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.
+          choices[hashes['shorts'].index(arg)] = value
+
+        elsif arg =~ /=/ && longs.value?(arg.split('=')[0])
+          # If we get a long with a = in it, grab it and the argument
+          # passed to it.
+          choices[longs.index(arg.split('=')[0])] = arg.split('=')[1]
+
+        elsif longs.value?(arg)
+          # If we get a long with no =, just set it to true.
+          choices[longs.index(arg)] = true
+
+        else
+          # If we're here, we have no idea what the passed argument is.  Die.
+          raise UnknownArgument 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.
+        raise ArgumentValidationFails if validators[name] && validators[name] !~ value
+        
+        # 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
+      
+      # 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
+    
+    # All the possible exceptions this module can raise.
+    class ParseError < Exception; end
+    class HashExpectedForOption < Exception; end
+    class UnknownArgument < ParseError; end      
+    class ArgumentRequired < ParseError; end
+    class ValidateExpectsRegexp < ParseError; end
+    class ArgumentValidationFails < ParseError; end
+  end
+end