ivanvc-choice 0.1.3.1

data/lib/choice/parser.rb

@@ -0,0 +1,233 @@
+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)
+      
+      # Operate on a copy of the inputs
+      args = args.dup
+      
+      # 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
+      
+      rest = []
+      
+      # Go through the arguments and try to figure out whom they belong to
+      # at this point.
+      while arg = args.shift
+        if hashes['shorts'].value?(arg)
+          # Set the value to the next element in the args array since
+          # this is a short.
+
+          # If the next argument isn't a value, set this value to true
+          if args.empty? || args.first.match(/^-/)
+            value = true
+          else
+            value = args.shift
+          end
+
+          # 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] << value unless value.nil?
+            choices[name]  += arrayize_arguments(args)
+          else
+            choices[name] = value
+          end
+
+        elsif (m = arg.match(/^(--[^=]+)=?/)) && longs.value?(m[1])
+          # The joke here is we always accept both --long=VALUE and --long VALUE.
+          
+          # Grab values from --long=VALUE format
+          name, value = arg.split('=', 2)
+          name = longs.index(name)
+          
+          if value.nil? && args.first !~ /^-/
+            # Grab value otherwise if not in --long=VALUE format.  Assume --long VALUE.
+            # Value is nil if we don't have a = and the next argument is no good
+            value = args.shift
+          end
+
+          # If we expect an array, tack this argument on.
+          if arrayed[name]
+            # If this is arrayed and the value isn't nil, set it.
+            choices[name] ||= []
+            choices[name] << value unless value.nil?
+            choices[name] += arrayize_arguments(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.
+          if arg =~ /^-/
+            raise UnknownOption 
+          else
+            rest << arg
+          end
+        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 and the rest of the args
+      [ choices, rest ]
+    end
+
+  private
+    # Turns trailing command line arguments into an array for an arrayed value
+    def arrayize_arguments(args)
+      # Go through trailing arguments and suck them in if they don't seem
+      # to have an owner.
+      array = []
+      until args.empty? || args.first.match(/^-/)
+        array << args.shift
+      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

data/lib/choice/version.rb

@@ -0,0 +1,9 @@
+module Choice
+  module Version #:nodoc:
+    MAJOR  = 0
+    MINOR  = 1
+    TINY   = 3
+    PATCH  = 1
+    STRING = [MAJOR, MINOR, TINY, PATCH] * '.'
+  end
+end

data/lib/choice/writer.rb

@@ -0,0 +1,187 @@
+module Choice
+  # This module writes to the screen.  As of now, its only real use is writing
+  # the help screen.
+  module Writer #:nodoc: all
+    
+    # Some constants used for printing and line widths
+    SHORT_LENGTH = 6
+    SHORT_BREAK_LENGTH = 2 
+    LONG_LENGTH = 29
+    PRE_DESC_LENGTH = SHORT_LENGTH + SHORT_BREAK_LENGTH + LONG_LENGTH
+    
+    
+    # The main method.  Takes a hash of arguments with the following possible
+    # keys, running them through the appropriate method:
+    #  banner, header, options, footer
+    #
+    # Can also be told where to print (default STDOUT) and not to exit after
+    # printing the help screen, which it does by default.
+    def self.help(args, target = STDOUT, dont_exit = false)
+      # Set our printing target.
+      self.target = target
+
+      # The banner method needs to know about the passed options if it's going
+      # to do its magic.  Only really needs :options if :banner is nil.
+      banner(args[:banner], args[:options])
+
+      # Run these three methods, passing in the appropriate hash element.
+      %w[header options footer].each do |meth|
+        send(meth, args[meth.to_sym])
+      end
+
+      # Exit.  Unless you don't want to.
+      exit unless dont_exit
+    end
+
+    class <<self
+      private
+      
+      # Print a passed banner or assemble the default banner, which is usage.
+      def banner(banner, options)
+        if banner
+          puts banner
+        else
+          # Usage needs to know about the defined options.
+          usage(options)
+        end
+      end
+      
+      # Print our header, which is just lines after the banner and before the
+      # options block.  Needs an array, prints each element as a line.
+      def header(header)
+        if header.is_a?(Array) and header.size > 0
+          header.each { |line| puts line }
+        end
+      end
+
+      # Print out the options block by going through each option and printing
+      # it as a line (or more).  Expects an array.
+      def options(options)
+        # Do nothing if there's nothing to do.
+        return if options.nil? || !options.size
+        
+        # If the option is a hash, run it through option_line.  Otherwise
+        # just print it out as is.
+        options.each do |name, option|
+          if option.respond_to?(:to_h)
+            option_line(option.to_h)          
+          else
+            puts name
+          end
+        end
+      end
+      
+      # The heavy lifting: print a line for an option.  Has intimate knowledge
+      # of what keys are expected.
+      def option_line(option)
+        # Expect a hash
+        return unless option.is_a?(Hash)
+
+        # Make this easier on us
+        short = option['short']
+        long = option['long']
+        line = ''
+
+        # Get the short part.
+        line << sprintf("%#{SHORT_LENGTH}s", short)
+        line << sprintf("%-#{SHORT_BREAK_LENGTH}s", (',' if short && long))
+
+        # Get the long part.
+        line << sprintf("%-#{LONG_LENGTH}s", long)
+
+        # Print what we have so far
+        print line
+
+        # If there's a desc, print it.
+        if option['desc']
+          # If the line is too long, spill over to the next line
+          if line.length > PRE_DESC_LENGTH
+            puts           
+            print " " * PRE_DESC_LENGTH
+          end
+
+          puts option['desc'].shift
+          
+          # If there is more than one desc line, print each one in succession
+          # as separate lines.
+          option['desc'].each do |desc| 
+            puts ' '*37 + desc
+          end
+
+        else
+          # No desc, just print a newline.
+          puts 
+
+        end
+      end
+      
+      # Expects an array, prints each element as a line.
+      def footer(footer)
+        footer.each { |line| puts line } unless footer.nil?
+      end
+      
+      # Prints the usage statement, e.g. Usage prog.rb [-abc]
+      # Expects an array.
+      def usage(options)
+        # Really we just need an enumerable.
+        return unless options.respond_to?(:each)
+
+        # Start off the options with a dash.
+        opts = '-'
+
+        # Figure out the option shorts.
+        options.dup.each do |option|
+          # We really need an array here.
+          next unless option.is_a?(Array)
+
+          # Grab the hash of the last element, which should be the second 
+          # element.
+          option = option.last.to_h
+
+          # Add the short to the options string.
+          opts << option['short'].sub('-','') if option['short']
+        end
+        
+        # Figure out if we actually got any options.
+        opts = if opts =~ /^-(.+)/
+                 " [#{opts}]"
+               end.to_s
+        
+        # Print it out, with our newly aquired options string.
+        puts "Usage: #{program}" << opts
+      end
+
+      # Figure out the name of this program based on what was run.
+      def program
+        (/(\/|\\)/ =~ $0) ? File.basename($0) : $0
+      end
+
+      # Set where we print.
+      def target=(target)
+        @@target = target
+      end
+      
+      # Where do we print?
+      def target
+        @@target
+      end
+
+      public
+      # Fake puts
+      def puts(str = nil)
+        str = '' if str.nil?
+        print(str + "\n")
+      end
+      
+      # Fake printf
+      def printf(format, *args)
+        print(sprintf(format, *args))
+      end
+
+      # Fake print -- just add to target, which may not be STDOUT.
+      def print(str)
+        target << str 
+      end
+    end
+  end
+end

data/test/test_choice.rb

@@ -0,0 +1,234 @@
+$:.unshift "../lib:lib"
+require 'test/unit'
+require 'choice'
+
+$VERBOSE = nil
+
+class TestChoice < Test::Unit::TestCase
+  
+  def setup
+    Choice.reset!
+    Choice.dont_exit_on_help = true
+    Choice.send(:class_variable_set, '@@choices', true)
+  end
+    
+  def test_choices
+    Choice.options do
+      header "Tell me about yourself?"
+      header ""
+      option :band do
+        short "-b"
+        long "--band=BAND"
+        cast String
+        desc "Your favorite band."
+        validate /\w+/
+      end
+      option :animal do
+        short "-a"
+        long "--animal=ANIMAL"
+        cast String
+        desc "Your favorite animal."
+      end
+      footer ""
+      footer "--help This message"
+    end
+
+    band = 'LedZeppelin'
+    animal = 'Reindeer'
+
+    args = ['-b', band, "--animal=#{animal}"]
+    Choice.args = args
+
+    assert_equal band, Choice.choices['band']
+    assert_equal animal, Choice.choices[:animal]
+    assert_equal ["Tell me about yourself?", ""], Choice.header
+    assert_equal ["", "--help This message"], Choice.footer
+
+    assert_equal Choice.choices['band'], Choice['band']
+    assert_equal Choice.choices[:animal], Choice[:animal]
+  end
+
+  def test_failed_parse
+    assert Hash.new, Choice.parse
+  end
+
+  HELP_STRING = ''
+  def test_help
+    Choice.output_to(HELP_STRING)
+
+    Choice.options do
+      banner "Usage: choice [-mu]"
+      header ""
+      option :meal do
+        short '-m'
+        desc 'Your favorite meal.'
+      end
+      
+      separator ""
+      separator "And you eat it with..."
+      
+      option :utencil do
+        short "-u"
+        long "--utencil[=UTENCIL]"
+        desc "Your favorite eating utencil."
+      end
+    end
+
+    Choice.args = ['-m', 'lunch', '--help']
+    
+    help_string = <<-HELP
+Usage: choice [-mu]
+
+    -m                               Your favorite meal.
+
+And you eat it with...
+    -u, --utencil[=UTENCIL]          Your favorite eating utencil.
+HELP
+
+    assert_equal help_string, HELP_STRING
+  end
+  
+  UNKNOWN_STRING = ''
+  def test_unknown_argument
+    Choice.output_to(UNKNOWN_STRING)
+    
+    Choice.options do
+      banner "Usage: choice [-mu]"
+      header ""
+      option :meal do
+        short '-m'
+        desc 'Your favorite meal.'
+      end
+      
+      separator ""
+      separator "And you eat it with..."
+      
+      option :utencil do
+        short "-u"
+        long "--utencil[=UTENCIL]"
+        desc "Your favorite eating utencil."
+      end
+    end
+
+    Choice.args = ['-m', 'lunch', '--motorcycles']
+    
+    help_string = <<-HELP
+Usage: choice [-mu]
+
+    -m                               Your favorite meal.
+
+And you eat it with...
+    -u, --utencil[=UTENCIL]          Your favorite eating utencil.
+HELP
+    
+    assert_equal help_string, UNKNOWN_STRING
+  end
+  
+  REQUIRED_STRING = ''
+  def test_required_argument
+    Choice.output_to(REQUIRED_STRING)
+    
+    Choice.options do
+      banner "Usage: choice [-mu]"
+      header ""
+      option :meal, :required => true do
+        short '-m'
+        desc 'Your favorite meal.'
+      end
+      
+      separator ""
+      separator "And you eat it with..."
+      
+      option :utencil do
+        short "-u"
+        long "--utencil[=UTENCIL]"
+        desc "Your favorite eating utencil."
+      end
+    end
+
+    Choice.args = ['-u', 'spork']
+    
+    help_string = <<-HELP
+Usage: choice [-mu]
+
+    -m                               Your favorite meal.
+
+And you eat it with...
+    -u, --utencil[=UTENCIL]          Your favorite eating utencil.
+HELP
+    
+    assert_equal help_string, REQUIRED_STRING
+  end
+
+  def test_shorthand_choices
+    Choice.options do
+      header "Tell me about yourself?"
+      header ""
+      options :band => { :short => "-b", :long => "--band=BAND", :cast => String, :desc => ["Your favorite band.", "Something cool."],
+                        :validate => /\w+/ },
+              :animal => { :short => "-a", :long => "--animal=ANIMAL", :cast => String, :desc => "Your favorite animal." }
+      
+      footer ""
+      footer "--help This message"
+    end
+    
+    band = 'LedZeppelin'
+    animal = 'Reindeer'
+    
+    args = ['-b', band, "--animal=#{animal}"]
+    Choice.args = args
+    
+    assert_equal band, Choice.choices['band']
+    assert_equal animal, Choice.choices[:animal]
+    assert_equal ["Tell me about yourself?", ""], Choice.header
+    assert_equal ["", "--help This message"], Choice.footer
+  end
+  
+  def test_args_of
+    suits = %w[clubs diamonds spades hearts]
+    stringed_numerics = (1..13).to_a.map { |a| a.to_s }
+    valid_cards = stringed_numerics + %w[jack queen king ace]
+    cards = {}
+    stringed_numerics.each { |n| cards[n] = n }
+    cards.merge!('1' => 'ace', '11' => 'jack', '12' => 'queen', '13' => 'king')
+    
+    Choice.options do
+      header "Gambling is fun again!  Pick a card and a suit (or two), then see if you win!"
+      header ""
+      header "Options:" 
+
+      option :suit, :required => true do
+        short '-s'
+        long '--suit *SUITS'
+        desc "The suit you wish to choose.  Required.  You can pass in more than one, even."
+        desc "  Valid suits: #{suits * ' '}"
+        valid suits
+      end
+
+      separator ''
+
+      option :card, :required => true do
+        short '-c'
+        long '--card CARD'
+        desc "The card you wish to gamble on.  Required.  Only one, please."
+        desc "  Valid cards: 1 - 13, jack, queen, king, ace"
+        valid valid_cards
+        cast String
+      end
+      
+      #cheat! to test --option=
+      option :autowin do
+        short '-a'
+        long '--autowin=PLAYER'
+        desc 'The person who should automatically win every time'
+        desc 'Beware: raises the suspitions of other players'
+      end
+    end
+    
+    args = ["-c", "king", "--suit", "clubs", "diamonds", "spades", "hearts", "--autowin", "Grant"]
+    Choice.args = args
+    assert_equal ["king"], Choice.args_of("-c")
+    assert_equal ["clubs", "diamonds", "spades", "hearts"], Choice.args_of("--suit")
+    assert_equal ["Grant"], Choice.args_of("--autowin")
+  end
+end