class NumRu::Misc::KeywordOpt

Overview

A class to facilitate optional keyword arguments. More specifically, it helps the use of a Hash to mimic the keyword argument system.

Usage example

Suppose that you introduce keyword arguments "flag" and "number" to the method "hoge" in a class/module Foo. It can be done as follows:

require 'numru/misc/keywordopt'
include NumRu

class Foo
  @@opt_hoge = KeywordOpt.new(
    ['flag',   false, 'whether or not ...'],
    ['number', 1,     'number of ...'],
    ['help',   false, 'show help message']
  )
  def hoge(regular_arg1, regular_arg2, options=nil)
    opt = @@opt_hoge.interpret(options)
    if opt['help']
      puts @@opt_hoge.help
      puts ' Current values='+opt.inspect
      raise HelpMessagingException, '** show help message and raise **'
    end
    # do what you want below 
    # (options are set in the Hash opt: opt['flag'] and opt['number'])
  end
end

Here, the options are defined in the class variable @@opt_hoge with option names, defualt values, and descriptions (for help messaging). One can use the method hoge as follows:

foo = Foo.new
...
x = ...
y = ...
...
foo.hoge( x, y, {'flag'=>true, 'number'=>10} )

Or equivalently,

foo.hoge( x, y, 'flag'=>true, 'number'=>10 )

because '{}' can be omitted here. If you want to show the help message, use

foo.hoge( x, y, 'help'=>true )

Tails of options names can be shortened as long as unambiguous:

foo.hoge( x, y, 'fla'=>true, 'num'=>10 )

This will cause an exception raised with the following help message such as:

\** Description of options **
  option name => default value (description), ..:
{  "flag" => false (whether or not ...),
  "number" => 1 (number of ...),
  "help" => false (show help message)}
 Current values={"help"=>true, "number"=>1, "flag"=>false}
NumRu::Misc::HelpMessagingException: ** show help message and raise **
        from (irb):78:in `hoge'
        from (irb):83

Class methods

KeywordOpt.new( *args )

Constructor.

ARGUMENTS

• args : arrays of two or three elements: [option name, defualt value, description ], where the third element (description) can be omitted. Option names and descriptions must be String.

RETURN VALUE

• a KeywordOpt object

Methods

interpret(hash)

Interprets a hash that specifies option values.

ARGUMENTS

• hash (Hash) : a hash with string keys matching option names (initialized when constructed). The matching is case sensitive and done such that the tail of a option name can be omitted as long as unambiguous (for example, 'num' for 'number').

RETURN VALUE

• a Hash containing the option values (default values overwritten with hash).

POSSIBLE EXCEPTION

• hash has a key that does not match any of the option names.
• hash has a key that is ambigous

help

Returns a help message

RETURN VALUE

• a String describing the option names, defualt values, and descriptions