diff options
Diffstat (limited to 'activemodel/lib')
| -rw-r--r-- | activemodel/lib/active_model/attribute_methods.rb | 8 | ||||
| -rw-r--r-- | activemodel/lib/active_model/errors.rb | 13 | ||||
| -rw-r--r-- | activemodel/lib/active_model/mass_assignment_security.rb | 244 | ||||
| -rw-r--r-- | activemodel/lib/active_model/mass_assignment_security/sanitizer.rb | 8 | ||||
| -rw-r--r-- | activemodel/lib/active_model/naming.rb | 32 | ||||
| -rw-r--r-- | activemodel/lib/active_model/observer_array.rb | 27 | ||||
| -rw-r--r-- | activemodel/lib/active_model/observing.rb | 205 | ||||
| -rw-r--r-- | activemodel/lib/active_model/secure_password.rb | 54 | ||||
| -rw-r--r-- | activemodel/lib/active_model/serializers/json.rb | 38 | ||||
| -rw-r--r-- | activemodel/lib/active_model/serializers/xml.rb | 36 | ||||
| -rw-r--r-- | activemodel/lib/active_model/validations.rb | 161 | ||||
| -rw-r--r-- | activemodel/lib/active_model/validations/callbacks.rb | 87 | ||||
| -rw-r--r-- | activemodel/lib/active_model/validations/validates.rb | 74 | ||||
| -rw-r--r-- | activemodel/lib/active_model/validations/with.rb | 34 | ||||
| -rw-r--r-- | activemodel/lib/active_model/validator.rb | 22 |
15 files changed, 765 insertions, 278 deletions
diff --git a/activemodel/lib/active_model/attribute_methods.rb b/activemodel/lib/active_model/attribute_methods.rb index 21b1209875..ef04f1fa49 100644 --- a/activemodel/lib/active_model/attribute_methods.rb +++ b/activemodel/lib/active_model/attribute_methods.rb @@ -1,6 +1,14 @@ module ActiveModel # Raised when an attribute is not defined. + # + # class User < ActiveRecord::Base + # has_many :pets + # end + # + # user = User.first + # user.pets.select(:id).first.user_id + # # => ActiveModel::MissingAttributeError: missing attribute: user_id class MissingAttributeError < NoMethodError end # == Active Model Attribute Methods diff --git a/activemodel/lib/active_model/errors.rb b/activemodel/lib/active_model/errors.rb index d68086584e..1026b0f4d3 100644 --- a/activemodel/lib/active_model/errors.rb +++ b/activemodel/lib/active_model/errors.rb @@ -436,6 +436,19 @@ module ActiveModel # Raised when a validation cannot be corrected by end users and are considered # exceptional. + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name + # + # validates_presence_of :name, strict: true + # end + # + # person = Person.new + # person.name = nil + # person.valid? + # # => ActiveModel::StrictValidationFailed: Name can't be blank class StrictValidationFailed < StandardError end end diff --git a/activemodel/lib/active_model/mass_assignment_security.rb b/activemodel/lib/active_model/mass_assignment_security.rb index 87c0bcf59b..f9841abcb0 100644 --- a/activemodel/lib/active_model/mass_assignment_security.rb +++ b/activemodel/lib/active_model/mass_assignment_security.rb @@ -3,7 +3,48 @@ require 'active_model/mass_assignment_security/permission_set' require 'active_model/mass_assignment_security/sanitizer' module ActiveModel - # = Active Model Mass-Assignment Security + # == Active Model Mass-Assignment Security + # + # Mass assignment security provides an interface for protecting attributes + # from end-user assignment. For more complex permissions, mass assignment + # security may be handled outside the model by extending a non-ActiveRecord + # class, such as a controller, with this behavior. + # + # For example, a logged in user may need to assign additional attributes + # depending on their role: + # + # class AccountsController < ApplicationController + # include ActiveModel::MassAssignmentSecurity + # + # attr_accessible :first_name, :last_name + # attr_accessible :first_name, :last_name, :plan_id, as: :admin + # + # def update + # ... + # @account.update_attributes(account_params) + # ... + # end + # + # protected + # + # def account_params + # role = admin ? :admin : :default + # sanitize_for_mass_assignment(params[:account], role) + # end + # + # end + # + # === Configuration options + # + # * <tt>mass_assignment_sanitizer</tt> - Defines sanitize method. Possible + # values are: + # * <tt>:logger</tt> (default) - writes filtered attributes to logger + # * <tt>:strict</tt> - raise <tt>ActiveModel::MassAssignmentSecurity::Error</tt> + # on any protected attribute update. + # + # You can specify your own sanitizer object eg. <tt>MySanitizer.new</tt>. + # See <tt>ActiveModel::MassAssignmentSecurity::LoggerSanitizer</tt> for + # example implementation. module MassAssignmentSecurity extend ActiveSupport::Concern @@ -16,55 +57,17 @@ module ActiveModel self.mass_assignment_sanitizer = :logger end - # Mass assignment security provides an interface for protecting attributes - # from end-user assignment. For more complex permissions, mass assignment security - # may be handled outside the model by extending a non-ActiveRecord class, - # such as a controller, with this behavior. - # - # For example, a logged in user may need to assign additional attributes depending - # on their role: - # - # class AccountsController < ApplicationController - # include ActiveModel::MassAssignmentSecurity - # - # attr_accessible :first_name, :last_name - # attr_accessible :first_name, :last_name, :plan_id, :as => :admin - # - # def update - # ... - # @account.update_attributes(account_params) - # ... - # end - # - # protected - # - # def account_params - # role = admin ? :admin : :default - # sanitize_for_mass_assignment(params[:account], role) - # end - # - # end - # - # = Configuration options - # - # * <tt>mass_assignment_sanitizer</tt> - Defines sanitize method. Possible values are: - # * <tt>:logger</tt> (default) - writes filtered attributes to logger - # * <tt>:strict</tt> - raise <tt>ActiveModel::MassAssignmentSecurity::Error</tt> on any protected attribute update - # - # You can specify your own sanitizer object eg. MySanitizer.new. - # See <tt>ActiveModel::MassAssignmentSecurity::LoggerSanitizer</tt> for example implementation. - # - # module ClassMethods # Attributes named in this macro are protected from mass-assignment # whenever attributes are sanitized before assignment. A role for the - # attributes is optional, if no role is provided then :default is used. - # A role can be defined by using the :as option with a symbol or an array of symbols as the value. + # attributes is optional, if no role is provided then <tt>:default</tt> + # is used. A role can be defined by using the <tt>:as</tt> option with a + # symbol or an array of symbols as the value. # # Mass-assignment to these attributes will simply be ignored, to assign # to them you can use direct writer methods. This is meant to protect # sensitive attributes from being overwritten by malicious users - # tampering with URLs or forms. Example: + # tampering with URLs or forms. # # class Customer # include ActiveModel::MassAssignmentSecurity @@ -73,7 +76,7 @@ module ActiveModel # # attr_protected :logins_count # # Suppose that admin can not change email for customer - # attr_protected :logins_count, :email, :as => :admin + # attr_protected :logins_count, :email, as: :admin # # def assign_attributes(values, options = {}) # sanitize_for_mass_assignment(values, options[:as]).each do |k, v| @@ -82,23 +85,23 @@ module ActiveModel # end # end # - # When using the :default role: + # When using the <tt>:default</tt> role: # # customer = Customer.new - # customer.assign_attributes({ "name" => "David", "email" => "a@b.com", :logins_count => 5 }, :as => :default) - # customer.name # => "David" - # customer.email # => "a@b.com" - # customer.logins_count # => nil + # customer.assign_attributes({ name: 'David', email: 'a@b.com', logins_count: 5 }, as: :default) + # customer.name # => "David" + # customer.email # => "a@b.com" + # customer.logins_count # => nil # - # And using the :admin role: + # And using the <tt>:admin</tt> role: # # customer = Customer.new - # customer.assign_attributes({ "name" => "David", "email" => "a@b.com", :logins_count => 5}, :as => :admin) - # customer.name # => "David" - # customer.email # => nil - # customer.logins_count # => nil + # customer.assign_attributes({ name: 'David', email: 'a@b.com', logins_count: 5}, as: :admin) + # customer.name # => "David" + # customer.email # => nil + # customer.logins_count # => nil # - # customer.email = "c@d.com" + # customer.email = 'c@d.com' # customer.email # => "c@d.com" # # To start from an all-closed default and enable attributes as needed, @@ -124,8 +127,9 @@ module ActiveModel # mass-assignment. # # Like +attr_protected+, a role for the attributes is optional, - # if no role is provided then :default is used. A role can be defined by - # using the :as option with a symbol or an array of symbols as the value. + # if no role is provided then <tt>:default</tt> is used. A role can be + # defined by using the <tt>:as</tt> option with a symbol or an array of + # symbols as the value. # # This is the opposite of the +attr_protected+ macro: Mass-assignment # will only set attributes in this list, to assign to the rest of @@ -141,9 +145,9 @@ module ActiveModel # attr_accessor :name, :credit_rating # # # Both admin and default user can change name of a customer - # attr_accessible :name, :as => [:admin, :default] + # attr_accessible :name, as: [:admin, :default] # # Only admin can change credit rating of a customer - # attr_accessible :credit_rating, :as => :admin + # attr_accessible :credit_rating, as: :admin # # def assign_attributes(values, options = {}) # sanitize_for_mass_assignment(values, options[:as]).each do |k, v| @@ -152,20 +156,20 @@ module ActiveModel # end # end # - # When using the :default role: + # When using the <tt>:default</tt> role: # # customer = Customer.new - # customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :default) + # customer.assign_attributes({ name: 'David', credit_rating: 'Excellent', last_login: 1.day.ago }, as: :default) # customer.name # => "David" # customer.credit_rating # => nil # - # customer.credit_rating = "Average" + # customer.credit_rating = 'Average' # customer.credit_rating # => "Average" # - # And using the :admin role: + # And using the <tt>:admin</tt> role: # # customer = Customer.new - # customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :admin) + # customer.assign_attributes({ name: 'David', credit_rating: 'Excellent', last_login: 1.day.ago }, as: :admin) # customer.name # => "David" # customer.credit_rating # => "Excellent" # @@ -185,23 +189,131 @@ module ActiveModel self._active_authorizer = self._accessible_attributes end + # Returns an instance of <tt>ActiveModel::MassAssignmentSecurity::BlackList</tt> + # with the attributes protected by #attr_protected method. If no +role+ + # is provided, then <tt>:default</tt> is used. + # + # class Customer + # include ActiveModel::MassAssignmentSecurity + # + # attr_accessor :name, :email, :logins_count + # + # attr_protected :logins_count + # attr_protected :logins_count, :email, as: :admin + # end + # + # Customer.protected_attributes + # # => #<ActiveModel::MassAssignmentSecurity::BlackList: {"logins_count"}> + # + # Customer.protected_attributes(:default) + # # => #<ActiveModel::MassAssignmentSecurity::BlackList: {"logins_count"}> + # + # Customer.protected_attributes(:admin) + # # => #<ActiveModel::MassAssignmentSecurity::BlackList: {"logins_count", "email"}> def protected_attributes(role = :default) protected_attributes_configs[role] end + # Returns an instance of <tt>ActiveModel::MassAssignmentSecurity::WhiteList</tt> + # with the attributes protected by #attr_accessible method. If no +role+ + # is provided, then <tt>:default</tt> is used. + # + # class Customer + # include ActiveModel::MassAssignmentSecurity + # + # attr_accessor :name, :credit_rating + # + # attr_accessible :name, as: [:admin, :default] + # attr_accessible :credit_rating, as: :admin + # end + # + # Customer.accessible_attributes + # # => #<ActiveModel::MassAssignmentSecurity::WhiteList: {"name"}> + # + # Customer.accessible_attributes(:default) + # # => #<ActiveModel::MassAssignmentSecurity::WhiteList: {"name"}> + # + # Customer.accessible_attributes(:admin) + # # => #<ActiveModel::MassAssignmentSecurity::WhiteList: {"name", "credit_rating"}> def accessible_attributes(role = :default) accessible_attributes_configs[role] end + # Returns a hash with the protected attributes (by #attr_accessible or + # #attr_protected) per role. + # + # class Customer + # include ActiveModel::MassAssignmentSecurity + # + # attr_accessor :name, :credit_rating + # + # attr_accessible :name, as: [:admin, :default] + # attr_accessible :credit_rating, as: :admin + # end + # + # Customer.active_authorizers + # # => { + # # :admin=> #<ActiveModel::MassAssignmentSecurity::WhiteList: {"name", "credit_rating"}>, + # # :default=>#<ActiveModel::MassAssignmentSecurity::WhiteList: {"name"}> + # # } def active_authorizers self._active_authorizer ||= protected_attributes_configs end alias active_authorizer active_authorizers + # Returns an empty array by default. You can still override this to define + # the default attributes protected by #attr_protected method. + # + # class Customer + # include ActiveModel::MassAssignmentSecurity + # + # def self.attributes_protected_by_default + # [:name] + # end + # end + # + # Customer.protected_attributes + # # => #<ActiveModel::MassAssignmentSecurity::BlackList: {:name}> def attributes_protected_by_default [] end + # Defines sanitize method. + # + # class Customer + # include ActiveModel::MassAssignmentSecurity + # + # attr_accessor :name + # + # attr_protected :name + # + # def assign_attributes(values) + # sanitize_for_mass_assignment(values).each do |k, v| + # send("#{k}=", v) + # end + # end + # end + # + # # See ActiveModel::MassAssignmentSecurity::StrictSanitizer for more information. + # Customer.mass_assignment_sanitizer = :strict + # + # customer = Customer.new + # customer.assign_attributes(name: 'David') + # # => ActiveModel::MassAssignmentSecurity::Error: Can't mass-assign protected attributes for Customer: name + # + # Also, you can specify your own sanitizer object. + # + # class CustomSanitizer < ActiveModel::MassAssignmentSecurity::Sanitizer + # def process_removed_attributes(klass, attrs) + # raise StandardError + # end + # end + # + # Customer.mass_assignment_sanitizer = CustomSanitizer.new + # + # customer = Customer.new + # customer.assign_attributes(name: 'David') + # # => StandardError: StandardError def mass_assignment_sanitizer=(value) self._mass_assignment_sanitizer = if value.is_a?(Symbol) const_get(:"#{value.to_s.camelize}Sanitizer").new(self) @@ -227,11 +339,11 @@ module ActiveModel protected - def sanitize_for_mass_assignment(attributes, role = nil) + def sanitize_for_mass_assignment(attributes, role = nil) #:nodoc: _mass_assignment_sanitizer.sanitize(self.class, attributes, mass_assignment_authorizer(role)) end - def mass_assignment_authorizer(role) + def mass_assignment_authorizer(role) #:nodoc: self.class.active_authorizer[role || :default] end end diff --git a/activemodel/lib/active_model/mass_assignment_security/sanitizer.rb b/activemodel/lib/active_model/mass_assignment_security/sanitizer.rb index 44ce5a489d..dafb7cdff3 100644 --- a/activemodel/lib/active_model/mass_assignment_security/sanitizer.rb +++ b/activemodel/lib/active_model/mass_assignment_security/sanitizer.rb @@ -1,6 +1,6 @@ module ActiveModel module MassAssignmentSecurity - class Sanitizer + class Sanitizer #:nodoc: # Returns all attributes not denied by the authorizer. def sanitize(klass, attributes, authorizer) rejected = [] @@ -18,7 +18,7 @@ module ActiveModel end end - class LoggerSanitizer < Sanitizer + class LoggerSanitizer < Sanitizer #:nodoc: def initialize(target) @target = target super() @@ -50,7 +50,7 @@ module ActiveModel end end - class StrictSanitizer < Sanitizer + class StrictSanitizer < Sanitizer #:nodoc: def initialize(target = nil) super() end @@ -65,7 +65,7 @@ module ActiveModel end end - class Error < StandardError + class Error < StandardError #:nodoc: def initialize(klass, attrs) super("Can't mass-assign protected attributes for #{klass.name}: #{attrs.join(', ')}") end diff --git a/activemodel/lib/active_model/naming.rb b/activemodel/lib/active_model/naming.rb index af89391413..7ba439fb3e 100644 --- a/activemodel/lib/active_model/naming.rb +++ b/activemodel/lib/active_model/naming.rb @@ -218,6 +218,14 @@ module ActiveModel # Returns an ActiveModel::Name object for module. It can be # 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| @@ -254,11 +262,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.route_key(Blog::Post) #=> post # - # For shared engine: - # ActiveModel::Naming.route_key(Blog::Post) #=> blog_post + # # For shared engine: + # ActiveModel::Naming.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 @@ -266,11 +274,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. @@ -281,11 +289,11 @@ 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 diff --git a/activemodel/lib/active_model/observer_array.rb b/activemodel/lib/active_model/observer_array.rb index 8de6918d18..77bc0f71e3 100644 --- a/activemodel/lib/active_model/observer_array.rb +++ b/activemodel/lib/active_model/observer_array.rb @@ -5,20 +5,21 @@ module ActiveModel # a particular model class. class ObserverArray < Array attr_reader :model_class - def initialize(model_class, *args) + def initialize(model_class, *args) #:nodoc: @model_class = model_class super(*args) end - # Returns true if the given observer is disabled for the model class. - def disabled_for?(observer) + # Returns +true+ if the given observer is disabled for the model class, + # +false+ otherwise. + def disabled_for?(observer) #:nodoc: disabled_observers.include?(observer.class) end # Disables one or more observers. This supports multiple forms: # # ORM.observers.disable :all - # # => disables all observers for all models subclassed from + # # => disables all observers for all models subclassed from # # an ORM base class that includes ActiveModel::Observing # # e.g. ActiveRecord::Base # @@ -43,7 +44,7 @@ module ActiveModel # Enables one or more observers. This supports multiple forms: # # ORM.observers.enable :all - # # => enables all observers for all models subclassed from + # # => enables all observers for all models subclassed from # # an ORM base class that includes ActiveModel::Observing # # e.g. ActiveRecord::Base # @@ -71,11 +72,11 @@ module ActiveModel protected - def disabled_observers + def disabled_observers #:nodoc: @disabled_observers ||= Set.new end - def observer_class_for(observer) + def observer_class_for(observer) #:nodoc: return observer if observer.is_a?(Class) if observer.respond_to?(:to_sym) # string/symbol @@ -86,25 +87,25 @@ module ActiveModel end end - def start_transaction + def start_transaction #:nodoc: disabled_observer_stack.push(disabled_observers.dup) each_subclass_array do |array| array.start_transaction end end - def disabled_observer_stack + def disabled_observer_stack #:nodoc: @disabled_observer_stack ||= [] end - def end_transaction + def end_transaction #:nodoc: @disabled_observers = disabled_observer_stack.pop each_subclass_array do |array| array.end_transaction end end - def transaction + def transaction #:nodoc: start_transaction begin @@ -114,13 +115,13 @@ module ActiveModel end end - def each_subclass_array + def each_subclass_array #:nodoc: model_class.descendants.each do |subclass| yield subclass.observers end end - def set_enablement(enabled, observers) + def set_enablement(enabled, observers) #:nodoc: if block_given? transaction do set_enablement(enabled, observers) diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb index acc96ddc9f..9db7639ea3 100644 --- a/activemodel/lib/active_model/observing.rb +++ b/activemodel/lib/active_model/observing.rb @@ -8,6 +8,7 @@ require 'active_support/core_ext/object/try' require 'active_support/descendants_tracker' module ActiveModel + # == Active Model Observers Activation module Observing extend ActiveSupport::Concern @@ -16,9 +17,7 @@ module ActiveModel end module ClassMethods - # == Active Model Observers Activation - # - # Activates the observers assigned. Examples: + # Activates the observers assigned. # # class ORM # include ActiveModel::Observing @@ -34,34 +33,95 @@ module ActiveModel # ORM.observers = Cacher, GarbageCollector # # Note: Setting this does not instantiate the observers yet. - # +instantiate_observers+ is called during startup, and before + # <tt>instantiate_observers</tt> is called during startup, and before # each development request. def observers=(*values) observers.replace(values.flatten) end - # Gets an array of observers observing this model. - # The array also provides +enable+ and +disable+ methods - # that allow you to selectively enable and disable observers. - # (see <tt>ActiveModel::ObserverArray.enable</tt> and - # <tt>ActiveModel::ObserverArray.disable</tt> for more on this) + # Gets an array of observers observing this model. The array also provides + # +enable+ and +disable+ methods that allow you to selectively enable and + # disable observers (see ActiveModel::ObserverArray.enable and + # ActiveModel::ObserverArray.disable for more on this). + # + # class ORM + # include ActiveModel::Observing + # end + # + # ORM.observers = :cacher, :garbage_collector + # ORM.observers # => [:cacher, :garbage_collector] + # ORM.observers.class # => ActiveModel::ObserverArray def observers @observers ||= ObserverArray.new(self) end - # Gets the current observer instances. + # Returns the current observer instances. + # + # class Foo + # include ActiveModel::Observing + # + # attr_accessor :status + # end + # + # class FooObserver < ActiveModel::Observer + # def on_spec(record, *args) + # record.status = true + # end + # end + # + # Foo.observers = FooObserver + # Foo.instantiate_observers + # + # Foo.observer_instances # => [#<FooObserver:0x007fc212c40820>] def observer_instances @observer_instances ||= [] end # Instantiate the global observers. + # + # class Foo + # include ActiveModel::Observing + # + # attr_accessor :status + # end + # + # class FooObserver < ActiveModel::Observer + # def on_spec(record, *args) + # record.status = true + # end + # end + # + # Foo.observers = FooObserver + # + # foo = Foo.new + # foo.status = false + # foo.notify_observers(:on_spec) + # foo.status # => false + # + # Foo.instantiate_observers # => [FooObserver] + # + # foo = Foo.new + # foo.status = false + # foo.notify_observers(:on_spec) + # foo.status # => true def instantiate_observers observers.each { |o| instantiate_observer(o) } end - # Add a new observer to the pool. - # The new observer needs to respond to 'update', otherwise it - # raises an +ArgumentError+ exception. + # Add a new observer to the pool. The new observer needs to respond to + # <tt>update</tt>, otherwise it raises an +ArgumentError+ exception. + # + # class Foo + # include ActiveModel::Observing + # end + # + # class FooObserver < ActiveModel::Observer + # end + # + # Foo.add_observer(FooObserver.instance) + # + # Foo.observers_instance + # # => [#<FooObserver:0x007fccf55d9390>] def add_observer(observer) unless observer.respond_to? :update raise ArgumentError, "observer needs to respond to 'update'" @@ -69,16 +129,47 @@ module ActiveModel observer_instances << observer end - # Notify list of observers of a change. + # Fires notifications to model's observers. + # + # def save + # notify_observers(:before_save) + # ... + # notify_observers(:after_save) + # end + # + # Custom notifications can be sent in a similar fashion: + # + # notify_observers(:custom_notification, :foo) + # + # This will call <tt>custom_notification</tt>, passing as arguments + # the current object and <tt>:foo</tt>. def notify_observers(*args) observer_instances.each { |observer| observer.update(*args) } end - # Total number of observers. + # Returns the total number of instantiated observers. + # + # class Foo + # include ActiveModel::Observing + # + # attr_accessor :status + # end + # + # class FooObserver < ActiveModel::Observer + # def on_spec(record, *args) + # record.status = true + # end + # end + # + # Foo.observers = FooObserver + # Foo.observers_count # => 0 + # Foo.instantiate_observers + # Foo.observers_count # => 1 def observers_count observer_instances.size end + # <tt>count_observers</tt> is deprecated. Use #observers_count. def count_observers msg = "count_observers is deprecated in favor of observers_count" ActiveSupport::Deprecation.warn(msg) @@ -103,27 +194,36 @@ module ActiveModel end # Notify observers when the observed class is subclassed. - def inherited(subclass) + def inherited(subclass) #:nodoc: super notify_observers :observed_class_inherited, subclass end end - # Fires notifications to model's observers + # Notify a change to the list of observers. + # + # class Foo + # include ActiveModel::Observing # - # def save - # notify_observers(:before_save) - # ... - # notify_observers(:after_save) + # attr_accessor :status # end # - # Custom notifications can be sent in a similar fashion: + # class FooObserver < ActiveModel::Observer + # def on_spec(record, *args) + # record.status = true + # end + # end # - # notify_observers(:custom_notification, :foo) + # Foo.observers = FooObserver + # Foo.instantiate_observers # => [FooObserver] # - # This will call +custom_notification+, passing as arguments - # the current object and :foo. + # foo = Foo.new + # foo.status = false + # foo.notify_observers(:on_spec) + # foo.status # => true # + # See ActiveModel::Observing::ClassMethods.notify_observers for more + # information. def notify_observers(method, *extra_args) self.class.notify_observers(method, self, *extra_args) end @@ -135,15 +235,15 @@ module ActiveModel # behavior outside the original class. This is a great way to reduce the # clutter that normally comes when the model class is burdened with # functionality that doesn't pertain to the core responsibility of the - # class. Example: + # class. # # class CommentObserver < ActiveModel::Observer # def after_save(comment) - # Notifications.comment("admin@do.com", "New comment was posted", comment).deliver + # Notifications.comment('admin@do.com', 'New comment was posted', comment).deliver # end # end # - # This Observer sends an email when a Comment#save is finished. + # This Observer sends an email when a <tt>Comment#save</tt> is finished. # # class ContactObserver < ActiveModel::Observer # def after_create(contact) @@ -160,44 +260,50 @@ module ActiveModel # == Observing a class that can't be inferred # # 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 <tt>Observer.observe</tt> - # class method which takes either the concrete class (Product) or a symbol for that - # class (:product): + # name. So <tt>CommentObserver</tt> will be tied to observing <tt>Comment</tt>, + # <tt>ProductManagerObserver</tt> to <tt>ProductManager</tt>, and so on. If + # you want to name your observer differently than the class you're interested + # in observing, you can use the <tt>Observer.observe</tt> class method which + # takes either the concrete class (<tt>Product</tt>) or a symbol for that + # class (<tt>:product</tt>): # # class AuditObserver < ActiveModel::Observer # observe :account # # def after_update(account) - # AuditTrail.new(account, "UPDATED") + # AuditTrail.new(account, 'UPDATED') # end # end # - # If the audit observer needs to watch more than one kind of object, this can be - # specified with multiple arguments: + # If the audit observer needs to watch more than one kind of object, this can + # be specified with multiple arguments: # # class AuditObserver < ActiveModel::Observer # observe :account, :balance # # def after_update(record) - # AuditTrail.new(record, "UPDATED") + # AuditTrail.new(record, 'UPDATED') # end # end # - # The AuditObserver will now act on both updates to Account and Balance by treating - # them both as records. + # The <tt>AuditObserver</tt> will now act on both updates to <tt>Account</tt> + # and <tt>Balance</tt> by treating them both as records. # - # If you're using an Observer in a Rails application with Active Record, be sure to - # read about the necessary configuration in the documentation for + # If you're using an Observer in a Rails application with Active Record, be + # sure to read about the necessary configuration in the documentation for # ActiveRecord::Observer. - # class Observer include Singleton extend ActiveSupport::DescendantsTracker class << self # Attaches the observer to the supplied model classes. + # + # class AuditObserver < ActiveModel::Observer + # observe :account, :balance + # end + # + # AuditObserver.observed_classes # => [Account, Balance] def observe(*models) models.flatten! models.collect! { |model| model.respond_to?(:to_sym) ? model.to_s.camelize.constantize : model } @@ -206,6 +312,8 @@ module ActiveModel # Returns an array of Classes to observe. # + # AccountObserver.observed_classes # => [Account] + # # You can override this instead of using the +observe+ helper. # # class AuditObserver < ActiveModel::Observer @@ -217,8 +325,11 @@ module ActiveModel Array(observed_class) end - # The class observed by default is inferred from the observer's class name: - # assert_equal Person, PersonObserver.observed_class + # Returns the class observed by default. It's inferred from the observer's + # class name. + # + # PersonObserver.observed_class # => Person + # AccountObserver.observed_class # => Account def observed_class name[/(.*)Observer/, 1].try :constantize end @@ -226,7 +337,7 @@ module ActiveModel # Start observing the declared classes and their subclasses. # Called automatically by the instance method. - def initialize + def initialize #:nodoc: observed_classes.each { |klass| add_observer!(klass) } end @@ -237,7 +348,7 @@ module ActiveModel # Send observed_method(object) if the method exists and # the observer is enabled for the given object's class. def update(observed_method, object, *extra_args, &block) #:nodoc: - return if !respond_to?(observed_method) || disabled_for?(object) + return if !respond_to?(observed_method) || disabled_for?(object) send(observed_method, object, *extra_args, &block) end @@ -254,7 +365,7 @@ module ActiveModel end # Returns true if notifications are disabled for this object. - def disabled_for?(object) + def disabled_for?(object) #:nodoc: klass = object.class return false unless klass.respond_to?(:observers) klass.observers.disabled_for?(self) diff --git a/activemodel/lib/active_model/secure_password.rb b/activemodel/lib/active_model/secure_password.rb index dc89efd2d1..d011402081 100644 --- a/activemodel/lib/active_model/secure_password.rb +++ b/activemodel/lib/active_model/secure_password.rb @@ -6,12 +6,12 @@ module ActiveModel # Adds methods to set and authenticate against a BCrypt password. # This mechanism requires you to have a password_digest attribute. # - # Validations for presence of password on create, confirmation of password (using - # a "password_confirmation" attribute) are automatically added. - # If you wish to turn off validations, pass 'validations: false' as an argument. - # You can add more validations by hand if need be. + # Validations for presence of password on create, confirmation of password + # (using a +password_confirmation+ attribute) are automatically added. If + # you wish to turn off validations, pass <tt>validations: false</tt> as an + # argument. You can add more validations by hand if need be. # - # You need to add bcrypt-ruby (~> 3.0.0) to Gemfile to use has_secure_password: + # You need to add bcrypt-ruby (~> 3.0.0) to Gemfile to use #has_secure_password: # # gem 'bcrypt-ruby', '~> 3.0.0' # @@ -22,24 +22,25 @@ module ActiveModel # has_secure_password # end # - # user = User.new(:name => "david", :password => "", :password_confirmation => "nomatch") + # user = User.new(name: 'david', password: '', password_confirmation: 'nomatch') # user.save # => false, password required - # user.password = "mUc3m00RsqyRe" + # user.password = 'mUc3m00RsqyRe' # user.save # => false, confirmation doesn't match - # user.password_confirmation = "mUc3m00RsqyRe" + # user.password_confirmation = 'mUc3m00RsqyRe' # user.save # => true - # user.authenticate("notright") # => false - # user.authenticate("mUc3m00RsqyRe") # => user - # User.find_by_name("david").try(:authenticate, "notright") # => false - # User.find_by_name("david").try(:authenticate, "mUc3m00RsqyRe") # => user + # user.authenticate('notright') # => false + # user.authenticate('mUc3m00RsqyRe') # => user + # User.find_by_name('david').try(:authenticate, 'notright') # => false + # User.find_by_name('david').try(:authenticate, 'mUc3m00RsqyRe') # => user def has_secure_password(options = {}) # Load bcrypt-ruby only when has_secure_password is used. - # This is to avoid ActiveModel (and by extension the entire framework) being dependent on a binary library. + # This is to avoid ActiveModel (and by extension the entire framework) + # being dependent on a binary library. gem 'bcrypt-ruby', '~> 3.0.0' require 'bcrypt' attr_reader :password - + if options.fetch(:validations, true) validates_confirmation_of :password validates_presence_of :password, :on => :create @@ -50,7 +51,7 @@ module ActiveModel include InstanceMethodsOnActivation if respond_to?(:attributes_protected_by_default) - def self.attributes_protected_by_default + def self.attributes_protected_by_default #:nodoc: super + ['password_digest'] end end @@ -58,13 +59,32 @@ module ActiveModel end module InstanceMethodsOnActivation - # Returns self if the password is correct, otherwise false. + # Returns +self+ if the password is correct, otherwise +false+. + # + # class User < ActiveRecord::Base + # has_secure_password validations: false + # end + # + # user = User.new(name: 'david', password: 'mUc3m00RsqyRe') + # user.save + # user.authenticate('notright') # => false + # user.authenticate('mUc3m00RsqyRe') # => user def authenticate(unencrypted_password) BCrypt::Password.new(password_digest) == unencrypted_password && self end - # Encrypts the password into the password_digest attribute, only if the + # Encrypts the password into the +password_digest+ attribute, only if the # new password is not blank. + # + # class User < ActiveRecord::Base + # has_secure_password validations: false + # end + # + # user = User.new + # user.password = nil + # user.password_digest # => nil + # user.password = 'mUc3m00RsqyRe' + # user.password_digest # => "$2a$10$4LEA7r4YmNHtvlAvHhsYAeZmk/xeUVtMTYqwIvYY76EW5GUqDiP4." def password=(unencrypted_password) unless unencrypted_password.blank? @password = unencrypted_password diff --git a/activemodel/lib/active_model/serializers/json.rb b/activemodel/lib/active_model/serializers/json.rb index eaea0475ad..a4252b995d 100644 --- a/activemodel/lib/active_model/serializers/json.rb +++ b/activemodel/lib/active_model/serializers/json.rb @@ -18,8 +18,8 @@ module ActiveModel # passed through +options+. # # The option <tt>include_root_in_json</tt> controls the top-level behavior - # of +as_json+. If true +as_json+ will emit a single root node named after - # the object's type. The default value for <tt>include_root_in_json</tt> + # of +as_json+. If +true+, +as_json+ will emit a single root node named + # after the object's type. The default value for <tt>include_root_in_json</tt> # option is +false+. # # user = User.find(1) @@ -100,6 +100,40 @@ module ActiveModel end end + # Sets the model +attributes+ from a JSON string. Returns +self+. + # + # class Person + # include ActiveModel::Serializers::JSON + # + # attr_accessor :name, :age, :awesome + # + # def attributes=(hash) + # hash.each do |key, value| + # instance_variable_set("@#{key}", value) + # end + # end + # + # def attributes + # instance_values + # end + # end + # + # json = { name: 'bob', age: 22, awesome:true }.to_json + # person = Person.new + # person.from_json(json) # => #<Person:0x007fec5e7a0088 @age=22, @awesome=true, @name="bob"> + # person.name # => "bob" + # person.age # => 22 + # person.awesome # => true + # + # The default value for +include_root+ is +false+. You can change it to + # +true+ if the given JSON string includes a single root node. + # + # json = { person: { name: 'bob', age: 22, awesome:true } }.to_json + # person = Person.new + # person.from_json(json) # => #<Person:0x007fec5e7a0088 @age=22, @awesome=true, @name="bob"> + # person.name # => "bob" + # person.age # => 22 + # person.awesome # => true def from_json(json, include_root=include_root_in_json) hash = ActiveSupport::JSON.decode(json) hash = hash.values.first if include_root diff --git a/activemodel/lib/active_model/serializers/xml.rb b/activemodel/lib/active_model/serializers/xml.rb index 2b3e9ce134..016d821fdf 100644 --- a/activemodel/lib/active_model/serializers/xml.rb +++ b/activemodel/lib/active_model/serializers/xml.rb @@ -110,7 +110,7 @@ module ActiveModel end end - # TODO This can likely be cleaned up to simple use ActiveSupport::XmlMini.to_tag as well. + # TODO: This can likely be cleaned up to simple use ActiveSupport::XmlMini.to_tag as well. def add_associations(association, records, opts) merged_options = opts.merge(options.slice(:builder, :indent)) merged_options[:skip_instruct] = true @@ -161,8 +161,8 @@ module ActiveModel # Returns XML representing the model. Configuration can be # passed through +options+. # - # Without any +options+, the returned XML string will include all the model's - # attributes. For example: + # Without any +options+, the returned XML string will include all the + # model's attributes. # # user = User.find(1) # user.to_xml @@ -175,18 +175,42 @@ module ActiveModel # <created-at type="dateTime">2011-01-30T22:29:23Z</created-at> # </user> # - # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the attributes - # included, and work similar to the +attributes+ method. + # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the + # attributes included, and work similar to the +attributes+ method. # # To include the result of some method calls on the model use <tt>:methods</tt>. # # To include associations use <tt>:include</tt>. # - # For further documentation see activerecord/lib/active_record/serializers/xml_serializer.xml. + # For further documentation, see <tt>ActiveRecord::Serialization#to_xml</tt> def to_xml(options = {}, &block) Serializer.new(self, options).serialize(&block) end + # Sets the model +attributes+ from a JSON string. Returns +self+. + # + # class Person + # include ActiveModel::Serializers::Xml + # + # attr_accessor :name, :age, :awesome + # + # def attributes=(hash) + # hash.each do |key, value| + # instance_variable_set("@#{key}", value) + # end + # end + # + # def attributes + # instance_values + # end + # end + # + # xml = { name: 'bob', age: 22, awesome:true }.to_xml + # person = Person.new + # person.from_xml(xml) # => #<Person:0x007fec5e3b3c40 @age=22, @awesome=true, @name="bob"> + # person.name # => "bob" + # person.age # => 22 + # person.awesome # => true def from_xml(xml) self.attributes = Hash.from_xml(xml).values.first self diff --git a/activemodel/lib/active_model/validations.rb b/activemodel/lib/active_model/validations.rb index 5ae3a97c6b..4762f39044 100644 --- a/activemodel/lib/active_model/validations.rb +++ b/activemodel/lib/active_model/validations.rb @@ -32,11 +32,11 @@ module ActiveModel # person.first_name = 'zoolander' # person.valid? # => false # person.invalid? # => true - # person.errors # => #<Hash {:first_name=>["starts with z."]}> + # person.errors.messages # => {:first_name=>["starts with z."]} # - # Note that <tt>ActiveModel::Validations</tt> automatically adds an +errors+ method - # to your instances initialized with a new <tt>ActiveModel::Errors</tt> object, so - # there is no need for you to do this manually. + # Note that <tt>ActiveModel::Validations</tt> automatically adds an +errors+ + # method to your instances initialized with a new <tt>ActiveModel::Errors</tt> + # object, so there is no need for you to do this manually. module Validations extend ActiveSupport::Concern @@ -62,24 +62,25 @@ module ActiveModel # # attr_accessor :first_name, :last_name # - # validates_each :first_name, :last_name, :allow_blank => true do |record, attr, value| + # validates_each :first_name, :last_name, allow_blank: true do |record, attr, value| # record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z # end # end # # Options: # * <tt>:on</tt> - Specifies the context where this validation is active - # (e.g. <tt>:on => :create</tt> or <tt>:on => :custom_validation_context</tt>) + # (e.g. <tt>on: :create</tt> or <tt>on: :custom_validation_context</tt>) # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+. # * <tt>:allow_blank</tt> - Skip validation if attribute is blank. # * <tt>:if</tt> - Specifies a method, proc or string to call to determine - # if the validation should occur (e.g. <tt>:if => :allow_validation</tt>, - # or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, - # proc or string should return or evaluate to a true or false value. - # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should - # not occur (e.g. <tt>:unless => :skip_validation</tt>, or - # <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The - # method, proc or string should return or evaluate to a true or false value. + # if the validation should occur (e.g. <tt>if: :allow_validation</tt>, + # or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method, + # proc or string should return or evaluate to a +true+ or +false+ value. + # * <tt>:unless</tt> - Specifies a method, proc or string to call to + # determine if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>, + # or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The + # method, proc or string should return or evaluate to a +true+ or +false+ + # value. def validates_each(*attr_names, &block) validates_with BlockValidator, _merge_attributes(attr_names), &block end @@ -96,7 +97,7 @@ module ActiveModel # validate :must_be_friends # # def must_be_friends - # errors.add(:base, "Must be friends to leave a comment") unless commenter.friend_of?(commentee) + # errors.add(:base, 'Must be friends to leave a comment') unless commenter.friend_of?(commentee) # end # end # @@ -110,7 +111,7 @@ module ActiveModel # end # # def must_be_friends - # errors.add(:base, "Must be friends to leave a comment") unless commenter.friend_of?(commentee) + # errors.add(:base, 'Must be friends to leave a comment') unless commenter.friend_of?(commentee) # end # end # @@ -120,23 +121,24 @@ module ActiveModel # include ActiveModel::Validations # # validate do - # errors.add(:base, "Must be friends to leave a comment") unless commenter.friend_of?(commentee) + # errors.add(:base, 'Must be friends to leave a comment') unless commenter.friend_of?(commentee) # end # end # # Options: # * <tt>:on</tt> - Specifies the context where this validation is active - # (e.g. <tt>:on => :create</tt> or <tt>:on => :custom_validation_context</tt>) + # (e.g. <tt>on: :create</tt> or <tt>on: :custom_validation_context</tt>) # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+. # * <tt>:allow_blank</tt> - Skip validation if attribute is blank. # * <tt>:if</tt> - Specifies a method, proc or string to call to determine - # if the validation should occur (e.g. <tt>:if => :allow_validation</tt>, - # or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, - # proc or string should return or evaluate to a true or false value. - # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should - # not occur (e.g. <tt>:unless => :skip_validation</tt>, or - # <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The - # method, proc or string should return or evaluate to a true or false value. + # if the validation should occur (e.g. <tt>if: :allow_validation</tt>, + # or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method, + # proc or string should return or evaluate to a +true+ or +false+ value. + # * <tt>:unless</tt> - Specifies a method, proc or string to call to + # determine if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>, + # or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The + # method, proc or string should return or evaluate to a +true+ or +false+ + # value. def validate(*args, &block) options = args.extract_options! if options.key?(:on) @@ -170,39 +172,101 @@ module ActiveModel end # List all validators that are being used to validate a specific attribute. + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name , :age + # + # validates_presence_of :name + # validates_inclusion_of :age, in: 0..99 + # end + # + # Person.validators_on(:name) + # # => [ + # # #<ActiveModel::Validations::PresenceValidator:0x007fe604914e60 @attributes=[:name], @options={}>, + # # #<ActiveModel::Validations::InclusionValidator:0x007fe603bb8780 @attributes=[:age], @options={:in=>0..99}> + # # ] def validators_on(*attributes) attributes.map do |attribute| _validators[attribute.to_sym] end.flatten end - # Check if method is an attribute method or not. + # Returns +true+ if +attribute+ is an attribute method, +false+ otherwise. + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name + # end + # + # User.attribute_method?(:name) # => true + # User.attribute_method?(:age) # => false def attribute_method?(attribute) method_defined?(attribute) end # Copy validators on inheritance. - def inherited(base) + def inherited(base) #:nodoc: dup = _validators.dup base._validators = dup.each { |k, v| dup[k] = v.dup } super end end - # Clean the +Errors+ object if instance is duped - def initialize_dup(other) # :nodoc: + # Clean the +Errors+ object if instance is duped. + def initialize_dup(other) #:nodoc: @errors = nil super end - # Returns the +Errors+ object that holds all information about attribute error messages. + # Returns the +Errors+ object that holds all information about attribute + # error messages. + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name + # validates_presence_of :name + # end + # + # person = Person.new + # person.valid? # => false + # person.errors # => #<ActiveModel::Errors:0x007fe603816640 @messages={:name=>["can't be blank"]}> def errors @errors ||= Errors.new(self) end - # Runs all the specified validations and returns true if no errors were added - # otherwise false. Context can optionally be supplied to define which callbacks - # to test against (the context is defined on the validations using :on). + # Runs all the specified validations and returns +true+ if no errors were + # added otherwise +false+. + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name + # validates_presence_of :name + # end + # + # person = Person.new + # person.name = '' + # person.valid? # => false + # person.name = 'david' + # person.valid? # => true + # + # Context can optionally be supplied to define which callbacks to test + # against (the context is defined on the validations using <tt>:on</tt>). + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name + # validates_presence_of :name, on: :new + # end + # + # person = Person.new + # person.valid? # => true + # person.valid?(:new) # => false def valid?(context = nil) current_context, self.validation_context = validation_context, context errors.clear @@ -211,8 +275,35 @@ module ActiveModel self.validation_context = current_context end - # Performs the opposite of <tt>valid?</tt>. Returns true if errors were added, - # false otherwise. + # Performs the opposite of <tt>valid?</tt>. Returns +true+ if errors were + # added, +false+ otherwise. + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name + # validates_presence_of :name + # end + # + # person = Person.new + # person.name = '' + # person.invalid? # => true + # person.name = 'david' + # person.invalid? # => false + # + # Context can optionally be supplied to define which callbacks to test + # against (the context is defined on the validations using <tt>:on</tt>). + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name + # validates_presence_of :name, on: :new + # end + # + # person = Person.new + # person.invalid? # => false + # person.invalid?(:new) # => true def invalid?(context = nil) !valid?(context) end @@ -237,7 +328,7 @@ module ActiveModel protected - def run_validations! + def run_validations! #:nodoc: run_callbacks :validate errors.empty? end diff --git a/activemodel/lib/active_model/validations/callbacks.rb b/activemodel/lib/active_model/validations/callbacks.rb index dbafd0bd1a..bf3fe7ff04 100644 --- a/activemodel/lib/active_model/validations/callbacks.rb +++ b/activemodel/lib/active_model/validations/callbacks.rb @@ -2,24 +2,24 @@ require 'active_support/callbacks' module ActiveModel module Validations + # == Active Model Validation callbacks + # + # Provides an interface for any class to have +before_validation+ and + # +after_validation+ callbacks. + # + # First, include ActiveModel::Validations::Callbacks from the class you are + # creating: + # + # class MyModel + # include ActiveModel::Validations::Callbacks + # + # before_validation :do_stuff_before_validation + # after_validation :do_stuff_after_validation + # end + # + # Like other <tt>before_*</tt> callbacks if +before_validation+ returns + # +false+ then <tt>valid?</tt> will not be called. module Callbacks - # == Active Model Validation callbacks - # - # Provides an interface for any class to have <tt>before_validation</tt> and - # <tt>after_validation</tt> callbacks. - # - # First, include ActiveModel::Validations::Callbacks from the class you are - # creating: - # - # class MyModel - # include ActiveModel::Validations::Callbacks - # - # before_validation :do_stuff_before_validation - # after_validation :do_stuff_after_validation - # end - # - # Like other before_* callbacks if <tt>before_validation</tt> returns false - # then <tt>valid?</tt> will not be called. extend ActiveSupport::Concern included do @@ -28,6 +28,30 @@ module ActiveModel end module ClassMethods + # Defines a callback that will get called right before validation + # happens. + # + # class Person + # include ActiveModel::Validations + # include ActiveModel::Validations::Callbacks + # + # attr_accessor :name + # + # validates_length_of :name, maximum: 6 + # + # before_validation :remove_whitespaces + # + # private + # + # def remove_whitespaces + # name.strip! + # end + # end + # + # person = Person.new + # person.name = ' bob ' + # person.valid? # => true + # person.name # => "bob" def before_validation(*args, &block) options = args.last if options.is_a?(Hash) && options[:on] @@ -37,6 +61,33 @@ module ActiveModel set_callback(:validation, :before, *args, &block) end + # Defines a callback that will get called right after validation + # happens. + # + # class Person + # include ActiveModel::Validations + # include ActiveModel::Validations::Callbacks + # + # attr_accessor :name, :status + # + # validates_presence_of :name + # + # after_validation :set_status + # + # private + # + # def set_status + # self.status = errors.empty? + # end + # end + # + # person = Person.new + # person.name = '' + # person.valid? # => false + # person.status # => false + # person.name = 'bob' + # person.valid? # => true + # person.status # => true def after_validation(*args, &block) options = args.extract_options! options[:prepend] = true @@ -49,7 +100,7 @@ module ActiveModel protected # Overwrite run validations to include callbacks. - def run_validations! + def run_validations! #:nodoc: run_callbacks(:validation) { super } end end diff --git a/activemodel/lib/active_model/validations/validates.rb b/activemodel/lib/active_model/validations/validates.rb index ecda9dffcf..5892ad29d1 100644 --- a/activemodel/lib/active_model/validations/validates.rb +++ b/activemodel/lib/active_model/validations/validates.rb @@ -11,18 +11,18 @@ module ActiveModel # # Examples of using the default rails validators: # - # validates :terms, :acceptance => true - # validates :password, :confirmation => true - # validates :username, :exclusion => { :in => %w(admin superuser) } - # validates :email, :format => { :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i, :on => :create } - # validates :age, :inclusion => { :in => 0..9 } - # validates :first_name, :length => { :maximum => 30 } - # validates :age, :numericality => true - # validates :username, :presence => true - # validates :username, :uniqueness => true + # validates :terms, acceptance: true + # validates :password, confirmation: true + # validates :username, exclusion: { in: %w(admin superuser) } + # validates :email, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i, on: :create } + # validates :age, inclusion: { in: 0..9 } + # validates :first_name, length: { maximum: 30 } + # validates :age, numericality: true + # validates :username, presence: true + # validates :username, uniqueness: true # # The power of the +validates+ method comes when using custom validators - # and default validators in one call for a given attribute e.g. + # and default validators in one call for a given attribute. # # class EmailValidator < ActiveModel::EachValidator # def validate_each(record, attribute, value) @@ -35,12 +35,12 @@ module ActiveModel # include ActiveModel::Validations # attr_accessor :name, :email # - # validates :name, :presence => true, :uniqueness => true, :length => { :maximum => 100 } - # validates :email, :presence => true, :email => true + # validates :name, presence: true, uniqueness: true, length: { maximum: 100 } + # validates :email, presence: true, email: true # end # # Validator classes may also exist within the class being validated - # allowing custom modules of validators to be included as needed e.g. + # allowing custom modules of validators to be included as needed. # # class Film # include ActiveModel::Validations @@ -51,25 +51,27 @@ module ActiveModel # end # end # - # validates :name, :title => true + # validates :name, title: true # end # - # Additionally validator classes may be in another namespace and still used within any class. + # Additionally validator classes may be in another namespace and still + # used within any class. # # validates :name, :'film/title' => true # - # The validators hash can also handle regular expressions, ranges, - # arrays and strings in shortcut form, e.g. + # The validators hash can also handle regular expressions, ranges, arrays + # and strings in shortcut form. # - # validates :email, :format => /@/ - # validates :gender, :inclusion => %w(male female) - # validates :password, :length => 6..20 + # validates :email, format: /@/ + # validates :gender, inclusion: %w(male female) + # validates :password, length: 6..20 # # When using shortcut form, ranges and arrays are passed to your - # validator's initializer as +options[:in]+ while other types including - # regular expressions and strings are passed as +options[:with]+ + # validator's initializer as <tt>options[:in]</tt> while other types + # including regular expressions and strings are passed as <tt>options[:with]</tt>. # # There is also a list of options that could be used along with validators: + # # * <tt>:on</tt> - Specifies when this validation is active. Runs in all # validation contexts by default (+nil+), other options are <tt>:create</tt> # and <tt>:update</tt>. @@ -87,14 +89,12 @@ module ActiveModel # # Example: # - # validates :password, :presence => true, :confirmation => true, :if => :password_required? - # - # Finally, the options +:if+, +:unless+, +:on+, +:allow_blank+, +:allow_nil+ and +:strict+ - # can be given to one specific validator, as a hash: - # - # validates :password, :presence => { :if => :password_required? }, :confirmation => true + # validates :password, presence: true, confirmation: true, if: :password_required? # + # Finally, the options +:if+, +:unless+, +:on+, +:allow_blank+, +:allow_nil+ + # and +:strict+ can be given to one specific validator, as a hash: # + # validates :password, presence: { if: :password_required? }, confirmation: true def validates(*attributes) defaults = attributes.extract_options!.dup validations = defaults.slice!(*_validates_default_keys) @@ -122,8 +122,20 @@ module ActiveModel # users and are considered exceptional. So each validator defined with bang # or <tt>:strict</tt> option set to <tt>true</tt> will always raise # <tt>ActiveModel::StrictValidationFailed</tt> instead of adding error - # when validation fails. - # See <tt>validates</tt> for more information about the validation itself. + # when validation fails. See <tt>validates</tt> for more information about + # the validation itself. + # + # class Person + # include ActiveModel::Validations + # + # attr_accessor :name + # validates! :name, presence: true + # end + # + # person = Person.new + # person.name = '' + # person.valid? + # # => ActiveModel::StrictValidationFailed: Name can't be blank def validates!(*attributes) options = attributes.extract_options! options[:strict] = true @@ -134,7 +146,7 @@ module ActiveModel # When creating custom validators, it might be useful to be able to specify # additional default keys. This can be done by overwriting this method. - def _validates_default_keys + def _validates_default_keys #:nodoc: [:if, :unless, :on, :allow_blank, :allow_nil , :strict] end diff --git a/activemodel/lib/active_model/validations/with.rb b/activemodel/lib/active_model/validations/with.rb index 3c516f8b22..869591cd9e 100644 --- a/activemodel/lib/active_model/validations/with.rb +++ b/activemodel/lib/active_model/validations/with.rb @@ -34,7 +34,7 @@ module ActiveModel # class MyValidator < ActiveModel::Validator # def validate(record) # if some_complex_logic - # record.errors.add :base, "This record is invalid" + # record.errors.add :base, 'This record is invalid' # end # end # @@ -48,30 +48,32 @@ module ActiveModel # # class Person # include ActiveModel::Validations - # validates_with MyValidator, MyOtherValidator, :on => :create + # validates_with MyValidator, MyOtherValidator, on: :create # end # # Configuration options: # * <tt>:on</tt> - Specifies when this validation is active - # (<tt>:create</tt> or <tt>:update</tt> + # (<tt>:create</tt> or <tt>:update</tt>. # * <tt>:if</tt> - Specifies a method, proc or string to call to determine - # if the validation should occur (e.g. <tt>:if => :allow_validation</tt>, - # or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). - # The method, proc or string should return or evaluate to a true or false value. + # if the validation should occur (e.g. <tt>if: :allow_validation</tt>, + # or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). + # The method, proc or string should return or evaluate to a +true+ or + # +false+ value. # * <tt>:unless</tt> - Specifies a method, proc or string to call to # determine if the validation should not occur - # (e.g. <tt>:unless => :skip_validation</tt>, or - # <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). - # The method, proc or string should return or evaluate to a true or false value. + # (e.g. <tt>unless: :skip_validation</tt>, or + # <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). + # The method, proc or string should return or evaluate to a +true+ or + # +false+ value. # * <tt>:strict</tt> - Specifies whether validation should be strict. # See <tt>ActiveModel::Validation#validates!</tt> for more information. # # If you pass any additional configuration options, they will be passed - # to the class and available as <tt>options</tt>: + # to the class and available as +options+: # # class Person # include ActiveModel::Validations - # validates_with MyValidator, :my_custom_key => "my custom value" + # validates_with MyValidator, my_custom_key: 'my custom value' # end # # class MyValidator < ActiveModel::Validator @@ -119,17 +121,17 @@ module ActiveModel # class Person # include ActiveModel::Validations # - # validate :instance_validations, :on => :create + # validate :instance_validations, on: :create # # def instance_validations # validates_with MyValidator, MyOtherValidator # end # end # - # Standard configuration options (:on, :if and :unless), which are - # available on the class version of +validates_with+, should instead be - # placed on the +validates+ method as these are applied and tested - # in the callback. + # Standard configuration options (<tt>:on</tt>, <tt>:if</tt> and + # <tt>:unless</tt>), which are available on the class version of + # +validates_with+, should instead be placed on the +validates+ method + # as these are applied and tested in the callback. # # If you pass any additional configuration options, they will be passed # to the class and available as +options+, please refer to the diff --git a/activemodel/lib/active_model/validator.rb b/activemodel/lib/active_model/validator.rb index cbbf58505b..87e4319421 100644 --- a/activemodel/lib/active_model/validator.rb +++ b/activemodel/lib/active_model/validator.rb @@ -1,6 +1,6 @@ require "active_support/core_ext/module/anonymous" -module ActiveModel #:nodoc: +module ActiveModel # == Active Model Validator # @@ -26,7 +26,7 @@ module ActiveModel #:nodoc: # end # # Any class that inherits from ActiveModel::Validator must implement a method - # called <tt>validate</tt> which accepts a <tt>record</tt>. + # called +validate+ which accepts a +record+. # # class Person # include ActiveModel::Validations @@ -40,8 +40,8 @@ module ActiveModel #:nodoc: # end # end # - # To cause a validation error, you must add to the <tt>record</tt>'s errors directly - # from within the validators message + # To cause a validation error, you must add to the +record+'s errors directly + # from within the validators message. # # class MyValidator < ActiveModel::Validator # def validate(record) @@ -61,7 +61,7 @@ module ActiveModel #:nodoc: # end # # The easiest way to add custom validators for validating individual attributes - # is with the convenient <tt>ActiveModel::EachValidator</tt>. For example: + # is with the convenient <tt>ActiveModel::EachValidator</tt>. # # class TitleValidator < ActiveModel::EachValidator # def validate_each(record, attribute, value) @@ -70,7 +70,7 @@ module ActiveModel #:nodoc: # end # # This can now be used in combination with the +validates+ method - # (see <tt>ActiveModel::Validations::ClassMethods.validates</tt> for more on this) + # (see <tt>ActiveModel::Validations::ClassMethods.validates</tt> for more on this). # # class Person # include ActiveModel::Validations @@ -81,8 +81,7 @@ module ActiveModel #:nodoc: # # Validator may also define a +setup+ instance method which will get called # with the class that using that validator as its argument. This can be - # useful when there are prerequisites such as an +attr_accessor+ being present - # for example: + # useful when there are prerequisites such as an +attr_accessor+ being present. # # class MyValidator < ActiveModel::Validator # def setup(klass) @@ -92,15 +91,13 @@ module ActiveModel #:nodoc: # # This setup method is only called when used with validation macros or the # class level <tt>validates_with</tt> method. - # class Validator attr_reader :options - # Returns the kind of the validator. Examples: + # Returns the kind of the validator. # # PresenceValidator.kind # => :presence # UniquenessValidator.kind # => :uniqueness - # def self.kind @kind ||= name.split('::').last.underscore.sub(/_validator$/, '').to_sym unless anonymous? end @@ -111,6 +108,9 @@ module ActiveModel #:nodoc: end # Return the kind for this validator. + # + # PresenceValidator.new.kind # => :presence + # UniquenessValidator.new.kind # => :uniqueness def kind self.class.kind end |