dcl_ext.rb

# 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