Synopsis

GetOptions - Yet another command line argument parser for Ruby.

If you are familiar with Perl's Getopt::Long specification syntax you should feel right at home. The following specifications are currently supported:

default    -- This is the default case, the option is either there or it isn't
flag!      -- You can specify either --flag or --no-flag to set true or false
name|a1|a2 -- You can use '|' to set up option aliases.  In this example, the
              'name' option will be set if either 'name', 'a1', or 'a2' is 
              specified on the command line.

optional:x -- An argument with an optional argument of type x
required=x -- An argument with a required argument of type x 
[email protected]   -- An argument that takes a list of things of type x

The following types are currently supported:

s|string  -- A string value 
i|integer -- An integer value
f|float   -- A floating point value
For integer and float, an exception will be thrown if ruby
can't find a way to convert the supplied argument string.

As with Getopt::Long, you specify the long form of the option, but it can parse short options as well. For example, if you have an option named 'help', both –help and -h would enable the option. You can also specify a small portion of the long form, and if it is enough to uniquely identify the option, it will work. For example, –he or –hel would map to –help as long as you don't have –hell, –hello, … as an option.

There are several ways to get the option data after parsing. Of course there is the hash style, which could look something like:

options = GetOptions.new(%w(help verbose!))
puts "I'm going to go do stuff now..." if options['verbose']

You can also use a symbol (options) instead of a string if you want. In addition, you can access fields using the .-style accessor syntax:

show_help() if options.help

Examples

Kicking the tires:

$ cat myscript1.rb
require 'getoptions'

opt = GetOptions.new(%w(help debug! verbose+ prefix:s size=i [email protected])) 
p opt

$ ./myscript1.rb --help 
help: true  

$ ./myscript1.rb --debug   
debug: true

$ ./myscript1.rb --no-debug
debug: false

$ ./myscript1.rb -vvvvv    
verbose: 5

$ ./myscript1.rb -vv --verbose
verbose: 3

$ ./myscript1.rb --pre        
prefix: nil

$ ./myscript1.rb --pre myprefix
prefix: "myprefix"

$ ./myscript1.rb --size 5      
size: 5

Mixing arguments with non-arguments:

$ cat myscript2.rb
require 'getoptions'

opt = GetOptions.new(%w(help debug! verbose+ prefix:s size=i [email protected])) 
p opt
puts '--'
p ARGV

$ ./myscript2.rb --siz 10 file1 file2 file3
size: 10
--
["file1", "file2", "file3"]

$ ./myscript2.rb --host host1 host2 -- file1 file2 file3
host: ["host1", "host2"]
--
["file1", "file2", "file3"]

Processing your own input stream:

$ cat myscript3.rb
require 'getoptions'

input = %w(-vv -w 1 -2 -- file1)
opt = GetOptions.new(%w(verbose+ weights:@i), input)
p opt
puts '--'
p input

$ ./myscript3.rb
verbose: 2
weights: [1, -2]
--
["file1"]