jeffp-enumerated_attribute 0.1.7 → 0.2.0.2

data/.gitignore

@@ -1,5 +1,12 @@
 .DS_Store
+**/*.log
 pkg
 rdoc
 coverage
-*.log
+doc
+log
+nbproject
+tmp
+vendor
+lib/tasks/*
+TODO.rdoc

data/README.rdoc

@@ -1,6 +1,8 @@
 = enumerated_attribute
 
-+enumerated_attribute+ simplifies the definition of enumeration-based attributes, their accessors, initializers and common predicate and enumeration methods.
+Easily code enumerations for your models and expose them as  
+drop-down lists with the +enum_select+ helper, or use any of +enumerated_attribute+ 
+features to simplify coding enumerations in any Ruby object.
 
 == Resources
 
@@ -12,13 +14,16 @@ Source
 
 * git://github.com/jeffp/enumerated_attribute.git
 
+Install
+
+* sudo gem install jeffp-enumerated_attribute --source=http://gems.github.com
+	
 == Description
 
 Enumerations are a common and useful pattern in programming.  Typically, in Ruby, 
 enumerated attributes are implemented with strings, symbols or constants.  Often the 
 developer is burdened with repeatedly defining common methods in support of each
-attribute.  Such repetition coding unnecessarily increases
-costs and wastes time.
+attribute.  Such repetition coding unnecessarily increases costs and wastes time.
 
 +enumerated_attribute+ simplifies the definition of enumerated attributes by emphasizing 
 convention and DRYing the implementation.  Repetitive code such as initializers, accessors, 
@@ -26,32 +31,78 @@ predicate and enumeration methods are automatically generated, resulting in bett
 encapsulation, quicker implementation and cleaner code.
 
 Features include:
-* Short and simple definition
+* ActiveRecord integration
+* ActionView form helpers
+* Configurable enumeration labels
 * Auto-defined attribute methods
 * Dynamically-generated predicate methods
-* Attribute initialization
-* Method definition short-hand (DSL)
-* ActiveRecord integration
+* Automatic initialization
+* Advanced configuration DSL
+
+== Setup
+
+For a Ruby application, install the gem and require it 
+
+  require 'enumerated_attribute'
+
+or for a rails application configure the gem in the config block of the
+config/environment.rb file
+
+  config.gem "jeffp-enumerated_attribute", :lib=>"enumerated_attribute"
+
+and run the gem install rake task
+
+  rake gems:install
+
 
-== Example
+== Rails Example
 
-Here's a quick example of what +enumerated_attribute+ can do:
+Here's an example of +enumerated_attribute+ features in a Rails application:
+
+In the migration, declare your enumeration attributes with +enum+
+
+  create_table :users, :force=>true do |t|
+    t.string :first_name
+    t.enum :gender
+    t.enum :degree
+    ...
+  end
+
+Define the enumerations in your models with +enum_attr+
+
+  class User < ActiveRecord::Base
+    enum_attr :gender, %w(male female)
+    enum_attr :degree, %w(^none high_school college graduate)
+  end
+
+Expose the enumeration in your forms with +enum_select+
+
+  <% form_for :user do |f| %>
+    <%= f.label :user %> <%= f.text_field :first_name %><br/>
+    <%= f.label :gender %> <%= f.enum_select :gender %><br/>
+    <%= f.label :degree %> <%= f.enum_select :degree %><br/>
+    <%= submit_tag 'save' %>
+  <% end %>
+
+The select options text can be customized.  See 'Customizing Labels' in the Integration section.
+
+== Ruby Example
+
+Here's an example of +enumerated_attribute+ features in a Ruby application:
 
   require 'enumerated_attribute'
   
   class Tractor
-    enum_attr :gear, %w(reverse ^neutral first second over_drive) do
-      driving? [:first, :second, :over_drive]
-      upshift { self.gear_is_not_in_over_drive? ? self.gear_next : self.gear }
-    end
+    enum_attr :gear, %w(reverse ^neutral first second over_drive)
+		
   end
   
   t = Tractor.new
   t.gear                            # => :neutral
-  t.gear_is_neutral?                # => true
-  t.driving?                        # => false
-  t.upshift                         # => :first
-  t.driving?                        # => true
+  t.neutral?                        # => true
+  t.gear_next                       # => :first
+  t.not_neutral?                    # => true
+  t.gear_previous                   # => :neutral
   t.gear = :second                  # => :second
   t.gear_is_not_in_first?           # => true
 
@@ -203,22 +254,25 @@ Alternatively, the :init option can be used to indicate the initial value of the
 
 ==== Setting Attributes to nil
 
-By default, the attribute setter does not allow nils unless the :nil option is set to true
-in the definition as demonstrated here:
+By default, the attribute setter allows nils unless the :nil option is set to false.
+When :nil is set to false, the attribute may initialize to nil, but may not be set
+to nil thereafter.
 
   class Tractor 
-    enum_attr :plow %w(^up down), :nil=>true
+    enum_attr :plow, %w(up down), :nil=>false
   end
   
   t = Tractor.new
-  t.plow                            # => :up
-  t.plow_nil?                       # => :false
-  t.plow = nil                      # => nil
-  t.plow_is_nil?                    # => true
-  t.plow_is_not_nil?                # => false
+  t.plow                            # => nil
+  t.plow_nil?                       # => true
+  t.plow = :up                      # => :up
+  t.plow_is_nil?                    # => false
+  t.plow_is_not_nil?                # => true
+  t.plow = nil                      # => raises error
   
 Regardless of the :nil option setting, the plugin can dynamically recognize and define
-predicate methods for testing 'nil' values.
+predicate methods for testing 'nil' values.  The setter methods also treat empty
+strings (or '') as nil values.
 
 
 ==== Changing Method Names
@@ -357,6 +411,62 @@ enumeration functionality is consistent across integrations.
   o.invoice                         # => "43556334-W84"
 	
 
+==== Labels
+
+Each enumeration value has a corresponding text label.  The defaults are made 
+up from the enumeration symbols.  For the Tractor class example:
+
+  t=Tractor.new
+  t.enums(:gear)                    # => [:reverse, :neutral, :first, :second, :over_drive]
+  t.enums(:gear).labels             # => ['Reverse', 'Neutral', 'First', 'Second', 'Over drive']
+
+The +enums(:attribute)+ method provides information about the attribute's enumerations. 
+It is the same as the plural form of the attribute name.  There are several kinds
+of information available from the +enums+ method.
+
+  t=Tractor.new
+  e = t.enums(:plow)                # => [:up, :down]
+  e.labels                          # => ['Up', 'Down']
+  e.hash                            # => {:up=>'Up', :down=>'Down'}
+  e.select_options                  # => [['Up', 'up'], ['Down', 'down']]
+  e.label(:up)                      # => 'Up'
+  
+==== Customizing Labels
+
+Labels can be customized as shown here:
+
+  class User < ActiveRecord::Base
+    enum_attr :contact_options, %w(none phone email mail) do
+      label :none=>'Please do not contact me'
+      label :phone=>'I would like a representative to call me'
+      label :email=>'I would like information via email'
+      label :mail=>'I would like information mailed to me'
+    end
+  end
+
+Likewise, the labels can be provided on the same line
+
+  class Tractor
+    enum_attr :gear, %w(reverse ^neutral first second over_drive) do
+      labels :first=>'1st Gear', :second=>'2nd Gear', :over_drive=>'Over Drive'
+    end
+  end
+
+==== View Helpers
+
+There are two +enum_select+ helpers, one for use with +form_for+ and one for use without
+it.  An example for form_for was given in the examples at the beginning.  Here's an
+example with the +form_tag+ and a @user object.
+
+  <% form_tag :action=>:register do %>
+    <%= label_tag 'First name' %>: <%= text_field :user, :first_name %><br/>
+    <%= label_tag 'Gender' %>: <%= enum_select :user, :gender %><br/>
+    <%= label_tag 'Degree' %>: <%= enum_select :user, :degree %><br/>
+    ...
+    <%= submit_tag 'Register' %>
+  <% end %>
+
+
 === Implementation Notes
 
 ==== New and Method_missing methods
@@ -366,7 +476,7 @@ implementations in the same class declaring an enumerated_attribute should come
 declaration; otherwise, the 'new' and 'method_missing' implementations must chain in order to avoid 
 overwriting the plugin's methods.  The best approach is shown here:
 
-  class A
+  class Soup
     def self.new(*args)
       ...
     end
@@ -376,24 +486,28 @@ overwriting the plugin's methods.  The best approach is shown here:
       ...
     end
 		
-    enum_attr :state, %w(cold warm hot boiling)
+    enum_attr temp:, %w(cold warm hot boiling)
   end
 
 
 == Testing
 
-The plugin uses RSpec for testing.  Make sure you have the RSpec gem installed:
+The plugin uses RSpec and Webrat for testing.  Make sure you have the RSpec gem installed:
 
-  gem install rspec
+  gem install rspec webrat
   
 To test the plugin for regular ruby objects, run:
 
-  rake spec
+  rake spec:object
 	
 Testing ActiveRecord integration requires the install of Sqlite3 and the 
 sqlite3-ruby gem.  To test ActiveRecord, run:
 
   rake spec:active_record
+
+And for testing +enum_select+ in form views:
+
+  rake spec:forms
 	
 To test all specs:
 
@@ -402,5 +516,5 @@ To test all specs:
 
 == Dependencies
 
-* ActiveRecord
+* ActiveRecord (but not required)
 * Sqlite3 and sqlite3-ruby gem (for testing)

data/Rakefile

@@ -5,12 +5,14 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name = 'enumerated_attribute'
-  s.version = '0.1.7'
+  s.version = '0.2.0.2'
   s.platform = Gem::Platform::RUBY
-  s.description = 'An enumerated attribute accessor'
-  s.summary = 'Add enumerated attributes with initialization, dynamic predicate methods, more ...'
+  s.description = 'Enumerated model attributes and view helpers'
+  s.summary = 'Add enumerated attributes to your models and expose them in drop-down lists in your views'
   
-  s.files = FileList['{examples,lib,tasks,spec}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc .gitignore) - FileList['**/*.log']
+  exclude_folders = 'spec/rails/{doc,lib,log,nbproject,tmp,vendor,test}'
+  exclude_files = FileList['**/*.log'] + FileList[exclude_folders+'/**/*'] + FileList[exclude_folders]
+  s.files = FileList['{examples,lib,tasks,spec}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc .gitignore) - exclude_files
   s.require_path = 'lib'
   s.has_rdoc = true
   s.test_files = Dir['spec/*_spec.rb']
@@ -24,24 +26,37 @@ require 'spec/version'
 require 'spec/rake/spectask'
 
 desc "Run specs"
-Spec::Rake::SpecTask.new(:spec) do |t|
-	t.spec_files = FileList['spec/*_spec.rb']
-	t.libs << 'lib' << 'spec'
-	t.rcov = false
-	#t.spec_opts = ['--options', 'spec/spec.opts']
-	#t.rcov_dir = 'coverage'
-	#t.rcov_opts = ['--exclude', "kernel,load-diff-lcs\.rb,instance_exec\.rb,lib/spec.rb,lib/spec/runner.rb,^spec/*,bin/spec,examples,/gems,/Library/Ruby,\.autotest,#{ENV['GEM_HOME']}"]
-end
 
 namespace :spec do
+	task :default=>:object
+	Spec::Rake::SpecTask.new(:object) do |t|
+		t.spec_files = FileList['spec/*_spec.rb']
+		t.libs << 'lib' << 'spec'
+		t.rcov = false
+		t.spec_opts = ['--options', 'spec/spec.opts']
+		#t.rcov_dir = 'coverage'
+		#t.rcov_opts = ['--exclude', "kernel,load-diff-lcs\.rb,instance_exec\.rb,lib/spec.rb,lib/spec/runner.rb,^spec/*,bin/spec,examples,/gems,/Library/Ruby,\.autotest,#{ENV['GEM_HOME']}"]
+	end
   desc "Run ActiveRecord integration specs"
 	Spec::Rake::SpecTask.new(:active_record) do |t|
 		t.spec_files = FileList['spec/active_record/*_spec.rb']
 		t.libs << 'lib' << 'spec/active_record'
+		t.spec_opts = ['--options', 'spec/spec.opts']    
+		t.rcov = false
+	end
+	Spec::Rake::SpecTask.new(:forms) do |t|
+		t.spec_files = FileList['spec/rails/spec/integrations/*_spec.rb']
+		t.libs << 'lib' << 'spec/rails/spec'
+		t.spec_opts = ['--options', 'spec/spec.opts']    
 		t.rcov = false
 	end
+#	Spec::Rake::SpecTask.new(:associations) do |t|
+#		t.spec_files = FileList['spec/active_record/associations_spec.rb']
+#		t.libs << 'lib' << 'spec/active_record'
+#		t.rcov = false
+#	end
 	desc "Run all specs"
-	task :all=>[:spec, :active_record] 
+	task :all=>[:object, :active_record, :forms] 
 end
 
 
@@ -63,7 +78,7 @@ end
  
 Rake::GemPackageTask.new(spec) do |p|
   p.gem_spec = spec
-  p.need_tar = true
+  p.need_tar = RUBY_PLATFORM =~ /mswin/ ? false : true
   p.need_zip = true
 end
 

data/lib/enumerated_attribute.rb

@@ -20,4 +20,3 @@ Class.class_eval do
   include EnumeratedAttribute::MacroMethods
 end
 
-

data/lib/enumerated_attribute/attribute.rb

@@ -1,5 +1,8 @@
+require 'enumerated_attribute/attribute/attribute_descriptor'
 require 'enumerated_attribute/method_definition_dsl'
 require 'enumerated_attribute/integrations'
+require 'enumerated_attribute/rails_helpers'
+
 
 module EnumeratedAttribute
 
@@ -24,7 +27,7 @@ module EnumeratedAttribute
 
 				initial_value = nil
 				plural_name = opts[:plural] || opts[:enums_accessor] || opts[:enums] || begin 
-					case
+				case
 					when attr_name =~ /[aeiou]y$/
 						"#{attr_name}s"
 					when attr_name =~ /y$/
@@ -38,15 +41,13 @@ module EnumeratedAttribute
 				incrementor = opts[:incrementor] || opts[:inc] || "#{attr_name}_next"
 				decrementor = opts[:decrementor] || opts[:dec] || "#{attr_name}_previous"
 
-				enums = enums.map{|v| (v =~ /^\^/ ? (initial_value = v[1, v.length-1].to_sym) : v.to_sym )}
-
+				enums = enums.map{|v| (v =~ /^\^/ ? (initial_value ||= v[1, v.length-1].to_sym) : v.to_sym )}
+				
 				class_eval <<-ATTRIB
-					@@enumerated_attribute_names ||= []
-					@@enumerated_attribute_names << '#{attr_name}'
-					@@enumerated_attribute_options ||={}
-					@@enumerated_attribute_options[:#{attr_name}] = {#{opts.to_a.map{|v| ':'+v.first.to_s+'=>:'+v.last.to_s}.join(', ')}}
-					@@enumerated_attribute_values ||= {}
-					@@enumerated_attribute_values[:#{attr_name}] = [:#{enums.join(',:')}]
+					def self.enumerated_attributes; @@enumerated_attributes; end
+					def enums(attr); @@enumerated_attributes[attr.to_sym]; end
+					@@enumerated_attributes ||= {}
+					@@enumerated_attributes[:#{attr_name}] = AttributeDescriptor.new(:#{attr_name}, #{enums.inspect}, #{opts.inspect})
 				ATTRIB
 				
 				#define_enumerated_attribute_[writer, reader] may be modified in a named Integrations module (see Integrations::ActiveRecord)
@@ -60,16 +61,17 @@ module EnumeratedAttribute
 						include(@integration_map[:module]) if @integration_map[:module]
 						
 						def self.has_enumerated_attribute?(name)
-							@@enumerated_attribute_names.include?(name.to_s)
+							return(false) if name.nil?
+							@@enumerated_attributes.key?(name.to_sym)
 						end
 						def self.enumerated_attribute_allows_nil?(name)
-							return (false) unless @@enumerated_attribute_options[name.to_sym]
-							@@enumerated_attribute_options[name.to_sym][:nil] || false
+							return(false) unless (descriptor = @@enumerated_attributes[name.to_sym])
+							descriptor.allows_nil?
 						end
 						def self.enumerated_attribute_allows_value?(name, value)
-							return (false) unless @@enumerated_attribute_values[name.to_sym]
-							return enumerated_attribute_allows_nil?(name) if value == nil
-							@@enumerated_attribute_values[name.to_sym].include?(value.to_sym)
+							return (false) unless (descriptor = @@enumerated_attributes[name.to_sym])
+							return descriptor.allows_nil? if (value == nil || value == '')
+							descriptor.allows_value?(value)
 						end
 					end
 				MAP
@@ -114,7 +116,7 @@ module EnumeratedAttribute
 							middle = meth_name.chop #remove the ?
 							
 							attr = nil
-							@@enumerated_attribute_names.each do |name|
+							@@enumerated_attributes.keys.each do |name|
 								if middle.sub!(Regexp.new("^"+name.to_s), "")
 									attr = name; break
 								end
@@ -122,16 +124,16 @@ module EnumeratedAttribute
 							
 							value = nil
 							attr_sym = attr ? attr.to_sym : nil
-							if (enum_values = @@enumerated_attribute_values[attr_sym] )	#nil if [nil]
-								enum_values.each do |v|
+							if (descriptor = @@enumerated_attributes[attr_sym])
+								descriptor.enums.each do |v|
 									if middle.sub!(Regexp.new(v.to_s+"$"), "")
 										value = v; break
 									end
 								end	
 							else
 								#search through enum values one at time and identify any ambiguities
-								@@enumerated_attribute_values.each do |attr_key,enums|
-									enums.each do|v|
+								@@enumerated_attributes.each do |attr_key,descriptor|
+									descriptor.enums.each do|v|
 										if middle.match(v.to_s+"$")
 											raise(AmbiguousMethod, meth_name+" is ambiguous, use something like "+attr_sym.to_s+(middle[0,1]=='_'? '' : '_')+middle+"? or "+attr_key.to_s+(middle[0,1]=='_'? '' : '_')+middle+"?", caller) if attr_sym
 											attr_sym = attr_key
@@ -170,7 +172,7 @@ module EnumeratedAttribute
 				#create state and action methods from block
 				initial_value = opts[:init] || initial_value  
 				if block_given?
-					m = EnumeratedAttribute::MethodDefinitionDSL.new(self, attr_name, enums)
+					m = EnumeratedAttribute::MethodDefinitionDSL.new(self, enumerated_attributes[attr_sym]) #attr_name, enums)
 					m.instance_eval(&block)
 					initial_value = m.initial_value || initial_value
 					plural_name = m.pluralized_name || plural_name
@@ -181,16 +183,16 @@ module EnumeratedAttribute
 				#define the enum values accessor
 				class_eval <<-ENUM
 					def #{plural_name}
-						@@enumerated_attribute_values[:#{attr_name}]
+						@@enumerated_attributes[:#{attr_name}]
 					end
 					def #{incrementor}
-						z = @@enumerated_attribute_values[:#{attr_name}]
-						index = z.index(@#{attr_name})
+						z = @@enumerated_attributes[:#{attr_name}].enums
+						index = z.index(read_enumerated_attribute(:#{attr_name}))
 						write_enumerated_attribute(:#{attr_name}, z[index >= z.size-1 ? 0 : index+1])
 					end
 					def #{decrementor}
-						z = @@enumerated_attribute_values[:#{attr_name}]
-						index = z.index(@#{attr_name})
+						z = @@enumerated_attributes[:#{attr_name}].enums
+						index = z.index(read_enumerated_attribute(:#{attr_name}))
 						write_enumerated_attribute(:#{attr_name}, z[index > 0 ? index-1 : z.size-1])
 					end
 				ENUM