elemental 0.1.1

data/README.txt

@@ -0,0 +1,364 @@
+= ELEMENTAL
+
+Elemental gives you enumerated sets.  You code symbolically,
+keeping literals away from your conditional logic.
+
+== REQUIREMENTS:
+
+  * Ruby 1.8+
+  * Ruby Gems
+
+== INSTALL:
+
+Project Hosts:
+  * http://elemental.rubyforge.net
+  * http://github.com/mwlang/elemental/tree/master
+
+From Gem:
+    sudo gem install elemental
+
+From Source:
+    gem install bones, rake, test-unit
+    git clone git://github.com/mwlang/elemental.git
+    cd elemental
+    rake gem:package
+    cd pkg
+    sudo gem install elemental
+
+Working Examples:
+  Check out the projects in the examples folder for working examples of
+  using Elemental.  Examples may be limited presently, but more are planned.
+  If you have a unique/interesting application of Elemental, please feel free
+  to contact me and let me know about it for possible inclusion.
+
+== FEATURES/PROBLEMS:
+
+  * Code with symbols, easily display what the user needs to see.
+  * Associate any number of values/attributes with a symbolic element.
+  * Change the display values without worrying about logical side-effects.
+  * Access elements in a variety of ways: symbol, constant, index.
+  * Store in database as either string (the default) or ordinal value.
+  * Elemental is also Enumerable.  You can iterate all members and sort, too.
+  * A default flag can be set that makes it easier to render views.
+
+== DESCRIPTION:
+
+Elemental provides enumerated collection of elements that allow you to associate
+ruby symbols to arbitrary "display" values, thus allowing your code to "think"
+symbolically and unambiguously while giving you the means to easily display what
+end-users need to see. Additionally, symbols are associated with ordinal values,
+allowing easy storage/retrieval to persistent stores (databases, files,
+marshalling, etc) by saving the Element#value as appropriate (String by default,
+Fixnum if you "persist_ordinally").
+
+The primary aim of Elemental is to collect and abstract literals away
+from your code logic. There's an old programmer's wisdom that you should not
+encode your logic using literal values, especially those the end-user is exposed to.
+
+Yet, interpreted languages seem to be famous for sowing the practice of doing
+boolean expressions replete with string literals. Which can be ok until one day
+your client says, "I don't like 'Active' can we use 'enabled' instead?").
+
+In your code, instead of:
+
+  if my_user.status == 'Active' ...
+        or worse
+  my_user.favorite_color = 1
+
+  (what color is 1?!)
+
+The above suffers from the following:
+  - literals are subject to change or are cryptic.
+  - diff spellings mean diff things ('Active' != 'active' != 'Actve').
+  - relying on literals error prone and hard to test.
+  - code is often not readable as-is (what color is 1, again?).
+
+With Elemental, do this:
+
+  if my_user.status == UserStatus::active.value
+  my_user.favorite_color = Color::blue
+
+When you save a value to a persistent store (database, stream, file, etc.), you
+assign the Element#value like so:
+
+  my_user.status = UserStatus::active.value
+
+(more on what you get via "value" later)
+
+If UserStatus::active isn't defined, you get an error immediately that you can
+attribute to a typo in your code. This behavior is by design in Elemental.
+That's a unit test you *don't* have to write! Simply define your class or module
+and include the Ruby symbols you need:
+
+  class AccountStatus
+    extend Elemental
+    member :active,       :display => 'Active'
+    member :delinquent,   :display => "Account Past Due"
+    member :inactive      :display => "Inactive"
+  end
+
+Elemental can return the Element#value as either a Ruby symbol (Symbol) or an
+ordinal (Fixnum) value. The default is a Ruby symbol. To override this and
+return an ordinal value, use "persist_ordinally" as follows:
+
+  class AccountStatus
+    extend Elemental
+    persist_ordinally
+
+    member :active,       :display => 'Active'
+    member :delinquent,   :display => "Account Past Due"
+    member :inactive      :display => "Inactive"
+  end
+
+== SYNOPSIS:
+
+Elementals are "containers" for your elements (a.k.a. Ruby symbols).
+They are declared like this:
+
+  class AccountStatus
+    extend Elemental
+    member :active,       :display => 'Active', :default => true
+    member :delinquent,   :display => "Account Past Due"
+    member :inactive      :display => "Inactive"
+  end
+
+  class Fruit
+    extend Elemental
+    member :orange,       :position => 10
+    member :banana,       :position => 5,  :default => true
+    member :blueberry,    :position => 15
+  end
+
+Where:
+  * The symbol is main accessor for Elemental
+  * Display is what the end-user sees. Display defaults to the symbol's to_s.
+  * Position lets you define a display sort order (use WidgetType.sort...)
+  * Position defaults to Ordinal value if not given.
+  * Absent Position, the default sort order is the order in which
+      elements are declared (ordinal).
+  * Specifying Position does not change Ordinal value.
+  * An ElementNotFoundError is raised if you try an nonexistent Symbol.
+
+Another example:
+
+  class Color
+    extend Elemental
+    member :red,      :display "#FF0000"
+    member :green,    :display "#00FF00"
+    member :blue,     :display "#0000FF"
+  end
+
+So you roll with this for a few months and decided you don't like primary colors?
+Its simple to change the color constants (in display):
+
+  class Color
+    extend Elemental
+    member :red,      :display "#AA5555"
+    member :green,    :display "#55AA55"
+    member :blue,     :display "#5555AA"
+  end
+
+Your code logic remains the same because the symbols didn't change!
+
+Once you have your Elemental classes defined, replace your conditionals
+that use string literals.
+
+So, instead of:
+  if widget.widget_type == "Foo bar"
+
+(where widget is an Activerecord instance and widget_type is an attribute/column)
+(mental note: was that "FOO BAR", "foobar", "Foo Bar", "foo bar", or "Foo bar"??)
+
+Do this and be confident:
+  if WidgetType[widget.widget_type] == WidgetType::foo_bar
+
+Or shorter:
+  if WidgetType[widget.widget_type].is?(WidgetType::foo_bar)
+
+Or shorter, still:
+  if WidgetType[widget.widget_type].is?(:foo_bar)
+
+Although Elemental wasn't specifically written for Rails, it is trivial to put to use.  Instead
+if creating a new model and migration script and all that, simply establish your Elemental
+class definition and then iterate the Elemental to construct your views as appropriate.
+
+With Elemental, simply populate select dropdowns like this:
+
+in your $RAILS_ROOT/config/initializers/constants.rb:
+
+  class AccountStatus
+    extend Elemental
+    member :active,       :display => 'Active', :default => true
+    member :delinquent,   :display => "Account Past Due"
+    member :inactive      :display => "Inactive"
+  end
+
+Then in your view:
+
+  <p><label for="account_status">Account Status</label><br/>
+    <%= select "user", "status",
+      AccountStatus.sort.map{|a| [a.display, a.value]},
+      { :include_blank => false,
+        :selected => AccountStatus.defaults.first.value }
+    %></select>
+  </p>
+
+Or render checkboxes with:
+
+  <% Color.sort.each |c| do %>
+			<%= check_box_tag("user[favorite_colors][#{c.value}]",
+			  "1", Color.defaults.detect{|color| color == c}) %>
+			<%= "#{c.display}"%><br />
+  <% end %>
+
+Life is simplified because:
+  - No more migrate scripts for tiny tables
+  - No worries that the auto-incrementer is guaranteeing to assign
+      same ID accross deployments.
+  - No database penalties looking up rarely changing values
+  - No worries that an empty lookup table breaks your application logic/flow
+  - Values that mean something in your app are symbolic while what's displayed
+      and sorted on are free to change as the application grows and evolves.
+
+More than one default is supported (dropdowns only use one, so first.value
+gets you first one, radio buttons or checkboxes can use all defaults). Ordinal
+position is preserved and traditionally shouldn't be changed during the life
+of the project, although, Ruby being Ruby and developers saying "Ruby ain't C,"
+an Elemental's elements almost definitely will get changed by some developer at
+some time.
+
+The chances of the name of the symbol changing is much lower than a developer's
+tendency to keep an orderly house by sorting member elements alphabetically. As
+such, the default behavior for "value" is to return the symbol rather than
+ordinal value and storing as a string in DB, which seems the safest route to
+take albeit not the optimal performance-wise (finding records by integral value
+is faster than string searches, even with indexes in place). If you want to
+override this, simply call "persist_ordinally" when you declare your Elemental
+classes.
+
+  class Color
+    extend Elemental
+    persist_ordinally
+    member :red
+    member :green
+    member :blue
+  end
+
+With that, Color::red.value returns Fixnum 0 instead of the Symbol :red
+
+You can also associate many values with a particular element through custom accessors.  
+To extend the Color example further:
+
+class Color
+  extend Elemental
+  persist_ordinally
+  member :red, :display => "Primary Red", :red => 255, :green => 0, :blue => 0, :hex => "#FF0000"
+  member :green, :display => "Primary Green", :red => 0, :green => 255, :blue => 0, :hex => "#00FF00"
+  member :blue, :display => "Primary Blue", :red => 0, :green => 0, :blue => 255, :hex => "#0000FF"
+end
+
+With that:
+  Color::red.red => 255
+  Color::red.green => 0
+  Color::red.blue => 0
+  Color::red.hex => "#FF0000"
+
+Elements can be accessed multiple ways:
+
+  def test_different_retrievals_get_same_element
+    a1 = Car::honda
+    a2 = Car::Honda
+    a3 = Car[:honda]
+    a4 = Car[:Honda]
+    a5 = Car["Honda"]
+    a6 = Car["honda"]
+    a7 = Car.first
+    a8 = Car.last.succ
+    a9 = Car[0]
+    assert_element_sameness(a1, a2, :honda)
+    assert_element_sameness(a2, a3, :honda)
+    assert_element_sameness(a4, a5, :honda)
+    assert_element_sameness(a6, a7, :honda)
+    assert_element_sameness(a8, a1, :honda)
+    assert_element_sameness(a9, a2, :honda)
+  end
+
+There are also several convenience aliases to pull ordinal, value, symbol and display:
+
+  def test_aliases
+    assert_equal(Car::toyota.index, Car::toyota.to_i)
+    assert_equal(Car::toyota.to_i, Car::toyota.to_i)
+    assert_equal(Car::toyota.to_int, Car::toyota.to_i)
+    assert_equal(Car::toyota.ord, Car::toyota.to_i)
+    assert_equal(Car::toyota.ordinal, Car::toyota.to_i)
+    assert_equal(Car::toyota.to_sym, Car::toyota.value)
+    assert_equal(:toyota, Car::toyota.to_sym)
+    assert_equal(:toyota, Car::toyota.value)
+    assert_equal("toyota", Car::toyota.display)
+    assert_equal("toyota", Car::toyota.humanize)
+  end
+
+Full test coverage is provided.
+
+One known limitation (which is probably a reflection of my not-so-great Ruby skills):
+
+You cannot inherit and Elemental from another Elemental, esp. since none of the classes or
+modules are ever actually instantiated.  The following will NOT WORK:
+
+  class Fruit           # OK
+    extend Elemental
+    member :orange
+    member :banana
+    member :blueberry
+  end
+
+  class Vegetable       # OK
+    extend Elemental
+    member :potato
+    member :carrot
+    member :tomato
+  end
+
+  class Food            # NOT OK
+    extend Fruit
+    extend Vegetable
+  end
+
+Also, this doesn't work, either:
+
+  class Food < Fruit   # NOT OK
+    extend Vegetable
+  end
+
+Nor:
+
+  class ExoticFruit < Fruit   # NOT OK
+    member :papaya
+    member :mango
+  end
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Michael Lang
+
+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/Rakefile

@@ -0,0 +1,29 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'elemental'
+
+task :default => 'test:run'
+
+PROJ.name = 'elemental'
+PROJ.authors = 'Michael Lang'
+PROJ.email = 'mwlang@cybrains.net'
+PROJ.url = 'http://github.com/mwlang/elemental/tree/master'
+PROJ.version = Elemental::VERSION
+PROJ.rubyforge.name = 'elemental'
+PROJ.spec.opts << '--color'
+
+# EOF

data/elemental.gemspec

@@ -0,0 +1,23 @@
+Gem::Specification.new do |s|
+  s.name     = "elemental"
+  s.version  = "0.1.1"
+  s.date     = "2009-06-03"
+  s.summary  = "Implements a set of elements that are enumerable."
+  s.email    = "mwlang@cybrains.net"
+  s.homepage = "http://github.com/mwlang/elemental"
+  s.description = "Elemental provides enumerated set of elements allowing your code to think symbolically and unambiguously while giving you the means to easily display what end-users need to see."
+  s.has_rdoc = true
+  s.authors  = ["Michael Lang"]
+  s.platform = Gem::Platform::RUBY
+  s.files    = [ 
+		"elemental.gemspec", 
+		"README.txt",
+		"Rakefile",
+		"lib/element.rb",
+		"lib/elemental.rb",
+		"test/test_elemental.rb"
+	]
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Elemental", "--main", "README.txt"]
+  s.extra_rdoc_files = ["README.txt"]
+end
+

data/lib/element.rb

@@ -0,0 +1,106 @@
+=begin
+Copyright (c) 2009 Michael Lang
+
+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.
+=end
+class Element
+
+  attr_accessor :symbol, :ordinal, :display, :position, :default
+
+  # Initializes a new element
+  def initialize(elemental, symbol, ordinal, options={})
+    @elemental = elemental
+    @symbol = symbol
+    @ordinal = ordinal
+    
+    # Sets all options and optionally creates an accessor method
+    options.each do |k, v|
+      eval("def #{k}; @#{k}; end") unless respond_to?(k)
+      v.is_a?(String) ? eval("@#{k} = '#{v}'") : eval("@#{k} = #{v}")
+    end
+    
+    # Force the following values (overrides above looped assignments)
+    @default = options[:default] || false
+    @display = options[:display] || symbol.to_s
+    @position = options[:position] || ordinal
+  end
+
+  def is?(value)
+    self == (value.is_a?(Element) ? value : @elemental[value])
+  end
+
+  def value
+    @elemental.value_as_ordinal ? to_i : to_sym
+  end
+
+  # Will sort on position (which defaults to ordinal if not explicitly set)
+  def <=>(other)
+    position <=> other.position
+  end
+
+  # Returns the element that follows this element.
+  # If this is last element, returns first element
+  def succ
+    @elemental.succ(@symbol)
+  end
+
+  # Returns the element that precedes this element.
+  # If this is the first element, returns last element
+  def pred
+    @elemental.pred(@symbol)
+  end
+
+  # Returns the symbol for this element as a string
+  def to_s
+    @symbol.to_s
+  end
+
+  # Returns this element's symbol
+  def to_sym
+    @symbol
+  end
+
+  # Returns the ordinal value for this element
+  def index
+    @ordinal
+  end
+
+  # Returns true if is default.  (useful if populating select lists)
+  def default?
+    @default
+  end
+
+  # Generates a reasonable inspect string
+  def inspect
+    "#<#{self.class}:#{self.object_id} {symbol => :#{@symbol}, " +
+    "ordinal => #{@ordinal}, display => \"#{@display}\", " +
+    "position => #{@position}, default => #{@default}}>"
+  end
+
+  # swiped from Rails...
+  def humanize
+    return @display if @display != to_s
+    return self.to_s.gsub(/_id$/, "").gsub(/_/, " ").capitalize
+  end
+
+  alias :to_i :index
+  alias :to_int :index
+  alias :ord :index
+end

data/lib/elemental.rb

@@ -0,0 +1,169 @@
+=begin
+Copyright (c) 2009 Michael Lang
+
+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.
+=end
+
+begin
+  require 'lib/element'
+rescue LoadError
+  require 'element'
+end
+
+module Elemental
+
+  VERSION = '0.1.1'
+
+  include Enumerable
+
+  attr_reader :value_as_ordinal
+
+  # Causes the Element#value method to return ordinal value, which
+  # normally returns the ruby symbol
+  #
+  # Note:  If you choose for Element#value to return ordinal and you are
+  #   storing value to database, then you should always APPEND new elements
+  #   to the declared Elemental class.  Otherwise, you WILL CHANGE the
+  #   ordinal values and thus invalidate any persistent stores.  If you're
+  #   not persistently storing ordinal values, then order of membership is moot.
+  def persist_ordinally
+    @value_as_ordinal = true
+  end
+
+  # Adds an element in the order given to the enumerable's class
+  # Order matters if you store ordinal to database or other persistent stores
+  def member(symbol, options={})
+    @unordered_elements ||= {}
+    @ordered_elements ||= []
+    symbol = conform_to_symbol(symbol)
+    element = Element.new(self, symbol, @ordered_elements.size, options)
+
+    @unordered_elements[symbol] = element
+    @ordered_elements << element
+  end
+
+  # allows you to define aliases for a given member with adding
+  # additional elements to the elemental class.
+  #
+  #    class Fruit
+  #      extend Elemental
+  #      member :apple
+  #      member :kiwi
+  #      synonym :machintosh, :apple
+  #    end
+  #
+  # will yield an Elemental with only two elements (apple and kiwi),
+  # but give the ability to retrieve Fruit::apple using Fruit::machintosh
+  def synonym(new_symbol, existing_symbol)
+    element = self[existing_symbol]
+    @unordered_elements[conform_to_symbol(new_symbol)] = element
+  end
+
+  # Returns the first element in this class
+  def first
+    @ordered_elements.first
+  end
+
+  # Returns the last element in this class
+  def last
+    @ordered_elements.last
+  end
+
+  # Returns the number of elements added
+  def size
+    @ordered_elements.size
+  end
+
+  # Returns the element that follows the given element.  If given element is
+  # last element, then first element is returned.
+  def succ(value)
+    index = self[value].to_i + 1
+    (index >= size) ? first : @ordered_elements[index]
+  end
+
+  # Returns the element that precedes the given element.  If given element is
+  # the first element, then last element is returned.
+  def pred(value)
+    index = self[value].to_i - 1
+    (index < 0) ? last : @ordered_elements[index]
+  end
+
+  # Shortcut to getting to a specific element
+  # Can get by symbol or constant (i.e. Color[:red] or Color[:Red])
+  def [](value)
+    value.is_a?(Fixnum) ? get_ordered_element(value) : get_unordered_element(value)
+  end
+
+  # iterates over the elements, passing each to the given block
+  def each(&block)
+    @ordered_elements.each(&block)
+  end
+
+  # Allows Car::honda
+  def method_missing(value)
+    self[value]
+  end
+
+  # Allows Car::Honda
+  def const_missing(const)
+    get_unordered_element(const)
+  end
+
+  # Returns all elements that are flagged as a default
+  def defaults
+    @ordered_elements.select{|s| s.default?}
+  end
+
+  # Outputs a sensible inspect string
+  def inspect
+    "#<#{self}:#{object_id} #{@ordered_elements.inspect}>"
+  end
+
+  private
+
+  # Takes a "CamelCased-String" and returns "camel_cased_string"
+  def underscore(camel_cased_word)
+    camel_cased_word.to_s.
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+
+  # Transforms given string or symbol
+  # into a :lowered_case_underscored_symbol
+  def conform_to_symbol(text_or_symbol)
+    underscore(text_or_symbol.to_s).downcase.to_sym
+  end
+
+  # returns the nth element, raising an exception if index out of bounds
+  def get_ordered_element(index)
+    result = @ordered_elements[index]
+    raise RuntimeError if result.nil?
+    result
+  end
+
+  # returns the requested element by name, raising exception if non-existent
+  def get_unordered_element(what)
+    result = @unordered_elements[conform_to_symbol(what)]
+    raise RuntimeError if result.nil?
+    result
+  end
+end

data/test/test_elemental.rb

@@ -0,0 +1,399 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'lib/elemental'
+
+module TestElemental
+
+  class TestElemental < Test::Unit::TestCase
+
+    class Fruit
+      extend Elemental
+      member :apple
+      member :pear, :default => true
+      member :banana, :default => true
+      member :kiwi
+
+      synonym :machintosh, :apple
+    end
+
+    FRUIT_SIZE = 4
+
+    class Color
+      extend Elemental
+      member :blue, :display => "Hazel Blue", :default => true
+      member :red, :display => "Fire Engine Red"
+      member :yellow
+    end
+
+    COLOR_SIZE = 3
+
+    class Car
+      extend Elemental
+      member :honda, :position => 100
+      member :toyota, :position => 30
+      member :ford, :position => 50
+      member :gm, :position => 25
+      member :mazda, :position => 1
+    end
+
+    CAR_SIZE = 5
+
+    class JumbledMess
+      extend Elemental
+      member :testing
+      member :Oh_one
+      member :two_three
+      member :FourFiveSix
+      member :what_an_id
+      member :your_idea
+    end
+
+    class TalkingNumbers
+      extend Elemental
+      persist_ordinally
+      member :zilch, :display => "zero", :alt => "zip", :zero => true, :custom => 0
+      member :uno,:display => "one", :alt => "1st", :zero => false, :custom => 1.0
+      member :dos, :display => "two", :alt => "2nd", :zero => false, :custom => 2
+      member :tres, :display => "three", :alt => "3rd", :zero => false, :custom => "3"
+    end
+
+    def test_values_as_ordinal
+      one = TalkingNumbers[:uno]
+      two = TalkingNumbers["dos"]
+      three = TalkingNumbers[3]
+
+      assert_equal(one.to_i, one.value)
+      assert_equal(2, two.value)
+      assert_equal(3, three.value)
+    end
+
+    def test_humanize
+      assert_equal("Testing", JumbledMess::testing.humanize)
+      assert_equal("Oh one", JumbledMess::oh_one.humanize)
+      assert_equal("Two three", JumbledMess::two_three.humanize)
+      assert_equal("Four five six", JumbledMess::FourFiveSix.humanize)
+    end
+
+    # Test the order of breadth for each
+    def test_size_of_elemental
+      assert_equal(FRUIT_SIZE, Fruit.size)
+      assert_equal(COLOR_SIZE, Color.size)
+      assert_equal(CAR_SIZE, Car.size)
+    end
+
+    def assert_can_map_elements
+      assert_not_nil(Car.collect{|c| c.value})
+    end
+
+    def assert_element_sameness(a, b, symbol)
+      assert_not_nil(a)
+      assert_not_nil(b)
+      assert(a.is_a?(Element))
+      assert(b.is_a?(Element))
+      assert_equal(a, b)
+      assert_equal(symbol, a.to_sym)
+      assert_equal(symbol, b.to_sym)
+      assert_equal(a, b)
+    end
+
+    def test_basic_retrieval
+      assert_not_nil(Fruit::apple)
+      assert_not_nil(Fruit::banana)
+      assert_not_nil(Fruit::pear)
+      assert_not_nil(Fruit::kiwi)
+    end
+
+    def test_jumbled_retrival
+      assert_not_nil(JumbledMess::testing)
+      assert_not_nil(JumbledMess::two_three)
+      assert_not_nil(JumbledMess::what_an_id)
+      assert_not_nil(JumbledMess::your_idea)
+      assert_not_nil(JumbledMess::oh_one)
+      assert_not_nil(JumbledMess["oh_one"])
+
+      assert_not_nil(JumbledMess::Oh_one)
+      assert_not_nil(JumbledMess::Oh_One)
+      assert_not_nil(JumbledMess::FourFiveSix)
+      assert_not_nil(JumbledMess::Four_Five_six)
+    end
+
+    def test_basic_nonretrieval
+      assert_raise(RuntimeError) { Fruit::tomato }
+      assert_raise(RuntimeError) { Fruit::Potato }
+      assert_raise(RuntimeError) { Fruit[:squash] }
+      assert_raise(RuntimeError) { Fruit["okra"] }
+      assert_raise(RuntimeError) { Fruit[10] }
+    end
+
+    def test_retrieval_by_ordinal
+      apple1 = Fruit[0]
+      apple2 = Fruit.select{|s| s.to_sym == :apple}.first
+      assert_element_sameness(apple1, apple2, :apple)
+
+      pear1 = Fruit[1]
+      pear2 = Fruit[:pear]
+      assert_element_sameness(pear1, pear2, :pear)
+
+      kiwi1 = Fruit[-1]
+      kiwi2 = Fruit.last
+      assert_element_sameness(kiwi1, kiwi2, :kiwi)
+    end
+
+    def test_retrieval_by_symbol
+      a1 = Fruit::apple
+      a2 = Fruit[:apple]
+      a3 = Fruit.select{|s| s.to_sym == :apple}.first
+      assert_element_sameness(a1, a2, :apple)
+      assert_element_sameness(a1, a3, :apple)
+      assert_element_sameness(a2, a3, :apple)
+
+      b1 = Fruit::banana
+      b2 = Fruit[:banana]
+      b3 = Fruit.select{|s| s.to_sym == :banana}.first
+      assert_element_sameness(b1, b2, :banana)
+      assert_element_sameness(b1, b3, :banana)
+      assert_element_sameness(b2, b3, :banana)
+    end
+
+    def test_retrieval_by_constant
+      a1 = Car::Toyota
+      a2 = Car[:Toyota]
+      a3 = Car.select{|s| s.to_sym == :toyota}.first
+      assert_element_sameness(a1, a2, :toyota)
+      assert_element_sameness(a1, a3, :toyota)
+      assert_element_sameness(a2, a3, :toyota)
+    end
+
+    def test_different_retrievals_get_same_element
+      a1 = Car::honda
+      a2 = Car::Honda
+      a3 = Car[:honda]
+      a4 = Car[:Honda]
+      a5 = Car["Honda"]
+      a6 = Car["honda"]
+      a7 = Car.first
+      a8 = Car.last.succ
+      a9 = Car[0]
+      assert_element_sameness(a1, a2, :honda)
+      assert_element_sameness(a2, a3, :honda)
+      assert_element_sameness(a4, a5, :honda)
+      assert_element_sameness(a6, a7, :honda)
+      assert_element_sameness(a8, a1, :honda)
+      assert_element_sameness(a9, a2, :honda)
+    end
+
+    def test_get_first_element
+      e1 = Color.first
+      e2 = Color::blue
+      assert_element_sameness(e1,e2,:blue)
+      assert_equal(e1.to_i, 0)
+      assert_equal(e1.to_i, e2.ord)
+      assert_equal(e2.ordinal, 0)
+    end
+
+    def test_walk_succ
+      e1 = Color.first
+      assert_element_sameness(e1, Color::blue, :blue)
+      assert_equal(0, e1.ordinal)
+      e1 = e1.succ
+      assert_element_sameness(e1, Color::red, :red)
+      assert_equal(1, e1.ordinal)
+      e1 = e1.succ
+      assert_element_sameness(e1, Color::yellow, :yellow)
+      assert_equal(2, e1.ordinal)
+      e1 = e1.succ
+      assert_element_sameness(e1, Color::blue, :blue)
+      assert_equal(0, e1.ordinal)
+    end
+
+    def test_get_last_element
+      e1 = Color.last
+      e2 = Color::yellow
+      assert_element_sameness(e1,e2,:yellow)
+      assert_equal(e1.to_i, COLOR_SIZE - 1)
+      assert_equal(e1.to_i, e2.ord)
+      assert_equal(e2.ordinal, COLOR_SIZE - 1)
+    end
+
+    def test_walk_pred
+      e1 = Color.first
+      assert_element_sameness(e1, Color::blue, :blue)
+      assert_equal(0, e1.ordinal)
+
+      e1 = e1.pred
+      assert_element_sameness(e1, Color::yellow, :yellow)
+      assert_equal(2, e1.ordinal)
+
+      e1 = e1.pred
+      assert_element_sameness(e1, Color::red, :red)
+      assert_equal(1, e1.ordinal)
+
+      e1 = e1.pred
+      assert_element_sameness(e1, Color::blue, :blue)
+      assert_equal(0, e1.ordinal)
+    end
+
+    def test_get_as_array
+      a = Color.to_a
+      assert(a.is_a?(Array))
+      assert_equal(COLOR_SIZE, a.size)
+      assert(a.first.is_a?(Element))
+      assert_element_sameness(Color.first, a.first, :blue)
+      assert_element_sameness(Color.first.succ, a[1], :red)
+    end
+
+    def test_aliases
+      assert_equal(Car::toyota.index, Car::toyota.to_i)
+      assert_equal(Car::toyota.to_i, Car::toyota.to_i)
+      assert_equal(Car::toyota.to_int, Car::toyota.to_i)
+      assert_equal(Car::toyota.ord, Car::toyota.to_i)
+      assert_equal(Car::toyota.ordinal, Car::toyota.to_i)
+      assert_equal(Car::toyota.to_sym, Car::toyota.value)
+      assert_equal(:toyota, Car::toyota.to_sym)
+      assert_equal(:toyota, Car::toyota.value)
+      assert_equal("toyota", Car::toyota.display)
+      assert_equal("Toyota", Car::toyota.humanize)
+    end
+
+    def test_to_a_gives_elements_in_ordinal_position
+      a = Color.to_a
+      assert(a.is_a?(Array))
+      assert_equal(COLOR_SIZE, a.size)
+      assert(a.first.is_a?(Element))
+      a.each_with_index do |element, index|
+        assert_equal(index, element.ordinal)
+      end
+    end
+
+    def test_each_gives_elements_in_ordinal_position
+      Car.each_with_index do |element, index|
+        assert_equal(index, element.ordinal)
+      end
+    end
+
+    def test_sorted_by_position_is_equal_to_ordinal_when_position_not_specified
+      a = Color.to_a
+      b = Color.sort
+      assert(b.is_a?(Array))
+      assert_equal(COLOR_SIZE, b.size)
+      assert(b.first.is_a?(Element))
+
+      # Position (and thus order) should be same as ordinal order when position not specified at creation
+      a.each_with_index do |element, index|
+        assert_element_sameness(element, b[index], element.to_sym)
+      end
+
+      Color.sort.each_with_index do |element, index|
+        assert_element_sameness(element, b[index], element.to_sym)
+      end
+    end
+
+    def test_can_use_map
+      Car.map{|m| assert(m.is_a?(Element))}
+    end
+
+    def test_equality
+      assert_equal(:mazda, Car::mazda.value)
+      assert_equal(:mazda, Car::mazda.to_sym)
+    end
+
+    def test_sorted_by_position_is_different_than_ordinal_order
+      a = Car.to_a
+      b = Car.sort
+      assert(b.is_a?(Array))
+      assert_equal(CAR_SIZE, b.size)
+      assert(b.first.is_a?(Element))
+      assert_element_sameness(Car::mazda, b.first, :mazda)
+      assert_element_sameness(Car::honda, b.last, :honda)
+
+      # Position (and thus order) should be same as ordinal order when position not specified at creation
+      a.each_with_index do |element, index|
+        assert_not_equal(b[index], element)
+      end
+
+      def test_sorted_by_position_is_ascending_by_position
+        b = Car.sort
+        last_ordinal = -1
+        b.each_with_index do |element, index|
+          assert(last_ordinal < element.ordinal)
+          last_ordinal = element.ordinal
+        end
+      end
+    end
+
+    def test_display_can_be_set
+      assert_equal("yellow", Color::yellow.to_s)
+      assert_equal("yellow", "#{Color::yellow}")
+      assert_equal("yellow", Color::yellow.display)
+
+      a = Color::blue
+      assert_equal("Hazel Blue", a.display)
+      assert_equal("blue", "#{a}")
+
+      assert_equal("Fire Engine Red", Color::red.display)
+    end
+
+    def test_setting_display_does_not_affect_symbol_to_string
+      a = Color::blue
+      assert_equal("Hazel Blue", a.display)
+      assert_equal("blue", "#{a}")
+      assert_not_equal("Hazel Blue", a.to_s)
+    end
+
+    def test_default_is_false_by_default
+      Car.each{|c| assert_equal(false, c.default?)}
+    end
+
+    def test_banana_is_default
+      assert_equal(true, Fruit::banana.default?)
+    end
+
+    def test_can_get_array_of_defaults
+      a = Fruit.defaults
+      b = [Fruit::banana, Fruit::pear]
+      assert_equal(2, a.size)
+      assert_equal(2, b.size)
+      b.each{|element| assert(a.include?(element), "a, #{a.inspect} does not contain #{element.inspect}")}
+    end
+
+    def test_defaults_is_only_defaults
+      a = [Fruit::banana, Fruit::pear]
+      c = Fruit.reject{|r| a.include?(r)}
+      assert_equal(2, a.size)
+      assert_equal(FRUIT_SIZE - 2, c.size)
+      c.each{|element| assert(!a.include?(element), "a, #{a.inspect} should not contain #{element.inspect}")}
+    end
+
+    def test_is_conditional
+      assert_equal(true, Fruit::banana.is?(:banana))
+      assert_equal(true, Fruit::banana.is?(Fruit::banana))
+      assert_equal(false, Fruit::banana.is?(:kiwi))
+      assert_equal(true, TalkingNumbers[1].is?(:uno))
+      assert_equal(true, TalkingNumbers[2].is?("dos"))
+      assert_equal(true, TalkingNumbers["tres"].is?(3))
+    end
+
+    def test_extended_attributes
+      assert_equal('1st', TalkingNumbers[1].alt)
+      assert_equal('2nd', TalkingNumbers[:dos].alt)
+      assert_equal('3rd', TalkingNumbers["tres"].alt)
+
+      assert_equal(true, TalkingNumbers[0].zero)
+      assert_equal(false, TalkingNumbers[1].zero)
+      assert_equal(false, TalkingNumbers[:dos].zero)
+      assert_equal(false, TalkingNumbers["tres"].zero)
+
+      assert_equal(0, TalkingNumbers[0].custom)
+      assert_equal(true, TalkingNumbers[1].custom.is_a?(Float))
+      assert_equal(true, TalkingNumbers[2].custom.is_a?(Fixnum))
+      assert_equal(true, TalkingNumbers[3].custom.is_a?(String))
+    end
+
+    def test_synonym_accessor
+      a = Fruit::apple
+      b = Fruit::machintosh
+      assert_equal(a, b)
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: elemental
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Michael Lang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-03 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Elemental provides enumerated set of elements allowing your code to think symbolically and unambiguously while giving you the means to easily display what end-users need to see.
+email: mwlang@cybrains.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+files: 
+- elemental.gemspec
+- README.txt
+- Rakefile
+- lib/element.rb
+- lib/elemental.rb
+- test/test_elemental.rb
+has_rdoc: true
+homepage: http://github.com/mwlang/elemental
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Elemental
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Implements a set of elements that are enumerable.
+test_files: []
+