README.txt

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"]