From aceb4a58a6cc5aecb49f91424926ccce19833a17 Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Sun, 21 Oct 2012 00:59:59 -0500 Subject: update AR::AttributeMethods documentation [ci skip] --- .../lib/active_record/attribute_methods.rb | 147 +++++++++++++++++---- 1 file changed, 124 insertions(+), 23 deletions(-) diff --git a/activerecord/lib/active_record/attribute_methods.rb b/activerecord/lib/active_record/attribute_methods.rb index 0aff2562b8..008696f6de 100644 --- a/activerecord/lib/active_record/attribute_methods.rb +++ b/activerecord/lib/active_record/attribute_methods.rb @@ -2,7 +2,7 @@ require 'active_support/core_ext/enumerable' module ActiveRecord # = Active Record Attribute Methods - module AttributeMethods #:nodoc: + module AttributeMethods extend ActiveSupport::Concern include ActiveModel::AttributeMethods @@ -20,7 +20,7 @@ module ActiveRecord module ClassMethods # Generates all the attribute related methods for columns in the database # accessors, mutators and query methods. - def define_attribute_methods + def define_attribute_methods # :nodoc: # Use a mutex; we don't want two thread simaltaneously trying to define # attribute methods. @attribute_methods_mutex.synchronize do @@ -31,15 +31,29 @@ module ActiveRecord end end - def attribute_methods_generated? + def attribute_methods_generated? # :nodoc: @attribute_methods_generated ||= false end - def undefine_attribute_methods + def undefine_attribute_methods # :nodoc: super if attribute_methods_generated? @attribute_methods_generated = false end + # Raises a ActiveRecord::DangerousAttributeError exception when an + # \Active \Record method is defined in the model, otherwise +false+. + # + # class Person < ActiveRecord::Base + # def save + # 'already defined by Active Record' + # end + # end + # + # Person.instance_method_already_implemented?(:save) + # # => ActiveRecord::DangerousAttributeError: save is defined by ActiveRecord + # + # Person.instance_method_already_implemented?(:name) + # # => false def instance_method_already_implemented?(method_name) if dangerous_attribute_method?(method_name) raise DangerousAttributeError, "#{method_name} is defined by ActiveRecord" @@ -56,11 +70,11 @@ module ActiveRecord # A method name is 'dangerous' if it is already defined by Active Record, but # not by any ancestors. (So 'puts' is not dangerous but 'save' is.) - def dangerous_attribute_method?(name) + def dangerous_attribute_method?(name) # :nodoc: method_defined_within?(name, Base) end - def method_defined_within?(name, klass, sup = klass.superclass) + def method_defined_within?(name, klass, sup = klass.superclass) # :nodoc: if klass.method_defined?(name) || klass.private_method_defined?(name) if sup.method_defined?(name) || sup.private_method_defined?(name) klass.instance_method(name).owner != sup.instance_method(name).owner @@ -72,13 +86,27 @@ module ActiveRecord end end + # Returns +true+ if +attribute+ is an attribute method and table exists, + # +false+ otherwise. + # + # class Person < ActiveRecord::Base + # end + # + # Person.attribute_method?('name') # => true + # Person.attribute_method?(:age=) # => true + # Person.attribute_method?(:nothing) # => false def attribute_method?(attribute) super || (table_exists? && column_names.include?(attribute.to_s.sub(/=$/, ''))) end - # Returns an array of column names as strings if it's not - # an abstract class and table exists. - # Otherwise it returns an empty array. + # Returns an array of column names as strings if it's not an abstract class and + # table exists. Otherwise it returns an empty array. + # + # class Person < ActiveRecord::Base + # end + # + # Person.attribute_names + # # => ["id", "created_at", "updated_at", "name", "age"] def attribute_names @attribute_names ||= if !abstract_class? && table_exists? column_names @@ -90,7 +118,7 @@ module ActiveRecord # If we haven't generated any methods yet, generate them, then # see if we've created the method we're looking for. - def method_missing(method, *args, &block) + def method_missing(method, *args, &block) # :nodoc: unless self.class.attribute_methods_generated? self.class.define_attribute_methods @@ -104,7 +132,7 @@ module ActiveRecord end end - def attribute_missing(match, *args, &block) + def attribute_missing(match, *args, &block) # :nodoc: if self.class.columns_hash[match.attr_name] ActiveSupport::Deprecation.warn( "The method `#{match.method_name}', matching the attribute `#{match.attr_name}' has " \ @@ -118,22 +146,60 @@ module ActiveRecord super end + # A Person object with a name attribute can ask person.respond_to?(:name), + # person.respond_to?(:name=), and person.respond_to?(:name?) + # which will all return +true+. It also define the attribute methods if they have + # not been generated. + # + # class Person < ActiveRecord::Base + # end + # + # person = Person.new + # person.respond_to(:name) # => true + # person.respond_to(:name=) # => true + # person.respond_to(:name?) # => true + # person.respond_to('age') # => true + # person.respond_to('age=') # => true + # person.respond_to('age?') # => true + # person.respond_to(:nothing) # => false def respond_to?(name, include_private = false) self.class.define_attribute_methods unless self.class.attribute_methods_generated? super end - # Returns true if the given attribute is in the attributes hash + # Returns +true+ if the given attribute is in the attributes hash, otherwise +false+. + # + # class Person < ActiveRecord::Base + # end + # + # person = Person.new + # person.has_attribute?(:name) # => true + # person.has_attribute?('age') # => true + # person.has_attribute?(:nothing) # => false def has_attribute?(attr_name) @attributes.has_key?(attr_name.to_s) end # Returns an array of names for the attributes available on this object. + # + # class Person < ActiveRecord::Base + # end + # + # person = Person.new + # person.attribute_names + # # => ["id", "created_at", "updated_at", "name", "age"] def attribute_names @attributes.keys end # Returns a hash of all the attributes with their names as keys and the values of the attributes as values. + # + # class Person < ActiveRecord::Base + # end + # + # person = Person.create(name: 'Francesco', age: 22) + # person.attributes + # # => {"id"=>3, "created_at"=>Sun, 21 Oct 2012 04:53:04, "updated_at"=>Sun, 21 Oct 2012 04:53:04, "name"=>"Francesco", "age"=>22} def attributes attribute_names.each_with_object({}) { |name, attrs| attrs[name] = read_attribute(name) @@ -146,7 +212,7 @@ module ActiveRecord # :db format. Other attributes return the value of # #inspect without modification. # - # person = Person.create!(:name => "David Heinemeier Hansson " * 3) + # person = Person.create!(name: 'David Heinemeier Hansson ' * 3) # # person.attribute_for_inspect(:name) # # => '"David Heinemeier Hansson David Heinemeier Hansson D..."' @@ -165,14 +231,34 @@ module ActiveRecord end end - # Returns true if the specified +attribute+ has been set by the user or by a database load and is neither - # nil nor empty? (the latter only applies to objects that respond to empty?, most notably Strings). + # Returns +true+ if the specified +attribute+ has been set by the user or by a + # database load and is neither +nil+ nor empty? (the latter only applies + # to objects that respond to empty?, most notably Strings). Otherwise, +false+. + # + # class Person < ActiveRecord::Base + # end + # + # person = Person.new(name: '') + # person.attribute_present?(:name) # => false + # person.name = 'Francesco' + # person.attribute_present?(:name) # => true def attribute_present?(attribute) value = read_attribute(attribute) !value.nil? && !(value.respond_to?(:empty?) && value.empty?) end - # Returns the column object for the named attribute. + # Returns the column object for the named attribute. Returns +nil+ if the + # named attribute not exists. + # + # class Person < ActiveRecord::Base + # end + # + # person = Person.new + # person.column_for_attribute(:name) # the result depends on the ConnectionAdapter + # # => # + # + # person.column_for_attribute(:nothing) + # # => nil def column_for_attribute(name) # FIXME: should this return a null object for columns that don't exist? self.class.columns_hash[name.to_s] @@ -180,42 +266,57 @@ module ActiveRecord # Returns the value of the attribute identified by attr_name after it has been typecast (for example, # "2004-12-12" in a data column is cast to a date object, like Date.new(2004, 12, 12)). - # (Alias for the protected read_attribute method). + # (Alias for the protected read_attribute method). + # + # class Person < ActiveRecord::Base + # end + # + # person = Person.new(name: 'Francesco', age: '22' + # person[:name] # => "Francesco" + # person[:age] # => 22 def [](attr_name) read_attribute(attr_name) end # Updates the attribute identified by attr_name with the specified +value+. - # (Alias for the protected write_attribute method). + # (Alias for the protected write_attribute method). + # + # class Person < ActiveRecord::Base + # end + # + # person = Person.new + # person[:age] = '22' + # person[:age] # => 22 + # person[:age] # => Fixnum def []=(attr_name, value) write_attribute(attr_name, value) end protected - def clone_attributes(reader_method = :read_attribute, attributes = {}) + def clone_attributes(reader_method = :read_attribute, attributes = {}) # :nodoc: attribute_names.each do |name| attributes[name] = clone_attribute_value(reader_method, name) end attributes end - def clone_attribute_value(reader_method, attribute_name) + def clone_attribute_value(reader_method, attribute_name) # :nodoc: value = send(reader_method, attribute_name) value.duplicable? ? value.clone : value rescue TypeError, NoMethodError value end - def arel_attributes_with_values_for_create(attribute_names) + def arel_attributes_with_values_for_create(attribute_names) # :nodoc: arel_attributes_with_values(attributes_for_create(attribute_names)) end - def arel_attributes_with_values_for_update(attribute_names) + def arel_attributes_with_values_for_update(attribute_names) # :nodoc: arel_attributes_with_values(attributes_for_update(attribute_names)) end - def attribute_method?(attr_name) + def attribute_method?(attr_name) # :nodoc: defined?(@attributes) && @attributes.include?(attr_name) end -- cgit v1.2.3