renum 1.3.1 → 1.4.0

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+  - ruby-head
+  - jruby-head
+  - 1.8.7
+  - ree

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'rake', :group => [:development, :test]
+gem 'rspec', :group => [:development, :test]
+gem 'jeweler', :group => [:development, :test]

data/Gemfile.lock

@@ -0,0 +1,30 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.5)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jeweler
+  rake
+  rspec

data/README.textile

@@ -1,12 +1,10 @@
 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
+!https://secure.travis-ci.org/duelinmarkers/renum.png(Build Status)!:http://travis-ci.org/duelinmarkers/renum
 
-<pre syntax="ruby">sudo gem install renum</pre>
+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. Demonstration of usage
+h2. Usage
 
 Renum allows you to do things like this:
 
@@ -31,15 +29,15 @@ 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
@@ -47,54 +45,90 @@ Giving you something that satisfies this spec, plus a bit more:
   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).
+[This feature is brand new and should be considered beta-quality.]
+
+Use Renum::NameSerializer with ActiveRecord's "`serialize`":http://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Serialization/ClassMethods.html#method-i-serialize method to store enum values as strings.
 
 <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
-  
+
+  serialize :status, Renum::NameSerializer.new(Status)
+
+end
+
+v = Vehicle.create! :status => Vehicle::Status::New
+# Now the database has the string "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 "Salvage".
+v.status.requires_warning_buyer?          # => true
+
+# Note that if you assign a String, the value will remain a String until you save.
+v.status = "Used"
+v.status.requires_warning_buyer?          # => raises NoMethodError</pre>
+
+Before ActiveRecord had such flexible serialization support, I wrote a Rails plugin called "constantize_attribute":https://github.com/duelinmarkers/constantize_attribute/tree that would store the fully qualified name of your value in a string column. It hasn't been tested against a recent version of Rails, but it should still work. It's not packaged as a gem, so if you want to use it, I'd recommend you just grab the code. (It's quite tiny.)
+
+<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
@@ -113,7 +147,7 @@ v.status.requires_warning_buyer?          # => false</pre>
 
 h2. License
 
-This code is free to use under the terms of the MIT 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

data/Rakefile

@@ -1,22 +1,17 @@
-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
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler or a dependency not available. To install: sudo gem install jeweler"
-end
+require 'rubygems'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+
+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
+Jeweler::RubygemsDotOrgTasks.new

data/VERSION

@@ -1 +1 @@
-1.3.1
+1.4.0

data/lib/renum.rb

@@ -1,13 +1,19 @@
 require 'renum/enumerated_value_type_factory'
+require 'renum/name_serializer'
+require 'renum/index_serializer'
 
-# Requiring 'renum' mixes the Renum module into both the main Object and 
-# Module, so it can be called from anywhere that you might reasonably 
+# Requiring 'renum' mixes the Renum module into both the main Object and
+# Module, so it can be called from anywhere that you might reasonably
 # define an enumeration with an implicit receiver.
 module Renum
 
-  # Figures out whether the new enumeration will live in Object or the 
-  # receiving Module, then delegates to EnumeratedValueTypeFactory#create for 
-  # all the real work.
+  # Declares an enumerated type. If called inside a module, the enumerated type class will
+  # be nested inside that module.
+  #
+  # @param [Symbol] type_name The name of the EnumeratedType class to create
+  # @param [optional, Array<Symbol, String>] values
+  #   the names of the values in order, can be omitted if you'll specify them via method calls in a block
+  # @param block can be used to specify values with method calls, instance methods
   def enum type_name, values = :defined_in_block, &block
     nest = self.is_a?(Module) ? self : Object
     EnumeratedValueTypeFactory.create(nest, type_name, values, &block)

data/lib/renum/enumerated_value.rb

@@ -2,7 +2,8 @@ require 'forwardable'
 
 module Renum
 
-  # This is the superclass of all enumeration classes. 
+  # This is the superclass of your enumeration classes.
+  # The class methods defined here are intended to be called on your enumerated value classes.
   # An enumeration class is Enumerable over its values and exposes them by numeric index via [].
   # Values are also comparable, sorting into the order in which they're declared.
   class EnumeratedValue
@@ -13,15 +14,19 @@ module Renum
 
       def_delegators :values, :each, :[]
 
-      # Returns an array of values in the order they're declared.
+      # @return [Array] values of this type in the order they're declared.
       def values
         @values ||= []
       end
 
+      # Lookup by name.
+      # @param [String] name of the value you want
+      # @return [EnumeratedValue, nil] the value with `name` or nil if there is no value by that name
       def with_name name
         values_by_name[name]
       end
 
+      # @return [{String => EnumeratedType}] values keyed by name.
       def values_by_name
         @values_by_name ||= values.inject({}) do |memo, value|
           memo[value.name] = value
@@ -35,6 +40,9 @@ module Renum
 
     attr_reader :name, :index
 
+    # You should never directly new-up an EnumeratedValue, so this is basically internal.
+    # It sets up the value with its class, so if you override, be sure to call super!
+    # Better yet define init as shown in the README.
     def initialize name
       @name = name.to_s.freeze
       @index = self.class.values.size
@@ -42,7 +50,7 @@ module Renum
     end
 
     # Returns the fully qualified name of the constant referring to this value.
-    # Don't override this if you're using Renum with the constantize_attribute 
+    # Don't override this if you're using Renum with the constantize_attribute
     # plugin, which relies on this behavior.
     def to_s
       "#{self.class}::#{name}"
@@ -53,5 +61,8 @@ module Renum
       index <=> other.index
     end
 
+    def == other
+      equal? other
+    end
   end
 end

data/lib/renum/index_serializer.rb

@@ -0,0 +1,15 @@
+module Renum
+  class IndexSerializer
+    def initialize enum_class
+      @enum_class = enum_class
+    end
+
+    def dump v
+      v && v.index
+    end
+
+    def load i
+      i && @enum_class[i]
+    end
+  end
+end

data/lib/renum/name_serializer.rb

@@ -0,0 +1,19 @@
+module Renum
+  class NameSerializer
+    def initialize enum_class
+      @enum_class = enum_class
+    end
+
+    def dump v
+      v && if v.is_a?(String)
+             v
+           else
+             v.name
+           end
+    end
+
+    def load s
+      s && @enum_class.with_name(s)
+    end
+  end
+end

data/renum.gemspec

@@ -1,49 +1,57 @@
 # Generated by jeweler
 # DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{renum}
-  s.version = "1.3.1"
+  s.name = "renum"
+  s.version = "1.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["John Hume"]
-  s.date = %q{2010-08-17}
-  s.description = %q{provides a readable but terse enum facility for Ruby}
-  s.email = %q{duelin.markers@gmail.com}
+  s.date = "2013-03-16"
+  s.description = "provides a readable but terse enum facility for Ruby"
+  s.email = "duelin.markers@gmail.com"
   s.extra_rdoc_files = [
     "README.textile"
   ]
   s.files = [
+    ".travis.yml",
+    "Gemfile",
+    "Gemfile.lock",
     "README.textile",
-     "Rakefile",
-     "VERSION",
-     "lib/renum.rb",
-     "lib/renum/enumerated_value.rb",
-     "lib/renum/enumerated_value_type_factory.rb",
-     "renum.gemspec",
-     "spec/renum_spec.rb",
-     "spec/spec_helper.rb"
-  ]
-  s.homepage = %q{http://github.com/duelinmarkers/renum}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{provides a readable but terse enum facility for Ruby}
-  s.test_files = [
+    "Rakefile",
+    "VERSION",
+    "lib/renum.rb",
+    "lib/renum/enumerated_value.rb",
+    "lib/renum/enumerated_value_type_factory.rb",
+    "lib/renum/index_serializer.rb",
+    "lib/renum/name_serializer.rb",
+    "renum.gemspec",
     "spec/renum_spec.rb",
-     "spec/spec_helper.rb"
+    "spec/spec_helper.rb"
   ]
+  s.homepage = "http://github.com/duelinmarkers/renum"
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.15"
+  s.summary = "provides a readable but terse enum facility for Ruby"
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
     else
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
     end
   else
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
   end
 end
 

data/spec/renum_spec.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'spec_helper'
 
 enum :Status, [ :NOT_STARTED, :IN_PROGRESS, :COMPLETE ]
 
@@ -43,6 +43,10 @@ describe "basic enum" do
   it "makes values comparable" do
     Color::RED.should < Color::GREEN
   end
+
+  it "doesn't let Comparable's == confuse things" do
+    Color[0].should_not == Status[0]
+  end
 end
 
 module MyNamespace
@@ -158,14 +162,35 @@ end
 
 describe "prevention of subtle and annoying bugs" do
   it "prevents you modifying the values array" do
-    lambda { Color.values << 'some crazy value' }.should raise_error(TypeError, /can't modify frozen/)
+    expect { Color.values << 'some crazy value' }.to raise_error(/modify frozen/)
   end
 
   it "prevents you modifying the name hash" do
-    lambda { Color.values_by_name['MAGENTA'] = 'some crazy value' }.should raise_error(TypeError, /can't modify frozen/)
+    expect { Color.values_by_name['MAGENTA'] = 'some crazy value' }.to raise_error(/modify frozen/)
   end
 
   it "prevents you modifying the name of a value" do
-    lambda { Color::RED.name << 'dish-Brown' }.should raise_error(TypeError, /can't modify frozen/)
+    expect { Color::RED.name << 'dish-Brown' }.to raise_error(/modify frozen/)
+  end
+end
+
+describe "serialization (for ActiveRecord or what-have-you)" do
+  it "can serialize to and deserialize from its name string" do
+    serializer = Renum::NameSerializer.new Color
+    serializer.dump(Color::RED).should == "RED"
+    serializer.dump("RED").should == "RED" # for convenient param assignment
+    serializer.load("RED").should == Color::RED
+
+    serializer.dump(nil).should == nil
+    serializer.load(nil).should == nil
+  end
+
+  it "can serialize to and deserialize from its positional index" do
+    serializer = Renum::IndexSerializer.new Color
+    serializer.dump(Color::RED).should == 0
+    serializer.load(0).should == Color::RED
+
+    serializer.dump(nil).should == nil
+    serializer.load(nil).should == nil
   end
 end

data/spec/spec_helper.rb

@@ -1,12 +1,2 @@
-begin
-  require 'spec'
-rescue LoadError
-  require 'rubygems'
-  gem 'rspec'
-  require 'spec'
-end
-
-if ENV['USE_GEM']
-  require 'rubygems'
-end
+require 'rspec'
 require 'renum'

metadata

@@ -1,76 +1,92 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: renum
-version: !ruby/object:Gem::Version 
-  hash: 25
-  prerelease: false
-  segments: 
-  - 1
-  - 3
-  - 1
-  version: 1.3.1
+version: !ruby/object:Gem::Version
+  version: 1.4.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - John Hume
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2010-08-17 00:00:00 -04:00
-default_executable: 
-dependencies: []
-
+date: 2013-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &19725600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *19725600
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &19725120 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *19725120
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &19724600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *19724600
 description: provides a readable but terse enum facility for Ruby
 email: duelin.markers@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.textile
-files: 
+files:
+- .travis.yml
+- Gemfile
+- Gemfile.lock
 - README.textile
 - Rakefile
 - VERSION
 - lib/renum.rb
 - lib/renum/enumerated_value.rb
 - lib/renum/enumerated_value_type_factory.rb
+- lib/renum/index_serializer.rb
+- lib/renum/name_serializer.rb
 - renum.gemspec
 - spec/renum_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
 homepage: http://github.com/duelinmarkers/renum
 licenses: []
-
 post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
-require_paths: 
+rdoc_options: []
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: provides a readable but terse enum facility for Ruby
-test_files: 
-- spec/renum_spec.rb
-- spec/spec_helper.rb
+test_files: []