== 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
alist=@x -- 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[:verbose]) 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 host=@s))
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 host=@s))
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"]