activemodel 3.2.22.5 → 4.0.0.beta1

data/lib/active_model/lint.rb

@@ -1,25 +1,31 @@
 module ActiveModel
   module Lint
-    # == Active Model Lint Tests
+    # == Active \Model \Lint \Tests
     #
-    # You can test whether an object is compliant with the Active Model API by
-    # including <tt>ActiveModel::Lint::Tests</tt> in your TestCase. It will include
-    # tests that tell you whether your object is fully compliant, or if not,
-    # which aspects of the API are not implemented.
+    # You can test whether an object is compliant with the Active \Model API by
+    # including <tt>ActiveModel::Lint::Tests</tt> in your TestCase. It will
+    # include tests that tell you whether your object is fully compliant,
+    # or if not, which aspects of the API are not implemented.
+    #
+    # Note an object is not required to implement all APIs in order to work
+    # with Action Pack. This module only intends to provide guidance in case
+    # you want all features out of the box.
     #
     # These tests do not attempt to determine the semantic correctness of the
-    # returned values. For instance, you could implement valid? to always
-    # return true, and the tests would pass. It is up to you to ensure that
-    # the values are semantically meaningful.
+    # returned values. For instance, you could implement <tt>valid?</tt> to
+    # always return true, and the tests would pass. It is up to you to ensure
+    # that the values are semantically meaningful.
     #
-    # Objects you pass in are expected to return a compliant object from a
-    # call to to_model. It is perfectly fine for to_model to return self.
+    # Objects you pass in are expected to return a compliant object from a call
+    # to <tt>to_model</tt>. It is perfectly fine for <tt>to_model</tt> to return
+    # +self+.
     module Tests
 
       # == Responds to <tt>to_key</tt>
       #
       # Returns an Enumerable of all (primary) key attributes
-      # or nil if model.persisted? is false
+      # or nil if <tt>model.persisted?</tt> is false. This is used by
+      # <tt>dom_id</tt> to generate unique ids for the object.
       def test_to_key
         assert model.respond_to?(:to_key), "The model should respond to to_key"
         def model.persisted?() false end
@@ -29,13 +35,14 @@ module ActiveModel
       # == Responds to <tt>to_param</tt>
       #
       # Returns a string representing the object's key suitable for use in URLs
-      # or nil if model.persisted? is false.
+      # or +nil+ if <tt>model.persisted?</tt> is +false+.
       #
-      # Implementers can decide to either raise an exception or provide a default
-      # in case the record uses a composite primary key. There are no tests for this
-      # behavior in lint because it doesn't make sense to force any of the possible
-      # implementation strategies on the implementer. However, if the resource is
-      # not persisted?, then to_param should always return nil.
+      # Implementers can decide to either raise an exception or provide a
+      # default in case the record uses a composite primary key. There are no
+      # tests for this behavior in lint because it doesn't make sense to force
+      # any of the possible implementation strategies on the implementer.
+      # However, if the resource is not persisted?, then <tt>to_param</tt>
+      # 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
@@ -45,70 +52,50 @@ module ActiveModel
 
       # == Responds to <tt>to_partial_path</tt>
       #
-      # Returns a string giving a relative path.  This is used for looking up
+      # Returns a string giving a relative path. This is used for looking up
       # partials. For example, a BlogPost model might return "blog_posts/blog_post"
-      #
       def test_to_partial_path
         assert model.respond_to?(:to_partial_path), "The model should respond to to_partial_path"
         assert_kind_of String, model.to_partial_path
       end
 
-      # == Responds to <tt>valid?</tt>
-      #
-      # Returns a boolean that specifies whether the object is in a valid or invalid
-      # state.
-      def test_valid?
-        assert model.respond_to?(:valid?), "The model should respond to valid?"
-        assert_boolean model.valid?, "valid?"
-      end
-
       # == Responds to <tt>persisted?</tt>
       #
-      # Returns a boolean that specifies whether the object has been persisted yet.
-      # This is used when calculating the URL for an object. If the object is
-      # not persisted, a form for that object, for instance, will be POSTed to the
-      # collection. If it is persisted, a form for the object will be PUT to the
-      # URL for the object.
+      # Returns a boolean that specifies whether the object has been persisted
+      # yet. This is used when calculating the URL for an object. If the object
+      # is not persisted, a form for that object, for instance, will route to
+      # the create action. If it is persisted, a form for the object will routes
+      # to the update action.
       def test_persisted?
         assert model.respond_to?(:persisted?), "The model should respond to persisted?"
         assert_boolean model.persisted?, "persisted?"
       end
 
-      # == Naming
+      # == \Naming
       #
       # Model.model_name must return a string with some convenience methods:
-      # :human, :singular, and :plural. Check ActiveModel::Naming for more information.
-      #
+      # <tt>:human</tt>, <tt>:singular</tt> and <tt>:plural</tt>. Check
+      # ActiveModel::Naming for more information.
       def test_model_naming
         assert model.class.respond_to?(:model_name), "The model should respond to model_name"
         model_name = model.class.model_name
-        assert_kind_of String, model_name
-        assert_kind_of String, model_name.human
-        assert_kind_of String, model_name.singular
-        assert_kind_of String, model_name.plural
+        assert model_name.respond_to?(:to_str)
+        assert model_name.human.respond_to?(:to_str)
+        assert model_name.singular.respond_to?(:to_str)
+        assert model_name.plural.respond_to?(:to_str)
       end
 
-      # == Errors Testing
-      #
-      # Returns an object that has :[] and :full_messages defined on it. See below
-      # for more details.
+      # == \Errors Testing
       #
-      # Returns an Array of Strings that are the errors for the attribute in
-      # question. If localization is used, the Strings should be localized
-      # for the current locale. If no error is present, this method should
-      # return an empty Array.
+      # Returns an object that implements [](attribute) defined which returns an
+      # Array of Strings that are the errors for the attribute in question.
+      # If localization is used, the Strings should be localized for the current
+      # locale. If no error is present, this method should return an empty Array.
       def test_errors_aref
         assert model.respond_to?(:errors), "The model should respond to errors"
         assert model.errors[:hello].is_a?(Array), "errors#[] should return an Array"
       end
 
-      # Returns an Array of all error messages for the object. Each message
-      # should contain information about the field, if applicable.
-      def test_errors_full_messages
-        assert model.respond_to?(:errors), "The model should respond to errors"
-        assert model.errors.full_messages.is_a?(Array), "errors#full_messages should return an Array"
-      end
-
       private
         def model
           assert @model.respond_to?(:to_model), "The object should respond_to to_model"

data/lib/active_model/locale/en.yml

@@ -9,10 +9,11 @@ en:
       inclusion: "is not included in the list"
       exclusion: "is reserved"
       invalid: "is invalid"
-      confirmation: "doesn't match confirmation"
+      confirmation: "doesn't match %{attribute}"
       accepted: "must be accepted"
       empty: "can't be empty"
       blank: "can't be blank"
+      present: "must be blank"
       too_long: "is too long (maximum is %{count} characters)"
       too_short: "is too short (minimum is %{count} characters)"
       wrong_length: "is the wrong length (should be %{count} characters)"
@@ -23,5 +24,6 @@ en:
       equal_to: "must be equal to %{count}"
       less_than: "must be less than %{count}"
       less_than_or_equal_to: "must be less than or equal to %{count}"
+      other_than: "must be other than %{count}"
       odd: "must be odd"
       even: "must be even"

data/lib/active_model/model.rb

@@ -0,0 +1,97 @@
+module ActiveModel
+
+  # == Active \Model Basic \Model
+  #
+  # Includes the required interface for an object to interact with
+  # <tt>ActionPack</tt>, using different <tt>ActiveModel</tt> modules.
+  # It includes model name introspections, conversions, translations and
+  # validations. Besides that, it allows you to initialize the object with a
+  # hash of attributes, pretty much like <tt>ActiveRecord</tt> does.
+  #
+  # A minimal implementation could be:
+  #
+  #   class Person
+  #     include ActiveModel::Model
+  #     attr_accessor :name, :age
+  #   end
+  #
+  #   person = Person.new(name: 'bob', age: '18')
+  #   person.name # => 'bob'
+  #   person.age  # => 18
+  #
+  # Note that, by default, <tt>ActiveModel::Model</tt> implements <tt>persisted?</tt>
+  # to return +false+, which is the most common case. You may want to override
+  # it in your class to simulate a different scenario:
+  #
+  #   class Person
+  #     include ActiveModel::Model
+  #     attr_accessor :id, :name
+  #
+  #     def persisted?
+  #       self.id == 1
+  #     end
+  #   end
+  #
+  #   person = Person.new(id: 1, name: 'bob')
+  #   person.persisted? # => true
+  #
+  # Also, if for some reason you need to run code on <tt>initialize</tt>, make
+  # sure you call +super+ if you want the attributes hash initialization to
+  # happen.
+  #
+  #   class Person
+  #     include ActiveModel::Model
+  #     attr_accessor :id, :name, :omg
+  #
+  #     def initialize(attributes={})
+  #       super
+  #       @omg ||= true
+  #     end
+  #   end
+  #
+  #   person = Person.new(id: 1, name: 'bob')
+  #   person.omg # => true
+  #
+  # For more detailed information on other functionalities available, please
+  # refer to the specific modules included in <tt>ActiveModel::Model</tt>
+  # (see below).
+  module Model
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        extend  ActiveModel::Naming
+        extend  ActiveModel::Translation
+        include ActiveModel::Validations
+        include ActiveModel::Conversion
+      end
+    end
+
+    # Initializes a new model with the given +params+.
+    #
+    #   class Person
+    #     include ActiveModel::Model
+    #     attr_accessor :name, :age
+    #   end
+    #
+    #   person = Person.new(name: 'bob', age: '18')
+    #   person.name # => "bob"
+    #   person.age  # => 18
+    def initialize(params={})
+      params.each do |attr, value|
+        self.public_send("#{attr}=", value)
+      end if params
+    end
+
+    # Indicates if the model is persisted. Default is +false+.
+    #
+    #  class Person
+    #    include ActiveModel::Model
+    #    attr_accessor :id, :name
+    #  end
+    #
+    #  person = Person.new(id: 1, name: 'bob')
+    #  person.persisted? # => false
+    def persisted?
+      false
+    end
+  end
+end

data/lib/active_model/naming.rb

@@ -1,43 +1,173 @@
-require 'active_support/inflector'
 require 'active_support/core_ext/hash/except'
 require 'active_support/core_ext/module/introspection'
-require 'active_support/deprecation'
 
 module ActiveModel
-  class Name < String
-    attr_reader :singular, :plural, :element, :collection, :partial_path,
-      :singular_route_key, :route_key, :param_key, :i18n_key
+  class Name
+    include Comparable
+
+    attr_reader :singular, :plural, :element, :collection,
+      :singular_route_key, :route_key, :param_key, :i18n_key,
+      :name
 
     alias_method :cache_key, :collection
 
-    deprecate :partial_path => "ActiveModel::Name#partial_path is deprecated. Call #to_partial_path on model instances directly instead."
+    ##
+    # :method: ==
+    #
+    # :call-seq:
+    #   ==(other)
+    #
+    # Equivalent to <tt>String#==</tt>. Returns +true+ if the class name and
+    # +other+ are equal, otherwise +false+.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name == 'BlogPost'  # => true
+    #   BlogPost.model_name == 'Blog Post' # => false
 
-    def initialize(klass, namespace = nil, name = nil)
-      name ||= klass.name
+    ##
+    # :method: ===
+    #
+    # :call-seq:
+    #   ===(other)
+    #
+    # Equivalent to <tt>#==</tt>.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name === 'BlogPost'  # => true
+    #   BlogPost.model_name === 'Blog Post' # => false
 
-      raise ArgumentError, "Class name cannot be blank. You need to supply a name argument when anonymous class given" if name.blank?
+    ##
+    # :method: <=>
+    #
+    # :call-seq:
+    #   ==(other)
+    #
+    # Equivalent to <tt>String#<=></tt>.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name <=> 'BlogPost'  # => 0
+    #   BlogPost.model_name <=> 'Blog'      # => 1
+    #   BlogPost.model_name <=> 'BlogPosts' # => -1
+
+    ##
+    # :method: =~
+    #
+    # :call-seq:
+    #   =~(regexp)
+    #
+    # Equivalent to <tt>String#=~</tt>. Match the class name against the given
+    # regexp. Returns the position where the match starts or +nil+ if there is
+    # no match.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name =~ /Post/ # => 4
+    #   BlogPost.model_name =~ /\d/   # => nil
 
-      super(name)
+    ##
+    # :method: !~
+    #
+    # :call-seq:
+    #   !~(regexp)
+    #
+    # Equivalent to <tt>String#!~</tt>. Match the class name against the given
+    # regexp. Returns +true+ if there is no match, otherwise +false+.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name !~ /Post/ # => false
+    #   BlogPost.model_name !~ /\d/   # => true
 
-      @unnamespaced = self.sub(/^#{namespace.name}::/, '') if namespace
+    ##
+    # :method: eql?
+    #
+    # :call-seq:
+    #   eql?(other)
+    #
+    # Equivalent to <tt>String#eql?</tt>. Returns +true+ if the class name and
+    # +other+ have the same length and content, otherwise +false+.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name.eql?('BlogPost')  # => true
+    #   BlogPost.model_name.eql?('Blog Post') # => false
+
+    ##
+    # :method: to_s
+    #
+    # :call-seq:
+    #   to_s()
+    #
+    # Returns the class name.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name.to_s # => "BlogPost"
+
+    ##
+    # :method: to_str
+    #
+    # :call-seq:
+    #   to_str()
+    #
+    # Equivalent to +to_s+.
+    delegate :==, :===, :<=>, :=~, :"!~", :eql?, :to_s,
+             :to_str, :to => :name
+
+    # Returns a new ActiveModel::Name instance. By default, the +namespace+
+    # and +name+ option will take the namespace and name of the given class
+    # respectively.
+    #
+    #   module Foo
+    #     class Bar
+    #     end
+    #   end
+    #
+    #   ActiveModel::Name.new(Foo::Bar).to_s
+    #   # => "Foo::Bar"
+    def initialize(klass, namespace = nil, name = nil)
+      @name = name || klass.name
+
+      raise ArgumentError, "Class name cannot be blank. You need to supply a name argument when anonymous class given" if @name.blank?
+
+      @unnamespaced = @name.sub(/^#{namespace.name}::/, '') if namespace
       @klass        = klass
-      @singular     = _singularize(self).freeze
-      @plural       = ActiveSupport::Inflector.pluralize(@singular).freeze
-      @element      = ActiveSupport::Inflector.underscore(ActiveSupport::Inflector.demodulize(self)).freeze
-      @human        = ActiveSupport::Inflector.humanize(@element).freeze
-      @collection   = ActiveSupport::Inflector.tableize(self).freeze
-      @partial_path = "#{@collection}/#{@element}".freeze
-      @param_key    = (namespace ? _singularize(@unnamespaced) : @singular).freeze
-      @i18n_key     = self.underscore.to_sym
+      @singular     = _singularize(@name)
+      @plural       = ActiveSupport::Inflector.pluralize(@singular)
+      @element      = ActiveSupport::Inflector.underscore(ActiveSupport::Inflector.demodulize(@name))
+      @human        = ActiveSupport::Inflector.humanize(@element)
+      @collection   = ActiveSupport::Inflector.tableize(@name)
+      @param_key    = (namespace ? _singularize(@unnamespaced) : @singular)
+      @i18n_key     = @name.underscore.to_sym
 
       @route_key          = (namespace ? ActiveSupport::Inflector.pluralize(@param_key) : @plural.dup)
-      @singular_route_key = ActiveSupport::Inflector.singularize(@route_key).freeze
+      @singular_route_key = ActiveSupport::Inflector.singularize(@route_key)
       @route_key << "_index" if @plural == @singular
-      @route_key.freeze
     end
 
     # Transform the model name into a more humane format, using I18n. By default,
-    # it will underscore then humanize the class name
+    # it will underscore then humanize the class name.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
     #
     #   BlogPost.model_name.human # => "Blog post"
     #
@@ -53,7 +183,7 @@ module ActiveModel
       defaults << options[:default] if options[:default]
       defaults << @human
 
-      options = {:scope => [@klass.i18n_scope, :models], :count => 1, :default => defaults}.merge(options.except(:default))
+      options = { :scope => [@klass.i18n_scope, :models], :count => 1, :default => defaults }.merge!(options.except(:default))
       I18n.translate(defaults.shift, options)
     end
 
@@ -64,7 +194,7 @@ module ActiveModel
     end
   end
 
-  # == Active Model Naming
+  # == Active \Model \Naming
   #
   # Creates a +model_name+ method on your object.
   #
@@ -81,11 +211,20 @@ module ActiveModel
   #   BookModule::BookCover.model_name.i18n_key  # => :"book_module/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.
+  # is required to pass the Active Model Lint test. So either extending the
+  # provided method below, or rolling your own is required.
   module Naming
     # Returns an ActiveModel::Name object for module. It can be
-    # used to retrieve all kinds of naming-related information.
+    # used to retrieve all kinds of naming-related information
+    # (See ActiveModel::Name for more information).
+    #
+    #   class Person < ActiveModel::Model
+    #   end
+    #
+    #   Person.model_name          # => Person
+    #   Person.model_name.class    # => ActiveModel::Name
+    #   Person.model_name.singular # => "person"
+    #   Person.model_name.plural   # => "people"
     def model_name
       @_model_name ||= begin
         namespace = self.parents.detect do |n|
@@ -95,7 +234,7 @@ module ActiveModel
       end
     end
 
-    # Returns the plural class name of a record or class. Examples:
+    # Returns the plural class name of a record or class.
     #
     #   ActiveModel::Naming.plural(post)             # => "posts"
     #   ActiveModel::Naming.plural(Highrise::Person) # => "highrise_people"
@@ -103,7 +242,7 @@ module ActiveModel
       model_name_from_record_or_class(record_or_class).plural
     end
 
-    # Returns the singular class name of a record or class. Examples:
+    # Returns the singular class name of a record or class.
     #
     #   ActiveModel::Naming.singular(post)             # => "post"
     #   ActiveModel::Naming.singular(Highrise::Person) # => "highrise_person"
@@ -111,10 +250,10 @@ module ActiveModel
       model_name_from_record_or_class(record_or_class).singular
     end
 
-    # Identifies whether the class name of a record or class is uncountable. Examples:
+    # Identifies whether the class name of a record or class is uncountable.
     #
     #   ActiveModel::Naming.uncountable?(Sheep) # => true
-    #   ActiveModel::Naming.uncountable?(Post) => false
+    #   ActiveModel::Naming.uncountable?(Post)  # => false
     def self.uncountable?(record_or_class)
       plural(record_or_class) == singular(record_or_class)
     end
@@ -122,11 +261,11 @@ module ActiveModel
     # Returns string to use while generating route names. It differs for
     # namespaced models regarding whether it's inside isolated engine.
     #
-    # For isolated engine:
-    # ActiveModel::Naming.route_key(Blog::Post) #=> post
+    #   # For isolated engine:
+    #   ActiveModel::Naming.singular_route_key(Blog::Post) #=> post
     #
-    # For shared engine:
-    # ActiveModel::Naming.route_key(Blog::Post) #=> blog_post
+    #   # For shared engine:
+    #   ActiveModel::Naming.singular_route_key(Blog::Post) #=> blog_post
     def self.singular_route_key(record_or_class)
       model_name_from_record_or_class(record_or_class).singular_route_key
     end
@@ -134,11 +273,11 @@ module ActiveModel
     # Returns string to use while generating route names. It differs for
     # namespaced models regarding whether it's inside isolated engine.
     #
-    # For isolated engine:
-    # ActiveModel::Naming.route_key(Blog::Post) #=> posts
+    #   # For isolated engine:
+    #   ActiveModel::Naming.route_key(Blog::Post) #=> posts
     #
-    # For shared engine:
-    # ActiveModel::Naming.route_key(Blog::Post) #=> blog_posts
+    #   # For shared engine:
+    #   ActiveModel::Naming.route_key(Blog::Post) #=> blog_posts
     #
     # The route key also considers if the noun is uncountable and, in
     # such cases, automatically appends _index.
@@ -149,23 +288,24 @@ module ActiveModel
     # Returns string to use for params names. It differs for
     # namespaced models regarding whether it's inside isolated engine.
     #
-    # For isolated engine:
-    # ActiveModel::Naming.param_key(Blog::Post) #=> post
+    #   # For isolated engine:
+    #   ActiveModel::Naming.param_key(Blog::Post) #=> post
     #
-    # For shared engine:
-    # ActiveModel::Naming.param_key(Blog::Post) #=> blog_post
+    #   # For shared engine:
+    #   ActiveModel::Naming.param_key(Blog::Post) #=> blog_post
     def self.param_key(record_or_class)
       model_name_from_record_or_class(record_or_class).param_key
     end
 
-    private
-      def self.model_name_from_record_or_class(record_or_class)
-        (record_or_class.is_a?(Class) ? record_or_class : convert_to_model(record_or_class).class).model_name
-      end
-
-      def self.convert_to_model(object)
-        object.respond_to?(:to_model) ? object.to_model : object
+    def self.model_name_from_record_or_class(record_or_class) #:nodoc:
+      if record_or_class.respond_to?(:model_name)
+        record_or_class.model_name
+      elsif record_or_class.respond_to?(:to_model)
+        record_or_class.to_model.class.model_name
+      else
+        record_or_class.class.model_name
       end
+    end
+    private_class_method :model_name_from_record_or_class
   end
-
 end