eymiha_util 0.1.6 → 1.0.0

data/lib/eymiha/util/envelope.rb

@@ -0,0 +1,130 @@
+# Envelopes are useful when finding the boundaries of a set of instances.
+# They expand as new values are added, and keep track of how many items
+# have been added to construct them.
+
+module Eymiha
+
+  # An EnvelopeException is generally raised when adding an object to an
+  # instance that it does not know how to interpret, or when requesting
+  # bounderies before any values have been added.
+  class EnvelopeException < Exception
+  end
+
+
+  # A BaseEnvelope provides a means to keep and provide a count of objects
+  # that have been added to an envelope.
+  class BaseEnvelope
+
+    # Called when requesting envelope bounderies before any values have been
+    # added.
+    def raise_no_envelope
+      raise EnvelopeException, "No values are enveloped"
+    end
+    
+    # Called when the value cannot be compared with the the boundaries of the
+    # instance.
+    def raise_no_compare(value=nil)
+      value = "'#{value}' " unless value == nil
+      raise EnvelopeException,
+      "The value #{value}cannot be compared with the envelope"
+    end
+    
+    # count of added values reader.
+    attr_reader :count
+    
+    # Returns a new instance with no values added.
+    def initialize
+      @count = 0
+    end
+    
+  end
+  
+  
+  # An Envelope is the minimum envelope that will completely contain a set of
+  # values. Values may be added to an instance, and it can return the number
+  # of values considered so far and its high and low boundaries.
+  #
+  # Envelopes can be used to generate ranges, however the result may be of
+  # limited utility if the types of values being enveloped don't play nicely
+  # with ranges.
+  class Envelope < BaseEnvelope
+    
+    # Creates and returns an instance. If an argument is given, it is passed
+    # to the set method to initialize the new instance.
+    def initialize(value=nil)
+      super()
+      add(value) unless value == nil
+    end
+    
+    # Returns a string representation of the instance.
+    def to_s
+      values = (count > 0)? "\n  high  #{high}\n  low   #{low}" : ""
+      "Envelope: count #{count}#{values}"
+    end
+    
+    # Adds a value to the instance. When
+    # * x is an Envelope, it is coalesced into the instance.
+    # * otherwise, the envelope is extened to contain the value.
+    # * if the value cannot be compared to the boundaries, an EnvelopeException is raised.
+    # The modified instance is returned.
+    def add(value)
+      if value.kind_of? Envelope
+        count = value.count
+        if (count > 0)
+          add value.high
+          add value.low
+          @count += (count-2)
+        end
+        self
+      else
+        begin
+          @high = value if (@count == 0 || value > @high)
+          @low = value if (@count == 0 || value < @low)
+          @count += 1
+          self
+        rescue
+          raise_no_compare value
+        end
+      end
+    end
+    
+    # Returns the high boundary of the instance.
+    # * if there are no boundaries, an EnvelopeException is raised.
+    def high
+      raise_no_envelope if @count == 0
+      @high
+    end
+    
+    # Returns the low boundary of the instance.
+    # * if there are no boundaries, an EnvelopeException is raised.
+    def low 
+      raise_no_envelope if @count == 0
+      @low
+    end
+    
+    # Returns true if the instance completely contains the argument:
+    # * value is an Envelope, its high and low are contained.
+    # * otherwise, the value is contained.
+    # * if the value cannot be compared to the boundaries, an EnvelopeException is raised.
+    def contains?(value)
+      if value.kind_of? Envelope
+        (contains? value.high) && (contains? value.low)
+      else
+        begin
+          (value >= low) && (value <= high)
+        rescue
+          raise_no_compare value
+        end
+      end
+    end
+    
+    alias === contains?
+    
+    # Returns an inclusive range from the low to high boundaries
+    def to_range
+      low..high
+    end
+    
+  end
+  
+end

data/lib/eymiha/util/forward_referencing.rb

@@ -0,0 +1,161 @@
+# Forward referencing is one of those painful problems in programming - if
+# you try to use something before it's defined, trouble ensues. Using the
+# ForwardReferencing module and the ForwardReference class can let you
+# gracefully recover from problems caused by forward references in data and
+# processing.
+
+require 'eymiha'
+
+module Eymiha
+
+  # The ForwardReferencing module can be mixed into a class to allow it to
+  # capture and resolve ForwardReferences.
+  module ForwardReferencing
+    
+    # An array containing the set of unresolved forward references.
+    attr_reader :forward_references
+    
+    # To be called from the initializer of the includer, this sets up the forward
+    # reference capture and resolution mechanisms.
+    def start_forward_referencing
+      forward_references_clear
+      @had_forward_reference_resolution = false
+      @forward_reference_resolver = nil
+    end
+    
+    # To be called when a section of code that could contain a forward reference
+    # is entered. The method returns a newly created ForwardReference with the
+    # given dependency that can be jumped to during resolution.
+    def create_forward_reference(dependency=nil,context=nil)
+      forward_reference = ForwardReference.new(dependency,context)
+      @forward_references << forward_reference
+      forward_reference
+    end
+    
+    # To be called when a section of code that could contain a forward reference
+    # has successfully been reached. It is used to remove the ForwardReference
+    # that was created at the start of the section, and asserts that a
+    # resolution was made.
+    def remove_forward_reference(forward_reference=nil)
+      @forward_references.delete forward_reference if
+        (forward_reference.kind_of? ForwardReference)
+      @had_forward_reference_resolution = true
+    end
+    
+    # To be called to try to resolve any unresolved ForwardReferences by jumping
+    # to each in turn and retrying the code that caused it. This method repeats
+    # until nothing more is resolved. At that point unresolved forward reference
+    # may still exist, to be possibly resolved by another call to this method
+    # downstream. Prior to continuing to a forward reference, the
+    # establish_forward_reference context method is called with the context that
+    # was provided at the time the forward reference was created to give the
+    # receiver a chance to reset any transcient infromation.
+    def resolve_forward_references
+      forward_references = @forward_references
+      forward_references_clear
+      @had_forward_reference_resolution = false
+      if forward_references.size > 0
+        @forward_reference_resolver ||= callcc {|cont| cont} while
+          (@forward_reference_resolver == nil)
+        forward_reference = forward_references.shift
+        if forward_reference != nil
+          establish_forward_reference_context(forward_reference.context) if
+            respond_to?(:establish_forward_reference_context,true)
+          forward_reference.continuation.call
+        end
+      end
+      @forward_reference_resolver = nil
+      resolve_forward_references if @had_forward_reference_resolution
+    end
+    
+    # To be called at the end of a section of code that could contain a forward
+    # reference, it will continue during normal processing and jump back to the
+    # resolve_forward_references method during resolution.
+    def continue_forward_reference_resolution
+      @forward_reference_resolver.call if @forward_reference_resolver
+    end
+    
+    # Returns a hash of dependencies to arrays of the ForwardReferences that
+    # have them as dependencies.
+    def forward_reference_dependencies
+      dependencies = {}
+      @forward_references.each { |forward_reference|
+        dependency = forward_reference.dependency || "nil"
+        forward_references = dependencies[dependency]
+        dependencies[dependency] = [] if forward_references == nil
+        dependencies[dependency] << forward_reference
+      }
+      dependencies
+    end
+    
+    # Returns a string indicating the current state of ForwardReferencing.
+    def forward_references_to_s
+      "#{class_name}  #{forward_references_remaining} unresolved"
+    end
+    
+    # Returns the number of unresolved forward references.
+    def forward_references_remaining
+      @forward_references.size
+    end
+    
+    # Remove the remaining unresolved forward references.
+    def forward_references_clear
+      @forward_references = []
+    end
+    
+  end
+  
+  
+  # A ForwardReferencer is simply a class-wrapper for the ForwardReferencing
+  # module. method have been shortened there is reduced potential for conflict
+  # from inheritence than from inclusion or extension.
+  class ForwardReferencer
+    
+    include ForwardReferencing
+    
+    alias initialize   start_forward_referencing
+    alias create       create_forward_reference
+    alias remove       remove_forward_reference
+    alias resolve      resolve_forward_references
+    alias continue     continue_forward_reference_resolution
+    alias dependencies forward_reference_dependencies
+    alias to_s         forward_references_to_s
+    alias remaining    forward_references_remaining
+    alias clear	     forward_references_clear
+    
+  end
+
+
+  # A ForwardReference holds a continuation and a dependency, the where and
+  # the why of forward referencing.
+  class ForwardReference
+    
+    # Holds the place to jump back to for attempting to resolve a forward
+    # reference.
+    attr_reader :continuation
+    
+    # Holds an arbitrary object that indicates why the forward reference
+    # occurred.
+    attr_accessor :dependency
+    
+    # Holds an arbitrary object that holds context that can be re-established
+    # to help resolve the forward reference.
+    attr_accessor :context
+    
+    # Returns a new instance with a valid continuation, the given dependency
+    # and contextual information.
+    def initialize(dependency=nil,context=nil)
+      @continuation = nil
+      @continuation = callcc{|cont| cont} while (@continuation == nil)
+      @dependency = dependency
+      @context = context
+    end
+    
+    # Returns a string indicating the current state of the ForwardReference.
+    def to_s
+      "#{class_name}  dependency #{dependency}  #{continuation}"
+    end
+    
+  end
+  
+end

data/lib/eymiha/util/histogram.rb

@@ -0,0 +1,112 @@
+# Histograms have lots of uses - whenever you need to keep track of the
+# occurences of items and how many times they've occured, a histogram is
+# just what's needed.
+
+module Eymiha
+
+  # An exception thrown when adding Arrays to Histograms that cannot be
+  # meaningfully interpretted.
+  class HistogramException < Exception
+  end
+
+
+  # A Histogram is a hash whose values are counts of the occurences of the keys.
+  class Histogram < Hash
+    
+    # Creates and returns an instance. If arguments are given, they are passed to
+    # the add method to initialize the new instance.
+    def initialize(key=nil,number=1)
+      super()
+      add(key,number) unless key == nil
+    end
+    
+    # Returns the number of occurences of the given key. If an array of keys
+    # is given, the sum of the number of occurences of those keys is returned.
+    def count(check_keys = keys)
+      check_keys = [check_keys] if ! check_keys.kind_of? Array
+      count = 0
+      check_keys.each { |key| count += self[key] if has_key? key }
+      count
+    end
+    
+    # Adds the key to the instance if it doesn't already exist, and adds the
+    # specified count to it value. If the key is
+    # * an Array, each member of the array is added. if the member itself is an Array, then if that array has one member, the member is added as a key; if two members, the member is added as a key and a count; otherwise, a HistogramException is thrown.
+    # * another histogram, the keys and counts in the key are added to the instance.
+    def add(key,count=1)
+      if key.kind_of? Array
+        key.each { |member|
+          if member.kind_of? Array
+            if member.size == 1
+              add(member[0])
+            elsif (member.size == 2) && (member[1].kind_of? Fixnum)
+              add(member[0],member[1])
+            else
+              raise HistogramException, "add cannot interpret Array to add"
+            end
+          else
+            add member
+          end
+        }
+      elsif key.kind_of? Histogram
+        key.each_pair { |k,v| add(k,v) }
+      else
+        self[key] = ((value = self[key]) == nil) ? count : value+count
+      end
+      self
+    end
+    
+    # Returns the number of keys in the instance.
+    def key_count
+      keys.size
+    end
+    
+    # Returns a new Histogram containing the elements with occurences greater
+    # than or equal to the given count.
+    def >=(count)
+      result = Histogram.new
+      each_pair { |k,v| result.add(k,v) if v >= count }
+      result
+    end
+    
+    # Returns a new Histogram containing the elements with occurences greater
+    # than the given count.
+    def >(count)
+      result = Histogram.new
+      each_pair { |k,v| result.add(k,v) if v > count }
+      result
+    end
+    
+    # Returns a new Histogram containing the elements with occurences less than
+    # or equal to the given count.
+    def <=(count)
+      result = Histogram.new
+      each_pair { |k,v| result.add(k,v) if v <= count }
+      result
+    end
+    
+    # Returns a new Histogram containing the elements with occurences less than
+    # the given count.
+    def <(count)
+      result = Histogram.new
+      each_pair { |k,v| result.add(k,v) if v < count }
+      result
+    end
+    
+    # If count is a number, a new Histogram containing the elements with
+    # occurences equal to the given countis returned. If the count is a
+    # histogram, true is returned if the instance contains the same keys and
+    # values; false otherwise.
+    def ==(count)
+      if count.kind_of? Numeric
+        result = Histogram.new
+        each_pair { |k,v| result.add(k,v) if v >= count }
+        result
+      else
+        super
+      end
+    end
+    
+  end
+  
+end

data/lib/eymiha/util/methodic_hash.rb

@@ -0,0 +1,70 @@
+module Eymiha
+  
+  # The MethodicHash is some method_missing magic that uses method names as hash
+  # keys, so hash assignment and lookup appear to be attribute writing and
+  # reading. For instance, if
+  #
+  #   mh = MethodicHash.new
+  #   mh['four']  = 'iv'
+  #   mh[:seven]  = 'vii'
+  #   mh.eighteen = 'xviii'
+  #
+  # then
+  #
+  #   mh['four']     ---> 'iv'
+  #   mh[:four]      ---> 'iv'
+  #   mh.four        ---> 'iv'
+  #   mh['seven']    ---> 'vii'
+  #   mh[:seven]     ---> 'vii'
+  #   mh.seven       ---> 'vii'
+  #   mh['eighteen'] ---> 'xviii'
+  #   mh[:eighteen]  ---> 'xviii'
+  #   mh.eighteen    ---> 'xviii'
+  #
+  # This allows access to simply declared facts to be embedded in Ruby code and
+  # leverages the possibility of hashing procs.
+  #
+  # Note that if the hash uses anything but strings or symbols as keys, the
+  # magic stands a good chance of failing, raising an error or acting in a
+  # bizarre manner. Note also that methods of the Hash cannot be used as
+  # 'attribute' names.
+  class MethodicHash < Hash
+    
+    # Try to look up using a key directly, or if that fails as a string, or as
+    # a symbol as last resort. If a symbol conversion doesn't exists, rescue
+    # with a nil.
+    def [](key)
+      begin
+        super(key) || super(key.to_s) || super(key.to_sym)
+      rescue
+        nil
+      end
+    end
+    
+    # Deletes and returns the key-value pairs from hash whose keys are equal to
+    # key.to_s or key.to_sym. If both key.to_s and key.to_sym are in the hash,
+    # then both values are returned in an Array, respectively. If neither key is
+    # found, the delete is deferred to the Hash.
+    def delete(key,&block)
+      values = [key.to_s, key.to_sym].collect {|k| super(k){ nil } }.compact
+      case values.size
+      when 0 then super(key,&block)
+      when 1 then values[0]
+      when 2 then values
+      end
+    end
+    
+    # A missing method is assummed to be the assignment of a value of a key, or
+    # the lookup of a value with a key.
+    def method_missing(method,*args)
+      string = method.to_s
+      if string[string.length-1,1] == '='
+        self[string[0,string.length-1].to_sym] = args[0]
+      else
+        self[method]
+      end
+    end
+    
+  end
+  
+end