Index

• class NumRu::Misc::KeywordOpt
• class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt

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. With this, you can set default values and description to each keyword argument.

Classes defined supplementarilly

class NumRu::Misc::HelpMessagingException < StandardError

This is for your convenience. See the usage example below.

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'  # or, specifically, require 'numru/misc/keywordopt'
include NumRu

class Foo
  @@opt_hoge = Misc::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 Misc::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, default 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.

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

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

To show the help message, call

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

This will cause the following help message printed with the exception HelpMessagingException raised.

<< 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: ** help messaging done **
       from (irb):78:in "hoge"
       from (irb):83

Do not affraid to write long descriptions. The help method breaks lines nicely if they are long.

Class methods

KeywordOpt.new( *args )

Constructor.

ARGUMENTS

• args : (case 1) arrays of two or three elements: [option name, default value, description ], or [option name, default value] if you do not want to write descriptions. Option names and descriptions must be String. (case 2) another KeywordOpt. Cases 1 and 2 can be mixed.

  When case 2, a link to the other KeywordOpt is kept. Thus, change of values in it is reflected to the current one. However, the link is deleted if values are changed by set.

RETURN VALUE

• a KeywordOpt object

EXAMPLE

• case 1

opt = Misc::KeywordOpt.new(
  ['flag',   false, 'whether or not ...'],
  ['help',   false, 'show help message']
)

• case 2

  opt = Misc::KeywordOpt.new( optA, optB )

• case 1 & 2

opt = Misc::KeywordOpt.new(
  ['flag',   false, 'whether or not ...'],
  optA
)

Methods

interpret(hash)

Interprets a hash that specifies option values.

ARGUMENTS

• hash (Hash or nil) : a hash with string keys matching option names (initializedwhen 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'). If the argument is nil, the current values are returned. If there are two options like 'max' and 'maxval', to use a key 'max' (identical to the former paramer) is allowed, although it matches 'maxval' as well. (Again 'ma' is regarded ambiguous.)

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 ambiguous

set(hash)

Similar to interpret but changes internal values.

ARGUMENTS

• hash (Hash) : see interpret. (Here, nil is not permitted though)

RETURN VALUE

• a Hash containing the values replaced (the ones before calling this method)

POSSIBLE EXCEPTION

• the argument is not a Hash
• others are same as in interpret

help

Returns a help message

RETURN VALUE

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

[key]

Returns a value associated with the key (exact matching unlike interpret)

class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt

Same as class NumRu::Misc::KeywordOpt, but the method interpret shows a help message and raise an exception if option 'help' is provided as an argument and is not nil or false (NumRu::Misc::HelpMessagingException < StandardError) or if the arguments cannot be interpreted correctly (ArgumentError). Option 'help' is automatically defined, so you do not have to define it yourself.