h1. renum

Renum provides a readable but terse enum facility for Ruby.  Enums are sometimes called object constants and are analogous to the type-safe enum pattern in Java, though obviously Ruby's flexibility means there's no such thing as type-safety.

h2. Installing

<pre syntax="ruby">sudo gem install renum</pre>

h2. Demonstration of usage

Renum allows you to do things like this:

<pre syntax="ruby">enum :Status, %w( NOT_STARTED IN_PROGRESS COMPLETE )

enum :Size do
  Small("Really really tiny")
  Medium("Sort of in the middle")
  Large("Quite big")

  attr_reader :description

  def init description
    @description = description
  end
end

module MyNamespace
  enum :FooValue, [ :Bar, :Baz, :Bat ]
end</pre>

Giving you something that satisfies this spec, plus a bit more:

<pre syntax="ruby">describe "enum" do
  
  it "creates a class for the value type" do
    Status.class.should == Class
  end
  
  it "makes each value an instance of the value type" do
    Status::NOT_STARTED.class.should == Status
  end
  
  it "exposes array of values" do
    Status.values.should == [Status::NOT_STARTED, Status::IN_PROGRESS, Status::COMPLETE]
  end

  it "provides an alternative means of declaring values where extra information can be provided for initialization" do
    Size::Small.description.should == "Really really tiny"
  end
  
  it "enumerates over values" do
    Status.map {|s| s.name}.should == %w[NOT_STARTED IN_PROGRESS COMPLETE]
  end
  
  it "indexes values" do
    Status[2].should == Status::COMPLETE
  end
  
  it "provides index lookup on values" do
    Status::IN_PROGRESS.index.should == 1
  end
  
  it "provides a reasonable to_s for values" do
    Status::NOT_STARTED.to_s.should == "Status::NOT_STARTED"
  end
  
  it "makes values comparable" do
    Status::NOT_STARTED.should < Status::COMPLETE
  end
  
  it "allows enums to be nested in other modules or classes" do
    MyNamespace::FooValue::Bar.class.should == MyNamespace::FooValue
  end
  
end</pre>

h2. "Rails":http://www.rubyonrails.com/ Integration

To use enumerated values as ActiveRecord attribute values, "use the constantize_attribute plugin":https://github.com/duelinmarkers/constantize_attribute/tree (also by me).

<pre syntax="ruby">class Vehicle < ActiveRecord::Base
  enum :Status do
    New()
    Used()
    Salvage(true)
    
    def init(warn = false)
      @warn = warn
    end
    
    def requires_warning_buyer?
      @warn
    end
  end
  
  constantize_attribute :status
  
end

v = Vehicle.create! :status => Vehicle::Status::New
# Now the database has the string "Vehicle::Status::New",
# but your record object exposes the Status object:
v.status.requires_warning_buyer?          # => false

v.update_attribute :status, Vehicle::Status::Salvage
# Now the database has the string "Vehicle::Status::Salvage".
v.status.requires_warning_buyer?          # => true

# Since constantize_attribute also accepts strings, it's easy
# to use enumerated values with forms.
v.status = "Vehicle::Status::Used"
v.status.requires_warning_buyer?          # => false</pre>

h2. License

This code is free to use under the terms of the MIT license. 

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.

h2. Contact

Renum was created by John D. Hume. Comments are welcome. Send an email to duelin dot markers at gmail or "contact me via my blog":http://elhumidor.blogspot.com/.