activemodel 3.0.0.rc → 3.0.0.rc2

data/lib/active_model/conversion.rb

@@ -17,24 +17,27 @@ module ActiveModel
   #   end
   #
   #   cm = ContactMessage.new
-  #   cm.to_model == self #=> true
-  #   cm.to_key           #=> nil
-  #   cm.to_param         #=> nil
+  #   cm.to_model == self # => true
+  #   cm.to_key           # => nil
+  #   cm.to_param         # => nil
   #
   module Conversion
-    # If your object is already designed to implement all of the Active Model 
-    # you can use the default to_model implementation, which simply returns 
+    # If your object is already designed to implement all of the Active Model
+    # you can use the default to_model implementation, which simply returns
     # self.
-    # 
-    # If your model does not act like an Active Model object, then you should 
-    # define <tt>:to_model</tt> yourself returning a proxy object that wraps 
+    #
+    # If your model does not act like an Active Model object, then you should
+    # define <tt>:to_model</tt> yourself returning a proxy object that wraps
     # your object with Active Model compliant methods.
     def to_model
       self
     end
 
-    # Returns an Enumerable of all (primary) key attributes or nil if 
-    # persisted? is false
+    # Returns an Enumerable of all key attributes if any is set, regardless
+    # if the object is persisted or not.
+    #
+    # Note the default implementation uses persisted? just because all objects
+    # in Ruby 1.8.x responds to :id.
     def to_key
       persisted? ? [id] : nil
     end
@@ -42,7 +45,7 @@ module ActiveModel
     # Returns a string representing the object's key suitable for use in URLs,
     # or nil if persisted? is false
     def to_param
-      to_key ? to_key.join('-') : nil
+      persisted? ? to_key.join('-') : nil
     end
   end
 end

data/lib/active_model/dirty.rb

@@ -6,47 +6,48 @@ require 'active_support/core_ext/object/duplicable'
 module ActiveModel
   # == Active Model Dirty
   #
-  # Provides a way to track changes in your object in the same way as 
+  # Provides a way to track changes in your object in the same way as
   # Active Record does.
-  # 
+  #
   # The requirements to implement ActiveModel::Dirty are to:
   #
   # * <tt>include ActiveModel::Dirty</tt> in your object
-  # * Call <tt>define_attribute_methods</tt> passing each method you want to 
+  # * Call <tt>define_attribute_methods</tt> passing each method you want to
   #   track
-  # * Call <tt>attr_name_will_change!</tt> before each change to the tracked 
+  # * Call <tt>attr_name_will_change!</tt> before each change to the tracked
   #   attribute
-  # 
-  # If you wish to also track previous changes on save or update, you need to 
+  #
+  # If you wish to also track previous changes on save or update, you need to
   # add
-  # 
+  #
   #   @previously_changed = changes
-  # 
+  #
   # inside of your save or update method.
-  # 
+  #
   # A minimal implementation could be:
-  # 
+  #
   #   class Person
-  #   
+  #
   #     include ActiveModel::Dirty
-  #   
+  #
   #     define_attribute_methods [:name]
-  #   
+  #
   #     def name
   #       @name
   #     end
-  #   
+  #
   #     def name=(val)
-  #       name_will_change!
+  #       name_will_change! unless val == @name
   #       @name = val
   #     end
-  #   
+  #
   #     def save
   #       @previously_changed = changes
+  #       @changed_attributes.clear
   #     end
-  #   
+  #
   #   end
-  # 
+  #
   # == Examples:
   #
   # A newly instantiated object is unchanged:
@@ -77,13 +78,10 @@ module ActiveModel
   #   person.changed        # => ['name']
   #   person.changes        # => { 'name' => ['Bill', 'Bob'] }
   #
-  # Resetting an attribute returns it to its original state:
-  #   person.reset_name!    # => 'Bill'
-  #   person.changed?       # => false
-  #   person.name_changed?  # => false
-  #   person.name           # => 'Bill'
+  # If an attribute is modified in-place then make use of <tt>[attribute_name]_will_change!</tt>
+  # to mark that the attribute is changing. Otherwise ActiveModel can't track changes to
+  # in-place attributes.
   #
-  # Before modifying an attribute in-place:
   #   person.name_will_change!
   #   person.name << 'y'
   #   person.name_change    # => ['Bill', 'Billy']

data/lib/active_model/errors.rb

@@ -12,50 +12,50 @@ module ActiveModel
   #
   # Provides a modified +OrderedHash+ that you can include in your object
   # for handling error messages and interacting with Action Pack helpers.
-  # 
+  #
   # A minimal implementation could be:
-  # 
+  #
   #   class Person
-  #   
+  #
   #     # Required dependency for ActiveModel::Errors
   #     extend ActiveModel::Naming
-  # 
+  #
   #     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
-  #   
+  #
   #     # The following methods are needed to be minimally implemented
   #
   #     def read_attribute_for_validation(attr)
   #       send(attr)
   #     end
-  #   
-  #     def ErrorsPerson.human_attribute_name(attr, options = {})
+  #
+  #     def Person.human_attribute_name(attr, options = {})
   #       attr
   #     end
-  #   
-  #     def ErrorsPerson.lookup_ancestors
+  #
+  #     def Person.lookup_ancestors
   #       [self]
   #     end
-  #   
+  #
   #   end
-  # 
+  #
   # The last three methods are required in your object for Errors to be
   # able to generate error messages correctly and also handle multiple
   # languages.  Of course, if you extend your object with ActiveModel::Translations
   # you will not need to implement the last two.  Likewise, using
   # ActiveModel::Validations will handle the validation related methods
   # for you.
-  # 
+  #
   # The above allows you to do:
-  # 
+  #
   #   p = Person.new
   #   p.validate!             # => ["can not be nil"]
   #   p.errors.full_messages  # => ["name can not be nil"]
@@ -66,7 +66,7 @@ module ActiveModel
     CALLBACKS_OPTIONS = [:if, :unless, :on, :allow_nil, :allow_blank]
 
     # Pass in the instance of the object that is using the errors object.
-    # 
+    #
     #   class Person
     #     def initialize
     #       @errors = ActiveModel::Errors.new(self)
@@ -80,23 +80,19 @@ module ActiveModel
     alias_method :get, :[]
     alias_method :set, :[]=
 
-    # When passed a symbol or a name of a method, returns an array of errors 
+    # When passed a symbol or a name of a method, returns an array of errors
     # for the method.
-    # 
-    #   p.errors[:name]   #=> ["can not be nil"]
-    #   p.errors['name']  #=> ["can not be nil"]
+    #
+    #   p.errors[:name]   # => ["can not be nil"]
+    #   p.errors['name']  # => ["can not be nil"]
     def [](attribute)
-      if errors = get(attribute.to_sym)
-        errors
-      else
-        set(attribute.to_sym, [])
-      end
+      get(attribute.to_sym) || set(attribute.to_sym, [])
     end
 
     # Adds to the supplied attribute the supplied error message.
-    # 
+    #
     #   p.errors[:name] = "must be set"
-    #   p.errors[:name] #=> ['must be set']
+    #   p.errors[:name] # => ['must be set']
     def []=(attribute, error)
       self[attribute.to_sym] << error
     end
@@ -104,12 +100,12 @@ module ActiveModel
     # Iterates through each error key, value pair in the error messages hash.
     # Yields the attribute and the error for that attribute.  If the attribute
     # has more than one error message, yields once for each error message.
-    # 
+    #
     #   p.errors.add(:name, "can't be blank")
     #   p.errors.each do |attribute, errors_array|
     #     # Will yield :name and "can't be blank"
     #   end
-    # 
+    #
     #   p.errors.add(:name, "must be specified")
     #   p.errors.each do |attribute, errors_array|
     #     # Will yield :name and "can't be blank"
@@ -122,29 +118,29 @@ module ActiveModel
     end
 
     # Returns the number of error messages.
-    # 
+    #
     #   p.errors.add(:name, "can't be blank")
-    #   p.errors.size #=> 1
+    #   p.errors.size # => 1
     #   p.errors.add(:name, "must be specified")
-    #   p.errors.size #=> 2
+    #   p.errors.size # => 2
     def size
       values.flatten.size
     end
 
     # Returns an array of error messages, with the attribute name included
-    # 
+    #
     #   p.errors.add(:name, "can't be blank")
     #   p.errors.add(:name, "must be specified")
-    #   p.errors.to_a   #=>   ["name can't be blank", "name must be specified"]
+    #   p.errors.to_a # => ["name can't be blank", "name must be specified"]
     def to_a
       full_messages
     end
 
     # Returns the number of error messages.
     #   p.errors.add(:name, "can't be blank")
-    #   p.errors.count #=> 1
+    #   p.errors.count # => 1
     #   p.errors.add(:name, "must be specified")
-    #   p.errors.count #=> 2
+    #   p.errors.count # => 2
     def count
       to_a.size
     end
@@ -155,11 +151,11 @@ module ActiveModel
     end
 
     # Returns an xml formatted representation of the Errors hash.
-    # 
+    #
     #   p.errors.add(:name, "can't be blank")
     #   p.errors.add(:name, "must be specified")
-    #   p.errors.to_xml   #=> Produces:
-    # 
+    #   p.errors.to_xml
+    #   # =>
     #   #  <?xml version=\"1.0\" encoding=\"UTF-8\"?>
     #   #  <errors>
     #   #    <error>name can't be blank</error>
@@ -169,16 +165,16 @@ module ActiveModel
       to_a.to_xml options.reverse_merge(:root => "errors", :skip_types => true)
     end
 
-    # Returns an array as JSON representation for this object.
+    # Returns an ActiveSupport::OrderedHash that can be used as the JSON representation for this object.
     def as_json(options=nil)
-      to_a
+      self
     end
 
     # Adds +message+ to the error messages on +attribute+, which will be returned on a call to
     # <tt>on(attribute)</tt> for the same attribute. More than one error can be added to the same
     # +attribute+ in which case an array will be returned on a call to <tt>on(attribute)</tt>.
     # If no +message+ is supplied, <tt>:invalid</tt> is assumed.
-    # 
+    #
     # If +message+ is a symbol, it will be translated using the appropriate scope (see +translate_error+).
     # If +message+ is a proc, it will be called, allowing for things like <tt>Time.now</tt> to be used within an error.
     def add(attribute, message = nil, options = {})
@@ -257,19 +253,19 @@ module ActiveModel
       full_messages
     end
 
-    # Translates an error message in its default scope 
+    # Translates an error message in its default scope
     # (<tt>activemodel.errors.messages</tt>).
     #
-    # Error messages are first looked up in <tt>models.MODEL.attributes.ATTRIBUTE.MESSAGE</tt>, 
-    # if it's not there, it's looked up in <tt>models.MODEL.MESSAGE</tt> and if that is not 
-    # there also, it returns the translation of the default message 
+    # Error messages are first looked up in <tt>models.MODEL.attributes.ATTRIBUTE.MESSAGE</tt>,
+    # if it's not there, it's looked up in <tt>models.MODEL.MESSAGE</tt> and if that is not
+    # there also, it returns the translation of the default message
     # (e.g. <tt>activemodel.errors.messages.MESSAGE</tt>). The translated model name,
     # translated attribute name and the value are available for interpolation.
     #
     # When using inheritance in your models, it will check all the inherited
     # models too, but only if the model itself hasn't been found. Say you have
-    # <tt>class Admin < User; end</tt> and you wanted the translation for 
-    # the <tt>:blank</tt> error +message+ for the <tt>title</tt> +attribute+, 
+    # <tt>class Admin < User; end</tt> and you wanted the translation for
+    # the <tt>:blank</tt> error +message+ for the <tt>title</tt> +attribute+,
     # it looks for these translations:
     #
     # <ol>

data/lib/active_model/lint.rb

@@ -38,6 +38,7 @@ module ActiveModel
       # not persisted?, then to_param should always return nil.
       def test_to_param
         assert model.respond_to?(:to_param), "The model should respond to to_param"
+        def model.to_key() [1] end
         def model.persisted?() false end
         assert model.to_param.nil?
       end
@@ -79,7 +80,7 @@ module ActiveModel
       end
 
       # == Errors Testing
-      # 
+      #
       # Returns an object that has :[] and :full_messages defined on it. See below
       # for more details.
       #

data/lib/active_model/naming.rb

@@ -17,7 +17,10 @@ module ActiveModel
     end
 
     # Transform the model name into a more humane format, using I18n. By default,
-    # it will underscore then humanize the class name (BlogPost.model_name.human #=> "Blog post").
+    # it will underscore then humanize the class name
+    #
+    #   BlogPost.model_name.human # => "Blog post"
+    #
     # Specify +options+ with additional translating options.
     def human(options={})
       return @human unless @klass.respond_to?(:lookup_ancestors) &&
@@ -38,16 +41,16 @@ module ActiveModel
   # == Active Model Naming
   #
   # Creates a +model_name+ method on your object.
-  # 
+  #
   # To implement, just extend ActiveModel::Naming in your object:
-  # 
+  #
   #   class BookCover
   #     extend ActiveModel::Naming
   #   end
-  # 
-  #   BookCover.model_name        #=> "BookCover"
-  #   BookCover.model_name.human  #=> "Book cover"
-  # 
+  #
+  #   BookCover.model_name        # => "BookCover"
+  #   BookCover.model_name.human  # => "Book cover"
+  #
   # Providing the functionality that ActiveModel::Naming provides in your object
   # is required to pass the Active Model Lint test.  So either extending the provided
   # method below, or rolling your own is required..
@@ -87,5 +90,5 @@ module ActiveModel
         (record_or_class.is_a?(Class) ? record_or_class : record_or_class.class).model_name
       end
   end
-  
+
 end

data/lib/active_model/observing.rb

@@ -10,7 +10,7 @@ module ActiveModel
 
     module ClassMethods
       # == Active Model Observers Activation
-      # 
+      #
       # Activates the observers assigned. Examples:
       #
       #   # Calls PersonObserver.instance
@@ -22,7 +22,7 @@ module ActiveModel
       #   # Same as above, just using explicit class references
       #   ActiveRecord::Base.observers = Cacher, GarbageCollector
       #
-      # Note: Setting this does not instantiate the observers yet. 
+      # Note: Setting this does not instantiate the observers yet.
       # +instantiate_observers+ is called during startup, and before
       # each development request.
       def observers=(*values)
@@ -123,9 +123,9 @@ module ActiveModel
   #
   # Observers will by default be mapped to the class with which they share a
   # name. So CommentObserver will be tied to observing Comment, ProductManagerObserver
-  # to ProductManager, and so on. If you want to name your observer differently than 
-  # the class you're interested in observing, you can use the Observer.observe class 
-  # method which takes either the concrete class (Product) or a symbol for that 
+  # to ProductManager, and so on. If you want to name your observer differently than
+  # the class you're interested in observing, you can use the Observer.observe class
+  # method which takes either the concrete class (Product) or a symbol for that
   # class (:product):
   #
   #   class AuditObserver < ActiveModel::Observer
@@ -136,7 +136,7 @@ module ActiveModel
   #     end
   #   end
   #
-  # If the audit observer needs to watch more than one kind of object, this can be 
+  # If the audit observer needs to watch more than one kind of object, this can be
   # specified with multiple arguments:
   #
   #   class AuditObserver < ActiveModel::Observer
@@ -147,7 +147,7 @@ module ActiveModel
   #     end
   #   end
   #
-  # The AuditObserver will now act on both updates to Account and Balance by treating 
+  # The AuditObserver will now act on both updates to Account and Balance by treating
   # them both as records.
   #
   class Observer