bahuvrihi-constants 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2006-2008, Regents of the University of Colorado.
+Developer:: Simon Chiang, Biomolecular Structure Program
+Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,125 @@
+= Constants
+
+Libraries of physical and chemical constants for scientific calculations in Ruby.
+
+== Description
+
+Constants provides libraries of constant values such as the precise mass of carbon 13, or 
+the spin of a strange quark.  When applicable, the constant values include uncertainty and
+units (via {ruby-units}[http://rubyforge.org/projects/ruby-units]).  Also provides 
+Constants::Library to index and generate common collections of constant values.
+
+I have attempted to use reputable sources for the constants data (see below).  Please notify 
+me of any errors and send me suggestions for other constants to include.
+
+* Rubyforge[http://rubyforge.org/projects/bioactive]
+* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/13504-constants/overview]
+* Github[http://github.com/bahuvrihi/constants/tree/master]
+
+== Usage
+
+  require 'constants'
+  include Constants::Libraries
+  
+  # Element predefines all chemical elements
+  c = Element::C
+  c.name                 # => "Carbon"
+  c.symbol               # => "C"
+  c.atomic_number        # => 6
+  c.mass                 # => 12.0
+  c.mass(13)             # => 13.0033548378
+  
+  # A smorgasbord of lookups methods
+  Element['Carbon']      # => Element::C
+  Element['C']           # => Element::C
+  Element[6]             # => Element::C
+
+=== Custom Libraries
+
+Making a new constants library is straightforward using the Constants::Library module.
+The following example is adapted from the molecule[http://github.com/bahuvrihi/molecules/tree/master]
+library (a subproject of constants).
+
+  # A library of amino acid residues.
+  class Residue
+    attr_reader :letter, :abbr, :name
+
+    def initialize(letter, abbr, name)
+      @letter = letter
+      @abbr = abbr
+      @name = name
+    end
+
+    A = Residue.new('A', "Ala", "Alanine")
+    C = Residue.new('C', "Cys", "Cysteine")
+    D = Residue.new('D', "Asp", "Aspartic Acid")
+    # ... normally you'd add the rest here ...
+
+    include Constants::Library
+
+    # add an index by an attribute or method
+    library.index_by_attribute :letter
+
+    # add an index where keys are calculated by a block
+    library.index_by 'upcase abbr' do |residue|
+      residue.abbr.upcase
+    end
+    
+    # add a collection (same basic idea, but using an array)
+    library.collect_attribute 'name'
+  end
+
+  # index access through []
+  Residue['D']                   # => Residue::D
+  Residue['ALA']                 # => Residue::A
+
+  # access an index hash or collection array
+  Residue.index('upcase abbr')   # => {'ALA' => Residue::A, 'CYS' => Residue::C, 'ASP' => Residue::D}
+  Residue.collection('name')     # => ["Alanine", "Cysteine", "Aspartic Acid"]
+
+As you can see, Constants::Library allows the predefinition of common views generated
+for a set of constants.  Nothing you couldn't do yourself, but very handy.
+
+== Known Issues
+
+* Particle data is from an unreliable source
+* Constants::Constant could use some development; constants should support mathematical 
+  operations and comparisons based on uncertainty as well as value.
+* Ruby doesn't track of the order of constant declaration until Ruby 1.9.  Constants
+  are indexed/collected as they appear in [module].constants
+
+== Installation
+
+Constants is available as a gem through RubyForge[http://rubyforge.org/projects/bioactive].  Use:
+
+  % gem install constants
+
+== Info 
+
+Copyright (c) 2006-2008, Regents of the University of Colorado.
+Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com], {Biomolecular Structure Program}[http://biomol.uchsc.edu/], {Hansen Lab}[http://hsc-proteomics.uchsc.edu/hansenlab/] 
+Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
+Licence:: MIT-Style
+
+=== Element Data
+
+Element isotope, mass, and abundance information was obtained from the NIST {Atomic Weights and Isotopic Compositions}[http://www.physics.nist.gov/PhysRefData/Compositions/index.html] reference.  All isotopes 
+with a non-nil isotopic composition (ie relative abundance) were compiled from this {view}[http://www.physics.nist.gov/cgi-bin/Compositions/stand_alone.pl?ele=&all=all&ascii=ascii2&isotype=all] 
+on 2008-01-22. 
+
+=== Physical Constant Data
+
+The physical constant data is assembled from the NIST {Fundamental Physical Constants}[http://www.physics.nist.gov/cuu/Constants/Table/allascii.txt]
+on 2008-04-28.
+
+Constants adds several units to ruby-units to support the physical constants 
+reported in the NIST data.  These are (as reported in the NIST data):
+
+electron-volt:: 1.602176487e-19 joules
+kelvin:: 1.3806504e-23 joules
+hartree:: 4.35974394e-18 joules
+
+=== Particle Data
+
+Particle data was assembled from a non-ideal source, wikipedia[http://www.wikipedia.org/], and will remain
+so until I have time to update it with something better.

data/Rakefile

@@ -0,0 +1,171 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'yaml'
+
+# tasks
+desc 'Default: Run tests.'
+task :default => :test
+
+desc 'Run tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = File.join('test', ENV['subset'] || '', ENV['pattern'] || '**/*_test.rb')
+  t.verbose = true
+end
+
+#
+# admin tasks
+#
+
+def gemspec
+  data = File.read('constants.gemspec')
+  spec = nil
+  Thread.new { spec = eval("$SAFE = 3\n#{data}") }.join
+  spec
+end
+
+Rake::GemPackageTask.new(gemspec) do |pkg|
+  pkg.need_tar = true
+end
+
+task :print_manifest do
+  # collect files from the gemspec, labeling 
+  # with true or false corresponding to the
+  # file existing or not
+  files = gemspec.files.inject({}) do |files, file|
+    files[File.expand_path(file)] = [File.exists?(file), file]
+    files
+  end
+  
+  # gather non-rdoc/pkg files for the project
+  # and add to the files list if they are not
+  # included already (marking by the absence
+  # of a label)
+  Dir.glob("**/*").each do |file|
+    next if file =~ /^(rdoc|pkg)/ || File.directory?(file)
+    
+    path = File.expand_path(file)
+    files[path] = ["", file] unless files.has_key?(path)
+  end
+  
+  # sort and output the results
+  files.values.sort_by {|exists, file| file }.each do |entry| 
+    puts "%-5s : %s" % entry
+  end
+end
+
+desc 'Generate documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'constants' 
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include(["README", 'MIT-LICENSE'])
+  rdoc.rdoc_files.include(gemspec.files.select {|file| file =~ /^lib/})
+end
+
+desc "Publish RDoc to RubyForge"
+task :publish_rdoc => [:rdoc] do
+  config = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
+  host = "#{config["username"]}@rubyforge.org"
+  
+  rsync_args = "-v -c -r"
+  remote_dir = "/var/www/gforge-projects/bioactive/constants"
+  local_dir = "rdoc"
+ 
+  sh %{rsync #{rsync_args} #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+#
+# constants tasks
+#
+
+desc "Regenerate physical constants and relationship data"
+task :generate_constants do
+  require 'open-uri'
+
+  nist_url = "http://www.physics.nist.gov/cuu/Constants/Table/allascii.txt"
+  nist_data = open(nist_url)
+  
+  split_regexp = /^(.+?\s\s)(\d[\de\-\s\.]*?\s\s\s*)(\d[\de\-\s\.]*?\s\s\s*)(.*)$/
+  split_regexp_str = nil
+  
+  constants = []
+  declarations = []
+  units = []
+
+  nist_data.each_line do |line|
+    next if line =~ /^(\s|-)/
+    
+    unless line =~ split_regexp
+      raise "could not match line:\n#{line}\nwith: #{split_regexp_str}" 
+    end
+    
+    if split_regexp_str == nil
+      split_regexp_str = "^(.{#{$1.length}})(.{#{$2.length}})(.{#{$3.length}})(.*)$"
+      split_regexp = Regexp.new(split_regexp_str)
+      redo
+    end
+    
+    name = $1
+    value = $2
+    uncertainty = $3
+    unit = $4
+    constant = name.split(/[\s\-]/).collect do |word| 
+      word = word.gsub(/\./, "")
+      word = word.gsub("/", "_")
+      
+      word =~ /^[A-z\d]+$/ ? word.upcase : nil
+    end.compact.join("_")
+    
+    if constants.include?(constant)
+      raise "constant name conflict: #{constant}" 
+    end
+    
+    constants << constant
+    type = (constant =~ /_RELATIONSHIP$/ ? units : declarations) 
+    type << [constant, name.strip, value.gsub(/\s/, ""), uncertainty.gsub(/\s/, "").gsub("(exact)", "0"), unit.strip]
+  end
+  
+  puts "# Constants from: #{nist_url}"
+  puts "# Date: #{Time.now.to_s}"
+  
+  max = declarations.inject(0) {|max, c| c.first.length > max ? c.first.length : max}
+  declarations.each do |declaration|
+    puts %Q{%-#{max}s = Physical.new("%s", "%s", "%s", "%s")} % declaration
+  end
+  
+  puts
+  puts "# Relationships from: #{nist_url}"
+  puts "# Date: #{Time.now.to_s}"
+  
+  require 'ruby-units'
+  base_units = Unit.class_eval('@@BASE_UNITS').collect {|u| u[1..-2] }
+  unit_map = Unit.class_eval('@@UNIT_MAP')
+  units = units.collect do |constant, name, value, uncertainty, unit|
+    
+    # parse the relationship units
+    unit_name, relation_name = name.strip.chomp('relationship').split('-', 2).collect do |str| 
+      str.strip!
+      case str
+      when 'atomic mass unit' then 'amu'
+      else str.gsub(/\s/, "-")
+      end
+    end
+    
+    # format constants to sort in the correct declaration order
+    constant = constant.chomp('_RELATIONSHIP')
+    [constant, unit_name, relation_name, value, unit, uncertainty]
+  end
+  
+  max = units.inject(0) {|max, c| c.first.length > max ? c.first.length : max}
+  units.each do |declaration|
+    puts %Q{%-#{max}s = ['%s', '%s', '%s', '%s', '%s']} % declaration
+  end
+end
+
+# desc "Regenerate elements data"
+# task :generate_elements do
+#   
+# end

data/lib/constants.rb

@@ -0,0 +1,5 @@
+$: << File.dirname(__FILE__)
+
+require 'constants/libraries/element'
+require 'constants/libraries/physical'
+require 'constants/libraries/particle'

data/lib/constants/constant.rb

@@ -0,0 +1,94 @@
+require 'constants/uncertainty'
+require 'constants/library'
+require 'rubygems'
+require 'ruby-units'
+
+# Adds several units to {ruby-units}[http://rubyforge.org/projects/ruby-units] for use
+# in reporting physical constant data.  See the README.
+class Unit < Numeric
+  
+  # Relationships from: http://www.physics.nist.gov/cuu/Constants/Table/allascii.txt
+  # Date: Mon Apr 28 21:09:29 -0600 2008
+  # ELECTRON_VOLT_JOULE            = ['electron-volt', 'joule', '1.602176487e-19', 'J', '0.000000040e-19']
+  # KELVIN_JOULE                   = ['kelvin',        'joule', '1.3806504e-23',   'J', '0.0000024e-23']
+  # HARTREE_JOULE                  = ['hartree',       'joule', '4.35974394e-18',  'J', '0.00000022e-18']
+  
+  UNIT_DEFINITIONS['<electron-volt>'] = [%w{eV}, 1.602176487e-19, :energy, %w{<meter> <meter> <kilogram>}, %w{<second> <second>}]
+  UNIT_DEFINITIONS['<kelvin>'] = [%w{K}, 1.3806504e-23, :energy, %w{<meter> <meter> <kilogram>}, %w{<second> <second>}]
+  UNIT_DEFINITIONS['<hartree>'] = [%w{E_h}, 4.35974394e-18, :energy, %w{<meter> <meter> <kilogram>}, %w{<second> <second>}]
+end
+Unit.setup
+
+module Constants
+  
+  # Constant tracks the value, uncertainty, and unit of measurement for a
+  # measured quantity.  Units are tracked via {ruby-units}[http://rubyforge.org/projects/ruby-units].
+  class Constant 
+    include Comparable
+
+    class << self
+
+      # Parses the common notation '<value>(<uncertainty>)' into a value and
+      # an uncertainty. When no uncertainty is specified, the uncertainty is nil.  
+      # Whitespace is allowed.
+      #
+      #  Base.parse("1.0(2)").vu                    # => [1.0, 0.2]
+      #  Base.parse("1.007 825 032 1(4)").vu        # => [1.0078250321, 1/2500000000]
+      #  Base.parse("6.626 068 96").vu              # => [6.62606896, nil]
+      #
+      def parse(str)
+        str = str.to_s.gsub(/\s/, '')
+        raise "cannot parse: #{str}" unless str =~ /^(-?\d+)(\.\d+)?(\(\d+\))?(e-?\d+)?(.*)$/
+
+        value = "#{$1}#{$2}#{$4}".to_f
+        unit = $5
+        uncertainty = case
+        when $3 == nil then nil
+        else
+          factor = $2 == nil ? 0 : 1 - $2.length
+          factor += $4[1..-1].to_i unless $4 == nil
+          $3[1..-2].to_i * 10 ** factor
+        end
+
+        block_given? ? yield(value, unit, uncertainty) : new(value, unit, uncertainty)
+      end
+    end
+    
+    # The measured value of the constant
+    attr_reader :value
+    
+    # The uncertainty of the measured value.  May be exact or unknown,
+    # represented by Uncertainty::EXACT (0) and Uncertainty::UNKNOWN 
+    # (nil) respectively.
+    attr_reader :uncertainty
+    
+    # The units of the measured value, may be nil for unitless constants
+    attr_reader :unit
+
+    def initialize(value, unit=nil, uncertainty=Uncertainty::UNKNOWN)
+      @value = value
+      @unit = unit.to_s.strip.empty? ? nil : Unit.new(unit)
+      @uncertainty = uncertainty
+    end
+    
+    # For Numeric inputs, compares value to another.  For all other inputs,
+    # peforms the default == comparison.
+    def ==(another)
+      case another
+      when Numeric then value == another
+      else super(another)
+      end
+    end
+    
+    # Compares the value of another to the value of self.
+    def <=>(another)
+      value <=> another.value
+    end
+    
+    # Returns the array: [value, uncertainty]
+    def to_a
+      [value, uncertainty]
+    end
+  end
+
+end

data/lib/constants/constant_library.rb

@@ -0,0 +1,299 @@
+require 'constants/stash'
+
+module Constants
+
+  # ConstantLibrary facilitates indexing and collection of a set of values.
+  #
+  #   lib = ConstantLibrary.new('one', 'two', :three)
+  #   lib.index_by('upcase') {|value| value.to_s.upcase }
+  #   lib.indicies['upcase']      # => {'ONE' => 'one', 'TWO' => 'two', 'THREE' => :three}
+  #
+  #   lib.collect("string") {|value| value.to_s }
+  #   lib.collections['string']   # => ['one', 'two', 'three']
+  #
+  # See Constants::Library for more details.
+  class ConstantLibrary
+    
+    # A hash-based Stash to index library objects.
+    class Index < Hash
+      include Constants::Stash
+      
+      # The block used to calculate keys during stash
+      attr_reader :block
+      
+      # Indicates when values are skipped during stash
+      attr_reader :exclusion_value
+      
+      # Initializes a new Index (a type of Hash).  
+      #
+      # The block is used by stash to calculate the key for 
+      # stashing a given value.  If the key equals the exclusion 
+      # value, then the value is skipped.  The new index will
+      # return nil_value for unknown keys (ie it is the default
+      # value for self) and CANNOT be stashed (see Stash). 
+      def initialize(exclusion_value=nil, nil_value=nil, &block)
+        super(nil_value, &nil)
+        @nil_value = nil_value
+        @exclusion_value = exclusion_value
+        @block = block
+      end
+
+      # Stashes the specified values using keys calculated 
+      # by the block.  Skips values when the block returns 
+      # the exclusion value.  
+      #
+      # See Constants::ConstantLibrary#index_by for more details.
+      def stash(values)
+        values.each_with_index do |value, index| 
+          result = block.call(value)
+          
+          case result
+          when exclusion_value then next
+          when Array then super(*result)
+          else super(result, value)
+          end
+        end
+        
+        self
+      end
+    end
+    
+    # An array-based Stash for collections of library objects.
+    #
+    #-- 
+    # Note: comparison of Index and Collection indicates that
+    # these are highly related classes.  Why no exclusion value
+    # and why no modifiable nil_value for Collection?  Simply
+    # because an array ALWAYS returns nil for uninitialized
+    # locations (esp out-of-bounds locations).  This means that
+    # Stash, which uses the value at self[] to determine when
+    # to stash and when not to stash, must have nil as it's
+    # nil_value to behave correctly.  Effectively treating
+    # nil as an exclusion value for collection works well in
+    # this case since nils cannot be stashed.
+    #
+    # Hashes (ie Index) do not share this behavior.  Since you
+    # can define a default value for missing keys, self[] can
+    # return something other than nil... hence there is an 
+    # opportunity to use non-nil nil_values and non-nil 
+    # exclusion values.
+    class Collection < Array
+      include Constants::Stash
+      
+      # The block used to calculate keys during stash
+      attr_reader :block
+
+      # Initializes a new Collection (a type of Array).  The block is 
+      # used by stash to calculate the values in a collection. 
+      def initialize(&block)
+        super(&nil)
+        @nil_value = nil
+        @block = block
+      end
+      
+      # Stashes the specified values in self using values calculated 
+      # by the block.  Values are skipped if the block returns nil.  
+      #
+      # See Constants::ConstantLibrary#collect for more details.
+      def stash(values)
+        values.each do |value| 
+          value, index = block.call(value)
+          next if value == nil
+        
+          super(index == nil ? self.length : index, value)
+        end
+        
+        self
+      end
+    end
+    
+    # An array of values in the library
+    attr_reader :values
+    
+    # A hash of (name, index) pairs tracking the indicies in self
+    attr_reader :indicies
+    
+    # A hash of (name, collection) pairs tracking the collections in self
+    attr_reader :collections
+
+    def initialize(*values)
+      @values = values.uniq
+      @indicies = {}
+      @collections = {}
+    end
+    
+    # Adds an index to self for all values currently in self.  The block is 
+    # used to specify keys for each value in self; it receives each value and 
+    # should return one of the following: 
+    # - a key
+    # - a [key, value] array when an alternate value should be stored
+    #   in the place of value
+    # - the exclusion_value to exclude the value from the index
+    #
+    # When multiple values return the same key, they are stashed into an array.
+    #
+    #   lib = ConstantLibrary.new('one', 'two', :one)
+    #   lib.index_by("string") {|value| value.to_s }
+    #   lib.indicies['string'] 
+    #   # => {
+    #   # 'one' => ['one', :one],
+    #   # 'two' => 'two'} 
+    #  
+    # Existing indicies by the specified name are overwritten.
+    #
+    # ==== nil values
+    #
+    # The index stores it's data in an Index (ie a Hash) where nil_value
+    # acts as the default value returned for non-existant keys as well as
+    # the stash nil_value.  Hence index_by will raise an error if you try 
+    # to store the nil_value.  
+    # 
+    # This behavior can be seen when the exclusion value is set to something
+    # other than nil, so that the nil value isn't skipped outright:
+    #
+    #   # the nil will cause trouble
+    #   lib = ConstantLibrary.new(1,2,nil)
+    #   lib.index_by("error", false, nil) {|value| value }  # ! ArgumentError
+    #
+    # Specify an alternate nil_value (and exclusion value) to index nils; 
+    # a plain old Object works well. 
+    #
+    #   obj = Object.new
+    #   index = lib.index_by("ok", false, obj) {|value| value }
+    #   index[1]                 # => 1
+    #   index[nil]               # => nil
+    #
+    #   # remember the nil_value is the default value
+    #   index['non-existant']    # => obj
+    # 
+    def index_by(name, exclusion_value=nil, nil_value=nil, &block) # :yields: value
+      raise ArgumentError.new("no block given") unless block_given?
+      
+      index = Index.new(exclusion_value, nil_value, &block)
+      indicies[name] = index
+      index.stash(values)
+    end
+    
+    # Adds an index using the attribute or method.  Equivalent to:
+    #
+    #   lib.index_by(attribute) {|value| value.attribute }
+    #
+    def index_by_attribute(attribute, exclusion_value=nil, nil_value=nil)
+      method = attribute.to_sym
+      index_by(attribute, exclusion_value, nil_value) {|value| value.send(method) }
+    end
+    
+    # Adds a collection to self for all values currently in self.  The block
+    # is used to calculate the values in the collection.  The block receives 
+    # each value in self and should return one of the following: 
+    # - a value to be pushed onto the collection
+    # - a [value, index] array when an alternate value should be stored
+    #   in the place of value, or when the value should be at a special
+    #   index in the collection. When multiple values are directed to the 
+    #   same index, they are stashed into an array.
+    # - nil to exclude the value from the collection
+    #
+    # For example:
+    #
+    #   lib = ConstantLibrary.new('one', 'two', :three)
+    #   lib.collect("string") {|value| value.to_s }
+    #   lib.collections['string']   # => ['one', 'two', 'three']
+    #
+    #   lib.collect("length") {|value| [value, value.to_s.length] }
+    #   lib.collections['length']   # => [nil, nil, nil, ['one', 'two'], nil, :three]
+    #
+    # Works much like index_by, except that the underlying data store for a 
+    # collection is a Collection (ie an array) rather than an Index (a hash).
+    def collect(name, &block) # :yields: value
+      raise ArgumentError.new("no block given") unless block_given?
+      
+      collection = Collection.new(&block)
+      collections[name] = collection
+      collection.stash(values)
+    end
+    
+    # Adds a collection using the attribute or method.  Equivalent to:
+    #
+    #   lib.collect(attribute) {|value| value.attribute }
+    #
+    def collect_attribute(attribute)
+      method = attribute.to_sym
+      collect(attribute) {|value| value.send(method) }
+    end
+    
+    # Lookup values by a key.  All indicies will be searched in order; the first 
+    # matching value is returned.  Returns nil if no matches are found. 
+    def [](key)
+      indicies.values.each do |index|
+        return index[key] if index.has_key?(key)
+      end
+    
+      nil
+    end
+    
+    # Clears all values, from self, indicies, and collections.  The indicies, 
+    # and collections themselves are preserved unless complete==true.
+    def clear(complete=false)
+      values.clear
+      
+      [indicies, collections].each do |stashes|
+        complete ? stashes.clear : stashes.values.each {|stash| stash.clear}
+      end
+    end
+    
+    # Add the specified values to self.  New values are incorporated into existing
+    # indicies and collections.  Returns the values added (ie values minus any 
+    # already-existing values). 
+    def add(*values)
+      new_values = values - self.values
+      self.values.concat(new_values)
+    
+      [indicies, collections].each do |stashes|
+        stashes.values.each do |stash| 
+          stash.stash(new_values)
+        end
+      end
+
+      #new_values.each(&add_block) if add_block
+      new_values
+    end
+    
+    # Adds the constants from the specified module.  If mod is a Class, then
+    # only constants that are a kind of mod will be added.  This behavior
+    # can be altered by providing a block which each constant value; values
+    # are only included if the block evaluates to true.
+    def add_constants_from(mod)
+      const_names = mod.constants.select do |const_name|
+        const = mod.const_get(const_name)
+        block_given? ? yield(const) : (mod.kind_of?(Class) ? const.kind_of?(mod) : true)
+      end
+
+      add(*const_names.collect {|const_name| mod.const_get(const_name) })
+    end
+    
+    # # Specifies a block to execute when values are added to self.  
+    # # Existing values are sent to the add_block immediately.
+    # def on_add(override=false, &block) # :yields: value
+    #   raise "Add block already set!" unless add_block.nil? || override
+    #   @add_block = block
+    #   values.each(&block)
+    #   block
+    # end
+
+    # def merge!(hash)
+    #   hash.each_pair do |key, item|
+    #     existing = self[key]
+    #     if existing != nil
+    #       items[items.index(existing)] = item
+    #     else
+    #       add(item)
+    #     end
+    #   end
+    # 
+    #   items = self.items
+    #   self.clear(false)
+    #   add *items
+    # end
+
+  end
+end