elemental 0.1.1 → 0.1.2

data/README.md

@@ -0,0 +1,369 @@
+# 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:
+* [Rubyforge](http://elemental.rubyforge.net)
+* [Github](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

@@ -4,7 +4,7 @@
 
 begin
   require 'bones'
-  Bones.setup
+  # Bones.setup
 rescue LoadError
   begin
     load 'tasks/setup.rb'
@@ -18,12 +18,12 @@ 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'
+# 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

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name     = "elemental"
-  s.version  = "0.1.1"
-  s.date     = "2009-06-03"
+  s.version  = "0.1.2"
+  s.date     = "2009-11-23"
   s.summary  = "Implements a set of elements that are enumerable."
   s.email    = "mwlang@cybrains.net"
   s.homepage = "http://github.com/mwlang/elemental"
@@ -11,13 +11,13 @@ Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.files    = [ 
 		"elemental.gemspec", 
-		"README.txt",
+		"README.md",
 		"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"]
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Elemental", "--main", "README.md"]
+  s.extra_rdoc_files = ["README.md"]
 end
 

data/lib/element.rb

@@ -24,7 +24,15 @@ class Element
 
   attr_accessor :symbol, :ordinal, :display, :position, :default
 
-  # Initializes a new element
+  ##
+  # Initializes a new element into the given Elemental Class
+  #
+  # @param [Elemental] elemental the "owning container" class
+  # @param [Symbol] symbol the symbolic name for the element
+  # @param [Fixnum] ordinal the desired ordinal value - defaults to position in list
+  # @param [Hash] options A hash of additional options to associate with the element
+  # @return [Element] Returns an instance for the given element properties
+  #
   def initialize(elemental, symbol, ordinal, options={})
     @elemental = elemental
     @symbol = symbol
@@ -42,59 +50,91 @@ class Element
     @position = options[:position] || ordinal
   end
 
+  ## 
+  # @return [true, false] Returns true if given value matches this Element's value
+  #
+  # @param [Symbol or Element] value the value we're are comparing against this element
+  #
   def is?(value)
     self == (value.is_a?(Element) ? value : @elemental[value])
   end
 
+  ## 
+  # @return [Fixnum, Symbol] returns either the ordinal value or the symbol for 
+  # this element.  The value type returned is determined by the value_as_ordinal property
+  #
   def value
     @elemental.value_as_ordinal ? to_i : to_sym
   end
 
+  ##
   # Will sort on position (which defaults to ordinal if not explicitly set)
+  #
+  # @param [Element] other the other Element to compare against
+  #
+  # @return [-1, 0, +1] 
   def <=>(other)
     position <=> other.position
   end
 
+  ##
   # Returns the element that follows this element.
   # If this is last element, returns first element
+  # @return [Element] 
   def succ
     @elemental.succ(@symbol)
   end
 
+  ##
   # Returns the element that precedes this element.
   # If this is the first element, returns last element
+  # @return [Element] 
   def pred
     @elemental.pred(@symbol)
   end
-
+  
+  ##
   # Returns the symbol for this element as a string
+  # @return [String]
   def to_s
     @symbol.to_s
   end
 
+  ## 
   # Returns this element's symbol
+  # @return [Symbol]
   def to_sym
     @symbol
   end
 
+  ##
   # Returns the ordinal value for this element
+  # @return [Fixnum]
   def index
     @ordinal
   end
 
+  ##
   # Returns true if is default.  (useful if populating select lists)
+  # @return [true, false]
   def default?
     @default
   end
 
+  ##
   # Generates a reasonable inspect string
+  # @return [String]
   def inspect
     "#<#{self.class}:#{self.object_id} {symbol => :#{@symbol}, " +
     "ordinal => #{@ordinal}, display => \"#{@display}\", " +
     "position => #{@position}, default => #{@default}}>"
   end
 
-  # swiped from Rails...
+  ## 
+  # Will humanize the Element's symbolic name by removing underscores and trailing "_id"
+  # monikers.  The words are capitialized.
+  # @author swiped from Rails...
+  # @return [String]
   def humanize
     return @display if @display != to_s
     return self.to_s.gsub(/_id$/, "").gsub(/_/, " ").capitalize

data/lib/elemental.rb

@@ -29,24 +29,29 @@ end
 
 module Elemental
 
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 
   include Enumerable
 
+  ##
+  # Affects whether #value returns symbolic name for element or ordinal value
+  # @return [true or false] value is ordinal value when true
   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.
+  # @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={})
@@ -59,7 +64,8 @@ module Elemental
     @ordered_elements << element
   end
 
-  # allows you to define aliases for a given member with adding
+  ##
+  # Allows you to define aliases for a given member with adding
   # additional elements to the elemental class.
   #
   #    class Fruit
@@ -76,69 +82,104 @@ module Elemental
     @unordered_elements[conform_to_symbol(new_symbol)] = element
   end
 
+  ##
   # Returns the first element in this class
+  #
+  # @return [Element]
   def first
     @ordered_elements.first
   end
 
+  ##
   # Returns the last element in this class
+  #
+  # @return [Element]
   def last
     @ordered_elements.last
   end
 
+  ##
   # Returns the number of elements added
+  #
+  # @return [Fixnum]
   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.
+  #
+  # @param [Symbol] value the symbolic reference to the element
+  # @return [Element]
   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.
+  #
+  # @param [Symbol] value the symbolic reference to the element
+  # @return [Element]
   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])
+  #
+  # @param [Symbol, Fixnum] value the Element to retrieve, referenced either by ordinal 
+  # position or by symbolic representation for the element.
+  #
+  # @return [Element]
   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
+  ##
+  # Iterates over the elements, passing each Element to the given block
   def each(&block)
     @ordered_elements.each(&block)
   end
 
+  ##
   # Allows Car::honda
+  # @return [Element]
   def method_missing(value)
     self[value]
   end
 
+  ##
   # Allows Car::Honda
+  # @return [Element]
   def const_missing(const)
     get_unordered_element(const)
   end
 
+  ##
   # Returns all elements that are flagged as a default
+  # @return [Array of Element]
   def defaults
     @ordered_elements.select{|s| s.default?}
   end
 
+  ##
   # Outputs a sensible inspect string
+  # @return [String]
   def inspect
     "#<#{self}:#{object_id} #{@ordered_elements.inspect}>"
   end
 
   private
 
+  ##
   # Takes a "CamelCased-String" and returns "camel_cased_string"
+  # @return [String]
+  # @author Rails team
   def underscore(camel_cased_word)
     camel_cased_word.to_s.
       gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
@@ -147,20 +188,26 @@ module Elemental
       downcase
   end
 
+  ##
   # Transforms given string or symbol
   # into a :lowered_case_underscored_symbol
+  # @return [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
+  # @return [Element]
   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
+  # @return [Element]
   def get_unordered_element(what)
     result = @unordered_elements[conform_to_symbol(what)]
     raise RuntimeError if result.nil?

data/test/test_elemental.rb

@@ -1,7 +1,11 @@
 #!/usr/bin/env ruby
 
 require 'test/unit'
-require 'lib/elemental'
+begin
+  require 'lib/elemental'
+rescue LoadError
+  require 'elemental'
+end
 
 module TestElemental
 
@@ -365,6 +369,10 @@ module TestElemental
       c.each{|element| assert(!a.include?(element), "a, #{a.inspect} should not contain #{element.inspect}")}
     end
 
+    def test_inspect
+      assert_equal(Fruit.inspect.match(/\#\<Element\:/).to_s, "#<Element:")
+    end
+    
     def test_is_conditional
       assert_equal(true, Fruit::banana.is?(:banana))
       assert_equal(true, Fruit::banana.is?(Fruit::banana))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: elemental
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Michael Lang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-03 00:00:00 -04:00
+date: 2009-11-23 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -20,16 +20,18 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README.txt
+- README.md
 files: 
 - elemental.gemspec
-- README.txt
+- README.md
 - Rakefile
 - lib/element.rb
 - lib/elemental.rb
 - test/test_elemental.rb
 has_rdoc: true
 homepage: http://github.com/mwlang/elemental
+licenses: []
+
 post_install_message: 
 rdoc_options: 
 - --line-numbers
@@ -37,7 +39,7 @@ rdoc_options:
 - --title
 - Elemental
 - --main
-- README.txt
+- README.md
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -55,9 +57,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.1
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: Implements a set of elements that are enumerable.
 test_files: []
 

data/README.txt

@@ -1,364 +0,0 @@
-= 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.