duelinmarkers-renum 1.0.2

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2007 John D. Hume
+
+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.textile

@@ -0,0 +1,120 @@
+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. 
+
+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/.

data/Rakefile

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'spec/rake/spectask'
+
+Spec::Rake::SpecTask.new do |t|
+end
+
+task :default => :spec
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "renum"
+    s.summary = "provides a readable but terse enum facility for Ruby"
+    s.email = "duelin.markers@gmail.com"
+    s.homepage = "http://github.com/duelinmarkers/renum"
+    s.description = "provides a readable but terse enum facility for Ruby"
+    s.authors = ["John Hume"]
+  end
+rescue LoadError
+  puts "Jeweler or a dependency not available. To install: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.2

data/lib/renum/enumerated_value.rb

@@ -0,0 +1,37 @@
+require 'forwardable'
+
+module Renum
+  class EnumeratedValue
+    
+    class << self
+      include Enumerable
+      extend Forwardable
+      
+      def_delegators :values, :each, :[]
+      
+      def values
+        @values ||= []
+      end
+      
+    end
+    
+    include Comparable
+    attr_reader :name
+    attr_reader :index
+    
+    def initialize name
+      @name = name.to_s
+      @index = self.class.values.size
+      self.class.values << self
+    end
+    
+    def to_s
+      "#{self.class}::#{name}"
+    end
+    
+    def <=> other
+      index <=> other.index
+    end
+    
+  end
+end

data/lib/renum/enumerated_value_type_factory.rb

@@ -0,0 +1,54 @@
+require 'renum/enumerated_value'
+
+module Renum
+  module EnumeratedValueTypeFactory
+    class << self
+      def create nest, type_name, values, &block
+        klass = create_class nest, type_name
+        create_values klass, values, &block
+      end
+    
+      def create_class nest, type_name
+        klass = Class.new EnumeratedValue
+        nest.const_set(type_name, klass)
+        klass
+      end
+    
+      def create_values klass, values, &block
+        setup_for_definition_in_block(klass) if values == :defined_in_block
+        klass.class_eval &block if block_given?
+        if values == :defined_in_block
+          klass.block_defined_values.each do |value_name, init_args|
+            value = klass.new(value_name)
+            klass.const_set(value_name, value)
+            value.init *init_args if init_args.any?
+          end
+          teardown_from_definition_in_block(klass)
+        else
+          values.each do |name|
+            klass.const_set(name, klass.new(name))
+          end
+        end
+      end
+    
+      def setup_for_definition_in_block klass
+        klass.class_eval do
+          def self.block_defined_values
+            @block_defined_values ||= []
+          end
+
+          def self.method_missing value_name, *init_args
+            block_defined_values << [value_name, init_args]
+          end
+        end
+      end
+    
+      def teardown_from_definition_in_block klass
+        class << klass
+          remove_method :block_defined_values
+          remove_method :method_missing
+        end
+      end
+    end
+  end
+end

data/lib/renum/version.rb

@@ -0,0 +1,9 @@
+module Renum #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 1
+    MINOR = 0
+    TINY  = 2
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/lib/renum.rb

@@ -0,0 +1,15 @@
+$:.unshift File.dirname(__FILE__)
+require 'renum/enumerated_value_type_factory'
+
+module Renum
+  def enum type_name, values = :defined_in_block, &block
+    nest = self.is_a?(Module) ? self : Object
+    EnumeratedValueTypeFactory.create(nest, type_name, values, &block)
+  end
+end
+
+extend Renum
+
+Module.module_eval do
+  include Renum
+end

data/spec/renum_spec.rb

@@ -0,0 +1,108 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+enum :Status, [ :NOT_STARTED, :IN_PROGRESS, :COMPLETE ]
+
+module MyNamespace
+  enum :FooValue, %w( Bar Baz Bat )
+end
+
+enum :Color, [ :RED, :GREEN, :BLUE ] do
+  def abbr
+    name[0..0]
+  end
+end
+
+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
+
+enum :HairColor do
+  BLONDE()
+  BRUNETTE()
+  RED()
+end
+
+describe "basic enum" do
+  
+  it "creates a class for the value type" do
+    Status.should be_an_instance_of(Class)
+  end
+  
+  it "makes each value an instance of the value type" do
+    Status::NOT_STARTED.should be_an_instance_of(Status)
+  end
+  
+  it "exposes array of values" do
+    Status.values.should == [Status::NOT_STARTED, Status::IN_PROGRESS, Status::COMPLETE]
+  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
+    Color[0].should == Color::RED
+  end
+  
+  it "provides index lookup on values" do
+    Status::IN_PROGRESS.index.should == 1
+    Color::GREEN.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
+    Color::RED.should < Color::GREEN
+  end
+end
+
+describe "nested enum" do
+  it "is namespaced in the containing module or class" do
+    MyNamespace::FooValue::Bar.class.should == MyNamespace::FooValue
+  end
+end
+
+describe "enum with a block" do
+  it "can define additional instance methods" do
+    Color::RED.abbr.should == "R"
+  end
+end
+
+describe "enum with no values array and values declared in the block" do
+  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 "works the same as the basic form with respect to ordering" do
+    Size.values.should == [Size::Small, Size::Medium, Size::Large]
+  end
+  
+  it "responds as expected to arbitrary method calls, in spite of using method_missing for value definition" do
+    lambda { Size.ExtraLarge() }.should raise_error(NoMethodError)
+  end
+  
+  it "supports there being no extra data and no init() method defined, if you don't need them" do
+    HairColor::BLONDE.name.should == "BLONDE"
+  end
+end
+
+# It was reported on my blog that <=> was causing segfaults.
+# I'd love to figure out why, but first I'd love to fix that. 
+describe "digging into this segfault/illegal instruction issue, renum" do
+  it "doesn't cause the ruby process to bomb!" do
+    Color::RED.should < Color::GREEN
+    Color::RED.should_not > Color::GREEN
+    Color::RED.should < Color::BLUE
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems'
+  gem 'rspec'
+  require 'spec'
+end
+
+if ENV['USE_GEM']
+  require 'rubygems'
+  require 'renum'
+else
+  require File.expand_path(File.dirname(__FILE__) + '/../lib/renum')
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: duelinmarkers-renum
+version: !ruby/object:Gem::Version 
+  version: 1.0.2
+platform: ruby
+authors: 
+- John Hume
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-19 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: provides a readable but terse enum facility for Ruby
+email: duelin.markers@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- License.txt
+- README.textile
+- Rakefile
+- VERSION
+- lib/renum.rb
+- lib/renum/enumerated_value.rb
+- lib/renum/enumerated_value_type_factory.rb
+- lib/renum/version.rb
+- spec/renum_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/duelinmarkers/renum
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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.2.0
+signing_key: 
+specification_version: 2
+summary: provides a readable but terse enum facility for Ruby
+test_files: 
+- spec/renum_spec.rb
+- spec/spec_helper.rb