activemodel 3.0.pre → 3.0.0.rc

data/CHANGELOG

@@ -1,4 +1,47 @@
-*Edge*
+*Rails 3.0.0 [release candidate] (July 26th, 2010)*
+
+* Added ActiveModel::MassAssignmentSecurity [Eric Chapweske, Josh Kalderimis]
+
+
+*Rails 3.0.0 [beta 4] (June 8th, 2010)*
+
+* JSON supports a custom root option: to_json(:root => 'custom')  #4515 [Jatinder Singh]
+
+
+*Rails 3.0.0 [beta 3] (April 13th, 2010)*
+
+* No changes
+
+
+*Rails 3.0.0 [beta 2] (April 1st, 2010)*
+
+* #new_record? and #destroyed? were removed from ActiveModel::Lint. Use
+  persisted? instead. A model is persisted if it's not a new_record? and it was 
+  not destroyed? [MG]
+
+* Added validations reflection in ActiveModel::Validations [JV]
+
+    Model.validators
+    Model.validators_on(:field)
+
+* #to_key was added to ActiveModel::Lint so we can generate DOM IDs for
+  AMo objects with composite keys [MG]
+
+
+*Rails 3.0.0 [beta 1] (February 4, 2010)*
+
+* ActiveModel::Observer#add_observer!
+
+  It has a custom hook to define after_find that should really be in a
+  ActiveRecord::Observer subclass:
+
+	  def add_observer!(klass)
+	    klass.add_observer(self)
+	    klass.class_eval 'def after_find() end' unless
+				klass.respond_to?(:after_find)
+	  end
+
+* Change the ActiveModel::Base.include_root_in_json default to true for Rails 3 [DHH]
 
 * Add validates_format_of :without => /regexp/ option. #430 [Elliot Winkler, Peer Allan]
 

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2004-2009 David Heinemeier Hansson
+Copyright (c) 2004-2010 David Heinemeier Hansson
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -0,0 +1,184 @@
+= Active Model -- model interfaces for Rails
+
+Active Model provides a known set of interfaces for usage in model classes.
+They allow for Action Pack helpers to interact with non-ActiveRecord models,
+for example. Active Model also helps building custom ORMs for use outside of
+the Rails framework.
+
+Prior to Rails 3.0, if a plugin or gem developer wanted to have an object
+interact with Action Pack helpers, it was required to either copy chunks of
+code from Rails, or monkey patch entire helpers to make them handle objects
+that did not exacly conform to the Active Record interface. This would result
+in code duplication and fragile applications that broke on upgrades.
+
+Active Model solves this. You can include functionality from the following
+modules:
+
+* Add attribute magic to objects
+
+    class Person
+      include ActiveModel::AttributeMethods
+      
+      attribute_method_prefix 'clear_'
+      define_attribute_methods [:name, :age]
+      
+      attr_accessor :name, :age
+      
+      def clear_attribute(attr)
+        send("#{attr}=", nil)
+      end
+    end
+    
+    person.clear_name
+    person.clear_age
+  
+  {Learn more}[link:classes/ActiveModel/AttributeMethods.html]
+  
+* Callbacks for certain operations
+
+    class Person
+      extend ActiveModel::Callbacks
+      define_model_callbacks :create
+    
+      def create
+        _run_create_callbacks do
+          # Your create action methods here
+        end
+      end
+    end
+  
+  This generates +before_create+, +around_create+ and +after_create+
+  class methods that wrap your create method.
+  
+  {Learn more}[link:classes/ActiveModel/CallBacks.html]
+
+* Tracking value changes
+
+  The ActiveModel::Dirty module allows for tracking attribute changes:
+
+    person = Person.new
+    person.name # => nil
+    person.changed? # => false
+    person.name = 'bob'
+    person.changed? # => true
+    person.changed # => ['name']
+    person.changes # => { 'name' => [nil, 'bob'] }
+    person.name = 'robert'
+    person.save
+    person.previous_changes # => {'name' => ['bob, 'robert']}
+  
+  {Learn more}[link:classes/ActiveModel/Dirty.html]
+
+* Adding +errors+ interface to objects
+
+  Exposing error messages allows objects to interact with Action Pack
+  helpers seamlessly.
+  
+    class Person
+    
+      def initialize
+        @errors = ActiveModel::Errors.new(self)
+      end
+    
+      attr_accessor :name
+      attr_reader   :errors
+    
+      def validate!
+        errors.add(:name, "can not be nil") if name == nil
+      end
+    
+      def ErrorsPerson.human_attribute_name(attr, options = {})
+        "Name"
+      end
+    
+    end
+    
+    person.errors.full_messages
+    # => ["Name Can not be nil"]
+    
+    person.errors.full_messages
+    # => ["Name Can not be nil"]
+
+  {Learn more}[link:classes/ActiveModel/Errors.html]
+
+* Model name introspection
+
+    class NamedPerson
+      extend ActiveModel::Naming
+    end
+    
+    NamedPerson.model_name        #=> "NamedPerson"
+    NamedPerson.model_name.human  #=> "Named person"
+
+  {Learn more}[link:classes/ActiveModel/Naming.html]
+
+* Observer support
+
+  ActiveModel::Observers allows your object to implement the Observer
+  pattern in a Rails App and take advantage of all the standard observer
+  functions.
+  
+  {Learn more}[link:classes/ActiveModel/Observer.html]
+
+* Making objects serializable
+
+  ActiveModel::Serialization provides a standard interface for your object
+  to provide +to_json+ or +to_xml+ serialization.
+  
+    s = SerialPerson.new
+    s.serializable_hash   # => {"name"=>nil}
+    s.to_json             # => "{\"name\":null}"
+    s.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
+  
+  {Learn more}[link:classes/ActiveModel/Serialization.html]
+
+* Internationalization (i18n) support
+
+    class Person
+      extend ActiveModel::Translation
+    end
+    
+    Person.human_attribute_name('my_attribute')
+    #=> "My attribute"
+  
+  {Learn more}[link:classes/ActiveModel/Translation.html]
+
+* Validation support
+
+   class Person
+     include ActiveModel::Validations
+
+     attr_accessor :first_name, :last_name
+
+     validates_each :first_name, :last_name do |record, attr, value|
+       record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z
+     end
+   end
+
+   person = Person.new
+   person.first_name = 'zoolander'
+   person.valid?  #=> false
+
+  {Learn more}[link:classes/ActiveModel/Validations.html]
+  
+* Custom validators
+
+   class Person
+     include ActiveModel::Validations
+     validates_with HasNameValidator
+     attr_accessor :name
+   end
+   
+   class HasNameValidator < ActiveModel::Validator
+     def validate(record)
+      record.errors[:name] = "must exist" if record.name.blank?
+     end
+   end
+   
+   p = ValidatorPerson.new
+   p.valid?                  #=>  false
+   p.errors.full_messages    #=> ["Name must exist"]
+   p.name = "Bob"
+   p.valid?                  #=>  true
+
+  {Learn more}[link:classes/ActiveModel/Validator.html]

data/lib/active_model.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2004-2009 David Heinemeier Hansson
+# Copyright (c) 2004-2010 David Heinemeier Hansson
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,32 +21,42 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
-activesupport_path = "#{File.dirname(__FILE__)}/../../activesupport/lib"
-$:.unshift(activesupport_path) if File.directory?(activesupport_path)
+activesupport_path = File.expand_path('../../../activesupport/lib', __FILE__)
+$:.unshift(activesupport_path) if File.directory?(activesupport_path) && !$:.include?(activesupport_path)
 require 'active_support'
 
+
 module ActiveModel
-  autoload :AttributeMethods, 'active_model/attribute_methods'
-  autoload :Conversion, 'active_model/conversion'
-  autoload :DeprecatedErrorMethods, 'active_model/deprecated_error_methods'
-  autoload :Dirty, 'active_model/dirty'
-  autoload :Errors, 'active_model/errors'
-  autoload :Lint, 'active_model/lint'
+  extend ActiveSupport::Autoload
+
+  autoload :AttributeMethods
+  autoload :BlockValidator, 'active_model/validator'
+  autoload :Callbacks
+  autoload :Conversion
+  autoload :DeprecatedErrorMethods
+  autoload :Dirty
+  autoload :EachValidator, 'active_model/validator'
+  autoload :Errors
+  autoload :Lint
+  autoload :MassAssignmentSecurity
   autoload :Name, 'active_model/naming'
-  autoload :Naming, 'active_model/naming'
+  autoload :Naming
   autoload :Observer, 'active_model/observing'
-  autoload :Observing, 'active_model/observing'
-  autoload :Serialization, 'active_model/serialization'
-  autoload :StateMachine, 'active_model/state_machine'
-  autoload :TestCase, 'active_model/test_case'
-  autoload :Validations, 'active_model/validations'
-  autoload :ValidationsRepairHelper, 'active_model/validations_repair_helper'
-  autoload :VERSION, 'active_model/version'
+  autoload :Observing
+  autoload :Serialization
+  autoload :TestCase
+  autoload :Translation
+  autoload :VERSION
+  autoload :Validations
+  autoload :Validator
 
   module Serializers
-    autoload :JSON, 'active_model/serializers/json'
-    autoload :Xml, 'active_model/serializers/xml'
+    extend ActiveSupport::Autoload
+
+    autoload :JSON
+    autoload :Xml
   end
 end
 
+require 'active_support/i18n'
 I18n.load_path << File.dirname(__FILE__) + '/active_model/locale/en.yml'

data/lib/active_model/attribute_methods.rb

@@ -4,39 +4,108 @@ require 'active_support/core_ext/class/inheritable_attributes'
 module ActiveModel
   class MissingAttributeError < NoMethodError
   end
-
+  # == Active Model Attribute Methods
+  #
+  # <tt>ActiveModel::AttributeMethods</tt> provides a way to add prefixes and suffixes
+  # to your methods as well as handling the creation of Active Record like class methods
+  # such as +table_name+.
+  # 
+  # The requirements to implement ActiveModel::AttributeMethods are to:
+  #
+  # * <tt>include ActiveModel::AttributeMethods</tt> in your object
+  # * Call each Attribute Method module method you want to add, such as 
+  #   attribute_method_suffix or attribute_method_prefix
+  # * Call <tt>define_attribute_methods</tt> after the other methods are
+  #   called.
+  # * Define the various generic +_attribute+ methods that you have declared
+  # 
+  # A minimal implementation could be:
+  # 
+  #   class Person
+  #     include ActiveModel::AttributeMethods
+  #     
+  #     attribute_method_affix  :prefix => 'reset_', :suffix => '_to_default!'
+  #     attribute_method_suffix '_contrived?'
+  #     attribute_method_prefix 'clear_'
+  #     define_attribute_methods ['name']
+  #     
+  #     attr_accessor :name
+  #     
+  #     private
+  #     
+  #     def attribute_contrived?(attr)
+  #       true
+  #     end
+  #     
+  #     def clear_attribute(attr)
+  #       send("#{attr}=", nil)
+  #     end
+  #     
+  #     def reset_attribute_to_default!(attr)
+  #       send("#{attr}=", "Default Name")
+  #     end
+  #   end
+  #
+  # Notice that whenever you include ActiveModel::AttributeMethods in your class,
+  # it requires you to implement a <tt>attributes</tt> methods which returns a hash 
+  # with each attribute name in your model as hash key and the attribute value as 
+  # hash value.
+  #
+  # Hash keys must be strings.
+  #
   module AttributeMethods
     extend ActiveSupport::Concern
 
-    # Declare and check for suffixed attribute methods.
     module ClassMethods
-      # Defines an "attribute" method (like +inheritance_column+ or
-      # +table_name+). A new (class) method will be created with the
-      # given name. If a value is specified, the new method will
-      # return that value (as a string). Otherwise, the given block
-      # will be used to compute the value of the method.
+      # Defines an "attribute" method (like +inheritance_column+ or +table_name+). 
+      # A new (class) method will be created with the given name. If a value is 
+      # specified, the new method will return that value (as a string). 
+      # Otherwise, the given block will be used to compute the value of the 
+      # method.
       #
-      # The original method will be aliased, with the new name being
-      # prefixed with "original_". This allows the new method to
-      # access the original value.
+      # The original method will be aliased, with the new name being prefixed
+      # with "original_". This allows the new method to access the original 
+      # value.
       #
       # Example:
       #
-      #   class A < ActiveRecord::Base
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      # 
+      #     cattr_accessor :primary_key
+      #     cattr_accessor :inheritance_column
+      #     
       #     define_attr_method :primary_key, "sysid"
       #     define_attr_method( :inheritance_column ) do
       #       original_inheritance_column + "_id"
       #     end
+      # 
       #   end
+      # 
+      # Provides you with:
+      # 
+      #   AttributePerson.primary_key
+      #   # => "sysid"
+      #   AttributePerson.inheritance_column = 'address'
+      #   AttributePerson.inheritance_column
+      #   # => 'address_id'
       def define_attr_method(name, value=nil, &block)
-        sing = metaclass
-        sing.send :alias_method, "original_#{name}", name
+        sing = singleton_class
+        sing.class_eval <<-eorb, __FILE__, __LINE__ + 1
+          if method_defined?(:original_#{name})
+            undef :original_#{name}
+          end
+          alias_method :original_#{name}, :#{name}
+        eorb
         if block_given?
           sing.send :define_method, name, &block
         else
           # use eval instead of a block to work around a memory leak in dev
           # mode in fcgi
-          sing.class_eval "def #{name}; #{value.to_s.inspect}; end"
+          sing.class_eval <<-eorb, __FILE__, __LINE__ + 1
+            def #{name}; #{value.to_s.inspect}; end
+          eorb
         end
       end
 
@@ -49,24 +118,30 @@ module ActiveModel
       #
       #   #{prefix}attribute(#{attr}, *args, &block)
       #
-      # An <tt>#{prefix}attribute</tt> instance method must exist and accept at least
-      # the +attr+ argument.
+      # An instance method <tt>#{prefix}attribute</tt> must exist and accept 
+      # at least the +attr+ argument.
       #
       # For example:
       #
-      #   class Person < ActiveRecord::Base
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      #     attr_accessor :name
       #     attribute_method_prefix 'clear_'
+      #     define_attribute_methods [:name]
       #
       #     private
-      #       def clear_attribute(attr)
-      #         ...
-      #       end
+      # 
+      #     def clear_attribute(attr)
+      #       send("#{attr}=", nil)
+      #     end
       #   end
       #
-      #   person = Person.find(1)
-      #   person.name          # => 'Gem'
+      #   person = Person.new
+      #   person.name = "Bob"
+      #   person.name          # => "Bob"
       #   person.clear_name
-      #   person.name          # => ''
+      #   person.name          # => nil
       def attribute_method_prefix(*prefixes)
         attribute_method_matchers.concat(prefixes.map { |prefix| AttributeMethodMatcher.new :prefix => prefix })
         undefine_attribute_methods
@@ -86,18 +161,24 @@ module ActiveModel
       #
       # For example:
       #
-      #   class Person < ActiveRecord::Base
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      #     attr_accessor :name
       #     attribute_method_suffix '_short?'
+      #     define_attribute_methods [:name]
       #
       #     private
-      #       def attribute_short?(attr)
-      #         ...
-      #       end
+      # 
+      #     def attribute_short?(attr)
+      #       send(attr).length < 5
+      #     end
       #   end
       #
-      #   person = Person.find(1)
-      #   person.name           # => 'Gem'
-      #   person.name_short?    # => true
+      #   person = Person.new
+      #   person.name = "Bob"
+      #   person.name          # => "Bob"
+      #   person.name_short?   # => true
       def attribute_method_suffix(*suffixes)
         attribute_method_matchers.concat(suffixes.map { |suffix| AttributeMethodMatcher.new :suffix => suffix })
         undefine_attribute_methods
@@ -118,16 +199,21 @@ module ActiveModel
       #
       # For example:
       #
-      #   class Person < ActiveRecord::Base
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      #     attr_accessor :name
       #     attribute_method_affix :prefix => 'reset_', :suffix => '_to_default!'
+      #     define_attribute_methods [:name]
       #
       #     private
-      #       def reset_attribute_to_default!(attr)
-      #         ...
-      #       end
+      # 
+      #     def reset_attribute_to_default!(attr)
+      #       ...
+      #     end
       #   end
       #
-      #   person = Person.find(1)
+      #   person = Person.new
       #   person.name                         # => 'Gem'
       #   person.reset_name_to_default!
       #   person.name                         # => 'Gemma'
@@ -138,7 +224,7 @@ module ActiveModel
 
       def alias_attribute(new_name, old_name)
         attribute_method_matchers.each do |matcher|
-          module_eval <<-STR, __FILE__, __LINE__+1
+          module_eval <<-STR, __FILE__, __LINE__ + 1
             def #{matcher.method_name(new_name)}(*args)
               send(:#{matcher.method_name(old_name)}, *args)
             end
@@ -146,6 +232,30 @@ module ActiveModel
         end
       end
 
+      # Declares a the attributes that should be prefixed and suffixed by 
+      # ActiveModel::AttributeMethods.
+      # 
+      # To use, pass in an array of attribute names (as strings or symbols),
+      # be sure to declare +define_attribute_methods+ after you define any
+      # prefix, suffix or affix methods, or they will not hook in.
+      # 
+      #   class Person
+      # 
+      #     include ActiveModel::AttributeMethods
+      #     attr_accessor :name, :age, :address
+      #     attribute_method_prefix 'clear_'
+      #
+      #     # Call to define_attribute_methods must appear after the
+      #     # attribute_method_prefix, attribute_method_suffix or
+      #     # attribute_method_affix declares.
+      #     define_attribute_methods [:name, :age, :address]
+      #
+      #     private
+      # 
+      #     def clear_attribute(attr)
+      #       ...
+      #     end
+      #   end
       def define_attribute_methods(attr_names)
         return if attribute_methods_generated?
         attr_names.each do |attr_name|
@@ -156,8 +266,13 @@ module ActiveModel
               if respond_to?(generate_method)
                 send(generate_method, attr_name)
               else
-                generated_attribute_methods.module_eval <<-STR, __FILE__, __LINE__+1
-                  def #{matcher.method_name(attr_name)}(*args)
+                method_name = matcher.method_name(attr_name)
+
+                generated_attribute_methods.module_eval <<-STR, __FILE__, __LINE__ + 1
+                  if method_defined?(:#{method_name})
+                    undef :#{method_name}
+                  end
+                  def #{method_name}(*args)
                     send(:#{matcher.method_missing_target}, '#{attr_name}', *args)
                   end
                 STR
@@ -168,6 +283,7 @@ module ActiveModel
         @attribute_methods_generated = true
       end
 
+      # Removes all the preiously dynamically defined methods from the class
       def undefine_attribute_methods
         generated_attribute_methods.module_eval do
           instance_methods.each { |m| undef_method(m) }
@@ -175,6 +291,7 @@ module ActiveModel
         @attribute_methods_generated = nil
       end
 
+      # Returns true if the attribute methods defined have been generated.
       def generated_attribute_methods #:nodoc:
         @generated_attribute_methods ||= begin
           mod = Module.new
@@ -183,6 +300,7 @@ module ActiveModel
         end
       end
 
+      # Returns true if the attribute methods defined have been generated.
       def attribute_methods_generated?
         @attribute_methods_generated ||= nil
       end
@@ -226,14 +344,17 @@ module ActiveModel
         end
     end
 
-    # Allows access to the object attributes, which are held in the <tt>@attributes</tt> hash, as though they
-    # were first-class methods. So a Person class with a name attribute can use Person#name and
-    # Person#name= and never directly use the attributes hash -- except for multiple assigns with
-    # ActiveRecord#attributes=. A Milestone class can also ask Milestone#completed? to test that
-    # the completed attribute is not +nil+ or 0.
+    # Allows access to the object attributes, which are held in the 
+    # <tt>@attributes</tt> hash, as though they were first-class methods. So a 
+    # Person class with a name attribute can use Person#name and Person#name= 
+    # and never directly use the attributes hash -- except for multiple assigns
+    # with ActiveRecord#attributes=. A Milestone class can also ask 
+    # Milestone#completed? to test that the completed attribute is not +nil+ 
+    # or 0.
     #
-    # It's also possible to instantiate related objects, so a Client class belonging to the clients
-    # table with a +master_id+ foreign key can instantiate master through Client#master.
+    # It's also possible to instantiate related objects, so a Client class 
+    # belonging to the clients table with a +master_id+ foreign key can 
+    # instantiate master through Client#master.
     def method_missing(method_id, *args, &block)
       method_name = method_id.to_s
       if match = match_attribute_method?(method_name)
@@ -252,7 +373,7 @@ module ActiveModel
         return true
       elsif !include_private_methods && super(method, true)
         # If we're here then we haven't found among non-private methods
-        # but found among all methods. Which means that given method is private.
+        # but found among all methods. Which means that the given method is private.
         return false
       elsif match_attribute_method?(method.to_s)
         return true