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