NAME
  options.rb

DESCRIPTION
  options.rb simplifies the common idiom of dealing with keyword options in
  ruby functions.  it also deals correctly with symbol vs string keywords and
  prevents many subtle programming errors that can arise from doing so
  incorrectly.  options.rb doesn't hack ruby's core with one exception: the
  method Array#options.

SYNOPSIS
  require 'options'

  def method(*args, &block)
    args, options = Options.parse(args)

    a = args.shift
    b = args.shift

    force = options.getopt(:force, default = false)
    verbose = options.getopt([:verbose, :VERBOSE])
    foo, bar = options.getopt(:foo, :bar)
  end

INSTALL
  gem install options

HISTORY
  2.1.0:
    - 1.9 compatibility
    - Validation of passed options

SAMPLES

  
  <========< samples/a.rb >========>

  ~ > cat samples/a.rb

    require 'options'
    
    # options.rb makes it super easy to deal with keyword options in a safe and
    # easy way.
    #
    
      def method(*args)
        args, options = Options.parse(args)
    
        force = options.getopt(:force, default=false)
        p force
      end
    
      method(:foo, :bar, :force => true)
      method('force' => true)

  ~ > ruby samples/a.rb

    true
    true


  <========< samples/b.rb >========>

  ~ > cat samples/b.rb

    require 'options'
    
    # options.rb avoids common mistakes made handling keyword arguments
    #
    
      def broken(*args)
        options = args.last.is_a?(Hash) ? args.pop : {}
        if options[:force]
          puts 'forcing'
        else
          puts 'broken'
        end
      end
    
      def nonbroken(*args)
        args, options = Options.parse(args)
        if options.getopt(:force)
          puts 'nonbroken'
        end
      end
    
      broken('force' => true)
      nonbroken('force' => true)
    
    
    
      def fubar(*args)
        options = args.last.is_a?(Hash) ? args.pop : {}
        verbose = options[:verbose] || true
        if verbose 
          if options[:verbose]
            puts 'verbosely'
          else
            puts 'fubar'
          end
        end
      end
    
      def nonfubar(*args)
        args, options = Options.parse(args)
        verbose = options.getopt(:verbose)
        if verbose 
          puts 'verbosely'
        else
          puts 'nonfubar'
        end
      end
    
      fubar(:verbose => false)
      nonfubar(:verbose => false)

  ~ > ruby samples/b.rb

    broken
    nonbroken
    fubar
    nonfubar


  <========< samples/c.rb >========>

  ~ > cat samples/c.rb

    require 'options'
    
    # options.rb hacks ruby core in exactly one way - the method Array#options
    #
    
      def method(*args)
        options = args.options
        p :args => args
        p :options => options
      end
    
      method(:a, :b, :k => :v)
    
      def method2(*args)
        options = args.options.pop
        p :args => args
        p :options => options
      end
    
      method2(:a, :b, :k => :v)

  ~ > ruby samples/c.rb

    {:args=>[:a, :b, {:k=>:v}]}
    {:options=>{:k=>:v}}
    {:args=>[:a, :b]}
    {:options=>{:k=>:v}}


  <========< samples/d.rb >========>

  ~ > cat samples/d.rb

    require 'options'
    
    # options.rb makes it easy to provide good error messages when people
    # misuse a method.
    #
    
      def method(*args)
        args, options = Options.parse(args)
        options.validate(:force)
    
        force = options.getopt(:force, default=false)
        p force
      end
    
      method(:foo, :bar, :misspelled_option => true)
    
    

  ~ > ruby samples/d.rb

    ./lib/options.rb:180:in `validate': Unrecognized options: misspelled_option (ArgumentError)
    	from samples/d.rb:9:in `method'
    	from samples/d.rb:15