NAME
.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.parse(args)
a = args.shift
b = args.shift
force = .getopt(:force, default = false)
verbose = .getopt([:verbose, :VERBOSE])
foo, = .getopt(:foo, :bar)
end
INSTALL
gem install
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