simple_enum 0.3.0

data/.gitignore

@@ -0,0 +1,2 @@
+doc
+pkg

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Lukas Westermann (Zurich, Switzerland)
+
+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.rdoc

@@ -0,0 +1,182 @@
+= SimpleEnum - unobtrusive enum-like fields for ActiveRecord
+
+A Rails plugin which brings easy-to-use enum-like functionality to
+ActiveRecord models.
+
+*Note*: a recent search on github for `enum` turned out, that there are many, many similar solutions.
+Yet, none seem to provide so many options, but I may be biased ;)
+
+== Quick start
+
+Add this to a model:
+
+    class User < ActiveRecord::Base
+      as_enum :gender, {:female => 1, :male => 0}
+    end
+
+Then create the new column using migrations:
+
+    class AddGenderColumnToUser < ActiveRecord::Migration
+      def self.up
+        add_column :users, :gender_cd, :integer
+      end
+
+      def self.down
+        remove_column :users, :gender_cd
+      end
+    end
+
+*Done*. Now it's possible to pull some neat tricks on the new column, yet
+the original db column (+gender_cd+) is still intact and not touched by
+any fancy metaclass or similar.
+
+    jane = User.new
+    jane.gender = :female
+    jane.female?   # => true
+    jane.male?     # => false
+    jane.gender    # => :female
+    jane.gender_cd # => 1
+    
+Easily switch to another value using the bang methods.
+    
+    joe = User.new
+    joe.male!     # => :male
+    joe.gender    # => :male
+    joe.gender_cd # => 0
+
+There are even some neat tricks at class level, which might be
+useful when creating queries, displaying option elements or similar:
+
+    User.genders            # => { :male => 0, :female => 1 }
+    User.genders(:male)     # => 0, same as User.male
+    User.female             # => 1
+    User.genders.female     # => 1, same as User.female or User.genders(:female)
+
+== Wait, there's more!
+* Too tired of always adding the integer values? Try:
+
+        class User < ActiveRecord::Base
+          as_enum :status, [:deleted, :active, :disabled] # translates to :deleted => 0, :active => 1, :disabled => 2
+        end
+
+  *Disclaimer*: if you _ever_ decide to reorder this array, beaware that any previous mapping is lost. So it's recommended
+  to create mappings (that might change) using hashes instead of arrays. For stuff like gender it might be probably perfectly
+  fine to use arrays though.
+* Maybe you've columns named differently than the proposed <tt>{column}_cd</tt> naming scheme, feel free to use any column name
+  by providing an option:
+
+        class User < ActiveRecord::Base
+          as_enum :gender, [:male, :female], :column => 'sex'
+        end
+        
+* To make it easier to create dropdowns with values use:
+
+        <%= select(:user, :gender, User.genders.keys) %>
+        
+* It's possible to validate the internal enum values, just like any other ActiveRecord validation:
+
+        class User < ActiveRecord::Base
+          as_enum :gender, [:male, :female]
+          validates_as_enum :gender
+        end
+
+  All common options like <tt>:if</tt>, <tt>:unless</tt>, <tt>:allow_nil</tt> and <tt>:message</tt> are supported, because it just works within
+  the standard <tt>validates_each</tt>-loop. This validation method does not check the value of <tt>user.gender</tt>, but
+  instead the value of <tt>@user.gender_cd</tt>.
+* If the shortcut methods (like <tt><symbol>?</tt>, <tt><symbol>!</tt> or <tt>Klass.<symbol></tt>) conflict with something in your class, it's possible to
+  define a prefix:
+  
+        class User < ActiveRecord::Base
+          as_enum :gender, [:male, :female], :prefix => true
+        end
+
+        jane = User.new :gender => :female
+        jane.gender_female? # => true
+        User.gender_female  # => 1, this also works on the class methods
+        
+  The <tt>:prefix</tt> option not only takes a boolean value as an argument, but instead can also be supplied a custom
+  prefix (i.e. any string or symbol), so with <tt>:prefix => 'foo'</tt> all shortcut methods would look like: <tt>foo_<symbol>...</tt>
+  *Note*: if the <tt>:slim => true</tt> is defined, this option has no effect whatsoever (because no shortcut methods are generated).
+* Sometimes it might be useful to disable the generation of the shortcut methods (<tt><symbol>?</tt>, <tt><symbol>!</tt> and <tt>Klass.<symbol></tt>), to do so just add the option <tt>:slim => true</tt>:
+  
+        class User < ActiveRecord::Base
+          as_enum :gender, [:male, :female], :slim => true
+        end
+
+        jane = User.new :gender => :female
+        jane.female? # => throws NoMethodError: undefined method `female?' 
+        User.male    # => throws NoMethodError: undefined method `male' 
+  
+  Yet the setter and getter for <tt>gender</tt>, as well as the <tt>User.genders</tt> methods are still available, only all shortcut
+  methods for each of the enumeration values are not generated.
+  
+  It's also possible to set <tt>:slim => :class</tt> which only disables the generation of any class-level shortcut method, because those
+  are also available via the enhanced enumeration hash:
+  
+        class Message < ActiveRecord::Base
+          as_enum :status, { :unread => 0, :read => 1, :archived => 99}, :slim => :class
+        end
+        
+        msg = Message.new :body => 'Hello World!', status_cd => 0
+        msg.read?                      # => false; shortuct methods on instance are still enabled
+        msg.status                     # => :unread
+        Message.unread                 # => throws NoMethodError: undefined method `unread`
+        Message.statuses.unread        # => 0
+        Message.statuses.unread(true)  # => :unread
+        
+* As a default an <tt>ArgumentError</tt> is raised if the user tries to set the field to an invalid enumeration value, to change this
+  behaviour use the <tt>:whiny</tt> option:
+  
+        class User < ActiveRecord::Base
+          as_enum :gender, [:male, :female], :whiny => false
+        end
+        
+* To define any option globally, like setting <tt>:whiny</tt> to +false+, or globally enable <tt>:prefix</tt>; all default options
+  are stored in <tt>SimpleEnum.default_options</tt>, this hash can be easily changed in your initializers or wherever:
+
+        # e.g. setting :prefix => true (globally)
+        SimpleEnum.default_options[:prefix] = true
+
+== Best practices
+
+Searching for certain values by using the finder methods:
+
+    User.find :all, :conditions => { :gender_cd => User.female }
+    
+Working with database backed values, now assuming that there exists a +genders+ table:
+
+    class Person < ActiveRecord::Base
+      as_enum :gender, Gender.find(:all).map { |g| [g.name.to_sym, g.id] } # map to array of symbols
+    end
+    
+Working with object backed values, the only requirement to enable this is that <em>a)</em> either a field name +name+ exists
+or <em>b)</em> a custom method to convert an object to a symbolized form named +to_enum_sym+ (for general uses overriding
++to_enum+ is perfectly fine) exists:
+
+    class Status < ActiveRecord::Base
+      # this has a column named :name
+      STATUSES = self.find(:all, :order => :name)
+    end
+    
+    class BankTransaction < ActiveRecord::Base
+      as_enum :status, Status.STATUSES
+    end
+    
+    # what happens now? the id's of Status now serve as enumeration key and the
+    # Status object as the value so...    
+    t = BankTransaction.new
+    t.pending!
+    t.status # => #<Status id: 1, name: "pending">
+        
+    # and it's also possible to access the objects/values using:
+    BankTransaction.statuses(:pending) # => 1, access by symbol (not) the object!
+    BankTransaction.statuses.pending   # => 1
+    BankTransaction.statuses.pending(true) # => #<Status id: 1, name: "pending">
+    
+== Known issues/Open items
+
+* Maybe the <tt>:whiny</tt> option should default to <tt>false</tt>, so that generally no exceptions are thrown if a user fakes a request?
+* Clean-up code and tests -> bring down LOC ;) (but maintain Code LOC vs. Test LOC ratio which is currently 1:2.9)
+
+== Licence & Copyright
+Copyright (c) 2009 by Lukas Westermann, Licenced under MIT Licence (see LICENCE file)

data/Rakefile

@@ -0,0 +1,70 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the simple_enum plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the simple_enum plugin (results in doc/).'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'SimpleEnum'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('LICENCE');
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "simple_enum"
+    gemspec.summary = "Simple enum-like field support for ActiveRecord (including validations and i18n)"
+    gemspec.email = "lukas.westermann@gmail.com"
+    gemspec.homepage = "http://github.com/lwe/simple_enum"
+    gemspec.authors = ["Lukas Westermann"]
+  end
+  Jeweler::GemcutterTasks.new  
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+namespace :metrics do
+  desc 'Report code statistics for library and tests to shell.'
+  task :stats do |t|
+    require 'code_statistics'
+    dirs = {
+      'Libraries' => 'lib',
+      'Unit tests' => 'test'
+    }.map { |name,dir| [name, File.join(File.dirname(__FILE__), dir)] }
+    CodeStatistics.new(*dirs).to_s
+  end
+  
+  desc 'Report code coverage to HTML (doc/coverage) and shell (requires rcov).'
+  task :coverage do |t|
+    rm_f "doc/coverage"
+    mkdir_p "doc/coverage"
+    rcov = %(rcov -Ilib:test --exclude '\/gems\/' -o doc/coverage -T test/*_test.rb )
+    system rcov
+  end
+end
+
+desc 'Start IRB console with loaded test/test_helper.rb and sqlite db.'
+task :console do |t|
+  chdir File.dirname(__FILE__)
+  exec 'irb -Ilib/ -r test/test_helper'
+end
+
+desc 'Clean up generated files.'
+task :clean do |t|
+  FileUtils.rm_rf "doc"
+  FileUtils.rm_rf "pkg"  
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 3
+:patch: 0

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'lib', 'simple_enum')

data/lib/simple_enum/array_support.rb

@@ -0,0 +1,15 @@
+module SimpleEnum
+  module ArraySupport
+    
+    # Magically convert an array to a hash, has some neat features
+    # for active record models and similar.
+    #
+    # TODO: add more documentation; allow block to be passed to customize key/value pairs
+    def to_hash_magic
+      v = enum_with_index.to_a unless first.is_a?(ActiveRecord::Base) or first.is_a?(Array)
+      v = map { |e| [e, e.id] } if first.is_a?(ActiveRecord::Base)
+      v ||= self
+      Hash[*v.flatten]
+    end
+  end
+end

data/lib/simple_enum/enum_hash.rb

@@ -0,0 +1,36 @@
+module SimpleEnum
+  
+  # Internal hash class, used to handle the enumerations et al.
+  # Works like to original +Hash+ class, but with some added value,
+  # like access to 
+  #
+  # 
+  class EnumHash < ::Hash
+    def initialize(hsh)
+      hsh = hsh.to_hash_magic unless hsh.is_a?(Hash)
+      
+      @reverse_sym_lookup = {}
+      @sym_value_lookup = {}
+      
+      hsh.each do |k,v|
+        sym = k.to_enum_sym
+        self[k] = v
+        @reverse_sym_lookup[sym] = k
+        @sym_value_lookup[sym] = v
+      end
+    end
+    
+    def default(k = nil)
+      @sym_value_lookup[k.to_enum_sym] if k
+    end
+        
+    def method_missing(symbol, *args)
+      if @sym_value_lookup.has_key?(symbol.to_enum_sym)
+        return @reverse_sym_lookup[symbol.to_enum_sym] if args.first
+        self[symbol]
+      else
+        super
+      end
+    end
+  end
+end

data/lib/simple_enum/object_support.rb

@@ -0,0 +1,37 @@
+module SimpleEnum
+  module ObjectSupport
+    
+    # Convert object to symbol for use in symbolized enum
+    # methods. Return value is supposed to be a symbol,
+    # though strings should work as well.
+    #
+    # The default behaviour is to try +to_sym+ first, then
+    # checks if a field named +name+ exists or finally falls
+    # back to +to_param+ method as provided by ActiveSupport.
+    #
+    # It's perfectly for subclasses to override this method,
+    # to provide custom +to_enum_sym+ behaviour, e.g. if
+    # the symbolized value is in e.g. +title+:
+    #
+    #    class FormOfAddress < ActiveRecord::Base
+    #      attr_accessor :title
+    #      def to_enum_sym; title; end
+    #    end
+    #
+    # *Note*: to provide better looking methods values for +name+
+    # are <tt>parametereize('_')</tt>'d, so it might be a good idea to do
+    # the same thing in a custom +to_enum_sym+ method, like (for the
+    # example above):
+    #
+    #    def to_enum_sym; title.parameterize('_').to_sym; end
+    #
+    # *TODO*: The current implementation does not handle nil values very
+    # gracefully, so if +name+ returns +nil+, it should be handled
+    # a bit better I suppose...
+    def to_enum_sym
+      return to_sym if respond_to?(:to_sym)
+      return name.to_s.parameterize('_').to_sym if respond_to?(:name)
+      to_param.to_sym unless blank? # fallback, unless empty...
+    end
+  end
+end

data/lib/simple_enum/validation.rb

@@ -0,0 +1,37 @@
+module SimpleEnum
+  module Validation
+    
+    # Validates an +as_enum+ field based on the value of it's column.
+    #
+    # Model:
+    #    class User < ActiveRecord::Base
+    #      as_enum :gender, [ :male, :female ]
+    #      validates_as_enum :gender
+    #    end
+    #
+    # View:
+    #    <%= select(:user, :gender, User.genders.keys) %>
+    #
+    # Configuration options:
+    # * <tt>:message</tt> - A custom error message (default: is <tt>[:activerecord, :errors, :messages, :invalid_enum]</tt>).
+    # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+    # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+    #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
+    #   method, proc or string should return or evaluate to a true or false value.
+    # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+    #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
+    #   method, proc or string should return or evaluate to a true or false value.
+    def validates_as_enum(*attr_names)
+      configuration = { :on => :save }
+      configuration.update(attr_names.extract_options!)      
+      attr_names.map! { |e| enum_definitions[e][:column] } # map to column name
+      
+      validates_each(attr_names, configuration) do |record, attr_name, value|
+        enum_def = enum_definitions[attr_name]
+        unless send(enum_def[:name].to_s.pluralize).values.include?(value)
+          record.errors.add(enum_def[:name], :invalid_enum, :default => configuration[:message], :value => value)
+        end
+      end
+    end    
+  end
+end

data/lib/simple_enum/version.rb

@@ -0,0 +1,14 @@
+module SimpleEnum
+  module VERSION #:nodoc:
+    def self.version
+      @VERSION_PARTS ||= YAML.load_file File.join(File.dirname(__FILE__), '..', '..', 'VERSION.yml')
+    end
+    
+    def self.to_s
+      @VERSION ||= [version[:major], version[:minor], version[:patch]].join('.').freeze
+    end
+  end
+  
+  NAME = "simple_enum".freeze
+  ABOUT = "#{NAME} #{VERSION}".freeze
+end

data/lib/simple_enum.rb

@@ -0,0 +1,227 @@
+# SimpleEnum allows for cross-database, easy to use enum-like fields to be added to your
+# ActiveRecord models. It does not rely on database specific column types like <tt>ENUM</tt> (MySQL),
+# but instead on integer columns.
+#
+# Author:: Lukas Westermann
+# Copyright:: Copyright (c) 2009 Lukas Westermann (Zurich, Switzerland)
+# Licence:: MIT-Licence (http://www.opensource.org/licenses/mit-license.php)
+#
+# See the +as_enum+ documentation for more details.
+
+require 'simple_enum/array_support'
+require 'simple_enum/enum_hash'
+require 'simple_enum/object_support'
+require 'simple_enum/validation'
+require 'simple_enum/version'
+
+# Base module which gets included in <tt>ActiveRecord::Base</tt>. See documentation
+# of +SimpleEnum::ClassMethods+ for more details.
+module SimpleEnum
+
+  class << self
+    
+    # Provides configurability to SimpleEnum, allows to override some defaults which are
+    # defined for all uses of +as_enum+. Most options from +as_enum+ are available, such as:
+    # * <tt>:prefix</tt> - Define a prefix, which is prefixed to the shortcut methods (e.g. <tt><symbol>!</tt> and
+    #   <tt><symbol>?</tt>), if it's set to <tt>true</tt> the enumeration name is used as a prefix, else a custom
+    #   prefix (symbol or string) (default is <tt>nil</tt> => no prefix)
+    # * <tt>:slim</tt> - If set to <tt>true</tt> no shortcut methods for all enumeration values are being generated, if
+    #   set to <tt>:class</tt> only class-level shortcut methods are disabled (default is <tt>nil</tt> => they are generated)
+    # * <tt>:upcase</tt> - If set to +true+ the <tt>Klass.foos</tt> is named <tt>Klass.FOOS</tt>, why? To better suite some
+    #   coding-styles (default is +false+ => downcase)
+    # * <tt>:whiny</tt> - Boolean value which if set to <tt>true</tt> will throw an <tt>ArgumentError</tt>
+    #   if an invalid value is passed to the setter (e.g. a value for which no enumeration exists). if set to
+    #   <tt>false</tt> no exception is thrown and the internal value is set to <tt>nil</tt> (default is <tt>true</tt>)
+    def default_options
+      @default_options ||= {
+        :whiny => true,
+        :upcase => false
+      } 
+    end
+    
+    def included(base) #:nodoc:
+      base.send :extend, ClassMethods
+    end
+  end
+  
+  module ClassMethods
+    # Provides ability to create simple enumerations based on hashes or arrays, backed
+    # by integer columns (but not limited to integer columns).
+    #
+    # Columns are supposed to be suffixed by <tt>_cd</tt>, if not, use <tt>:column => 'the_column_name'</tt>,
+    # so some example migrations:
+    #
+    #   add_column :users, :gender_cd, :integer
+    #   add_column :users, :status, :integer # and a custom column...
+    #      
+    # and then in your model:
+    #
+    #   class User < ActiveRecord::Base
+    #     as_enum :gender, [:male, :female]
+    #   end
+    #
+    #   # or use a hash:
+    #
+    #   class User < ActiveRecord::Base
+    #     as_enum :status, { :active => 1, :inactive => 0, :archived => 2, :deleted => 3 }, :column => 'status'
+    #   end
+    #
+    # Now it's possible to access the enumeration and the internally stored value like:
+    #
+    #   john_doe = User.new
+    #   john_doe.gender          # => nil
+    #   john_doe.gender = :male
+    #   john_doe.gender          # => :male
+    #   john_doe.gender_cd       # => 0
+    #
+    # And to make life a tad easier: a few shortcut methods to work with the enumeration are also created.
+    # 
+    #   john_doe.male?           # => true
+    #   john_doe.female?         # => false
+    #   john_doe.female!         # => :female (set's gender to :female => gender_cd = 1)
+    #   john_doe.male?           # => false
+    #
+    # Sometimes it's required to access the db-backed values, like e.g. in a query:
+    #
+    #   User.genders             # =>  { :male => 0, :female => 1}, values hash
+    #   User.genders(:male)      # => 0, value access (via hash)
+    #   User.female              # => 1, direct access
+    #   User.find :all, :conditions => { :gender_cd => User.female }  # => [...], list with all women
+    #
+    # To access the key/value assocations in a helper like the select helper or similar use:
+    #
+    #   <%= select(:user, :gender, User.genders.keys)
+    #
+    # The generated shortcut methods (like <tt>male?</tt> or <tt>female!</tt> etc.) can also be prefixed
+    # using the <tt>:prefix</tt> option. If the value is <tt>true</tt>, the shortcut methods are prefixed
+    # with the name of the enumeration.
+    #
+    #   class User < ActiveRecord::Base
+    #     as_enum :gender, [:male, :female], :prefix => true
+    #   end
+    #
+    #   jane_doe = User.new
+    #   jane_doe.gender = :female   # this is still as-is
+    #   jane_doe.gender_cd          # => 1, and so it this
+    #
+    #   jane_doe.gender_female?     # => true (instead of jane_doe.female?)
+    #
+    # It is also possible to supply a custom prefix.
+    #
+    #   class Item < ActiveRecord::Base
+    #     as_enum :status, [:inactive, :active, :deleted], :prefix => :state
+    #   end
+    #
+    #   item = Item.new(:status => :active)
+    #   item.state_inactive?       # => false
+    #   Item.state_deleted         # => 2
+    #   Item.status(:deleted)      # => 2, same as above...
+    #
+    # To disable the generation of the shortcut methods for all enumeration values, add <tt>:slim => true</tt> to
+    # the options.
+    #
+    #   class Address < ActiveRecord::Base
+    #     as_enum :canton, {:aargau => 'ag', ..., :wallis => 'vs', :zug => 'zg', :zurich => 'zh'}, :slim => true
+    #   end    
+    #
+    #   home = Address.new(:canton => :zurich, :street => 'Bahnhofstrasse 1', ...)
+    #   home.canton       # => :zurich
+    #   home.canton_cd    # => 'zh'
+    #   home.aargau!      # throws NoMethodError: undefined method `aargau!' 
+    #   Address.aargau    # throws NoMethodError: undefined method `aargau`
+    #
+    # This is especially useful if there are (too) many enumeration values, or these shortcut methods
+    # are not required.
+    #
+    # === Configuration options:
+    # * <tt>:column</tt> - Specifies a custom column name, instead of the default suffixed <tt>_cd</tt> column
+    # * <tt>:prefix</tt> - Define a prefix, which is prefixed to the shortcut methods (e.g. <tt><symbol>!</tt> and
+    #   <tt><symbol>?</tt>), if it's set to <tt>true</tt> the enumeration name is used as a prefix, else a custom
+    #   prefix (symbol or string) (default is <tt>nil</tt> => no prefix)
+    # * <tt>:slim</tt> - If set to <tt>true</tt> no shortcut methods for all enumeration values are being generated, if
+    #   set to <tt>:class</tt> only class-level shortcut methods are disabled (default is <tt>nil</tt> => they are generated)
+    # * <tt>:upcase</tt> - If set to +true+ the <tt>Klass.foos</tt> is named <tt>Klass.FOOS</tt>, why? To better suite some
+    #   coding-styles (default is +false+ => downcase)
+    # * <tt>:whiny</tt> - Boolean value which if set to <tt>true</tt> will throw an <tt>ArgumentError</tt>
+    #   if an invalid value is passed to the setter (e.g. a value for which no enumeration exists). if set to
+    #   <tt>false</tt> no exception is thrown and the internal value is set to <tt>nil</tt> (default is <tt>true</tt>)
+    def as_enum(enum_cd, values, options = {})
+      options = SimpleEnum.default_options.merge({ :column => "#{enum_cd}_cd" }).merge(options)
+      options.assert_valid_keys(:column, :whiny, :prefix, :slim, :upcase)
+    
+      # convert array to hash...
+      values = SimpleEnum::EnumHash.new(values)
+      values_inverted = values.invert
+    
+      # store info away
+      write_inheritable_attribute(:enum_definitions, {}) if enum_definitions.nil?
+      enum_definitions[enum_cd] = enum_definitions[options[:column]] = { :name => enum_cd, :column => options[:column], :options => options }
+    
+      # generate getter       
+      define_method("#{enum_cd}") do
+        id = read_attribute options[:column]
+        values_inverted[id]
+      end
+    
+      # generate setter
+      define_method("#{enum_cd}=") do |new_value|
+        v = new_value.nil? ? nil : values[new_value.to_sym]        
+        raise(ArgumentError, "Invalid enumeration value: #{new_value}") if (options[:whiny] and v.nil? and !new_value.nil?)
+        write_attribute options[:column], v
+      end
+    
+      # allow access to defined values hash, e.g. in a select helper or finder method.      
+      self_name = enum_cd.to_s.pluralize   
+      self_name.upcase! if options[:upcase]   
+      class_variable_set :"@@SE_#{self_name.upcase}", values
+      class_eval(<<-EOM, __FILE__, __LINE__ + 1)
+        def self.#{self_name}(sym = nil)
+          return class_variable_get(:@@SE_#{self_name.upcase}) if sym.nil?
+          class_variable_get(:@@SE_#{self_name.upcase})[sym]
+        end
+      EOM
+    
+      # only create if :slim is not defined
+      if options[:slim] != true
+        # create both, boolean operations and *bang* operations for each
+        # enum "value"
+        prefix = options[:prefix] && "#{options[:prefix] == true ? enum_cd : options[:prefix]}_"
+    
+        values.each do |k,code|
+          sym = k.to_enum_sym
+        
+          define_method("#{prefix}#{sym}?") do
+            code == read_attribute(options[:column])
+          end
+          define_method("#{prefix}#{sym}!") do
+            write_attribute options[:column], code
+            sym
+          end
+        
+          # allow class access to each value
+          unless options[:slim] === :class
+            metaclass.send(:define_method, "#{prefix}#{sym}", Proc.new { |*args| args.first ? k : code })
+          end
+        end
+      end
+    end
+
+    include Validation
+  
+    protected
+      # Returns enum definitions as defined by each call to
+      # +as_enum+.
+      def enum_definitions
+        read_inheritable_attribute(:enum_definitions)
+      end
+  end
+end
+
+# Tie stuff together and load translations if ActiveRecord is defined
+if Object.const_defined?('ActiveRecord')
+  Object.send(:include, SimpleEnum::ObjectSupport)
+  Array.send(:include, SimpleEnum::ArraySupport)
+    
+  ActiveRecord::Base.send(:include, SimpleEnum)
+  I18n.load_path << File.join(File.dirname(__FILE__), '..', 'locales', 'en.yml')
+end

data/locales/en.yml

@@ -0,0 +1,6 @@
+# english translation
+en:
+  activerecord:
+    errors:
+      messages:
+        invalid_enum: invalid option supplied.