constants 0.1.0

data/lib/constants/library.rb

@@ -0,0 +1,133 @@
+require 'constants/constant_library'
+
+module Constants
+
+  # Library adds methods for convenient indexing and access of constants
+  # in a module.  Usually Library is included after the constants have
+  # been defined.
+  #
+  #   module Color
+  #     RED = 'red'
+  #     GREEN = 'green'
+  #     BLUE = 'blue'
+  #     GREY = 'grey'
+  #
+  #     include Constants::Library
+  #     library.index_by('name') {|c| c }
+  #   end
+  #
+  # Now the Color constants can be accessed through the indicies hash
+  # or through [], which searches all indicies for the first match.
+  #
+  #   Color.index('name')
+  #   # => {
+  #   # 'red' => Color::RED,
+  #   # 'blue' => Color::BLUE,
+  #   # 'green' => Color::GREEN,
+  #   # 'grey' => Color::GREY}
+  #
+  #   Color['red']                  # => Color::RED
+  #
+  # Indexing is simplified for attributes.  Notice that multiple
+  # values matching the same key are stashed into one group:
+  #
+  #   Color.library.index_by_attribute 'length'
+  #   Color.index('length')
+  #   # => {
+  #   # 3 => Color::RED,
+  #   # 4 => [Color::BLUE, Color::GREY],
+  #   # 5 => Color::GREEN}
+  #
+  #   Color[4]                      # => [Color::BLUE, Color::GREY]
+  #
+  # Constants may also be assembled into ordered collections, which
+  # may or may not contain all the constants.
+  #
+  #   Color.library.collect('gstar') {|c| c =~ /^g/ ? c : nil }
+  #   Color.collection('gstar')     # => [Color::GREEN, Color::GREY]
+  #
+  #   Color.library.collect_attribute 'length'
+  #   Color.collection('length')    # => [3,5,4,4]
+  #
+  # New constants (even 'constants' that are not declared in the module) may be
+  # added manually, or by resetting the library.  All indexes and collections
+  # are updated automatically.
+  #
+  #   Color.library.add('yellow')
+  #   Color.index('length')
+  #   # => {
+  #   # 3 => Color::RED,
+  #   # 4 => [Color::BLUE, Color::GREY],
+  #   # 5 => Color::GREEN,
+  #   # 6 => 'yellow'}
+  #
+  #   module Color
+  #     ORANGE = 'orange'
+  #     reset_library
+  #   end
+  #
+  #   Color.index('length')   
+  #   # => {
+  #   # 3 => Color::RED,
+  #   # 4 => [Color::BLUE, Color::GREY],
+  #   # 5 => Color::GREEN,
+  #   # 6 => Color::ORANGE}
+  #
+  # Notice 'yellow' was removed when the library was reset.  The yellow example
+  # illustrates the fact that library only tracks the values of constants, not
+  # the constants themselves.  If, for some reason, you dynamically reset a constant
+  # value then the change will not be reflected in the library until the library
+  # is reset.
+  #
+  # ==== Ruby 1.8
+  # Ruby doesn't track of the order of constant declaration until Ruby 1.9... this
+  # may cause collected values to be re-ordered in an unpredictable fashion.  For
+  # instance in the Color example:
+  #
+  #   Color[4] # may equal [Color::BLUE, Color::GREY] or [Color::GREY, Color::BLUE].
+  #
+  # In any case, the constants will be ordered as in Color.constants.
+  #
+  # == Performance Considerations
+  # ConstantsLibrary makes access of constants easier, but at the expense of
+  # performance.  Naturally the constant itself is the highest-performing
+  # way of accessing the constant value.
+  #
+  module Library
+    
+    # Accesses the module constant library.
+    attr_accessor :library
+    
+    def self.included(mod)
+      mod.extend self
+    end
+    
+    def self.extended(mod)
+      mod.library = ConstantLibrary.new
+      mod.reset_library
+    end
+    
+    # Alias for library[identifier] (see Constants::ConstantLibrary#[])
+    def [](identifier)
+      library[identifier]
+    end
+    
+    # Returns the index by the specified name.
+    def index(name)
+      library.indicies[name]
+    end
+    
+    # Returns the collection by the specified name.
+    def collection(name)
+      library.collections[name]
+    end
+    
+    # Resets the library using constants from self.  A block
+    # can be provided to filter constants, see 
+    # Constants::ConstantLibrary#add_constants_from
+    def reset_library(&block)
+      library.clear
+      library.add_constants_from(self, &block)
+    end
+  end
+end

data/lib/constants/stash.rb

@@ -0,0 +1,94 @@
+module Constants
+  
+  # Stash provides methods to store values by a non-unique key.  The 
+  # initial stored value is directly stored by the key, subsequent 
+  # values are grouped into a StashArray.  
+  #
+  #   class StashingHash < Hash
+  #     include Constants::Stash
+  #
+  #     def initialize(*args)
+  #       super(*args)
+  #       @nil_value = nil
+  #     end
+  #   end
+  #
+  #   s = StashingHash.new
+  #
+  #   s.stash('key', 'one')
+  #   s['key']                # => 'one'
+  #  
+  #   s.stash('key', 'two')
+  #   s['key']                # => ['one' , 'two']
+  #   s['key'].class          # => Constants::Stash::StashArray
+  #
+  # The stash method requires some kind of flag to differentiate when a new
+  # value should be stored and when the existing value and new value
+  # should be converted into a StashArray.  If the existing value as 
+  # determined by [] is equal to the nil_value, then the new value is 
+  # stored through []=.
+  #
+  #  s = StashingHash.new
+  #  s['key']                # => nil    
+  #  s.nil_value             # => nil
+  #
+  #  s.stash('key', 1)
+  #  s['key']                # => 1
+  # 
+  #  s.stash('key', 2)
+  #  s['key']                # => [1, 2]
+  #
+  # In the first case, the existing value for 'key' is equals the nil_value,
+  # so the new value is set.  In the second case, the existing value for 'key' 
+  # does not equal the nil_value; stash takes this as a signal that a 
+  # non-unique key was specified and collects the values into a StashArray.
+  # As a consequence, neither the nil_value nor StashArrays may be stashed.
+  #
+  #   s.stash('key', nil)   # ! ArgumentError
+  #
+  module Stash
+    
+    # A subclass of Array with no new functionality, necessary
+    # to differentiate between regular arrays and collections
+    # in a Stash.
+    class StashArray < Array
+    end
+    
+    # The value considered to be nil in store (used to
+    # signal when a new value can be stashed for a given
+    # key; if store[key] == nil_value, then a new value
+    # can be stashed).
+    attr_accessor :nil_value
+    
+    # Assigns the value to key in store.  If the store already has a
+    # non-nil_value at key (as determined by []), then the existing 
+    # and new value will be concatenated into a StashArray.  All 
+    # subsequent values are added to the StashArray.  stash uses
+    # the []= method to set values.
+    #
+    # nil_value and StashArray values cannot be stashed; either raises 
+    # an error.
+    def stash(key, value)
+      case value
+      when nil_value
+        raise ArgumentError.new("the nil_value for self cannot be stashed")
+      when StashArray
+        raise ArgumentError.new("StashArrays cannot be stashed")
+      end
+      
+      current_value = self[key]
+      
+      case current_value
+      when nil_value
+        self[key] = value
+      when StashArray
+        current_value << value
+      else
+        self[key] = StashArray.new([current_value, value])
+      end
+      
+      self
+    end
+  end
+  
+end

data/lib/constants/uncertainty.rb

@@ -0,0 +1,8 @@
+module Constants
+  
+  # Simply defines the values for exact and unknown uncertainty.
+  module Uncertainty
+    UNKNOWN = nil
+    EXACT = 0
+  end
+end

data/test/constants/constant_library_test.rb

@@ -0,0 +1,304 @@
+require File.join(File.dirname(__FILE__), '../constants_test_helper.rb') 
+require 'constants/constant_library'
+
+class ConstantLibraryTest < Test::Unit::TestCase
+  include Constants
+
+  attr_accessor :lib
+  
+  def setup
+    @lib = ConstantLibrary.new 'one', 'two', :one
+  end
+  
+  #
+  # documentation test
+  #
+  
+  def test_documentation
+    lib = ConstantLibrary.new('one', 'two', :three)
+    lib.index_by('upcase') {|value| value.to_s.upcase }
+    assert_equal({'ONE' => 'one', 'TWO' => 'two', 'THREE' => :three}, lib.indicies['upcase'])
+  
+    lib.collect("string") {|value| value.to_s }
+    assert_equal(['one', 'two', 'three'], lib.collections['string'])
+  end
+  
+  #
+  # initialize test
+  #
+  
+  def test_initialize
+    lib = ConstantLibrary.new 
+    
+    assert_equal([], lib.values)
+    assert_equal({}, lib.indicies)
+    assert_equal({}, lib.collections)
+  end
+  
+  def test_initialize_with_values
+    assert_equal(['one', 'two', :one], lib.values)
+  end
+  
+  def test_initialize_removes_duplicate_values
+    lib = ConstantLibrary.new 'one', 'two', 'one'
+    assert_equal(['one', 'two'], lib.values)
+  end
+
+  # 
+  # index_by test
+  #
+  
+  def test_index_by_documentation
+    lib = ConstantLibrary.new('one', 'two', :one)
+    lib.index_by("string") {|value| value.to_s }
+    assert_equal({
+      'one' => ['one', :one],
+      'two' => 'two'},
+    lib.indicies['string'])
+
+    lib = ConstantLibrary.new(1,2,nil)                          
+    assert_raise(ArgumentError) { lib.index_by("error", false, nil) {|value| value } }
+
+
+    obj = Object.new
+    index = lib.index_by("ok", false, obj) {|value| value }
+    assert_equal 1, index[1]
+    assert_equal nil, index[nil]
+
+    assert_equal obj, index['non-existant']
+  end
+
+  def test_index_by_creates_a_new_index_for_the_specified_inputs
+    block = lambda {|v| }
+    lib.index_by("name", "nil", "nil_value", &block)
+    
+    assert lib.indicies.has_key?('name')
+    index = lib.indicies['name']
+    
+    assert_equal ConstantLibrary::Index, index.class
+    assert_equal "nil", index.exclusion_value
+    assert_equal "nil_value", index.nil_value
+    assert_equal block, index.block
+  end
+  
+  def test_index_by_uses_name_as_indicies_key
+    lib.index_by(:sym) {|v| v.to_s }
+    assert lib.indicies.has_key?(:sym)
+    assert !lib.indicies.has_key?('sym')
+    
+    lib.index_by('str') {|v| v.to_s }
+    assert !lib.indicies.has_key?(:str)
+    assert lib.indicies.has_key?('str')
+  end
+  
+  def test_index_stashes_values_by_block
+    lib.index_by("string") {|v| v.to_s }
+    assert_equal({'one' => ['one', :one], 'two' => 'two'}, lib.indicies["string"])
+  end
+  
+  def test_index_stashes_key_value_pairs_if_returned
+    lib.index_by("pairs") {|v| [v, v.to_s.upcase] }
+    assert_equal({'one' => 'ONE', :one => 'ONE', 'two' => 'TWO'}, lib.indicies["pairs"])
+  end
+  
+  def test_index_excludes_values_which_return_the_exclusion_value
+    lib.index_by("exclusion", nil) do |v| 
+      v.kind_of?(String) ? nil : [v, v.to_s.upcase]
+    end
+    
+    assert_equal({:one => 'ONE'}, lib.indicies["exclusion"])
+  end
+  
+  def test_index_by_default_exclusion_value_is_nil
+    lib.index_by("name") {|v|}
+    assert_equal nil, lib.indicies['name'].exclusion_value
+  end
+  
+  def test_index_by_raises_error_for_no_block_given
+    assert_raise(ArgumentError) { lib.index_by('name') }
+  end
+  
+  def test_index_by_returns_index
+    result = lib.index_by("name") {|v|}
+    assert_equal(lib.indicies['name'], result)
+  end
+  
+  # 
+  # index_by_attribute test
+  #
+  
+  def test_index_by_attribute_stashes_values_by_method_value
+    lib.index_by_attribute("to_s")
+    assert_equal({'one' => ['one', :one], 'two' => 'two'}, lib.indicies["to_s"])
+  end
+  
+  def test_index_by_attribute_returns_index
+    result = lib.index_by_attribute("object_id")
+    assert_equal(lib.indicies['object_id'], result)
+  end
+  
+  def test_index_by_attribute_raises_error_if_objects_dont_respond_to_attribute
+    assert_raise(NoMethodError) { lib.index_by_attribute("non_existant") }
+  end
+  
+  # 
+  # collect test
+  #
+  
+  def test_collect_documentation
+    lib = ConstantLibrary.new('one', 'two', :three)
+    lib.collect("string") {|value| value.to_s }
+    assert_equal ['one', 'two', 'three'], lib.collections['string'] 
+  
+    lib.collect("length") {|value| [value, value.to_s.length] }
+    assert_equal [nil, nil, nil, ['one', 'two'], nil, :three], lib.collections['length']
+  end
+  
+  def test_collect_creates_a_new_collection_for_the_specified_inputs
+    block = lambda {|v| }
+    lib.collect("name", &block)
+    
+    assert lib.collections.has_key?('name')
+    collection = lib.collections['name']
+    
+    assert_equal ConstantLibrary::Collection, collection.class
+    assert_equal nil, collection.nil_value
+    assert_equal block, collection.block
+  end
+
+  def test_collect_uses_name_as_collections_key
+    lib.collect(:sym) {|v| v.to_s }
+    assert lib.collections.has_key?(:sym)
+    assert !lib.collections.has_key?('sym')
+    
+    lib.collect('str') {|v| v.to_s }
+    assert !lib.collections.has_key?(:str)
+    assert lib.collections.has_key?('str')
+  end
+  
+  def test_collection_stashes_block_value
+    lib.collect("string") {|v| v.to_s }
+    assert_equal(['one', 'two', 'one'], lib.collections["string"])
+  end
+
+  def test_collection_stashes_values_index_pairs_if_returned
+    map = {'one' => 2, 'two' => 0}
+
+    lib.collect("pairs") {|v| [v, map[v.to_s]] }
+    assert_equal(['two', nil, ['one', :one]], lib.collections["pairs"])
+  end
+
+  def test_collection_excludes_values_which_return_nil
+    lib.collect("exclusion") do |v| 
+      v.kind_of?(String) ? nil : v
+    end
+    assert_equal([:one], lib.collections["exclusion"])
+  end
+
+  def test_collect_raises_error_for_no_block_given
+    assert_raise(ArgumentError) { lib.collect('name') }
+  end
+
+  def test_collect_returns_collection
+    result = lib.collect("name") {|v|}
+    assert_equal(lib.collections['name'], result)
+  end
+  
+  # 
+  # collect_attribute test
+  #
+  
+  def test_collect_attribute_collects_attribute_values
+    lib.collect_attribute("to_s")
+    assert_equal(['one', 'two', 'one'], lib.collections["to_s"])
+  end
+
+  #
+  # [] test
+  #
+ 
+  def test_get_searches_all_indicies_match
+    lib.index_by("string") {|v| v.to_s }
+    lib.index_by("strlen") {|v| v.to_s.length }
+    
+    assert_equal ['one', :one], lib['one']
+    assert_equal ['one', 'two', :one], lib[3]
+  end
+  
+  def test_get_returns_nil_if_no_matches_are_found
+    assert_equal nil, lib['three']
+  end
+  
+  def test_get_returns_first_match_only
+    lib.index_by("str1") {|v| v.to_s }
+    lib.index_by("str2") {|v| [v.to_s, v.to_s.upcase] }
+    
+    assert lib.indicies['str1'].has_key?('one')
+    assert lib.indicies['str2'].has_key?('one')
+    
+    assert_not_equal lib.indicies['str1']['one'], lib.indicies['str2']['one']
+    assert_equal lib.indicies['str1']['one'], lib['one']
+  end
+  
+  #
+  # clear test
+  #
+  
+  def test_clear_clears_all_values_from_lib_indicies_and_collections
+    lib.index_by("str") {|v| v.to_s }
+    lib.collect("str") {|v| v.to_s }
+    
+    assert !lib.values.empty?
+    assert !lib.indicies['str'].empty?
+    assert !lib.collections['str'].empty?
+    
+    lib.clear
+    
+    assert lib.values.empty?
+    assert lib.indicies['str'].empty?
+    assert lib.collections['str'].empty?
+  end
+  
+  def test_clear_only_removes_indicies_and_collections_if_specified
+    lib.index_by("str") {|v| v.to_s }
+    lib.collect("str") {|v| v.to_s }
+    
+    lib.clear
+    
+    assert !lib.indicies.empty?
+    assert !lib.collections.empty?
+    
+    lib.clear(true)
+    
+    assert lib.indicies.empty?
+    assert lib.collections.empty?
+  end
+  
+  #
+  # add test
+  #
+  
+  def test_add_adds_new_values
+    lib.add(:two, 'three')
+    assert_equal ['one', 'two', :one, :two, 'three'], lib.values
+  end
+  
+  def test_add_does_not_add_duplicate_values
+    lib.add(:one, :two, 'two', 'three')
+    assert_equal ['one', 'two', :one, :two, 'three'], lib.values
+  end
+  
+  def test_add_returns_newly_added_values
+    assert_equal [:two, 'three'], lib.add(:one, :two, 'two', 'three')
+  end
+  
+  def test_add_incorporates_new_values_into_existing_indicies_and_collections
+    lib.index_by("str") {|v| v.to_s }
+    lib.collect("length") {|v| [v, v.to_s.length] }
+    
+    lib.add(:one, :two, 'two', 'three')
+    assert_equal({'one' => ['one', :one], 'two' => ['two', :two], 'three' => 'three'}, lib.indicies['str'])
+    assert_equal([nil,nil,nil,['one', 'two', :one, :two], nil, 'three'], lib.collections['length'])
+  end
+  
+end