=begin
==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)

---keys

    Retunrs the keys.

---select_existent(hash_or_keys)

    Copies hash_or_keys, exclude ones that are not included in the option
    (by comparing keys), and returns it. I.e. select only the ones 
    exsitent. 

    NOTE: ambiguity is not checked, so the resultant value is not 
    necessarily accepted by ((<interpret>)).

    ARGUMENTS
    * hash_or_keys (Hash or Array)

    RETURN VALUE
    * a Hash or Array depending on the class of the argument hash_or_keys

= 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.

=end

module NumRu

  module Misc
    class HelpMessagingException < StandardError
    end

    class KeywordOpt
      def initialize(*args)
	# USAGE:
	#    KeywordOpt.new([key,val,description],[key,val,description],..)
	#    where key is a String, and description can be omitted.
	@val=Hash.new
	@description=Hash.new
	@keys = []
	args.each{ |x|
	  case x
	  when Array
	    unless (x[0]=='help') && @keys.include?(x[0])
	      #^only 'help' can overwrap in the arguments
	      @keys.push(x[0])
	      @val[x[0]] = x[1]
	      @description[x[0]] = ( (x.length>=3) ? x[2] : '' )
	    end
	  when KeywordOpt
	    x.keys.each{|k|
	      unless k=='help' && @keys.include?(k)
	        #^only 'help' can overwrap in the arguments
		@keys.push(k)
		@val[k] = x  #.val[k]
		@description[k] = x.description[k]
	      end
	    }
	    def @val.[](k)
	      val = super(k)
	      val.is_a?(KeywordOpt) ? val[k] : val
	    end
	    def @val.dup
	      out = Hash.new
	      each{|k,val| out[k] = (val.is_a?(KeywordOpt) ? val[k] : val)}
	      out
	    end
	  else
	    raise ArgumentError, "invalid argument: #{x.inspect}"
	  end
	}
	@keys_sort = @keys.sort
	if @keys_sort.length != @keys_sort.uniq.length
	  raise ArgumentError, "keys are not unique"
	end
      end

      def interpret(hash)
	return @val.dup if hash.nil?
	##
	len = @val.length
	im = 0
	out = @val.dup
	hash.keys.sort.each do |key|
	  rkey = /^#{key}/
	  loop do
	    if rkey =~ @keys_sort[im]
	      if im<len-1 && rkey=~@keys_sort[im+1] &&
		 key != @keys_sort[im]   # not identical
		raise ArgumentError, "Ambiguous key specification '#{key}'." 
	      end
	      out[@keys_sort[im]]=hash[key]
	      break
	    end
	    im += 1
	    if im==len
	      raise ArgumentError, "'#{key}' does not match any of the keys."
	    end
	  end
	end
	out
      end

      def select_existent(hash_or_keys)
	hash_or_keys = hash_or_keys.dup         # not to alter the original
	len = @val.length
	im = 0
	kys = ( Array === hash_or_keys ? hash_or_keys : hash_or_keys.keys )
	kys.sort.each do |key|
	  rkey = /^#{key}/
	  loop do
	    break if rkey =~ @keys_sort[im]
	    im += 1
	    if im==len
	      hash_or_keys.delete(key)
	      im = 0           # rewind
              break
	    end
	  end
	end
	hash_or_keys
      end

      def set(hash)
	raise ArgumentError, "not a hash" if !hash.is_a?(Hash)
	##
	replaced = Hash.new
	len = @val.length
	im = 0
	hash.keys.sort.each do |key|
	  rkey = /^#{key}/
	  loop do
	    if rkey =~ @keys_sort[im]
	      if im<len-1 && rkey=~@keys_sort[im+1]
		raise "Ambiguous key specification '#{key}'." 
	      end
	      replaced[@keys_sort[im]] = @val[@keys_sort[im]]
	      @val[@keys_sort[im]]=hash[key]
	      break
	    end
	    im += 1
	    raise "'#{key}' does not match any of the keys." if im==len
	  end
	end
	replaced
      end

#      def __line_feed(str)
#	if str.length >= 68
#	  idx = str[0..67].rindex(/\s/)
#	  if idx
#	    str[idx, 1] = "\n\t" 
#	  end
#	end
#	str
#      end
      def __line_feed(str, len)
	if str.length >= len
	  idx = str[0...len].rindex(/\s/)
	  if idx
	    str = str[0...idx] + "\n\t\t\t# " + __line_feed(str[(idx+1)..-1],50)
	  end
	end
	str
      end
      private :__line_feed

      def help
	 "  option name\tdefault value\t# description:\n" +
	 @keys.collect{|k| 
	   __line_feed("  #{k.inspect}\t#{@val[k].inspect}\t# #{@description[k]}", 66)
	 }.join("\n")
      end

      def [](k)
	v = @val[k]
	if v.is_a?(KeywordOpt)
	  v = v.val[k]
	end
	v
      end

      def keys
	@keys.dup
      end

      ##### protected methods #####
      protected
      attr_reader :val, :description
    end

    ##################################################

    class KeywordOptAutoHelp < KeywordOpt
      def initialize(*args)
	args.push(['help',  false, 'show help message if true'])
	super(*args)
      end

      def interpret(hash)
	begin
	  out = super(hash)
	rescue
	  raise $!.inspect + "\n  Available parameters are:\n" + help
	end
	if out['help']
	  puts 	"<< Description of options >>\n" + help
	  puts ' Current values=' + out.inspect
	  raise Misc::HelpMessagingException, '** help messaging done **'
	end
	out
      end

      def set(hash)
	raise ArgumentError, "not a hash" if !hash.is_a?(Hash)
	if hash['help']
	  puts 	"<< Description of options >>\n" + help
	  raise Misc::HelpMessagingException, '** help messaging done **'
	end
	super
      end
    end

  end
end

if __FILE__ == $0
  include NumRu

  class Foo
    @@opt_hoge = Misc::KeywordOpt.new(
      ['flag',   false, 'whether or not ...'],
      ['number', 1,     'number of ...'],
      ['fff',    1,     'fff...'],
      ['help',  false, 'show help message']
    )
    def self.change_default(hash)
      @@opt_hoge.set(hash)
    end
    def hoge(regular_arg1, regular_arg2, options=nil)
      opt = @@opt_hoge.interpret(options)
      if opt['help']
        puts "* Description of options:\n" + @@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'])
      p opt
    end
  end

  foo = Foo.new
  x = 1
  y = 1
  print "### 0 ###\n"
  foo.hoge( x, y, {'flag'=>true, 'number'=>10} )
  foo.hoge( x, y )
  print "### 1 ###\n"
  foo.hoge( x, y, 'fla'=>true, 'num'=>10 )
  print "### 2 ###\n"
  begin
    foo.hoge( x, y, 'help'=>true )
  rescue
    puts $!
  end
  print "### 3 ###\n"
  Foo.change_default( {'number'=>3} )
  begin
    foo.hoge( x, y, 'fla'=>true, 'num'=>10, 'help'=>true)
  rescue
    puts $!
  end
  print "### 4 ###\n"
  begin
    foo.hoge( x, y, 'dummy'=>nil)
  rescue
    puts $!
  end
  print "### 5 ###\n"
  begin
    foo.hoge( x, y, 'f'=>nil)
  rescue
    puts $!
  end

  print "\n######  test of KeywordOptAutoHelp ######\n"
  opt = Misc::KeywordOptAutoHelp.new(
    ['flag',   false, 'whether or not ...'],
    ['number', 1,     'number of ...']
  )
  print "### 11 ###\n"
  begin
    opt.interpret('flag'=>10,'help'=>true)
  rescue
    puts $!
  end
  print "### 12 ###\n"
  begin
    opt.interpret('nnn'=>10)
  rescue
    puts $!
  end

  print "### 13 ###\n"
  opt2 = Misc::KeywordOptAutoHelp.new(
    ['flafla',   false, 'whether or not ...']
  )
  opt3 = Misc::KeywordOptAutoHelp.new( opt, opt2 )
  p opt3.interpret('flag'=>true)
  begin
    opt3.interpret('help'=>true)
  rescue
    puts $!
  end

  print "### 14 ###\n"
  p opt2.keys, opt.keys
  p opt.select_existent({"flag"=>99, "num"=>88, 'acb'=>333})
  p opt.select_existent(["flag", "num", 'acb'])
end