jeffp-enumerated_attribute 0.1.1 → 0.1.2

data/CHANGELOG.rdoc

@@ -1,5 +1,12 @@
 == master
 
+== 0.1.2 / 2009-07-11
+
+* Added 'is_not' for negated custom method definitions
+* Added dynamic creation of 'nil' predicate methods
+* Refactored MethodDefinitionDSL
+* Added EnumeratedAttribute::MethodDefinition 
+
 == 0.1.1 / 2009-07-09
 
 * Added enum_attr_reader and enum_attr_writer

data/README.rdoc

@@ -63,7 +63,7 @@ form of +enumerated_attribute+ looks like this:
   
 Defining the attribute :gear has done a number things.  
 It has generated an instance variable '@gear', read/write accessors for the 
-attribute and three support methods
+attribute and support methods
 for the enumeration, including an incrementor and decrementor.  These methods are 
 demonstrated below using the Tractor class defined above:
 
@@ -72,9 +72,9 @@ demonstrated below using the Tractor class defined above:
 
   t = Tractor.new
   t.gear                            # => :neutral
-  t.gear= :reverse                  # => :reverse
+  t.gear = :reverse                 # => :reverse
   t.gear                            # => :reverse
-  t.gear= :third
+  t.gear = :third
   # => ArgumentError: 'third' is not an enumerated value for gear attribute
   
   t.gears                           # => [:reverse, :neutral, :first, :second, :over_drive]
@@ -144,7 +144,7 @@ the +initialize+ method.  Two ways are demonstrated here:
     enum_attr :front_light, %w(off low high), :init=>:off
   end
   
-  t=Tractor.new
+  t = Tractor.new
   t.gear                            # => :neutral
   t.front_light                     # => :off
 
@@ -157,6 +157,26 @@ The plugin recognizes that the gear attribute is to be initialized to :neutral.
 Alternatively, the :init option can be used to indicate the initial value of the attribute.
 
 
+==== 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:
+
+  class Tractor 
+    enum_attr :plow %w(^up down), :nil=>true
+  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
+  
+Regardless of the :nil option setting, the plugin can dynamically recognize and define
+predicate methods for testing 'nil' values.
+
+
 ==== Changing Method Names
 
 The plugin provides options for changing the method names of the enumeration accessor, incrementor
@@ -167,7 +187,7 @@ and decrementor (ie, +gears+, +gear_next+, +gear_previous+):
         :inc=>'lights_inc', :dec=>'lights_dec'
   end
   
-  t=Tractor.new
+  t = Tractor.new
   t.lights_values                   # => [:off, :low, :high]
   t.lights_inc                      # => :low
   t.lights_dec                      # => :off
@@ -187,13 +207,13 @@ the plugin provides a short-hand for defining these methods in the
 +enumerated_attribute+ block.
 
   class Tractor
-    enum_attr :gear, %(reverse ^neutral first second over_drive) do
+    enum_attr :gear, %w(reverse ^neutral first second over_drive) do
       parked? :neutral
       driving? [:first, :second, :third]
     end
   end
 
-  t=Tractor.new
+  t = Tractor.new
   t.parked?                         # => true
   t.driving?                        # => false
   
@@ -203,16 +223,29 @@ The first method, parked?, defines a method which evaluates
 the code {@gear == :neutral}.  The second method, driving?, evaluates
 to true if the attribute is set to one of the enumeration values defined in the array 
 [:first, :second, :third].
-  
+
+The same short-hand can be used to define methods where the attribute 'is not' equal to the
+indicated value or 'is not' included in the array of values.
+
+  class Tractor
+    enum_attr :gear, %w(reverse ^neutral first second over_drive) do
+      not_parked? is_not :neutral
+      not_driving? is_not [:first, :second, :third]
+    end
+  end
+
+
+==== Defining Other Methods With Blocks
+
 For predicate methods requiring fancier logic,
 a block can be used to define the method body.
 
   class Tractor
-    enum_attr :gear, %(reverse ^neutral first second over_drive) do
+    enum_attr :gear, %w(reverse ^neutral first second over_drive) do
       parked? :neutral
       driving? [:first, :second, :third]
     end
-    enum_attr :plow, %(^up down), :plural=>:plow_values do
+    enum_attr :plow, %w(^up down), :plural=>:plow_values do
       plowing? { self.gear_is_in_first? && @plow == :down }
     end
   end
@@ -227,7 +260,7 @@ can be defined to manipulate the attributes.  Here, two methods are defined acti
 as bounded incrementor and decrementor of the gear attribute.
 
   class Tractor
-    enum_attr :gear, %(reverse ^neutral first second over_drive) do
+    enum_attr :gear, %w(reverse ^neutral first second over_drive) do
       parked? :neutral
       driving? [:first, :second, :third]
       upshift { self.gear_is_in_over_drive? ? self.gear : self.gear_next }
@@ -236,11 +269,11 @@ as bounded incrementor and decrementor of the gear attribute.
   end
   
   t = Tractor.new
-  t.gear                          # => :neutral
+  t.gear                            # => :neutral
   10.times { t.upshift }
-  t.gear                          # => :over_drive
+  t.gear                            # => :over_drive
   10.times { t.downshift }
-  t.gear                          # => :neutral
+  t.gear                            # => :neutral
   
 Methods +upshift+ and +downshift+ use the automatically generated 
 incrementor and decrementor as

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
  
 spec = Gem::Specification.new do |s|
   s.name = 'enumerated_attribute'
-  s.version = '0.1.1'
+  s.version = '0.1.2'
   s.platform = Gem::Platform::RUBY
   s.description = 'A enumerated attribute accessor'
   s.summary = 'Defines enumerated attributes, initial state and dynamic state methods.'

data/lib/enumerated_attribute.rb

@@ -1,9 +1,12 @@
 module EnumeratedAttribute
 
+#todo: is_not/is -- test raised errors contain useful info on invalid syntax
+#todo: dynamic_enums
 #todo: system wide constants
 #todo: setter_callback
 #todo: ArgumentError may need to use Errors for ActiveRecord
 #todo: test new chaining plays nice
+#todo: attribute methods gear.enums, gear.inc, gear.dec
 
   def enum_attr_reader(*args, &block)
     if args.length > 1
@@ -86,11 +89,11 @@ module EnumeratedAttribute
         def parse_dynamic_method_parts(meth_name)
           return(nil) unless meth_name[-1, 1] == '?'
           
-          meth_name.chop! #remove the ?
+          middle = meth_name.chop #remove the ?
           
           attr = nil
           @@enumerated_attribute_names.each do |name|
-            if meth_name.sub!(Regexp.new("^"+name.to_s), "")
+            if middle.sub!(Regexp.new("^"+name.to_s), "")
               attr = name; break
             end
           end
@@ -100,23 +103,26 @@ module EnumeratedAttribute
           value = nil
           if @@enumerated_attribute_values.key?(attr_sym)
             @@enumerated_attribute_values[attr_sym].each do |v|
-              if meth_name.sub!(Regexp.new(v.to_s+"$"), "")
+              if middle.sub!(Regexp.new(v.to_s+"$"), "")
                 value = v; break
               end
             end
           end
-          return (nil) unless value
+          unless value #check for nil?
+            return (nil) unless middle.sub!(Regexp.new('nil$'), "")
+            value = nil
+          end
           
-          [attr, value, meth_name]
+          [attr, middle, value]
         end
       
         def define_enumerated_attribute_dynamic_method(methId)
           meth_name = methId.id2name
           return(false) unless (parts = parse_dynamic_method_parts(meth_name))
-          return(false) unless parts
           
-          negated = !!parts[2].downcase.match(/_not_/)
-          self.class.define_attribute_state_method(methId, parts[0], parts[1].to_sym, negated)
+          negated = !!parts[1].downcase.match(/_not_/)
+          value = parts[2] ? parts[2].to_sym : nil
+          self.class.define_enumerated_attribute_custom_method(methId, parts[0], value, negated)
           
           true
         end
@@ -124,7 +130,7 @@ module EnumeratedAttribute
     METHOD
 
     #create state and action methods from block
-    initial_value = opts[:init] || initial_value
+    initial_value = opts[:init] || initial_value  
     if block_given?
       m = EnumeratedAttribute::MethodDefinitionDSL.new(self, attr_name, enums)
       m.instance_eval(&block)
@@ -150,9 +156,6 @@ module EnumeratedAttribute
           index = z.index(@#{attr_name})
           @#{attr_name} = z[index > 0 ? index-1 : z.size-1]
         end
-        def #{attr_name}_nil?
-          @#{attr_name} == nil
-        end
       ENUM
     end
     
@@ -182,7 +185,7 @@ module EnumeratedAttribute
   #a short cut
   alias :enum_attr :enumerated_attribute
   
-  def define_attribute_state_method(symbol, attr_name, value, negated)
+  def define_enumerated_attribute_custom_method(symbol, attr_name, value, negated)
     define_method symbol do
       ival = instance_variable_get('@'+attr_name)
       negated ? ival != value : ival == value
@@ -208,51 +211,74 @@ module EnumeratedAttribute
   
   public
   
+  class MethodDefinition
+    attr_accessor :method_name, :negated, :argument    
+    
+    def initialize(name, arg, negated=false)
+      @method_name = name
+      @negated = negated
+      @argument = arg
+    end
+    
+    def is_predicate_method?
+      @method_name[-1, 1] == '?'
+    end
+    def has_method_name?
+      !!@method_name
+    end
+    def has_argument?
+      !!@argument
+    end    
+    
+  end
+  
   class MethodDefinitionDSL
     attr_reader :initial_value, :pluralized_name, :decrementor_name, :incrementor_name
     
     def initialize(class_obj, attr_name, values=[])
       @class_obj = class_obj
       @attr_name = attr_name
-      @attr_values = values
+      @attr_values = values      
+    end
+    
+    #we'll by pass this - they can use it if it helps make code more readable - not enforced - should it be??
+    def define
+    end
+    
+    def is_not(*args)
+      arg = args[0] if args.length > 0
+      MethodDefinition.new(nil, arg, true)
+    end
+    alias :isnt :is_not
+    
+    def is(*args)
+      arg = args[0] if args.length > 0
+      MethodDefinition.new(nil, arg)
     end
 
     def method_missing(methId, *args, &block)
       meth_name = methId.id2name
-      if meth_name[-1,1] != '?'
-        #not a state method - this must include either a proc or block - no short cuts
-        if args.size > 0
-          arg = args[0]
-          if arg.instance_of?(Proc)
-            @class_obj.send(:define_method, methId, arg)
-            return 
-          end
-        elsif block_given?
-          @class_obj.send(:define_method, methId, block)
-          return
-        end
-        raise ArgumentError, "method '#{meth_name}' must be followed by a proc or block", caller
-      end
-
-      if (args.size > 0)
+      
+      meth_def = nil
+      if args.size > 0
         arg = args[0]
-        case arg
-        when Symbol 
-          return create_method_from_symbol_or_string(meth_name, arg)
-        when String
-          return create_method_from_symbol_or_string(meth_name, arg)
-        when Array
-          return create_method_from_array(meth_name, arg)
-        when Proc
-          @class_obj.send(:define_method, methId, arg)
-          return
+        if arg.instance_of?(EnumeratedAttribute::MethodDefinition)
+          if arg.has_method_name?
+            raise_method_syntax_error(meth_name, arg.method_name)
+          end
+          meth_def = arg
+          meth_def.method_name = meth_name
+        else
+          meth_def = MethodDefinition.new(meth_name, arg)
         end
       elsif block_given?
-        @class_obj.send(:define_method, methId, block)
-        return
+        meth_def = MethodDefinition.new(meth_name, block)
+      else
+        raise_method_syntax_error(meth_name)
       end
-      raise ArgumentError , "method '#{meth_name}' for :#{@attr_name} attribute must be followed by a symbol, array, proc or block", caller   
-    end
+      evaluate_method_definition(meth_def)
+    end        
+      
      
     def init(value)
       if (!@attr_values.empty? && !@attr_values.include?(value.to_sym))
@@ -271,22 +297,56 @@ module EnumeratedAttribute
     
     private
     
-    def create_method_from_symbol_or_string(meth_name, arg)
-      if (!@attr_values.empty? && !@attr_values.include?(arg.to_sym))  
-        raise(NameError, "'#{arg}' in method '#{meth_name}' is not an enumeration value for :#{@attr_name} attribute", caller) 
+    def raise_method_syntax_error(meth_name, offending_token=nil)
+      suffix = offending_token ? "found '#{offending_token}'" : "found nothing" 
+      followed_by = (meth_name[-1,1] == '?' ? "is_not, an enumeration value, an array of enumeration values, " : "") + "a proc, lambda or code block"
+      raise NameError, "'#{meth_name}' should be followed by #{followed_by} -- but #{suffix}"
+    end
+        
+    def evaluate_method_definition(mdef)
+      unless mdef.has_argument?
+        return raise_method_syntax_error(mdef.method_name)
+      end
+      
+      if mdef.is_predicate_method?
+        case mdef.argument
+          when String
+            return create_custom_method_for_symbol_or_string(mdef)
+          when Symbol
+            return create_custom_method_for_symbol_or_string(mdef)
+          when Array
+            return create_custom_method_for_array_of_enums(mdef)
+          when Proc
+            return create_custom_method_for_proc(mdef)            
+        end
+      else #action method
+        if mdef.argument.instance_of?(Proc)
+          return create_custom_method_for_proc(mdef)
+        end
+      end
+      raise_method_syntax_error(mdef.method_name, mdef.argument)
+    end
+    
+    def create_custom_method_for_proc(mdef)
+      @class_obj.send(:define_method, mdef.method_name, mdef.argument)
+    end
+    
+    def create_custom_method_for_symbol_or_string(mdef)
+      if (!@attr_values.empty? && !@attr_values.include?(mdef.argument.to_sym))
+        raise(NameError, "'#{mdef.argument}' in method '#{mdef.method_name}' is not an enumeration value for :#{@attr_name} attribute", caller) 
       end
-      @class_obj.class_eval("def #{meth_name}; @#{@attr_name} == :#{arg}; end") 
+      @class_obj.class_eval("def #{mdef.method_name}; @#{@attr_name} #{mdef.negated ? '!=' : '=='} :#{mdef.argument}; end") 
     end
 
-    def create_method_from_array(meth_name, arg)
+    def create_custom_method_for_array_of_enums(mdef)
       if !@attr_values.empty?
-        arg.each do |m|
+        mdef.argument.each do |m|
           if !@attr_values.include?(m.to_sym)
-            raise(NameError, "'#{m}' in method '#{meth_name}' is not an enumeration value for :#{@attr_name} attribute", caller) 
+            raise(NameError, "'#{m}' in method '#{mdef.method_name}' is not an enumeration value for :#{@attr_name} attribute", caller) 
           end
         end
       end
-      @class_obj.class_eval("def #{meth_name}; [:#{arg.join(',:')}].include?(@#{@attr_name}); end")
+      @class_obj.class_eval("def #{mdef.method_name}; #{mdef.negated ? '!' : ''}[:#{mdef.argument.join(',:')}].include?(@#{@attr_name}); end")
     end
   end  
 end

data/spec/tractor.rb

@@ -13,8 +13,10 @@ class Tractor
   end
   
   enumerated_attribute :gear, %w(reverse ^neutral first second over_drive) do
-    parked? :neutral
-    driving? [:first, :second, :over_drive]
+    parked? is :neutral 
+    driving? is [:first, :second, :over_drive]
+    not_parked? isnt :neutral
+    not_driving? is_not [:first, :second, :over_drive]
     upshift { self.gear_is_in_over_drive? ? self.gear : self.gear_next }
     downshift { self.driving? ? self.gear_previous : self.gear }
   end

data/spec/tractor_spec.rb

@@ -1,6 +1,41 @@
 require 'tractor'
 
 describe "Tractor" do
+  
+  it "should dynamically create :plow_nil? and :plow_not_nil?" do
+    t=Tractor.new
+    t.plow_nil?.should be_false
+    t.plow_not_nil?.should be_true
+    t.plow = nil
+    t.plow_not_nil?.should be_false
+    t.plow_nil?.should be_true
+    Tractor.instance_methods(false).should include('plow_nil?')
+    Tractor.instance_methods(false).should include('plow_not_nil?')
+  end
+  
+  it "should dynamically create :plow_is_nil? and :plow_is_not_nil?" do
+    t=Tractor.new
+    t.plow_is_nil?.should be_false
+    t.plow_is_not_nil?.should be_true
+    t.plow = nil
+    t.plow_is_not_nil?.should be_false
+    t.plow_is_nil?.should be_true
+    Tractor.instance_methods(false).should include('plow_is_nil?')
+    Tractor.instance_methods(false).should include('plow_is_not_nil?')    
+  end
+  
+  it "should negate result for not_parked? defined with is_not" do
+    t=Tractor.new
+    t.gear = :neutral
+    t.not_parked?.should be_false
+  end
+  
+  it "should negate result for not_driving? defined with is_not" do
+    t=Tractor.new
+    t.gear = :neutral
+    t.not_driving?.should be_true
+  end
+  
   it "should have getter but no setter for :temperature" do
     Tractor.instance_methods.should_not include('temperature=')
     Tractor.instance_methods.should include('temperature')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: jeffp-enumerated_attribute
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Jeff Patmon
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-09 00:00:00 -07:00
+date: 2009-07-11 00:00:00 -07:00
 default_executable: 
 dependencies: []