Benry-CmdOpt

Table of Contents

Define, Parse, and Print Help

require 'benry/cmdopt'

## define
cmdopt = Benry::CmdOpt.new
cmdopt.add(:help   , '-h, --help'   , "print help message")
cmdopt.add(:version, '    --version', "print version")

## parse with error handling
options = cmdopt.parse(ARGV) do |err|
  abort "ERROR: #{err.message}"
end
p options     # ex: {:help => true, :version => true}
p ARGV        # options are removed from ARGV

## help
if options[:help]
  puts "Usage: foobar [<options>] [<args>...]"
  puts ""
  puts "Options:"
  puts cmdopt.to_s()
  ## or: puts cmdopt.to_s(20)              # width
  ## or: puts cmdopt.to_s("  %-20s : %s")  # format
  ## or:
  #format = "  %-20s : %s"
  #cmdopt.each_option_and_desc {|opt, help| puts format % [opt, help] }
end

You can set nil to option name only if long option specified.

## both are same
cmdopt.add(:help, "-h, --help", "print help message")
cmdopt.add(nil  , "-h, --help", "print help message")

Command Option Parameter

## required parameter
cmdopt.add(:file, '-f, --file=<FILE>', "filename")   # short & long
cmdopt.add(:file, '    --file=<FILE>', "filename")   # long only
cmdopt.add(:file, '-f <FILE>'        , "filename")   # short only

## optional parameter
cmdopt.add(:indent, '-i, --indent[=<N>]', "indent width")  # short & long
cmdopt.add(:indent, '    --indent[=<N>]', "indent width")  # long only
cmdopt.add(:indent, '-i[<N>]'           , "indent width")  # short only

Notice that "--file <FILE>" style is not supported for usability reason. Use "--file=<FILE>" style instead.

(From a usability perspective, the former style should not be supported. optparse.rb is wrong because it supports both styles and doesn't provide the way to disable the former style.)

Argument Validation

## type (class)
cmdopt.add(:indent , '-i <N>', "indent width", type: Integer)
## pattern (regular expression)
cmdopt.add(:indent , '-i <N>', "indent width", rexp: /\A\d+\z/)
## enum (Array or Set)
cmdopt.add(:indent , '-i <N>', "indent width", enum: ["2", "4", "8"])
## range (endless range such as ``1..`` available)
cmdopt.add(:indent , '-i <N>', "indent width", range: (0..8))
## callback
cmdopt.add(:indent , '-i <N>', "indent width") {|val|
  val =~ /\A\d+\z/  or
    raise "Integer expected."  # raise without exception class.
  val.to_i                     # convert argument value.
}

(For backward compatibilidy, keyword parameter pattern: is available which is same as rexp:.)

type: keyword argument accepts the following classes.

• Integer (/\A[-+]?\d+\z/)
• Float (/\A[-+]?(\d+\.\d*\|\.\d+)z/)
• TrueClass (/\A(true|on|yes|false|off|no)\z/)
• Date (/\A\d\d\d\d-\d\d?-\d\d?\z/)

Notice that Ruby doesn't have Boolean class. Benry-CmdOpt uses TrueClass instead.

In addition:

• Values of enum: or range: should match to type class specified by type:.
• When type: is not specified, then String class will be used instead.

## ok
cmdopt.add(:lang, '-l <lang>', "language", enum: ["en", "fr", "it"])

## error: enum values are not Integer
cmdopt.add(:lang, '-l <lang>', "language", enum: ["en", "fr", "it"], type: Integer)

## ok
cmdopt.add(:indent, '-i <N>', "indent", range: (0..), type: Integer)

## error: beginning value of range is not a String
cmdopt.add(:indent, '-i <N>', "indent", range: (0..))

Boolean (on/off) Option

Benry-CmdOpt doens't support --no-xxx style option for usability reason. Use boolean option instead.

ex3.rb:

require 'benry/cmdopt'
cmdopt = Benry::CmdOpt.new()
cmdopt.add(:foo, "--foo[=on|off]", "foo feature", type: TrueClass)  # !!!!
## or:
#cmdopt.add(:foo, "--foo=<on|off>", "foo feature", type: TrueClass)
options = cmdopt.parse(ARGV)
p options

Output example:

$ ruby ex3.rb --foo           # enable
{:foo=>true}
$ ruby ex3.rb --foo=on        # enable
{:foo=>true}
$ ruby ex3.rb --foo=off       # disable
{:foo=>false}

Alternative Value

Benry-CmdOpt supports alternative value.

require 'benry/cmdopt'
cmdopt = Benry::CmdOpt.new
cmdopt.add(:help1, "-h", "help")
cmdopt.add(:help2, "-H", "help", value: "HELP")   # !!!!!

options = cmdopt.parse(["-h", "-H"])
p options[:help1]   #=> true          # normal
p options[:help2]   #=> "HELP"        # alternative value

This is useful for boolean option.

require 'benry/cmdopt'
cmdopt = Benry::CmdOpt.new
cmdopt.add(:flag1, "--flag1[=<on|off>]", "f1", type: TrueClass)
cmdopt.add(:flag2, "--flag2[=<on|off>]", "f2", type: TrueClass, value: false)  # !!!!

## when `--flag2` specified, got `false` value.
options = cmdopt.parse(["--flag1", "--flag2"])
p options[:flag1]   #=> true
p options[:flag2]   #=> false (!!!!!)

Multiple Value Option

Release 2.4 or later supports multiple: true keyword arg.

require 'benry/cmdopt'
cmdopt = Benry::CmdOpt.new

cmdopt.add(:inc , '-I <path>', "include path", multiple: true)  # !!!!
options = cmdopt.parse(["-I", "/foo", "-I", "/bar", "-I/baz"])
p options   #=> {:inc=>["/foo", "/bar", "/baz"]}

On older version:

require 'benry/cmdopt'
cmdopt = Benry::CmdOpt.new

cmdopt.add(:inc , '-I <path>', "include path") {|options, key, val|
  arr = options[key] || []
  arr << val
  arr
  ## or:
  #(options[key] || []) << val
}

options = cmdopt.parse(["-I", "/foo", "-I", "/bar", "-I/baz"])
p options   #=> {:inc=>["/foo", "/bar", "/baz"]}

Hidden Option

Benry-CmdOpt regards the following options as hidden.

• Keyword argument hidden: true is passed to .add() method.
• Or description is nil.

Hidden options are not included in help message.

require 'benry/cmdopt'
cmdopt = Benry::CmdOpt.new
cmdopt.add(:help   , '-h', "help message")
cmdopt.add(:logging, '-L', "logging", hidden: true)  # hidden
cmdopt.add(:debug  , '-D', nil)                      # hidden (desc is nil)
puts cmdopt.to_s()

### output (neither '-L' nor '-D' is shown because hidden options)
#  -h             : help message

To show all options including hidden ones, add all: true to cmdopt.to_s().

...(snip)...
puts cmdopt.to_s(all: true)   # or: cmdopt.to_s(nil, all: true)

### output
#  -h             : help message
#  -L             : logging
#  -D             : 

Global Options with Sub-Commands

parse() accepts boolean keyword argument all.

• parse(argv, all: true) parses even options placed after arguments. This is the default.
• parse(argv, all: false) only parses options placed before arguments.

require 'benry/cmdopt'
cmdopt = Benry::CmdOpt.new()
cmdopt.add(:help   , '--help'   , "print help message")
cmdopt.add(:version, '--version', "print version")

## `parse(argv, all: true)` (default)
argv = ["--help", "arg1", "--version", "arg2"]
options = cmdopt.parse(argv, all: true)          # !!!
p options       #=> {:help=>true, :version=>true}
p argv          #=> ["arg1", "arg2"]

## `parse(argv, all: false)`
argv = ["--help", "arg1", "--version", "arg2"]
options = cmdopt.parse(argv, all: false)         # !!!
p options       #=> {:help=>true}
p argv          #=> ["arg1", "--version", "arg2"]

This is useful when parsing global options of sub-commands, like Git command.

require 'benry/cmdopt'

argv = ["-h", "commit", "xxx", "-m", "yyy"]

## parse global options
cmdopt = Benry::CmdOpt.new()
cmdopt.add(:help, '-h', "print help message")
global_opts = cmdopt.parse(argv, all: false)   # !!!false!!!
p global_opts       #=> {:help=>true}
p argv              #=> ["commit", "xxx", "-m", "yyy"]

## get sub-command
sub_command = argv.shift()
p sub_command       #=> "commit"
p argv              #=> ["xxx", "-m", "yyy"]

## parse sub-command options
cmdopt = Benry::CmdOpt.new()
case sub_command
when "commit"
  cmdopt.add(:message, '-m <message>', "commit message")
else
  # ...
end
sub_opts = cmdopt.parse(argv, all: true)       # !!!true!!!
p sub_opts          #=> {:message => "yyy"}
p argv              #=> ["xxx"]

Detailed Description of Option

#add() method in Benry::CmdOpt or Benry::CmdOpt::Schema supports detail: keyword argument which takes detailed description of option.

require 'benry/cmdopt'

cmdopt = Benry::CmdOpt.new()
cmdopt.add(:mode, "-m, --mode=<MODE>", "output mode", detail: <<"END")
  v, verbose: print many output
  q, quiet:   print litte output
  c, compact: print summary output
END
puts cmdopt.to_s()
## or:
#cmdopt.each_option_and_desc do |optstr, desc, detail|
#  puts "  %-20s : %s\n" % [optstr, desc]
#  puts detail.gsub(/^/, ' ' * 25) if detail
#end

Output:

  -m, --mode=<MODE>    : output mode
                           v, verbose: print many output
                           q, quiet:   print litte output
                           c, compact: print summary output

Option Tag

#add() method in Benry::CmdOpt or Benry::CmdOpt::Schema supports tag: keyword argument. You can use it for any purpose.

require 'benry/cmdopt'

cmdopt = Benry::CmdOpt.new()
cmdopt.add(:help, "-h, --help", "help message", tag: "important")  # !!!
cmdopt.add(:version, "--version", "print version", tag: nil)
cmdopt.schema.each do |item|
  puts "#{item.key}: tag=#{item.tag.inspect}"
end

## output:
#help: tag="important"
#version: tag=nil

Important Options

You can specify that the option is important or not. Pass important: true or important: false keyword argument to #add() method of Benry::CmdOpt or Benry::CmdOpt::Schema object.

The help message of options is decorated according to value of important: keyword argument.

• Printed in bold font when important: true specified to the option.
• Printed in gray color when important: false specified to the option.

require 'benry/cmdopt'

cmdopt = Benry::CmdOpt.new()
cmdopt.add(:help   , "-h", "help message")
cmdopt.add(:verbose, "-v", "verbose mode", important: true)   # !!!
cmdopt.add(:debug  , "-D", "debug mode"  , important: false)  # !!!
puts cmdopt.option_help()

## output:
#  -h       : help message
#  -v       : verbose mode      # bold font
#  -D       : debug mode        # gray color

Not Supported

• default value when the option not specified in command-line
• --no-xxx style option
• bash/zsh completion (may be supported in the future)
• I18N of error message (may be supported in the future)

Q: How to change or customize error messages?

A: Currently not supported. Maybe supported in the future.

Q: Is it possible to support -vvv style option?

A: Yes.

require 'benry/cmdopt'
cmdopt = Benry::CmdOpt.new

cmdopt.add(:verbose , '-v', "verbose level") {|opts, key, val|
  opts[key] ||= 0
  opts[key] += 1
}

p cmdopt.parse(["-v"])     #=> {:verbose=>1}
p cmdopt.parse(["-vv"])    #=> {:verbose=>2}
p cmdopt.parse(["-vvv"])   #=> {:verbose=>3}