alib 0.3.1

data/lib/alib-0.3.1.rb

@@ -0,0 +1,3872 @@
+#
+# the ALib module is a namespace for things i've found useful
+#
+  module ALib
+#--{{{
+    VERSION = '0.3.1'
+
+    require 'pathname'
+    require 'socket'
+    require 'tmpdir'
+    require 'rbconfig'
+    require 'logger'
+    require 'yaml'
+    require 'drb/drb'
+    require 'fileutils'
+    require 'tempfile'
+    require 'optparse'
+    require 'sync'
+    require 'time'
+
+    def ALib::export e
+#--{{{
+      (@__exported ||= []) << e
+      @__exported.uniq!
+      @__exported
+#--}}}
+    end
+
+  #
+  # the utility module is a namespace for things which otherwise wouldn't have a
+  # home.  the methods of Util can be used as module methods or included into a
+  # class and then used as instance OR class methods
+  #
+    module  Util
+#--{{{
+      class << self
+        def export(*syms)
+#--{{{
+          syms.each do |sym|
+            sym = "#{ sym }".intern
+            module_function sym 
+            public sym
+          end
+#--}}}
+        end
+        def append_features c
+#--{{{
+          super
+          c.extend self 
+#--}}}  
+        end
+      end
+    #
+    # requires a certain version of ruby or higher
+    #   require_version '1.8.0'
+    #
+      def require_version version
+#--{{{
+        major, minor, teeny = "#{ version }".split(%r/\./o).map{|n| Integer(n)}
+        required = "#{ major }.#{ minor }.#{ teeny }"
+        _major, _minor, _teeny = 
+          %w( MAJOR MINOR TEENY ).map{|k| Integer(::Config::CONFIG[k])}
+        actual = "#{ _major }.#{ _minor }.#{ _teeny }"
+        unless _major > major  or _major == major and _minor >= minor 
+          STDERR.puts("=" * 79)
+          STDERR.puts "this program requires a ruby version >= <#{ required }>"
+          STDERR.puts 
+          STDERR.puts "you are currenlty running ruby version <#{ actual }>"
+          STDERR.puts 
+          STDERR.puts "possible problems which could cause this are:"
+          STDERR.puts "  - improper PATH environment variable setting"
+          STDERR.puts "  - ruby > <#{ required }> has not been installed"
+          STDERR.puts("=" * 79)
+          exit 1
+        end
+#--}}}
+      end
+    #
+    # the basename of $0  
+    #
+      def prognam
+#--{{{
+        File::basename $0
+#--}}}
+      end
+      export 'prognam'
+    #
+    # marshal'd 'deep' copy of obj
+    #
+      def mcp obj
+#--{{{
+        Marshal.load(Marshal.dump(obj))
+#--}}}
+      end
+      export 'mcp'
+    #
+    # self.class 
+    #
+      def klass
+#--{{{
+        self.class
+#--}}}
+      end
+      export 'klass'
+    #
+    # File::expand_path + link resolution 
+    #
+      def realpath path
+#--{{{
+        path = File::expand_path "#{ path }"
+        begin
+          Pathname.new(path).realpath.to_s
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          path
+        end
+#--}}}
+      end
+      export 'realpath'
+    #
+    # collect n hashed into one hash - later keys overried earlier keys 
+    #
+      def hashify(*hashes)
+#--{{{
+        hashes.inject(accum={}){|accum,hash| accum.update hash}
+#--}}}
+      end
+      export 'hashify'
+    #
+    # look up key in hash as key, then string of key, then intern of key -
+    # returning the value or, if key is not found, nil or default  
+    #
+      def getopt opt, hash, default = nil
+#--{{{
+        keys = opt.respond_to?('each') ? opt : [opt]
+
+        keys.each do |key|
+          return hash[key] if hash.has_key? key
+          key = "#{ key }"
+          return hash[key] if hash.has_key? key
+          key = key.intern
+          return hash[key] if hash.has_key? key
+        end
+
+        return default
+#--}}}
+      end
+      alias get_opt getopt
+      export 'getopt'
+      export 'get_opt'
+    #
+    # determine if a key, key.to_s, or key.to_s.intern is in hash 
+    # see getopt
+    #
+      def hasopt opt, hash, default = false 
+#--{{{
+        keys = opt.respond_to?('each') ? opt : [opt]
+
+        keys.each do |key|
+          return key if hash.has_key? key
+          key = "#{ key }"
+          return key if hash.has_key? key
+          key = key.intern
+          return key if hash.has_key? key
+        end
+
+        return default
+#--}}}
+      end
+      alias has_opt hasopt
+      alias hasopt? hasopt
+      alias has_opt? hasopt
+      export 'hasopt'
+      export 'hasopt?'
+      export 'has_opt'
+      export 'has_opt?'
+    #
+    # delete key in hash as key, then string of key, then intern of key -
+    # returning the value or, if key is not found, nil or default  
+    #
+      def delopt opt, hash, default = nil
+#--{{{
+        keys = opt.respond_to?('each') ? opt : [opt]
+
+        keys.each do |key|
+          return hash.delete(key) if hash.has_key? key
+          key = "#{ key }"
+          return hash.delete(key) if hash.has_key? key
+          key = key.intern
+          return hash.delete(key) if hash.has_key? key
+        end
+
+        return default
+#--}}}
+      end
+      alias delete_opt delopt
+      alias extract_opt delopt
+      alias extractopt delopt
+      alias xopt delopt
+      export 'delete_opt'
+      export 'extract_opt'
+      export 'extractopt'
+      export 'xopt'
+      export 'delopt'
+    #
+    # returns true if pid is running, false otherwise
+    #
+      def alive pid
+#--{{{
+        pid = Integer("#{ pid }")
+        begin
+          Process::kill 0, pid
+          true
+        rescue Errno::ESRCH
+          false
+        end
+#--}}}
+      end
+      alias alive? alive
+      export 'alive', 'alive?'
+    #
+    # brutally shut down a process.  opts can contain the keys 'signals' which
+    # should be a list of signals used to send to the process and the key
+    # 'suspend' which is the amount of time to wait after firing each signal
+    # before seeing if the process is dead.  the defaults are %w(TERM QUIT KILL)
+    # and 4 respectively
+    #
+      def maim(pid, opts = {})
+#--{{{
+        sigs = Util::getopt 'signals', opts, %w(SIGTERM SIGQUIT SIGKILL)
+        suspend = Util::getopt 'suspend', opts, 4
+        pid = Integer("#{ pid }")
+        existed = false
+        sigs.each do |sig|
+          begin
+            Process::kill(sig, pid)
+            existed = true 
+          rescue Errno::ESRCH
+            unless existed
+              return nil 
+            else
+              return true 
+            end
+          end
+          return true unless alive?(pid)
+          sleep suspend
+          return true unless alive?(pid)
+        end
+        return(not alive?(pid)) 
+#--}}}
+      end
+      export 'maim'
+    #
+    # YYYY-MM-DD hh:mm:ss.uuuuuu representation of time.  if the option
+    # 'nospace' is true spaces are replaced with underscores/or the value of the
+    # nospace option - useful for constructing filenames
+    #
+      def timestamp arg = Time::now
+#--{{{
+        if Time === arg 
+          arg.iso8601 2
+        else
+          opts =
+            case arg
+              when Hash
+                opts = arg
+              when Time
+                {'time' => arg}
+              else
+                raise ArgumentError, "#{ arg.inspect } (#{ arg.class })"
+            end
+          time = Util::getopt 'time', opts, Time::now
+          local = Util::getopt 'local', opts, false 
+          nospace = Util::getopt('nospace', opts, Util::getopt('no_space', opts, false))
+          dateonly = Util::getopt('dateonly', opts, Util::getopt('date_only', opts, false))
+          time = time.utc unless local
+          usec = "#{ time.usec }"
+          usec << ('0' * (6 - usec.size)) if usec.size < 6 
+          stamp =
+          unless dateonly
+            time.strftime('%Y-%m-%d %H:%M:%S.') << usec
+          else
+            time.strftime('%Y-%m-%d')
+          end
+          if nospace
+            spc = TrueClass === nospace ? 'T' : "#{ nospace }"
+            stamp.gsub! %r/\s+/, spc
+          end
+          stamp
+        end
+#--}}}
+      end
+      export 'timestamp'
+    #
+    # inverse of timestamp.  the option 'local' determines whether the timestamp
+    # is interpreted as a local or utc time.
+    #
+# TODO - review hack to fix Time::parse bug with ms and tz
+# TODO - review hack to fix Time::parse bug with ms and tz
+# TODO - review hack to fix Time::parse bug with ms and tz
+      def stamptime string, opts = {} 
+#--{{{
+        tz = string[ %r/-\d\d:\d\d\s*$/ ]
+        time = nil
+        if opts.empty? or tz
+          u = string[%r/\.\d+/]
+          string[%r/\.\d+/] = '' if u 
+          time = Time::parse string
+          time += u.to_f if u
+        else
+          local = Util::getopt 'local', opts, false 
+          string = "#{ string }"
+          pat = %r/^\s*(\d\d\d\d)-(\d\d)-(\d\d)[\s_tT]+(\d\d):(\d\d):(\d\d)(?:.(\d+))?\s*$/o
+          match = pat.match string
+          raise ArgumentError, "<#{ string.inspect }>" unless match
+          yyyy,mm,dd,h,m,s,u = match.to_a[1..-1].map{|m| (m || 0).to_i}
+          if local
+            time = Time::local yyyy,mm,dd,h,m,s,u
+          else
+            time = Time::gm yyyy,mm,dd,h,m,s,u
+          end
+        end
+        return time
+#--}}}
+      end
+      export 'stamptime'
+    #
+    # escapes any occurances of char in s with esc modifying s inplace
+    #
+      def escape! s, char, esc
+#--{{{
+        # re = %r/([#{ 0x5c.chr << esc }]*)#{ char }/
+        re = %r/([#{ Regexp::quote esc }]*)#{ Regexp::quote char }/
+        s.gsub!(re) do
+          (($1.size % 2 == 0) ? ($1 << esc) : $1) + char 
+        end
+#--}}}
+      end
+      export 'escape!'
+    #
+    # new copy of s with any occurances of char escaped with esc
+    #
+      def escape s, char, esc
+#--{{{
+        escape! "#{ s }", char, esc
+#--}}}
+      end
+      export 'escape'
+    #
+    # a quiet fork
+    #
+      def fork(*args, &block)
+#--{{{
+        begin
+          verbose = $VERBOSE
+          $VERBOSE = nil
+          Process::fork(*args, &block)
+        ensure
+          $VERBOSE = verbose
+        end
+#--}}}
+      end
+      export 'fork'
+    #
+    # an quiet exec
+    #
+      def exec(*args, &block)
+#--{{{
+        begin
+          verbose = $VERBOSE
+          $VERBOSE = nil
+          Kernel::exec(*args, &block)
+        ensure
+          $VERBOSE = verbose
+        end
+#--}}}
+      end
+      export 'exec'
+    #
+    # a quiet system
+    #
+      def system(*args, &block)
+#--{{{
+        begin
+          verbose = $VERBOSE
+          $VERBOSE = nil
+          Kernel::system(*args, &block)
+        ensure
+          $VERBOSE = verbose
+        end
+#--}}}
+      end
+      export 'system'
+    #
+    # a quiet system which succeeds or throws errors
+    #
+      def spawn cmd, opts = {} 
+#--{{{
+        exitstatus = Util::getopt(%w( exitstatus exit_status status ), opts, 0)
+        Util::system cmd
+        status = $?.exitstatus
+        raise "cmd <#{ cmd }> failed with <#{ status }>" unless 
+          status == exitstatus
+        status
+#--}}}
+      end
+      export 'spawn'
+    #
+    # lookup, and cache, the hostname
+    #
+      def hostname
+#--{{{
+        @__hostname__ ||= Socket::gethostname
+#--}}}
+      end
+      export 'hostname'
+    #
+    # lookup, and cache, the host (first bit of hostname quad)
+    #
+      def host
+#--{{{
+        @__host__ ||= hostname.gsub(%r/\..*$/o,'')
+#--}}}
+      end
+      export 'host'
+    #
+    # format exception as Logger class does - no backtrace
+    #
+      def emsg e
+#--{{{
+        "#{ e.message } - (#{ e.class })"
+#--}}}
+      end
+      export 'emsg'
+    #
+    # format exception backtrace as string 
+    #
+      def btrace e
+#--{{{
+        (e.backtrace or []).join("\n")
+#--}}}
+      end
+      export 'btrace'
+    #
+    # format exception as Logger class does - with backtrace
+    #
+      def errmsg e
+#--{{{
+        emsg(e) << "\n" << btrace(e)
+#--}}}
+      end
+      export 'errmsg'
+    #
+    # determine equality of two exceptions
+    #
+      def erreq a, b
+#--{{{
+        a.class == b.class and
+        a.message == b.message and
+        a.backtrace == b.backtrace
+#--}}}
+      end
+      export 'erreq'
+    #
+    # generate a temporary filename for the directory dir using seed as a
+    # basename 
+    #
+      def tmpnam opts = {} 
+#--{{{
+        dir = Util::getopt 'dir', opts, Dir::tmpdir
+        seed = Util::getopt 'seed', opts, Util::prognam
+        path = 
+          "%s_%s_%s_%s_%d" % [
+            Util::hostname, 
+            seed,
+            Process::pid, 
+            Util::timestamp('nospace' => true),
+            rand(101010)
+          ] 
+        dirname, basename = File::dirname(path), File::basename(path)
+        tn = File::join(dir, dirname, basename.gsub(%r/[^0-9a-zA-Z]/,'_')).gsub(%r/\s+/, '_')
+        File::expand_path tn
+#--}}}
+      end
+      export 'tmpnam'
+      def tmpdir(*argv)
+#--{{{
+        args, opts = Util::optfilter argv
+        retries = Util::getopt 'retries', opts, 42
+        opts['dir'] ||= (args.first || Util::getopt('base', opts) || '.')
+        d = nil
+        retries.times do
+          td = Util::tmpnam(opts)
+          break if ((d = FileUtils::mkdir_p td rescue nil))
+        end
+        raise "surpassed max retries <#{ retries }>" unless d
+        d = File::expand_path d
+        if block_given?
+          cwd = Dir::pwd
+          begin
+            Dir::chdir d
+            yield [cwd,d]
+          ensure
+            Dir::chdir cwd if cwd
+            Dir[File::join(d, "**")].each{|e| FileUtils::rm_rf e}
+            FileUtils::rm_rf d
+          end
+        else
+          at_exit{ FileUtils::rm_rf d }
+          return d
+        end
+#--}}}
+      end
+      export 'tmpdir'
+    #
+    # make best effort to invalidate any inode caching done by nfs clients
+    #
+      def uncache file 
+#--{{{
+        refresh = nil
+        begin
+          is_a_file = File === file
+          path = (is_a_file ? file.path : file.to_s) 
+          stat = (is_a_file ? file.stat : File::stat(file.to_s)) 
+          refresh = tmpnam(File::dirname(path))
+          File::link path, refresh rescue File::symlink path, refresh
+          File::chmod stat.mode, path
+          File::utime stat.atime, stat.mtime, path
+          open(File::dirname(path)){|d| d.fsync rescue nil}
+        ensure 
+          begin
+            File::unlink refresh if refresh
+          rescue Errno::ENOENT
+          end
+        end
+#--}}}
+      end
+      export 'uncache'
+    #
+    # wrap a string using options width (default 80) and indent using the indent
+    # option (default 0)
+    #
+      def columnize buf, opts = {}
+#--{{{
+        width = Util::getopt 'width', opts, 80
+        indent = Util::getopt 'indent', opts
+        indent = Fixnum === indent ? (' ' * indent) : "#{ indent }"
+        column = []
+        words = buf.split %r/\s+/o
+        row = "#{ indent }"
+        while((word = words.shift))
+          if((row.size + word.size) < (width - 1))
+            row << word
+          else
+            column << row
+            row = "#{ indent }"
+            row << word
+          end
+          row << ' ' unless row.size == (width - 1)
+        end
+        column << row unless row.strip.empty?
+        column.join "\n"
+#--}}}
+      end
+      export 'columnize'
+    #
+    # search for a default value for 'var' using
+    #   * DEFAULT_VAR 
+    #   * self.class.var 
+    # returning the option default, or nil
+    #
+      def defval var, opts = {} 
+#--{{{  
+        default = Util::getopt 'default', opts, nil
+        v = "#{ var }"
+        c0, c1 = "DEFAULT_#{ v }".upcase, "#{ v }".upcase
+        begin 
+          klass.send(v) || klass.const_get(c0) || klass.const_get(c1)
+        rescue NameError
+          default
+        end
+#--}}}
+      end
+      export 'defval'
+    #
+    # initiates a catch block to do 'something'.  if the method try_again! is
+    # called the block is done over - if the method give_up! is called the block
+    # is aborted.  calls to attempt may be nested.
+    #
+      def attempt label = 'attempt'
+#--{{{
+        ret = nil
+        n_attempts = 0
+        loop{ break unless catch("#{ label }"){ ret = yield(n_attempts += 1) } == 'try_again' }
+        ret
+#--}}}
+      end 
+      export 'attempt'
+    #
+    # see attempt
+    #
+      def try_again! label = 'attempt'
+#--{{{
+        throw "#{ label }", 'try_again'
+#--}}}
+      end
+      alias try_again try_again!
+      alias again! try_again!
+      export 'try_again!', 'again!', 'try_again'
+    #
+    # see attempt
+    #
+      def give_up! label = 'attempt'
+#--{{{
+        throw "#{ label }", 'give_up'
+#--}}}
+      end
+      alias giveup! give_up! 
+      alias give_up give_up! 
+      export 'give_up!', 'giveup!', 'give_up'
+    #
+    # creates a class by class name
+    #
+      def klass_stamp(hierachy, *a, &b)
+#--{{{
+        ancestors = hierachy.split(%r/::/)
+        parent = Object
+        while((child = ancestors.shift))
+          klass = parent.const_get child
+          parent = klass
+        end
+        klass::new(*a, &b)
+#--}}}
+      end
+      export 'klass_stamp'
+    #
+    # shortcut to Find2
+    #
+      def find(*a, &b)
+#--{{{
+        a << '.' if a.empty?
+        Find2::find(*a, &b)
+#--}}}
+      end
+      export 'find'
+    #
+    # shortcut to Find2
+    #
+      def find2(*a, &b)
+#--{{{
+        a << '.' if a.empty?
+        Find2::find2(*a, &b)
+#--}}}
+      end
+      export 'find2'
+    #
+    # shortcut to Find2.prune
+    #
+      def prune
+    #--{{{
+        Find2.prune
+    #--}}}
+      end
+      export 'prune'
+    #
+    # pull out options from arglist
+    #
+      def optfilter(*list)
+#--{{{
+        args, opts = [ list ].flatten.partition{|item| not Hash === item}
+        [args, Util::hashify(*opts)]
+#--}}}
+      end
+      export 'optfilter'
+    #
+    # pop of options from an arglist
+    #
+      def argv_split(argv)
+#--{{{
+        args = argv
+        opts = args.pop if Hash === args.last
+        puts "args : #{ args.inspect }"
+        puts "opts : #{ opts.inspect }"
+        [args, opts]
+#--}}}
+      end
+      export 'argv_split'
+    #
+    # split a path into dirname, basename, extension
+    #
+      def splitpath path
+#--{{{
+        path = "#{ path }"
+        dirname, basename = File::split path
+        [ dirname, (%r/^([^\.]*)(.*)$/).match(basename)[1,2] ].flatten
+#--}}}
+      end
+      export 'splitpath'
+    #
+    # handle a pathname after unzipping (iff needed)
+    #
+      def unzipped path, z_pat = %r/\.(?:z|gz)$/io
+#--{{{
+        zipped = zipped?(path, z_pat)
+        unless zipped
+          yield path
+        else
+          unzipped = unzip path
+          begin
+            yield unzipped
+          ensure
+            zip unzipped
+          end
+        end
+#--}}}
+      end
+      export 'unzipped'
+    #
+    # zip a file - return zipped name
+    #
+      def zip path, z_ext = nil 
+#--{{{
+        z_ext ||= '.gz'
+        z_ext.gsub! %r/^\s*\.+/, '.'
+        Util::spawn "gzip --suffix #{ z_ext } --force #{ path }"
+        zipped = "#{ path }#{ z_ext }"
+        raise "could not create <#{ zipped }>" unless test ?e, zipped
+        if block_given?
+          yield zipped
+        else
+          zipped
+        end
+#--}}}
+      end
+      alias gzip zip
+      export 'gzip'
+      export 'zip'
+    #
+    # return the zipped name of a path
+    #
+      def zipped_name path, z_ext = nil 
+#--{{{
+        z_ext ||= '.gz'
+        z_ext.gsub! %r/^\s*\.+/, '.'
+        "#{ path }#{ z_ext }"
+#--}}}
+      end
+      export 'zipped_name'
+    #
+    # unzip a file - return unzipped name
+    #
+      def unzip path, z_pat = nil 
+#--{{{
+        z_pat ||= %r/\.(?:z|gz)$/io
+        Util::spawn "gzip --force --decompress #{ path }" if zipped?(path, z_pat)
+        #Util::spawn "gzip --force --decompress #{ path }"
+        uzn = Util::unzipped_name path, z_pat 
+        if block_given?
+          yield uzn
+        else
+          uzn
+        end
+#--}}}
+      end
+      alias gunzip unzip
+      export 'gunzip'
+      export 'unzip'
+    #
+    # return the unzipped name of a path
+    #
+      def unzipped_name path, z_pat = nil 
+#--{{{
+        z_pat ||= %r/\.(?:z|gz)$/io
+        path.gsub z_pat, ''
+#--}}}
+      end
+      export 'unzipped_name'
+    #
+    # guess if a file is zipped based on pathname
+    #
+      def zipped? path, z_pat = %r/\.(?:z|gz)$/io
+#--{{{
+        path =~ z_pat
+#--}}}
+      end
+      alias gzipped? zipped?
+      export 'gzipped?'
+      export 'zipped?'
+    #
+    # convert a string to an integer of any base
+    #
+      def strtod(s, opts = {})
+#--{{{
+        base = Util::getopt 'base', opts, 10
+        case base
+          when 2
+            s = "0b#{ s }" unless s =~ %r/^0b\d/
+          when 8
+            s = "0#{ s }" unless s =~ %r/^0\d/
+          when 16 
+            s = "0x#{ s }" unless s =~ %r/^0x\d/
+        end
+        Integer s
+#--}}}
+      end
+      export 'strtod'
+    #
+    # convert a string to an integer
+    #
+      def atoi(s, opts = {})
+#--{{{
+        strtod("#{ s }".gsub(%r/^0+/,''), 'base' => 10)
+#--}}}
+      end
+      export 'atoi'
+    #
+    # bin a integer into a int range using modulo logic
+    #
+      def rangemod n, ir
+#--{{{
+        a, b = Integer(ir.first), Integer(ir.last)
+        a, b = b, a if a >= b
+        exclusive = ir.exclude_end?
+        size = b - a 
+        size += 1 unless exclusive
+        offset = a - 0
+        x = (n + offset).modulo size
+        x += offset
+#--}}}
+      end
+    #
+    # bin a integer into a int range using modulo logic
+    #
+      def rangemod n, ir
+#--{{{
+        a, b = [ir.first.to_i, ir.last.to_i].sort
+        b += 1 if ir.exclude_end?
+        size = b - a 
+        if n < a
+          v = n - a
+          d = v.abs
+          r = d % size
+          n = b - r
+        elsif n > b
+          v = n - b
+          d = v.abs
+          r = d % size
+          n = a + r
+        end
+        raise "failed to rangemod #{ n } => #{ ir }" unless
+          ir.include? n
+        n
+#--}}}
+      end
+      export 'rangemod'
+    #
+    # explode a 
+    #
+      def hms seconds
+#--{{{
+        [
+          Integer(seconds / 3600),
+          Integer((seconds % 3600) / 60),
+          Float((seconds % 3600) / 60.0)
+        ]
+#--}}}
+      end
+      export 'hms'
+    #
+    # expand variables in a string destructively (to the string)
+    #
+      def expand! string, vars = {} 
+#--{{{
+        loop do
+          changed = false
+          vars.each do |var, value|
+            var.gsub! %r/[^a-zA-Z0-9_]/, ''
+            [ 
+              %r/\$#{ var }\b/, 
+              %r/\@#{ var }\b/, 
+              %r/\${\s*#{ var }\s*}/, 
+              %r/\@{\s*#{ var }\s*}/ 
+            ].each do |pat|
+              changed = string.gsub! pat, "#{ value }"
+            end
+          end
+          break unless changed
+        end
+        string
+#--}}}
+      end
+      export 'expand!'
+      def expand string, opts = {}
+#--{{{
+        Util::expand! string.dup, opts
+#--}}}
+      end
+      export 'expand'
+    #
+    # determine path of current ruby interpreter (argv[0] in c)
+    #
+      def which_ruby
+#--{{{
+        c = ::Config::CONFIG
+        File::join(c['bindir'], c['ruby_install_name']) << c['EXEEXT']
+#--}}}
+      end
+      export 'which_ruby'
+    #
+    # declare multi-dimensional arrays as in md[2,3,4]
+    #
+      def md
+#--{{{
+        @__md__ ||=
+          lambda{|*ds| Array::new(ds.shift||0).map{md[*ds] unless ds.empty?}}
+#--}}}
+      end
+      export 'md'
+    #
+    # find natural left margin of a here-doc and un-indent it
+    #
+      def unindent! s
+#--{{{
+        indent = nil
+        s.each do |line|
+          next if line =~ %r/^\s*$/
+          indent = line[%r/^\s*/] and break
+        end
+        s.gsub! %r/^#{ indent }/, "" if indent
+        indent ? s : nil
+#--}}}
+      end
+      export 'unindent!'
+      def unindent s
+#--{{{
+        s = "#{ s }"
+        Util::unindent! s
+        s
+#--}}}
+      end
+      export 'unindent'
+
+
+
+#--}}}
+    end # class Util
+    ALib::export Util
+
+  #
+  # the logging module extends classes (both at instance and class level) with
+  # many methods useful for logging.  it relies on the builtin Logger class
+  #
+    module Logging
+#--{{{
+    #
+    # a module that adds an accessor to Logging objects in ored to fix a bug where
+    # not all logging devices are put into sync mode, resulting in improper log
+    # rolling.  this is a hack.
+    #
+      module LoggerExt
+#--{{{
+        attr :logdev
+#--}}}
+      end # module LoggerExt
+    #
+    # implementations of the methods shared by both classes and objects of classes
+    # which include Logging
+    #
+      module LogMethods
+#--{{{
+        def __logger_mutex
+#--{{{
+          unless defined?(@__logger_mutex) and @__logger_mutex
+            begin
+              Thread.critical = true
+              @__logger_mutex = Sync::new unless defined?(@__logger_mutex) and @__logger_mutex
+            ensure
+              Thread.critical = false 
+            end
+          end
+          @__logger_mutex
+#--}}}
+        end
+        def __logger_sync
+#--{{{
+          __logger_mutex.synchronize{ yield }
+#--}}}
+        end
+        def logger
+#--{{{
+          return @logger if defined?(@logger)
+          __logger_sync do          
+            unless defined?(@logger)
+              klass = Class === self ? self : self::class
+              self.logger = klass::default_logger 
+            end
+          end
+          @logger
+#--}}}
+        end
+        def logger= log
+#--{{{
+          __logger_sync do          
+            @logger = log
+            @logger.extend LoggerExt
+            @logger.logdev.dev.sync = true rescue nil 
+            @logger
+          end
+#--}}}
+        end
+        %w( debug info warn error fatal ).each do |meth|
+          module_eval <<-code
+            def #{ meth }(*a, &b)
+              __logger_sync{ logger.#{ meth }(*a, &b) }
+            end
+          code
+        end
+        def log_err e
+#--{{{
+          if logger.debug?
+            error{ errmsg e } 
+          else
+            error{ emsg e } 
+          end
+#--}}}
+        end
+        def emsg e
+#--{{{
+          "#{ e.message } - (#{ e.class })"
+#--}}}
+        end
+        def btrace e
+#--{{{
+          e.backtrace.join("\n")
+#--}}}
+        end
+        def errmsg e
+#--{{{
+          emsg(e) << "\n" << btrace(e)
+#--}}}
+        end
+#--}}}
+      end # module LogMethods
+
+      module LogClassMethods
+#--{{{
+        def default_logger
+#--{{{
+          return @default_logger if defined?(@default_logger)
+          __logger_sync do
+            unless defined?(@default_logger)
+              self.default_logger = Logger.new STDERR
+              # @default_logger.warn{ "<#{ self }> using default logger"}
+            end
+          end
+          @default_logger
+#--}}}
+        end
+        def default_logger= log
+#--{{{
+          __logger_sync do
+            @default_logger = (Logger === log ? log : Logger::new(log))
+            @default_logger.extend LoggerExt
+            @default_logger.logdev.dev.sync = true rescue nil
+            @default_logger
+          end
+#--}}}      
+        end
+#--}}}      
+      end   
+
+      EOL    = "\n"
+      DIV0   = ("." * 79) << EOL 
+      DIV1   = ("-" * 79) << EOL 
+      DIV2   = ("=" * 79) << EOL 
+      DIV3   = ("#" * 79) << EOL 
+      SEC0   = ("." * 16) << EOL 
+      SEC1   = ("-" * 16) << EOL 
+      SEC2   = ("=" * 16) << EOL 
+      SEC3   = ("#" * 16) << EOL 
+
+      class << self
+#--{{{
+        def append_features c
+#--{{{
+          ret = super
+          c.extend LogMethods
+          c.extend LogClassMethods
+          ret
+#--}}}
+        end
+#--}}}
+      end
+      include LogMethods
+#--}}}
+    end # module Logging
+    ALib::export Logging
+
+  #
+  # yaml configfile class
+  #
+    class ConfigFile < ::Hash
+#--{{{
+      DEFAULT_CONIFG = {}
+      DEFAULT_SEARCH_PATH = %w(. ~ /usr/local/etc /usr/etc /etc)
+      DEFAULT_BASENAME = ".#{ File::basename $0 }.conf"
+
+      class << self
+#--{{{
+        attr :config, true
+        attr :search_path, true
+        attr :basename, true
+        attr :default_text, true
+        def init
+#--{{{
+          @config = DEFAULT_CONIFG
+          @search_path = DEFAULT_SEARCH_PATH
+          @basename = DEFAULT_BASENAME
+#--}}}
+        end
+        def gen_template port = nil 
+#--{{{
+          port ||= STDOUT
+          buf = @default_text || @config.to_yaml
+          if port.respond_to? 'write' 
+            port.write buf
+            port.write "\n"
+          else
+            open("#{ port }", 'w'){|f| f.puts buf}
+          end
+#--}}}
+        end
+        def default= conf
+#--{{{
+          if conf.respond_to?('read')
+            @default_text = munge conf.read
+            @config = YAML::load @default_text
+          else
+            case conf
+              when Hash
+                @config = conf
+              when Pathname 
+                open(conf) do |f| 
+                  @default_text = munge f.read
+                  @config = YAML::load @default_text
+                end
+              when String
+                @default_text = munge conf 
+                @config = YAML::load @default_text
+            end
+          end
+          @config
+#--}}}
+        end
+        alias set_default default=
+        def default(*a)
+#--{{{
+          if a.empty?
+            @config ||= {}
+          else
+            self.default= a.first
+          end
+#--}}}
+        end
+        def any(basename = @basename, *dirnames)
+#--{{{
+          config = nil
+          dirnames = @search_path if dirnames.empty?
+          dirnames.each do |dirname|
+            path = File::join dirname, basename 
+            path = File::expand_path path
+            if test ?e, path
+              config = self::new path
+              break
+            end
+          end
+          config || self::new('default') 
+#--}}}
+        end
+        def munge buf
+#--{{{
+          buf.gsub(%r/\t/o,' ')
+#--}}}
+        end
+#--}}}
+      end
+      self.init
+
+      attr :path
+      def initialize path = 'default'
+#--{{{
+        @path = nil 
+        yaml = nil
+        if path.nil? or path and path =~ /^\s*default/io
+          yaml = self.class.default 
+          @path = 'DEFAULT' 
+        else path
+          yaml = YAML::load(self.class.munge(open(path).read))
+          @path = path
+        end
+        self.update yaml
+#--}}}
+      end
+      def to_hash
+#--{{{
+        {}.update self
+#--}}}
+      end
+#--}}}
+    end # class ConfigFile
+    Configfile = ConfigFile
+    ALib::export ConfigFile 
+    ALib::export Configfile 
+
+  #
+  # file of lines, comments and blank lines are ignored
+  #
+    class ListFile < ::Array
+#--{{{
+      class << self
+#--{{{
+        def parse arg, &b
+#--{{{
+          arg.respond_to?('gets') ? loadio(arg, &b) : open("#{ path }"){|f| loadio(f, &b)}
+#--}}}
+        end
+        def loadio io
+#--{{{
+          while((line = io.gets))
+            line.gsub!(%r/#.*/o,'')
+            next if line =~ %r/^[^\S]+$/o
+            line.gsub!(%r/^[^\S]+|[^\S]+$/o,'')
+            yield line
+          end
+#--}}}
+        end
+#--}}}
+      end
+      attr :path
+      def initialize arg 
+#--{{{
+        case arg
+          when Pathname, String
+            @path = path
+            self.class.parse(arg){|line| self << line}
+          when IO
+            @path = arg.respond_to?('path') ? arg.path : arg.to_s
+            self.class.loadio(arg){|line| self << line}
+          else
+            raise "cannot initialize from <#{ arg.inspect }>"
+        end
+#--}}}
+      end
+#--}}}
+    end # class ListFile
+    Listfile = ListFile
+    ALib::export ListFile 
+    ALib::export Listfile 
+
+  #
+  # auto vivifying hash that dumps as yaml nicely
+  #
+    class AutoHash < ::Hash 
+#--{{{
+      def initialize(*args)
+#--{{{
+        super(*args){|a,k| a[k] = AutoHash::new(*args)}
+#--}}}
+      end
+      def class
+#--{{{
+        Hash
+#--}}}
+      end
+#--}}}
+    end # class AutoHash
+    ALib::export AutoHash
+
+  # AUTHOR
+  #    jan molic /mig/at/1984/dot/cz/
+  #
+  # DESCRIPTION
+  #    Hash with preserved order and some array-like extensions
+  #    Public domain. 
+  #
+  # THANKS
+  #    Andrew Johnson for his suggestions and fixes of Hash[],
+  #    merge, to_a, inspect and shift
+    class OrderedHash < Hash
+#--{{{
+        attr_accessor :order
+
+        class << self
+#--{{{
+            def [] *args
+#--{{{
+                hsh = OrderedHash.new
+                if Hash === args[0]
+                    hsh.replace args[0]
+                elsif (args.size % 2) != 0
+                    raise ArgumentError, "odd number of elements for Hash"
+                else
+                    hsh[args.shift] = args.shift while args.size > 0
+                end
+                hsh
+#--}}}
+            end
+#--}}}
+        end
+#        def initialize 
+##--{{{
+#            @order = []
+##--}}}
+#        end
+        def initialize(*a, &b)
+#--{{{
+          super
+          @order = []
+#--}}}
+        end
+        def store_only a,b
+#--{{{
+            store a,b
+#--}}}
+        end
+        alias orig_store store    
+        def store a,b
+#--{{{
+            @order.push a unless has_key? a
+            super a,b
+#--}}}
+        end
+        alias []= store
+        def == hsh2
+#--{{{
+            return false if @order != hsh2.order
+            super hsh2
+#--}}}
+        end
+        def clear
+#--{{{
+            @order = []
+            super
+#--}}}
+        end
+        def delete key
+#--{{{
+            @order.delete key
+            super
+#--}}}
+        end
+        def each_key
+#--{{{
+            @order.each { |k| yield k }
+            self
+#--}}}
+        end
+        def each_value
+#--{{{
+            @order.each { |k| yield self[k] }
+            self
+#--}}}
+        end
+        def each
+#--{{{
+            @order.each { |k| yield k,self[k] }
+            self
+#--}}}
+        end
+        alias each_pair each    
+        def delete_if
+#--{{{
+            @order.clone.each { |k| 
+                delete k if yield
+            }
+            self
+#--}}}
+        end
+        def values
+#--{{{
+            ary = []
+            @order.each { |k| ary.push self[k] }
+            ary
+#--}}}
+        end
+        def keys
+#--{{{
+            @order
+#--}}}
+        end
+        def invert
+#--{{{
+            hsh2 = Hash.new    
+            @order.each { |k| hsh2[self[k]] = k }
+            hsh2
+#--}}}
+        end
+        def reject &block
+#--{{{
+            self.dup.delete_if &block
+#--}}}
+        end
+        def reject! &block
+#--{{{
+            hsh2 = reject &block
+            self == hsh2 ? nil : hsh2
+#--}}}
+        end
+        def replace hsh2
+#--{{{
+            @order = hsh2.keys 
+            super hsh2
+#--}}}
+        end
+        def shift
+#--{{{
+            key = @order.first
+            key ? [key,delete(key)] : super
+#--}}}
+        end
+        def unshift k,v
+#--{{{
+            unless self.include? k
+                @order.unshift k
+                orig_store(k,v)
+                true
+            else
+                false
+            end
+#--}}}
+        end
+        def push k,v
+#--{{{
+            unless self.include? k
+                @order.push k
+                orig_store(k,v)
+                true
+            else
+                false
+            end
+#--}}}
+        end
+        def pop
+#--{{{
+            key = @order.last
+            key ? [key,delete(key)] : nil
+#--}}}
+        end
+        def to_a
+#--{{{
+            ary = []
+            each { |k,v| ary << [k,v] }
+            ary
+#--}}}
+        end
+        def to_s
+#--{{{
+            self.to_a.to_s
+#--}}}
+        end
+        def inspect
+#--{{{
+            ary = []
+            each {|k,v| ary << k.inspect + "=>" + v.inspect}
+            '{' + ary.join(", ") + '}'
+#--}}}
+        end
+        def update hsh2
+#--{{{
+            hsh2.each { |k,v| self[k] = v }
+            self
+#--}}}
+        end
+        alias :merge! update
+        def merge hsh2
+#--{{{
+            self.dup update(hsh2)
+#--}}}
+        end
+        def select
+#--{{{
+            ary = []
+            each { |k,v| ary << [k,v] if yield k,v }
+            ary
+#--}}}
+        end
+        def class
+#--{{{
+          Hash
+#--}}}
+        end
+#--}}}
+    end # class OrderedHash
+    ALib::export OrderedHash
+
+  #
+  # auto vivifying ordered hash that dumps as yaml nicely
+  #
+    class AutoOrderedHash < OrderedHash 
+#--{{{
+      def initialize(*args)
+#--{{{
+        super(*args){|a,k| a[k] = AutoHash::new(*args)}
+#--}}}
+      end
+      def class
+#--{{{
+        Hash
+#--}}}
+      end
+#--}}}
+    end # class AutoOrderedHash
+    OrderedAutoHash = AutoOrderedHash
+    ALib::export OrderedAutoHash 
+    ALib::export AutoOrderedHash
+
+  #                                                         -*- Ruby -*-
+  # Copyright (C) 1998, 2001  Motoyuki Kasahara
+  #
+  # This program is free software; you can redistribute it and/or modify
+  # it under the terms of the GNU General Public License as published by
+  # the Free Software Foundation; either version 2, or (at your option)
+  # any later version.
+  # 
+  # This program is distributed in the hope that it will be useful,
+  # but WITHOUT ANY WARRANTY; without even the implied warranty of
+  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  # GNU General Public License for more details.
+  #
+  #
+  # Traverse a file tree, replacement of `find.rb'.
+  #
+    class Find2
+#--{{{
+    #
+    # Constatnts
+    #
+      FIND1 = 1
+      FIND2 = 2
+    #
+    # Initializer.
+    #
+      def initialize(mode = FIND1)
+    #--{{{
+        @mode   = mode
+        @depth  = false
+        @follow = false
+        @xdev   = false
+    
+        @dirname_stats = Array.new
+        @found_files = Array.new
+        @target_device = 0
+
+        @handle = lambda { |file, stat_result, block|
+          case @mode
+            when FIND1
+              block ? block.call(file) : @found_files.push(file)
+            when FIND2
+              block ? block.call(file, stat_result) : @found_files.push([file, stat_result])
+          end
+        }
+    #--}}}
+      end
+    #
+    # Methods for accessing instances.
+    #
+      attr :depth
+      attr :follow
+      attr :xdev
+    #
+    # Find the directory `dirname'. (private)
+    #
+      def find(*arguments, &block)
+    #--{{{
+        #
+        # Parse options if specified.
+        #
+        #if arguments[0].type == Hash
+          #parse_options(arguments.shift)
+        #end
+
+# hack
+        args = []
+        opts = []
+        arguments.each do |arg|
+          case arg
+            when Hash
+              opts << arg
+            else
+              args << arg
+          end
+        end
+        opts.each{|opt| parse_options opt}
+        files = args.flatten.compact
+
+        #
+        # If a block is not given to the `find' method, found files are
+        # recorded in this array.
+        #
+        @dirname_stats.clear
+        @found_files.clear
+    
+        #
+        # Loop for each file in `files'.
+        #
+        files.each do |file|
+          catch(:prune) do
+          @dirname_stats.clear
+    
+          #
+          # Get `stat' or `lstat' of `file'.
+          #
+          begin
+            if @follow
+              begin
+                stat_result = File.stat(file)
+              rescue Errno::ENOENT, Errno::EACCES
+                stat_result = File.lstat(file)
+              end
+            else
+              stat_result = File.lstat(file)
+            end
+          rescue Errno::ENOENT, Errno::EACCES
+            next
+          end
+    
+          #
+          # Push `file' to the found stack, or yield with it,
+          # if the depth flag is enabled.
+          #
+          @handle[ file, stat_result, block ] if !@depth
+    
+          #
+          # If `file' is a directory, find files recursively.
+          #
+          if stat_result.directory?
+            @xdev_device = stat_result.dev if @xdev
+            @dirname_stats.push(stat_result)
+            find_directory(file, block)
+          end
+    
+          #
+          # Push `file' to the found stack, or yield with it.
+          # if the depth flag is disabled.
+          #
+          @handle[ file, stat_result, block ] if @depth
+
+          end
+        end
+
+        if block == nil
+          return @found_files
+        else
+          return nil
+        end
+    #--}}}
+      end
+    #
+    # Find the directory `dirname'. (private)
+    #
+      def find_directory(dirname, block)
+    #--{{{
+        #
+        # Open the directory `dirname'.
+        #
+        begin
+          dir = Dir.open(dirname)
+        rescue
+          return
+        end
+    
+        #
+        # Read all directory entries except for `.' and `..'.
+        #
+        entries = Array.new
+        loop do
+          begin
+          entry = dir.read
+          rescue
+          break
+          end
+          break if entry == nil
+          next if entry == '.' || entry == '..'
+          entries.push(entry)
+        end
+    
+        #
+        # Close `dir'.
+        #
+        dir.close
+    
+        #
+        # Loop for each entry in this directory.
+        #
+        catch(:prune) do
+          entries.each do |entry|
+          #
+          # Set `entry_path' to the full path of `entry'.
+          #
+          if dirname[-1, 1] == File::Separator
+            entry_path = dirname + entry
+          else
+            entry_path = dirname + File::Separator + entry
+          end
+    
+          #
+          # Get `stat' or `lstat' of `entry_path'.
+          #
+          begin
+            if @follow
+              begin
+                stat_result = File.stat(entry_path)
+              rescue Errno::ENOENT, Errno::EACCES
+                stat_result = File.lstat(entry_path)
+              end
+            else
+              stat_result = File.lstat(entry_path)
+            end
+          rescue Errno::ENOENT, Errno::EACCES
+            next
+          end
+    
+          #
+          # Push `entry_path' to the found stack, or yield with it,
+          # if the depth flag is enabled.
+          #
+
+          @handle[ entry_path, stat_result, block ] if !@depth
+    
+          #
+          # If `entry_path' is a directory, find recursively.
+          #
+          if stat_result.directory? \
+            && (!@xdev || @xdev_device == stat_result.dev) \
+            && (!@follow || !visited?(stat_result))
+            @dirname_stats.push(stat_result)
+            find_directory(entry_path, block)
+            @dirname_stats.pop
+          end
+    
+          #
+          # Push `entry_path' to the found stack, or yield with it,
+          # if the depth flag is disabled.
+          #
+          @handle[ entry_path, stat_result, block ] if @depth
+
+          end
+        end
+    #--}}}
+      end
+      private :find_directory
+    #
+    # Find the directory `dirname'. (class method)
+    #
+      def Find2.find(*arguments, &block)
+        Find2.new.find(*arguments, &block)
+      end
+    #
+    # Find the directory `dirname'. (class method)
+    #
+      def Find2.find2(*arguments, &block)
+        Find2.new(FIND2).find(*arguments, &block)
+      end
+    #
+    # Parse options.
+    #
+      def parse_options(options)
+    #--{{{
+        return if options == nil
+    
+        options.each_pair do |key, value|
+          case "#{ key }".strip.downcase
+            when 'depth'
+              @depth = value
+            when 'follow'
+              @follow = value
+            when 'xdev'
+              @xdev = value
+            else
+              raise ArgumentError, "unknown option - #{key}"
+          end
+        end
+    #--}}}
+      end
+      private :parse_options
+    #
+    # Prune the current visited directory.
+    #
+      def Find2.prune
+    #--{{{
+        throw :prune
+    #--}}}
+      end
+    #
+    # Did we visit the directory with the resouce `stat'? (private)
+    #
+      def visited?(stat_result)
+    #--{{{
+        dev = stat_result.dev
+        ino = stat_result.ino
+        @dirname_stats.each do |i|
+          return TRUE if i.dev == dev && i.ino == ino
+        end
+        return FALSE
+    #--}}}
+      end
+      private :visited?
+#--}}}
+    end # class Find2
+    Find = Find2
+    ALib::export Find 
+    ALib::export Find2
+
+  #
+  # Ruby/Bsearch - a binary search library for Ruby.
+  #
+  # Copyright (C) 2001 Satoru Takabayashi <satoru@namazu.org>
+  #     All rights reserved.
+  #     This is free software with ABSOLUTELY NO WARRANTY.
+  #
+  # You can redistribute it and/or modify it under the terms of 
+  # the Ruby's licence.
+  #
+  # Example:
+  #
+  #  % irb -r ./bsearch.rb
+  #  >> %w(a b c c c d e f).bsearch_first {|x| x <=> "c"}
+  #  => 2
+  #  >> %w(a b c c c d e f).bsearch_last {|x| x <=> "c"}
+  #  => 4
+  #  >> %w(a b c e f).bsearch_first {|x| x <=> "c"}
+  #  => 2
+  #  >> %w(a b e f).bsearch_first {|x| x <=> "c"}
+  #  => nil
+  #  >> %w(a b e f).bsearch_last {|x| x <=> "c"}
+  #  => nil
+  #  >> %w(a b e f).bsearch_lower_boundary {|x| x <=> "c"}
+  #  => 2
+  #  >> %w(a b e f).bsearch_upper_boundary {|x| x <=> "c"}
+  #  => 2
+  #  >> %w(a b c c c d e f).bsearch_range {|x| x <=> "c"}
+  #  => 2...5
+  #  >> %w(a b c d e f).bsearch_range {|x| x <=> "c"}
+  #  => 2...3
+  #  >> %w(a b d e f).bsearch_range {|x| x <=> "c"}
+  #  => 2...2
+  
+    module Bsearch
+#--{{{
+      VERSION = '1.5'
+
+      module BsearchMethods
+#--{{{
+      # 
+      # The binary search algorithm is extracted from Jon Bentley's
+      # Programming Pearls 2nd ed. p.93
+      #
+
+      #
+      # Return the lower boundary. (inside)
+      #
+# old
+        def bsearch_lower_boundary (range = 0 ... self.length, &block)
+    #--{{{
+          lower  = range.first() -1
+          upper = if range.exclude_end? then range.last else range.last + 1 end
+          while lower + 1 != upper
+            mid = ((lower + upper) / 2).to_i # for working with mathn.rb (Rational)
+            if yield(self[mid]) < 0
+          lower = mid
+            else 
+          upper = mid
+            end
+          end
+          return upper
+    #--}}}
+        end
+# new 
+        def bsearch_lower_boundary (arg = nil, &block)
+    #--{{{
+          range = nil
+          if arg and not block
+            block = lambda{|x| x <=> arg}
+            range = 0 ... self.length
+          end
+          range ||= (arg ? arg : (0...self.length))
+
+          lower  = range.first() -1
+          upper = if range.exclude_end? then range.last else range.last + 1 end
+          while lower + 1 != upper
+            mid = ((lower + upper) / 2).to_i # for working with mathn.rb (Rational)
+            if block[ self[mid] ] < 0
+          lower = mid
+            else 
+          upper = mid
+            end
+          end
+          return upper
+    #--}}}
+        end
+
+      #
+      # This method searches the FIRST occurrence which satisfies a
+      # condition given by a block in binary fashion and return the 
+      # index of the first occurrence. Return nil if not found.
+      #
+# old
+        def bsearch_first (range = 0 ... self.length, &block)
+    #--{{{
+          boundary = bsearch_lower_boundary(range, &block)
+          if boundary >= self.length || yield(self[boundary]) != 0
+            return nil
+          else 
+            return boundary
+          end
+    #--}}}
+        end
+# new 
+        def bsearch_first (arg = nil, &block)
+    #--{{{
+          range = nil
+          if arg and not block
+            block = lambda{|x| x <=> arg}
+            range = 0 ... self.length
+          end
+          range ||= (arg ? arg : (0...self.length))
+          boundary = bsearch_lower_boundary(range, &block)
+          if boundary >= self.length || block[ self[boundary] ] != 0
+            return nil
+          else 
+            return boundary
+          end
+    #--}}}
+        end
+
+      # alias bsearch bsearch_first
+        def bsearch(*a, &b)
+    #--{{{
+          unless b
+            obj = a.first
+            b = lambda{|x| x <=> obj}
+            bsearch_first(&b)
+          else
+            bsearch_first(*a, &b)
+          end
+    #--}}}
+        end
+      #
+      # Return the upper boundary. (outside)
+      #
+# old
+        def bsearch_upper_boundary (range = 0 ... self.length, &block)
+    #--{{{
+          lower  = range.first() -1
+          upper = if range.exclude_end? then range.last else range.last + 1 end
+          while lower + 1 != upper
+            mid = ((lower + upper) / 2).to_i # for working with mathn.rb (Rational)
+            if yield(self[mid]) <= 0
+          lower = mid
+            else 
+          upper = mid
+            end
+          end
+          return lower + 1 # outside of the matching range.
+    #--}}}
+        end
+# new 
+        def bsearch_upper_boundary (arg = nil, &block)
+    #--{{{
+          range = nil
+          if arg and not block
+            block = lambda{|x| x <=> arg}
+            range = 0 ... self.length
+          end
+          range ||= (arg ? arg : (0...self.length))
+
+          lower  = range.first() -1
+          upper = if range.exclude_end? then range.last else range.last + 1 end
+          while lower + 1 != upper
+            mid = ((lower + upper) / 2).to_i # for working with mathn.rb (Rational)
+            if block[ self[mid] ] <= 0
+          lower = mid
+            else 
+          upper = mid
+            end
+          end
+          return lower + 1 # outside of the matching range.
+    #--}}}
+        end
+      #
+      # This method searches the LAST occurrence which satisfies a
+      # condition given by a block in binary fashion and return the 
+      # index of the last occurrence. Return nil if not found.
+      #
+# old
+        def bsearch_last (range = 0 ... self.length, &block)
+    #--{{{
+          # `- 1' for canceling `lower + 1' in bsearch_upper_boundary.
+          boundary = bsearch_upper_boundary(range, &block) - 1
+      
+          if (boundary <= -1 || yield(self[boundary]) != 0)
+            return nil
+          else
+            return boundary
+          end
+    #--}}}
+        end
+# new
+        def bsearch_last (arg = nil, &block)
+    #--{{{
+          range = nil
+          if arg and not block
+            block = lambda{|x| x <=> arg}
+            range = 0 ... self.length
+          end
+          range ||= (arg ? arg : (0...self.length))
+
+          # `- 1' for canceling `lower + 1' in bsearch_upper_boundary.
+          boundary = bsearch_upper_boundary(range, &block) - 1
+      
+          if (boundary <= -1 || block[ self[boundary] ] != 0)
+            return nil
+          else
+            return boundary
+          end
+    #--}}}
+        end
+      #
+      # Return the search result as a Range object.
+      #
+# old
+        def bsearch_range (range = 0 ... self.length, &block)
+    #--{{{
+          lower = bsearch_lower_boundary(range, &block)
+          upper = bsearch_upper_boundary(range, &block)
+          return lower ... upper
+    #--}}}
+        end
+# new 
+        def bsearch_range (arg = nil, &block) 
+    #--{{{
+          range = nil
+          if arg and not block
+            block = lambda{|x| x <=> arg}
+            range = 0 ... self.length
+          end
+          range ||= (arg ? arg : (0...self.length))
+
+          lower = bsearch_lower_boundary(range, &block)
+          upper = bsearch_upper_boundary(range, &block)
+          return lower ... upper
+    #--}}}
+        end
+#--}}}
+      end
+
+if false
+      def Bsearch::append_features klass
+#--{{{
+        ::Array.module_eval{ include BsearchMethods }
+        super
+#--}}}
+      end
+end
+      ::Array.module_eval{ include BsearchMethods }
+#--}}}
+    end # module Bsearch
+    BSearch = Bsearch
+    ALib::export BSearch
+    ALib::export Bsearch
+
+  #
+  # template main building block classes
+  #
+
+    module MainModule
+#--{{{
+      module Mixins 
+#--{{{
+        include ALib
+        include ALib::Logging
+#--}}}
+      end
+      module Constants
+#--{{{
+        EXIT_SUCCESS = 0
+        EXIT_FAILURE = 1
+#--}}}
+      end
+      module ClassMethods
+#--{{{
+        include Mixins
+        include Constants
+        def stringlist(*list)
+#--{{{
+          list.flatten.compact.map{|item| "#{ item }".strip}
+#--}}}
+        end
+
+        def instance_attributes(*names)
+#--{{{
+          names = stringlist names
+          names.each do |name|
+            getter = "#{ name }"
+            setter = "#{ name }="
+            code = <<-code
+              def #{ name }(*a)
+                unless a.empty?
+                  self.#{ name }= a.shift
+                else
+                  @#{ name }
+                end
+              end
+              def #{ name }= value
+                @#{ name } = value
+              end
+              alias #{ name }? #{ name }
+            code
+            module_eval code
+          end
+#--}}}
+        end
+        alias instance_attribute instance_attributes
+        alias i_attrs instance_attributes
+        alias i_attr instance_attributes
+        alias attribute instance_attributes
+        alias attributes instance_attributes
+        
+        def class_attributes(*names)
+#--{{{
+          names = stringlist names
+          names.each do |name|
+            getter = "#{ name }"
+            setter = "#{ name }="
+            code = <<-code
+              class << self
+                def #{ name }(*a)
+                  unless a.empty?
+                    self.#{ name }= a.shift
+                  else
+                    @#{ name }
+                  end
+                end
+                def #{ name }= value
+                  @#{ name } = value
+                end
+                alias #{ name }? #{ name }
+              end
+            code
+            module_eval code
+          end
+#--}}}
+        end
+        alias class_attribute class_attributes
+        alias c_attrs class_attributes
+        alias c_attr class_attributes
+
+        %w( version author program optspec ).each do |meth|
+#--{{{
+          module_eval <<-code
+            def #{ meth }(*a)
+              unless a.empty?
+                self.#{ meth }= a.shift
+              else
+                @#{ meth }
+              end
+            end
+            def #{ meth }= value
+              @#{ meth } = value
+            end
+            def #{ meth }?
+              defined? @#{ meth } and @#{ meth }
+            end
+          code
+#--}}}
+        end
+        alias prognam program
+        alias prognam= program=
+        alias prognam? program?
+
+        %w( usage examples ).each do |meth|
+#--{{{
+          module_eval <<-code
+            def #{ meth }(*a)
+              unless a.empty?
+                self.#{ meth }= a.shift
+              else
+                @#{ meth }
+              end
+            end
+            def #{ meth }= msg 
+              @#{ meth } = unindent_block msg 
+            end
+            def #{ meth }?
+              defined? @#{ meth } and @#{ meth }
+            end
+          code
+#--}}}
+        end
+
+        def unindent_block buf
+#--{{{
+          buf = "#{ buf }"
+          lines = buf.to_a
+          indent_pat = %r/^\s*[\s|]/
+          indent = lines.first[ indent_pat ]
+          if indent
+            lines.map do |line| 
+              line[ indent.size..-1 ] || "\n"
+            end.join 
+          else
+            buf 
+          end
+#--}}}
+        end
+
+        def options(*list)
+#--{{{
+          @optspec ||= []
+          return @optspec if list.empty?
+          list = [list] unless Array === list.first
+          list.each{|spec| (@optspec ||= []) << spec}
+#--}}}
+        end
+        alias option options
+
+        def required_arguments(*list)
+#--{{{
+          @required_arguments ||= []
+          list.flatten.each do |arg| 
+            return(optional_argument(arg)) if Hash === arg
+            unless instance_methods.include? "#{ arg }"
+              module_eval <<-code
+                def #{ arg }(*__list)
+                  if __list.empty?
+                    @#{ arg }
+                  else
+                    send('#{ arg }=', *__list)
+                  end
+                end
+                def #{ arg }=(__arg, *__list)
+                  if __list.empty?
+                    @#{ arg } = __arg
+                  else
+                    @#{ arg } = ([__arg] + __list)
+                  end
+                end
+                def #{ arg }?
+                  defined? @#{ arg } and @#{ arg }
+                end
+              code
+            end
+            @required_arguments << "#{ arg }"
+          end
+          @required_arguments
+#--}}}
+        end
+        alias required_argument required_arguments
+        alias arguments required_arguments
+        alias argument required_arguments
+
+        def optional_arguments(*list)
+#--{{{
+          @optional_arguments ||= []
+          list.flatten.each do |arg| 
+            arg, default =
+              case arg
+                when Hash
+                  arg.to_a.first
+                else
+                  [arg, nil]
+              end
+            @do_not_gc ||= [] 
+            @do_not_gc << default unless @do_not_gc.include? default
+            unless instance_methods.include? "#{ arg }"
+              module_eval <<-code
+                def #{ arg }(*__list)
+                  unless @#{ arg }
+                    @#{ arg } = ObjectSpace::_id2ref #{ default.object_id }
+                  end
+                  if __list.empty?
+                    @#{ arg }
+                  else
+                    send('#{ arg }=', *__list)
+                  end
+                end
+                def #{ arg }=(__arg, *__list)
+                  if __list.empty?
+                    @#{ arg } = __arg
+                  else
+                    @#{ arg } = ([__arg] + __list)
+                  end
+                end
+                def #{ arg }?
+                  defined? @#{ arg } and @#{ arg }
+                end
+              code
+            end
+            @optional_arguments << "#{ arg }"
+          end
+          @optional_arguments
+#--}}}
+        end
+        alias optional_argument optional_arguments
+        def inherited klass
+#--{{{
+          ret = super
+          begin; klass.class_initialize; rescue NoMethodError; end
+          ret
+#--}}}
+        end
+#--}}}
+      end
+      module InstanceMethods
+#--{{{
+        include Mixins
+        include Constants
+        attr :logger
+        attr :program
+        attr :argv
+        attr :env
+        attr :cmdline
+        attr :console
+        attr :options
+        attr :listoptions
+        attr :op
+        attr :logdev
+        attr :verbosity
+
+        alias console? console
+
+        def initialize argv = ARGV, env = ENV
+#--{{{
+          @argv = Util::mcp(argv.to_a)
+          @env = Util::mcp(env.to_hash)
+          @program = File::expand_path $0
+          @cmdline = ([@program] + @argv).join ' '
+          @console = STDIN.tty?
+#--}}}
+        end
+        def klass; self.class; end
+        def required_arguments
+#--{{{
+          klass::required_arguments
+#--}}}
+        end
+        def optional_arguments
+#--{{{
+          klass::optional_arguments
+#--}}}
+        end
+
+        def run
+#--{{{
+          logcatch do
+            begin
+              pre_run
+              pre_parse_options
+              parse_options
+              post_parse_options
+              if(@options.has_key?('help') or (@argv.size == 1 and @argv.first =~ %r/help/i))
+                usage STDOUT
+                exit EXIT_SUCCESS
+              end
+              pre_parse_argv
+              parse_argv
+              post_parse_argv
+              init_logging
+              pre_main
+              status = main
+              post_main
+              post_run
+              exit(status ? EXIT_SUCCESS : EXIT_FAILURE)
+            rescue Errno::EPIPE
+              STDOUT.tty? ?  raise : exit(EXIT_FAILURE)
+            end
+          end
+#--}}}
+        end
+        def pre_parse_options; end
+        def post_parse_options; end
+        def pre_parse_argv; end
+        def post_parse_argv; end
+        def pre_run; end
+        def post_run; end
+        def pre_main; end
+        def post_main; end
+        def logcatch 
+#--{{{
+          ret = nil
+          @logger ||= Logger::new STDERR
+          begin
+            ret = yield
+          rescue Exception => e
+            unless SystemExit === e
+              fatal{ e }
+              exit EXIT_FAILURE
+            if false
+              if logger.debug?
+                fatal{ e }
+                exit EXIT_FAILURE
+              else
+                fatal{ emsg(e) }
+                exit EXIT_FAILURE
+              end
+            end
+            else
+              exit e.status 
+            end
+          end
+          ret
+#--}}}
+        end
+        def usage port = STDERR
+#--{{{
+          port << klass::usage << "\n" if klass::usage 
+          port << klass::examples << "\n" if klass::examples
+
+          if klass::optspec 
+            port << 'OPTIONS' << "\n"
+
+            klass::optspec.each do |os| 
+              a, b, c = os
+              long, short, desc = nil
+              [a,b,c].each do |word|
+                next unless word
+                word.strip!
+                case word
+                  when %r/^--[^-]/o
+                    long = word
+                  when %r/^-[^-]/o
+                    short = word
+                  else
+                    desc = word
+                end
+              end
+
+              spec = ((long and short) ? [long, short] : [long])
+
+              if spec
+                port << Util::columnize(spec.join(', '), :width => 80, :indent => 2)
+                port << "\n"
+              end
+
+              if desc
+                port << Util::columnize(desc, :width => 80, :indent => 8)
+                port << "\n"
+              end
+            end
+
+            port << "\n"
+          end
+
+          port
+#--}}}
+        end
+        def parse_options
+#--{{{
+          @op = OptionParser::new
+          @options = {}
+          @listoptions = Hash::new{|h,k| h[k] = []} 
+          klass::optspec.each do |spec|
+            k = spec.first.gsub(%r/(?:--)|(?:=.*$)|(?:\s+)/o,'')
+            @op.def_option(*spec) do |v| 
+              @options[k] = v
+              @listoptions[k] << v
+            end
+          end
+          #begin
+            op.parse! @argv 
+          #rescue OptionParser::InvalidOption => e
+            # preverve unknown options
+            #e.recover(argv)
+          #end
+          @options
+#--}}}
+        end
+        def init_logging opts = @options 
+#--{{{
+          log = Util::getopt 'log', opts
+          log_age = Util::getopt 'log_age', opts
+          log_size = Util::getopt 'log_size', opts
+          verbosity = Util::getopt 'verbosity', opts
+          log_age = Integer log_age rescue nil
+          log_size = Integer log_size rescue nil
+          $logger = @logger = Logger::new(log || STDERR, log_age, log_size)
+        #
+        # hack to fix Logger sync bug
+        #
+          begin
+            class << @logger; attr :logdev unless @logger.respond_to?(:logdev); end
+            @logdev = @logger.logdev.dev 
+            @logdev.sync = true
+          rescue
+            nil
+          end
+          level = nil
+          verbosity ||= 'info'
+          verbosity =
+            case verbosity
+              when /^\s*(?:4|d|debug)\s*$/io
+                level = 'Logging::DEBUG'
+                4
+              when /^\s*(?:3|i|info)\s*$/io
+                level = 'Logging::INFO'
+                3
+              when /^\s*(?:2|w|warn)\s*$/io
+                level = 'Logging::WARN'
+                2
+              when /^\s*(?:1|e|error)\s*$/io
+                level = 'Logging::ERROR'
+                1
+              when /^\s*(?:0|f|fatal)\s*$/io
+                level = 'Logging::FATAL'
+                0
+              else
+                abort "illegal verbosity setting <#{ verbosity }>" 
+            end
+          @logger.level = 2 - ((verbosity % 5) - 2) 
+          @logger
+#--}}}
+        end
+        def parse_argv
+#--{{{
+          a, b = [], []
+          klass::required_arguments.each do |arg|
+            value = @argv.shift
+            if value 
+              send "#{ arg }=", value
+            else
+              die 'msg' => "required_argument <#{ arg }> not given"
+            end
+            a << send("#{ arg }")
+          end
+          klass::optional_arguments.each do |arg|
+            value = @argv.shift
+            if value 
+              send "#{ arg }=", value
+            end
+            b << send("#{ arg }")
+          end
+          [a, b, @argv]
+#--}}}
+        end
+        def die opts = {} 
+#--{{{
+          msg = Util::getopt 'msg', opts, klass.usage
+          errno = Util::getopt 'errno', opts, EXIT_FAILURE
+          STDERR.puts("#{ msg }")
+          exit(Integer(errno))
+#--}}}
+        end
+        def main 
+#--{{{
+          raise NotImplementedError, 'you need to define main'
+#--}}}
+        end
+#--}}}
+      end
+      module Abilities
+#--{{{
+        def self::append_features other 
+#--{{{
+          other.extend ClassMethods 
+          other.module_eval { 
+            include Mixins
+            include Constants
+            include InstanceMethods
+          }
+#--}}}  
+        end
+#--}}}
+      end
+      class SimpleMain
+#--{{{
+        include Abilities
+        class << self
+#--{{{
+          def class_initialize 
+#--{{{
+            version '0.0.0'
+
+            prognam ALib::Util::prognam
+
+            usage <<-usage
+              NAME
+                #{ prognam } v#{ version }
+
+              SYNOPSIS
+                #{ prognam } [options]+ [file]+
+            usage
+
+            optspec [
+              [
+                '--help', '-h', 
+                'this message'
+              ],
+              [
+                '--log=path','-l', 
+                'set log file - (default stderr)'
+              ],
+              [
+                '--verbosity=verbostiy', '-v', 
+                '0|fatal < 1|error < 2|warn < 3|info < 4|debug - (default info)'
+              ],
+=begin
+              [
+                '--config=path',
+                'valid path - specify config file (default nil)'
+              ],
+              [
+                '--template=[path]',
+                'valid path - generate a template config file in path (default stdout)'
+              ],
+=end
+            ]
+#--}}}
+          end
+#--}}}
+        end
+        def pre_parse_argv
+#--{{{
+          if(@options.has_key?('help') or (@argv.size == 1 and @argv.first =~ %r/help/i))
+            usage STDOUT
+            exit EXIT_SUCCESS
+          end
+          if(@options.has_key?('version') or @argv.first =~ %r/version/i)
+            STDOUT.puts self.class.version
+            exit EXIT_SUCCESS
+          end
+#--}}}
+        end
+#--}}}
+      end
+      class ConfigurableMain
+#--{{{
+        include Abilities
+
+        class << self
+#--{{{
+          def class_initialize 
+#--{{{
+            version '0.0.0'
+
+            prognam ALib::Util::prognam
+
+            configfile Class::new(ALib::ConfigFile) #{ default = DATA; DATA.rewind; }
+
+            config_default_path "#{ prognam }.conf"
+
+            config_search_path %w(. ~ /usr/local/etc /usr/etc /etc)
+
+            usage <<-usage
+              NAME
+                #{ prognam } v#{ version }
+
+              SYNOPSIS
+                #{ prognam } [options]+ [file]+
+
+              CONFIG
+                default path -> #{ config_default_path }
+                search path -> #{ config_search_path.join ' ' }
+            usage
+
+            optspec [
+              [
+                '--help', '-h', 
+                'this message'
+              ],
+              [
+                '--log=path','-l', 
+                'set log file - (default stderr)'
+              ],
+              [
+                '--verbosity=verbostiy', '-v', 
+                '0|fatal < 1|error < 2|warn < 3|info < 4|debug - (default info)'
+              ],
+              [
+                '--config=path',
+                'valid path - specify config file (default nil)'
+              ],
+              [
+                '--template=[path]',
+                'valid path - generate a template config file in path (default stdout)'
+              ],
+            ]
+#--}}}
+          end
+#--}}}
+        end
+
+        class_attributes :config_default_path, :config_search_path, :configfile
+        attribute :config
+
+        def pre_parse_argv
+#--{{{
+          if(@options.has_key?('help') or @argv.first =~ %r/help/i)
+            usage STDOUT
+            exit EXIT_SUCCESS
+          end
+          if(@options.has_key?('version') or @argv.first =~ %r/version/i)
+            STDOUT.puts self.class.version
+            exit EXIT_SUCCESS
+          end
+          if(@options.has_key?('template') or @argv.first =~ %r/template/i)
+            @argv.shift if @argv.first =~ %r/template/i
+            arg = @argv.first
+            gen_template @options['template'] || @options['config'] || arg
+            exit EXIT_SUCCESS
+          end
+#--}}}
+        end
+        def gen_template template
+#--{{{
+          klass::configfile::gen_template(template)
+          self
+#--}}}
+        end
+        def post_parse_argv
+#--{{{
+          init_config
+#--}}}
+        end
+        def init_config opts = @options
+#--{{{
+          conf = Util::getopt 'config', opts
+          @config =
+            if conf 
+              klass::configfile::new(conf)
+            else
+              klass::configfile::any klass::config_default_path, klass::config_search_path
+            end
+          @config
+#--}}}
+        end
+#--}}}
+      end
+#--}}}
+    end # module MainModule
+
+    class << self
+#--{{{
+      def simple_main &b
+#--{{{
+        if b
+          Class::new(MainModule::SimpleMain, &b)
+        else
+          MainModule::SimpleMain
+        end
+#--}}}
+      end
+      def configurable_main &b
+#--{{{
+        if b
+          Class::new(MainModule::ConfigurableMain, &b)
+        else
+          MainModule::ConfigurableMain
+        end
+#--}}}
+      end
+#--}}}
+    end
+
+  SimpleMain = simple_main
+  ConfigurableMain = configurable_main
+
+=begin
+    class SimpleMain
+#--{{{
+      include ALib
+      include ALib::Logging
+
+      EXIT_SUCCESS = 0
+      EXIT_FAILURE = 1
+      
+      class << self
+#--{{{
+        def stringlist(*list)
+#--{{{
+          list.flatten.compact.map{|item| "#{ item }".strip}
+#--}}}
+        end
+        def instance_attribute(*names)
+#--{{{
+          names = stringlist names
+          names.each do |name|
+            getter = "#{ name }"
+            setter = "#{ name }="
+            code = <<-code
+              def #{ name }(*a)
+                unless a.empty?
+                  self.#{ name }= a.shift
+                else
+                  @#{ name }
+                end
+              end
+              def #{ name }= value
+                @#{ name } = value
+              end
+              alias #{ name }? #{ name }
+            code
+            module_eval code
+          end
+#--}}}
+        end
+        alias instance_attributes instance_attribute
+        alias i_attrs instance_attribute
+        alias i_attr instance_attribute
+        def class_attribute(*names)
+#--{{{
+          names = stringlist names
+          names.each do |name|
+            getter = "#{ name }"
+            setter = "#{ name }="
+            code = <<-code
+              class << self
+                def #{ name }(*a)
+                  unless a.empty?
+                    self.#{ name }= a.shift
+                  else
+                    @#{ name }
+                  end
+                end
+                def #{ name }= value
+                  @#{ name } = value
+                end
+                alias #{ name }? #{ name }
+              end
+            code
+            module_eval code
+          end
+#--}}}
+        end
+        alias class_attributes class_attribute
+        alias c_attrs class_attribute
+        alias c_attr class_attribute
+        def usage(*a)
+#--{{{
+          unless a.empty?
+            self.usage = a.shift
+          else
+            @usage
+          end
+#--}}}
+        end
+        def usage= block 
+#--{{{
+          @usage = unindent_block block 
+#--}}}
+        end
+        alias usage? usage 
+        def examples(*a)
+#--{{{
+          unless a.empty?
+            self.examples = a.shift
+          else
+            @examples
+          end
+#--}}}
+        end
+        def examples= block 
+#--{{{
+          @examples = unindent_block block 
+#--}}}
+        end
+        alias examples? examples 
+        def unindent_block buf
+#--{{{
+          buf = "#{ buf }"
+          lines = buf.to_a
+          indent_pat = %r/^\s*[\s|]/
+          indent = lines.first[ indent_pat ]
+          if indent
+            lines.map do |line| 
+              line[ indent.size..-1 ] || "\n"
+            end.join 
+          else
+            buf 
+          end
+#--}}}
+        end
+        def options(*list)
+#--{{{
+          list.each{|args| (@optspec ||= []) << args}
+#--}}}
+        end
+        def option(*args)
+#--{{{
+          options args.flatten
+#--}}}
+        end
+        def required_arguments(*list)
+#--{{{
+          @required_arguments ||= []
+          list.flatten.each{|arg| @required_arguments << "#{ arg }"}
+          @required_arguments
+#--}}}
+        end
+        alias required_argument required_arguments
+        alias arguments required_arguments
+        alias argument required_arguments
+        def optional_arguments(*list)
+#--{{{
+          @optional_arguments ||= []
+          list.flatten.each{|arg| @optional_arguments << "#{ arg }"}
+          @optional_arguments
+#--}}}
+        end
+        alias optional_argument optional_arguments
+
+        def option(*args)
+#--{{{
+          options args.flatten
+#--}}}
+        end
+        def init
+#--{{{
+          version '0.0.0'
+          author 'ara.t.howard@noaa.gov'
+          prognam ALib::Util::prognam
+
+          usage <<-usage
+            NAME
+              #{ prognam } v#{ version }
+
+            SYNOPSIS
+              #{ prognam } [options]+ [file]+
+
+            DESCRIPTTION
+
+            ENVIRONMENT
+
+            DIAGNOSTICS
+              success -> $? == 0
+              failure -> $? != 0
+
+            AUTHOR
+              #{ author }
+
+            BUGS
+              > 1
+          usage
+
+          examples <<-examples
+            EXAMPLES
+
+              0) #{ prognam }
+          examples
+
+          optspec [
+            [
+              '--help', '-h', 
+              'this message'
+            ],
+            [
+              '--log=path','-l', 
+              'set log file - (default stderr)'
+            ],
+            [
+              '--verbosity=verbostiy', '-v', 
+              '0|fatal < 1|error < 2|warn < 3|info < 4|debug - (default info)'
+            ],
+            [
+              '--config=path',
+              'valid path - specify config file (default nil)'
+            ],
+            [
+              '--template=[path]',
+              'valid path - generate a template config file in path (default stdout)'
+            ],
+          ]
+#--}}}
+        end
+        def inherited klass
+#--{{{
+          ret = super
+          klass.init
+          ret
+#--}}}
+        end
+#--}}}
+      end
+
+      class_attribute :version
+      class_attribute :author
+      class_attribute :prognam
+      class_attribute :optspec
+
+      self::init
+
+      attr :logger
+      attr :argv
+      attr :env
+      attr :cmdline
+      attr :options
+      attr :op
+      attr :logdev
+      attr :verbosity
+
+      def initialize argv = ARGV, env = ENV
+#--{{{
+        @argv = Util::mcp(argv.to_a)
+        @env = Util::mcp(env.to_hash)
+        @cmdline = ([$0] + @argv).join ' '
+#--}}}
+      end
+      def klass; self.class; end
+      def required_arguments
+#--{{{
+        klass.required_arguments
+#--}}}
+      end
+      def optional_arguments
+#--{{{
+        klass.optional_arguments
+#--}}}
+      end
+      def run
+#--{{{
+        logcatch do
+          parse_options
+          begin
+            if(@options.has_key?('help') or @argv.first =~ %r/help/i)
+              usage STDOUT
+              exit EXIT_SUCCESS
+            end
+            parse_argv
+            init_logging
+            status = main
+            exit(status ? EXIT_SUCCESS : EXIT_FAILURE)
+          rescue Errno::EPIPE
+            STDOUT.tty? ?  raise : exit(EXIT_FAILURE)
+          end
+        end
+#--}}}
+      end
+      def logcatch 
+#--{{{
+        ret = nil
+        @logger ||= Logger::new STDERR
+        begin
+          ret = yield
+        rescue => e
+          unless SystemExit === e
+            if logger.debug?
+              fatal{ e }
+              exit EXIT_FAILURE
+            else
+              fatal{ emsg(e) }
+              exit EXIT_FAILURE
+            end
+          else
+            exit e.status 
+          end
+        end
+        ret
+#--}}}
+      end
+      def usage port = STDERR
+#--{{{
+        port << klass::usage << "\n" if klass::usage 
+        port << klass::examples << "\n" if klass::examples
+
+        if klass::optspec 
+          port << 'OPTIONS' << "\n"
+
+          klass::optspec.each do |os| 
+            a, b, c = os
+            long, short, desc = nil
+            [a,b,c].each do |word|
+              next unless word
+              word.strip!
+              case word
+                when %r/^--[^-]/o
+                  long = word
+                when %r/^-[^-]/o
+                  short = word
+                else
+                  desc = word
+              end
+            end
+
+            spec = ((long and short) ? [long, short] : [long])
+
+            if spec
+              port << Util::columnize(spec.join(', '), :width => 80, :indent => 2)
+              port << "\n"
+            end
+
+            if desc
+              port << Util::columnize(desc, :width => 80, :indent => 8)
+              port << "\n"
+            end
+          end
+
+          port << "\n"
+        end
+
+        port
+#--}}}
+      end
+      def parse_options
+#--{{{
+        @op = OptionParser::new
+        @options = {}
+        @listoptions = Hash::new{|h,k| h[k] = []} 
+        klass::optspec.each do |spec|
+          k = spec.first.gsub(%r/(?:--)|(?:=.*$)|(?:\s+)/o,'')
+          @op.def_option(*spec) do |v| 
+            @options[k] = v
+            @listoptions[k] << v
+          end
+        end
+        #begin
+          op.parse! @argv 
+        #rescue OptionParser::InvalidOption => e
+          # preverve unknown options
+          #e.recover(argv)
+        #end
+        @options
+#--}}}
+      end
+      def init_logging
+#--{{{
+        log, log_age, log_size, verbosity = 
+          @options.values_at 'log', 'log_age', 'log_size', 'verbosity'
+        log_age = Integer log_age rescue nil
+        log_size = Integer log_size rescue nil
+        $logger = @logger = Logger::new(log || STDERR, log_age, log_size)
+      #
+      # hack to fix Logger sync bug
+      #
+        begin
+          class << @logger; attr :logdev unless @logger.respond_to?(:logdev); end
+          @logdev = @logger.logdev.dev 
+          @logdev.sync = true
+        rescue
+          nil
+        end
+        level = nil
+        verbosity ||= 'info'
+        verbosity =
+          case verbosity
+            when /^\s*(?:4|d|debug)\s*$/io
+              level = 'Logging::DEBUG'
+              4
+            when /^\s*(?:3|i|info)\s*$/io
+              level = 'Logging::INFO'
+              3
+            when /^\s*(?:2|w|warn)\s*$/io
+              level = 'Logging::WARN'
+              2
+            when /^\s*(?:1|e|error)\s*$/io
+              level = 'Logging::ERROR'
+              1
+            when /^\s*(?:0|f|fatal)\s*$/io
+              level = 'Logging::FATAL'
+              0
+            else
+              abort "illegal verbosity setting <#{ verbosity }>" 
+          end
+        @logger.level = 2 - ((verbosity % 5) - 2) 
+        @logger
+#--}}}
+      end
+      def parse_argv
+#--{{{
+        klass.required_arguments.each do |arg|
+          value = @argv.shift
+          if value 
+            klass.module_eval <<-code
+              def #{ arg }(*__list)
+                if __list.empty?
+                  @#{ arg }
+                else
+                  send('#{ arg }=', *__list)
+                end
+              end
+              def #{ arg }=(__arg, *__list)
+                if __list.empty?
+                  @#{ arg } = __arg
+                else
+                  @#{ arg } = ([__arg] + __list)
+                end
+              end
+            code
+            send "#{ arg }=", value
+          else
+            die 'msg' => "required_argument <#{ arg }> not given"
+          end
+        end
+
+        klass.optional_arguments.each do |arg|
+          value = @argv.shift
+          break unless value
+          if value 
+            klass.module_eval <<-code
+              def #{ arg }(*__list)
+                if __list.empty?
+                  @#{ arg }
+                else
+                  send('#{ arg }=', *__list)
+                end
+              end
+              def #{ arg }=(__arg, *__list)
+                if __list.empty?
+                  @#{ arg } = __arg
+                else
+                  @#{ arg } = ([__arg] + __list)
+                end
+              end
+            code
+            send "#{ arg }=", value
+          end
+        end
+
+        @argv
+#--}}}
+      end
+      def die opts = {} 
+#--{{{
+        msg = Util::getopt 'msg', opts, klass.usage
+        errno = Util::getopt 'errno', opts, EXIT_FAILURE
+        STDERR.puts("#{ msg }")
+        exit(Integer(errno))
+#--}}}
+      end
+      def main 
+#--{{{
+#--}}}
+      end
+#--}}}
+    end
+    class ConfigurableMain
+#--{{{
+      include ALib
+      include ALib::Logging
+
+      EXIT_SUCCESS = 0
+      EXIT_FAILURE = 1
+      
+      class << self
+#--{{{
+        def stringlist(*list)
+#--{{{
+          list.flatten.compact.map{|item| "#{ item }".strip}
+#--}}}
+        end
+        def instance_attribute(*names)
+#--{{{
+          names = stringlist names
+          names.each do |name|
+            getter = "#{ name }"
+            setter = "#{ name }="
+            code = <<-code
+              def #{ name }(*a)
+                unless a.empty?
+                  self.#{ name }= a.shift
+                else
+                  @#{ name }
+                end
+              end
+              def #{ name }= value
+                @#{ name } = value
+              end
+              alias #{ name }? #{ name }
+            code
+            module_eval code
+          end
+#--}}}
+        end
+        alias instance_attributes instance_attribute
+        alias i_attrs instance_attribute
+        alias i_attr instance_attribute
+        def class_attribute(*names)
+#--{{{
+          names = stringlist names
+          names.each do |name|
+            getter = "#{ name }"
+            setter = "#{ name }="
+            code = <<-code
+              class << self
+                def #{ name }(*a)
+                  unless a.empty?
+                    self.#{ name }= a.shift
+                  else
+                    @#{ name }
+                  end
+                end
+                def #{ name }= value
+                  @#{ name } = value
+                end
+                alias #{ name }? #{ name }
+              end
+            code
+            module_eval code
+          end
+#--}}}
+        end
+        alias class_attributes class_attribute
+        alias c_attrs class_attribute
+        alias c_attr class_attribute
+        def usage(*a)
+#--{{{
+          unless a.empty?
+            self.usage = a.shift
+          else
+            @usage
+          end
+#--}}}
+        end
+        def usage= block 
+#--{{{
+          @usage = unindent_block block 
+#--}}}
+        end
+        alias usage? usage 
+        def examples(*a)
+#--{{{
+          unless a.empty?
+            self.examples = a.shift
+          else
+            @examples
+          end
+#--}}}
+        end
+        def examples= block 
+#--{{{
+          @examples = unindent_block block 
+#--}}}
+        end
+        alias examples? examples 
+        def unindent_block buf
+#--{{{
+          buf = "#{ buf }"
+          lines = buf.to_a
+          indent_pat = %r/^\s*[\s|]/
+          indent = lines.first[ indent_pat ]
+          if indent
+            lines.map do |line| 
+              line[ indent.size..-1 ] || "\n"
+            end.join 
+          else
+            buf 
+          end
+#--}}}
+        end
+        def options(*list)
+#--{{{
+          list.each{|args| (@optspec ||= []) << args}
+#--}}}
+        end
+        def option(*args)
+#--{{{
+          options args.flatten
+#--}}}
+        end
+        def required_arguments(*list)
+#--{{{
+          @required_arguments ||= []
+          list.flatten.each{|arg| @required_arguments << "#{ arg }"}
+          @required_arguments
+#--}}}
+        end
+        alias required_argument required_arguments
+        alias arguments required_arguments
+        alias argument required_arguments
+        def optional_arguments(*list)
+#--{{{
+          @optional_arguments ||= []
+          list.flatten.each{|arg| @optional_arguments << "#{ arg }"}
+          @optional_arguments
+#--}}}
+        end
+        alias optional_argument optional_arguments
+        def init
+#--{{{
+          version '0.0.0'
+          author 'ara.t.howard@noaa.gov'
+          prognam ALib::Util::prognam
+          configfile Class::new(ALib::ConfigFile) #{ default = DATA; DATA.rewind; }
+          config_default_path "#{ prognam }.conf"
+          config_search_path %w(. ~ /usr/local/etc /usr/etc /etc)
+
+          usage <<-usage
+            NAME
+              #{ prognam } v#{ version }
+
+            SYNOPSIS
+              #{ prognam } [options]+ [file]+
+
+            DESCRIPTTION
+
+            ENVIRONMENT
+
+            CONFIG
+              default path -> #{ config_default_path }
+              search path -> #{ config_search_path.join ' ' }
+
+            DIAGNOSTICS
+              success -> $? == 0
+              failure -> $? != 0
+
+            AUTHOR
+              #{ author }
+
+            BUGS
+              > 1
+          usage
+
+          examples <<-examples
+            EXAMPLES
+
+              0) #{ prognam }
+          examples
+
+          optspec [
+            [
+              '--help', '-h', 
+              'this message'
+            ],
+            [
+              '--log=path','-l', 
+              'set log file - (default stderr)'
+            ],
+            [
+              '--verbosity=verbostiy', '-v', 
+              '0|fatal < 1|error < 2|warn < 3|info < 4|debug - (default info)'
+            ],
+            [
+              '--config=path',
+              'valid path - specify config file (default nil)'
+            ],
+            [
+              '--template=[path]',
+              'valid path - generate a template config file in path (default stdout)'
+            ],
+          ]
+#--}}}
+        end
+        def inherited klass
+#--{{{
+          ret = super
+          klass.init
+          ret
+#--}}}
+        end
+#--}}}
+      end
+
+      class_attribute :version
+      class_attribute :author
+      class_attribute :prognam
+      class_attribute :config_default_path
+      class_attribute :config_search_path
+      class_attribute :optspec
+      class_attribute :configfile
+
+      self::init
+
+      attr :logger
+      attr :argv
+      attr :env
+      attr :cmdline
+      attr :options
+      attr :op
+      attr :logdev
+      attr :verbosity
+      attr :config
+
+      def initialize argv = ARGV, env = ENV
+#--{{{
+        @argv = Util::mcp(argv.to_a)
+        @env = Util::mcp(env.to_hash)
+        @cmdline = ([$0] + @argv).join ' '
+#--}}}
+      end
+      def klass; self.class; end
+      def required_arguments
+#--{{{
+        klass.required_arguments
+#--}}}
+      end
+      def optional_arguments
+#--{{{
+        klass.optional_arguments
+#--}}}
+      end
+      def run
+#--{{{
+        logcatch do
+          parse_options
+          begin
+            if(@options.has_key?('help') or @argv.first =~ %r/help/i)
+              usage STDOUT
+              exit EXIT_SUCCESS
+            end
+            if(@options.has_key?('template') or @argv.first =~ %r/template/i)
+              @argv.shift if @argv.first =~ %r/template/i
+              arg = @argv.first
+              gen_template @options['template'] || @options['config'] || arg
+              exit EXIT_SUCCESS
+            end
+            parse_argv
+            init_logging
+            init_config
+            status = main
+            exit(status ? EXIT_SUCCESS : EXIT_FAILURE)
+          rescue Errno::EPIPE
+            STDOUT.tty? ?  raise : exit(EXIT_FAILURE)
+          end
+        end
+#--}}}
+      end
+      def logcatch 
+#--{{{
+        ret = nil
+        @logger ||= Logger::new STDERR
+        begin
+          ret = yield
+        rescue => e
+          unless SystemExit === e
+            if logger.debug?
+              fatal{ e }
+              exit EXIT_FAILURE
+            else
+              fatal{ emsg(e) }
+              exit EXIT_FAILURE
+            end
+          else
+            exit e.status 
+          end
+        end
+        ret
+#--}}}
+      end
+      def usage port = STDERR
+#--{{{
+        port << klass::usage << "\n" if klass::usage 
+        port << klass::examples << "\n" if klass::examples
+
+        if klass::optspec 
+          port << 'OPTIONS' << "\n"
+
+          klass::optspec.each do |os| 
+            a, b, c = os
+            long, short, desc = nil
+            [a,b,c].each do |word|
+              next unless word
+              word.strip!
+              case word
+                when %r/^--[^-]/o
+                  long = word
+                when %r/^-[^-]/o
+                  short = word
+                else
+                  desc = word
+              end
+            end
+
+            spec = ((long and short) ? [long, short] : [long])
+
+            if spec
+              port << Util::columnize(spec.join(', '), :width => 80, :indent => 2)
+              port << "\n"
+            end
+
+            if desc
+              port << Util::columnize(desc, :width => 80, :indent => 8)
+              port << "\n"
+            end
+          end
+
+          port << "\n"
+        end
+
+        port
+#--}}}
+      end
+      def parse_options
+#--{{{
+        @op = OptionParser::new
+        @options = {}
+        @listoptions = Hash::new{|h,k| h[k] = []} 
+        klass::optspec.each do |spec|
+          k = spec.first.gsub(%r/(?:--)|(?:=.*$)|(?:\s+)/o,'')
+          @op.def_option(*spec) do |v| 
+            @options[k] = v
+            @listoptions[k] << v
+          end
+        end
+        #begin
+          op.parse! @argv 
+        #rescue OptionParser::InvalidOption => e
+          # preverve unknown options
+          #e.recover(argv)
+        #end
+        @options
+#--}}}
+      end
+      def init_logging
+#--{{{
+        log, log_age, log_size, verbosity = 
+          @options.values_at 'log', 'log_age', 'log_size', 'verbosity'
+        log_age = Integer log_age rescue nil
+        log_size = Integer log_size rescue nil
+        $logger = @logger = Logger::new(log || STDERR, log_age, log_size)
+      #
+      # hack to fix Logger sync bug
+      #
+        begin
+          class << @logger; attr :logdev unless @logger.respond_to?(:logdev); end
+          @logdev = @logger.logdev.dev 
+          @logdev.sync = true
+        rescue
+          nil
+        end
+        level = nil
+        verbosity ||= 'info'
+        verbosity =
+          case verbosity
+            when /^\s*(?:4|d|debug)\s*$/io
+              level = 'Logging::DEBUG'
+              4
+            when /^\s*(?:3|i|info)\s*$/io
+              level = 'Logging::INFO'
+              3
+            when /^\s*(?:2|w|warn)\s*$/io
+              level = 'Logging::WARN'
+              2
+            when /^\s*(?:1|e|error)\s*$/io
+              level = 'Logging::ERROR'
+              1
+            when /^\s*(?:0|f|fatal)\s*$/io
+              level = 'Logging::FATAL'
+              0
+            else
+              abort "illegal verbosity setting <#{ verbosity }>" 
+          end
+        @logger.level = 2 - ((verbosity % 5) - 2) 
+        @logger
+#--}}}
+      end
+      def init_config
+#--{{{
+        @config =
+          if @options['config']
+            klass::configfile::new(@options['config'])
+          else
+            klass::configfile::any klass::config_default_path, klass::config_search_path
+          end
+        @config
+#--}}}
+      end
+      def gen_template template
+#--{{{
+        klass::configfile::gen_template(template)
+        self
+#--}}}
+      end
+      def parse_argv
+#--{{{
+        klass.required_arguments.each do |arg|
+          value = @argv.shift
+          if value 
+            klass.module_eval <<-code
+              def #{ arg }(*__list)
+                if __list.empty?
+                  @#{ arg }
+                else
+                  send('#{ arg }=', *__list)
+                end
+              end
+              def #{ arg }=(__arg, *__list)
+                if __list.empty?
+                  @#{ arg } = __arg
+                else
+                  @#{ arg } = ([__arg] + __list)
+                end
+              end
+            code
+            send "#{ arg }=", value
+          else
+            die 'msg' => "required_argument <#{ arg }> not given"
+          end
+        end
+
+        klass.optional_arguments.each do |arg|
+          value = @argv.shift
+          break unless value
+          if value 
+            klass.module_eval <<-code
+              def #{ arg }(*__list)
+                if __list.empty?
+                  @#{ arg }
+                else
+                  send('#{ arg }=', *__list)
+                end
+              end
+              def #{ arg }=(__arg, *__list)
+                if __list.empty?
+                  @#{ arg } = __arg
+                else
+                  @#{ arg } = ([__arg] + __list)
+                end
+              end
+            code
+            send "#{ arg }=", value
+          end
+        end
+
+        @argv
+#--}}}
+      end
+      def main 
+#--{{{
+        warn{ "foobar" }
+        p @listoptions 
+        return EXIT_SUCCESS
+#--}}}
+      end
+      def die errno = EXIT_FAILURE
+#--{{{
+        STDERR.puts klass.usage
+        exit EXIT_FAILURE
+#--}}}
+      end
+#--}}}
+    end
+=end
+
+
+  #
+  # on-demand extensions to standard classes - (incomplete now)
+  #
+    module ModuleExtensions
+#--{{{
+      def reader_attributes(*names)
+#--{{{
+        @reader_attributes ||= []
+        unless names.empty?
+          names.flatten.each do |name|
+            @reader_attributes << "#{ name }"
+            getter = "#{ name }"
+            unless instance_methods.include? getter
+              code = <<-code
+                def #{ name }(*a)
+                  unless a.empty?
+                    self.#{ name }= a.shift 
+                  else
+                    @#{ name }
+                  end
+                end
+              code
+              module_eval code
+            end
+
+            setter = "#{ name }="
+            unless instance_methods.include? setter
+              code = <<-code
+                def #{ name }= value
+                  @#{ name } = value
+                end
+                private '#{ name }='.intern
+              code
+              module_eval code
+            end
+
+            query = "#{ name }?"
+            unless instance_methods.include? query
+              code = <<-code
+                alias #{ name }? #{ name }
+              code
+              module_eval code
+            end
+          end
+        end
+        @reader_attributes
+#--}}}
+      end
+      alias reader_attribute reader_attributes
+      def writer_attributes(*names)
+#--{{{
+        @writer_attributes ||= []
+        unless names.empty?
+          names.flatten.each do |name|
+            @writer_attributes << "#{ name }="
+            getter = "#{ name }"
+            unless instance_methods.include? getter
+              code = <<-code
+                def #{ name }(*a)
+                  unless a.empty?
+                    self.#{ name }= a.shift 
+                  else
+                    @#{ name }
+                  end
+                end
+                private '#{ name }'.intern
+              code
+              module_eval code
+            end
+
+            setter = "#{ name }="
+            unless instance_methods.include? setter
+              code = <<-code
+                def #{ name }= value
+                  @#{ name } = value
+                end
+              code
+              module_eval code
+            end
+
+            query = "#{ name }?"
+            unless instance_methods.include? query
+              code = <<-code
+                alias #{ name }? #{ name }
+                private '#{ name }?'.intern
+              code
+              module_eval code
+            end
+          end
+        end
+        @writer_attributes
+#--}}}
+      end
+      alias writer_attribute writer_attributes
+      def attributes(*names)
+#--{{{
+        reader_attributes(*names) + writer_attributes(*names)
+#--}}}
+      end
+      alias attribute attributes
+      def class_reader_attributes(*names)
+#--{{{
+        class << self; self; end.instance_eval{ reader_attributes(*names) }
+#--}}}
+      end
+      alias class_reader_attribute class_reader_attributes
+      def class_writer_attributes(*names)
+#--{{{
+        class << self; self; end.instance_eval{ writer_attributes(*names) }
+#--}}}
+      end
+      alias class_writer_attribute class_writer_attributes
+      def class_attributes(*names)
+#--{{{
+        class << self; self; end.instance_eval{ attributes(*names) }
+#--}}}
+      end
+      alias class_attribute class_attributes
+      class << self
+        def self.append_features c
+#--{{{
+          Module.extend self 
+#--}}}  
+        end
+      end
+#--}}}
+    end # module ModuleExtensions
+    module ClassExtensions;
+    end # module ClassExtensions
+    module ObjectExtensions
+    end # module ObjectExtensions
+    module StandardExtensions
+      include ModuleExtensions
+      include ClassExtensions
+      include ObjectExtensions
+    end # StandardExtensions
+
+#--}}}
+  end
+
+  Alib = ALib