================
Cmdopt.rb README
================

Release: 0.2.0


About
-----

Cmdopt.rb is a command-option parser.
It is easier to use than optparse.rb (a standard library of Ruby).


Install
-------

::

$ gem install cmdopt


Usage
-----

Example::

## create parser
require 'cmdopt'
parser = Cmdopt::Parser.new
## define options
parser.option("-h, --help", "show help")
parser.option("-f, --file=FILE", "read file")
## parse args
defaults = "config.json"
begin
opts = parser.parse(ARGV, defaults)
p opts.help #=> true (if '-h' or '--help' specified)
p opts.file #=> "config.json" (if not specified)
p ARGV
rescue Cmdopt::ParseError => ex
$stderr.puts ex.message
exit(1)
end

More example::

## no argument
parser.option("-h", "show help")
parser.option(" --help", "show help")
parser.option("-h, --help", "show help")
## required argument
parser.option("-f FILE", "read file")
parser.option(" --file=FILE", "read file")
parser.option("-f, --file=FILE", "read file")
## optional argument
parser.option("-i[N]", "indent width")
parser.option(" --indent[=N]", "indent width")
parser.option("-i, --indent[=N]", "indent width")

Validation::

parser.option("-m, --mode=MODE", "set mode")\
.validation {|val| "'verbose' or 'quiet' expected." unless val =~ /^(verbose|quiet)$/ }
parser.option("-i, --indent[=N]", "indent width (default 2)")\
.validation {|val| "integer required." unless val == true || val =~ /^\d+$/ }

Action::

## change default handler
parser.option("--verbose", "quiet mode")\
.action {|val, opts| opts.mode = "verbose" } # default: opts.verbose = true
parser.option("--quiet", "quiet mode")\
.action {|val, opts| opts.mode = "quiet" } # default: opts.quiet = true

## The following definitions...
parser.option("-h, --help", "show help")
parser.option("-f, --file=FILE", "read file")
## are equivarent to:
parser.option("-h, --help", "show help")\
.action {|val, opts| opts.help = val }
parser.option("-f, --file=FILE", "read file")\
.action {|val, opts| opts.file = val }

Multiple option::

## define custom handler to store values into list
parser.option("-I path #paths", "include path (multiple OK)")\
.action {|val, opts| (opts.paths ||= []) << val }
##
opts = parser.parse(["-Ipath1", "-Ipath2", "-Ipath3"])
p opts.paths #=> ["path1", "path2", "path3"]

Attribute name::

## usually, long name or sort name is used as attribute name of opts.
parser.option("-h, --help", "show help")
opts = parser.parse(["-h"])
p opts.help #=> true (attr name == long name)
parser.option("-h", "show help")
opts = parser.parse(["-h"])
p opts.h #=> true (attr name == short name)
## it is possible to specify attribute name by '#name'.
## this is very helpful when you want not to use long name.
parser.option("-h #help", "show help")
opts = parser.parse(["-h"])
p opts.help #=> true (not 'opts.h')

Help message::

puts "Usage: command [options] [file...]"
puts parser.help # or parser.help(20, " ")

Private option::

parser.option("-D, --debug", nil) # private option: no description
p parser.help =~ /--debug/ #=> false (not included in help message)


History
-------

Release 0.2.0
~~~~~~~~~~~~~

* Public released


License
-------

$License: MIT License $


Copyright
---------

$Copyright: copyright(c) 2011 kuwata-lab.com all rights reserved $