kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

Grammar and RDoc formatting

Browse source
This commit is contained in:
Sean Griffin 2015-02-06 13:39:40 -07:00
parent bde5f345de
commit d2db321360
2 changed files with 37 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
activerecord/lib/active_record/attributes.rb
View file

@ -1,7 +1,9 @@
module ActiveRecord module ActiveRecord
# See ActiveRecord::Attributes::ClassMethods for documentation
module Attributes module Attributes
extend ActiveSupport::Concern extend ActiveSupport::Concern
# :nodoc:
Type = ActiveRecord::Type Type = ActiveRecord::Type
included do included do
@ -14,7 +16,7 @@ module ActiveRecord
# type of existing attributes if needed. This allows control over how # type of existing attributes if needed. This allows control over how
# values are converted to and from SQL when assigned to a model. It also # values are converted to and from SQL when assigned to a model. It also
# changes the behavior of values passed to # changes the behavior of values passed to
# +ActiveRecord::Relation::QueryMethods#where+. This will let you use # ActiveRecord::QueryMethods#where. This will let you use
# your domain objects across much of Active Record, without having to # your domain objects across much of Active Record, without having to
# rely on implementation details or monkey patching. # rely on implementation details or monkey patching.
# #
@ -31,9 +33,9 @@ module ActiveRecord
# is not passed, the previous default value (if any) will be used. # is not passed, the previous default value (if any) will be used.
# Otherwise, the default will be +nil+. # Otherwise, the default will be +nil+.
# #
# +array+ (PG only) specifies that the type should be an array (see the examples below) # +array+ (PG only) specifies that the type should be an array (see the examples below).
# #
# +range+ (PG only) specifies that the type should be a range (see the examples below) # +range+ (PG only) specifies that the type should be a range (see the examples below).
# #
# ==== Examples # ==== Examples
# #
@ -84,19 +86,20 @@ module ActiveRecord
# ==== Creating Custom Types # ==== Creating Custom Types
# #
# Users may also define their own custom types, as long as they respond # Users may also define their own custom types, as long as they respond
# to the methods defined on the value type. The +type_cast+ method on # to the methods defined on the value type. The method
# your type object will be called with values both from the database, and # +type_cast_from_database+ or +type_cast_from_user+ will be called on
# from your controllers. See +ActiveRecord::Attributes::Type::Value+ for # your type object, with raw input from the database or from your
# the expected API. It is recommended that your type objects inherit from # controllers. See ActiveRecord::Type::Value for the expected API. It is
# an existing type, or the base value type. # recommended that your type objects inherit from an existing type, or
# from ActiveRecord::Type::Value
# #
# class MoneyType < ActiveRecord::Type::Integer # class MoneyType < ActiveRecord::Type::Integer
# def type_cast(value) # def type_cast_from_user(value)
# if value.include?('$') # if value.include?('$')
# price_in_dollars = value.gsub(/\$/, '').to_f # price_in_dollars = value.gsub(/\$/, '').to_f
# price_in_dollars * 100 # super(price_in_dollars * 100)
# else # else
# value.to_i # super
# end # end
# end # end
# end # end
@ -109,11 +112,11 @@ module ActiveRecord
# store_listing.price_in_cents # => 1000 # store_listing.price_in_cents # => 1000
# #
# For more details on creating custom types, see the documentation for # For more details on creating custom types, see the documentation for
# +ActiveRecord::Type::Value+ # ActiveRecord::Type::Value
# #
# ==== Querying # ==== Querying
# #
# When +ActiveRecord::Relation::QueryMethods#where+ is called, it will # When ActiveRecord::QueryMethods#where is called, it will
# use the type defined by the model class to convert the value to SQL, # use the type defined by the model class to convert the value to SQL,
# calling +type_cast_for_database+ on your type object. For example: # calling +type_cast_for_database+ on your type object. For example:
# #
@ -149,9 +152,8 @@ module ActiveRecord
# #
# The type of an attribute is given the opportunity to change how dirty # The type of an attribute is given the opportunity to change how dirty
# tracking is performed. The methods +changed?+ and +changed_in_place?+ # tracking is performed. The methods +changed?+ and +changed_in_place?+
# will be called from +ActiveRecord::AttributeMethods::Dirty+. See the # will be called from ActiveModel::Dirty. See the documentation for those
# documentation for those methods in +ActiveRecord::Type::Value+ for more # methods in ActiveRecord::Type::Value for more details.
# details.
def attribute(name, cast_type, **options) def attribute(name, cast_type, **options)
name = name.to_s name = name.to_s
reload_schema_from_cache reload_schema_from_cache
@ -165,20 +167,20 @@ module ActiveRecord
# This is the low level API which sits beneath +attribute+. It only # This is the low level API which sits beneath +attribute+. It only
# accepts type objects, and will do its work immediately instead of # accepts type objects, and will do its work immediately instead of
# waiting for the schema to load. Automatic schema detection and # waiting for the schema to load. Automatic schema detection and
# +attribute+ both call this under the hood. While this method is # ClassMethods#attribute both call this under the hood. While this method
# provided so it can be used by plugin authors, application code should # is provided so it can be used by plugin authors, application code
# probably use +attribute+. # should probably use ClassMethods#attribute.
# #
# +name+ The name of the attribute being defined. Expected to be a +String+. # +name+ The name of the attribute being defined. Expected to be a +String+.
# #
# +cast_type+ The type object to use for this attribute # +cast_type+ The type object to use for this attribute.
# #
# +default+ The default value to use when no value is provided. If this option # +default+ The default value to use when no value is provided. If this option
# is not passed, the previous default value (if any) will be used. # is not passed, the previous default value (if any) will be used.
# Otherwise, the default will be +nil+. # Otherwise, the default will be +nil+.
# #
# +user_provided_default+ Whether the default value should be cast using # +user_provided_default+ Whether the default value should be cast using
# +type_cast_from_user+ or +type_cast_from_database+ # +type_cast_from_user+ or +type_cast_from_database+.
def define_attribute( def define_attribute(
name, name,
cast_type, cast_type,

28
activerecord/lib/active_record/type/value.rb
View file

@ -9,14 +9,15 @@ module ActiveRecord
@limit = limit @limit = limit
end end
def type; end # :nodoc: def type # :nodoc:
end
# Convert a value from database input to the appropriate ruby type. The # Convert a value from database input to the appropriate ruby type. The
# return value of this method will be returned from # return value of this method will be returned from
# +ActiveRecord::AttributeMethods::Read#read_attribute+. See also # ActiveRecord::AttributeMethods::Read#read_attribute. See also
# +type_cast+ and +cast_value+ # Value#type_cast and Value#cast_value.
# #
# +value+ The raw input, as provided from the database # +value+ The raw input, as provided from the database.
def type_cast_from_database(value) def type_cast_from_database(value)
type_cast(value) type_cast(value)
end end
@ -27,8 +28,8 @@ module ActiveRecord
# from. # from.
# #
# The return value of this method will be returned from # The return value of this method will be returned from
# +ActiveRecord::AttributeMethods::Read#read_attribute+. See also: # ActiveRecord::AttributeMethods::Read#read_attribute. See also:
# +type_cast+ and +cast_value+ # Value#type_cast and Value#cast_value.
# #
# +value+ The raw input, as provided to the attribute setter. # +value+ The raw input, as provided to the attribute setter.
def type_cast_from_user(value) def type_cast_from_user(value)
@ -38,7 +39,7 @@ module ActiveRecord
# Cast a value from the ruby type to a type that the database knows how # Cast a value from the ruby type to a type that the database knows how
# to understand. The returned value from this method should be a # to understand. The returned value from this method should be a
# +String+, +Numeric+, +Date+, +Time+, +Symbol+, +true+, +false+, or # +String+, +Numeric+, +Date+, +Time+, +Symbol+, +true+, +false+, or
# +nil+ # +nil+.
def type_cast_for_database(value) def type_cast_for_database(value)
value value
end end
@ -78,12 +79,12 @@ module ActiveRecord
# which could be mutated, you should override this method. You will need # which could be mutated, you should override this method. You will need
# to either: # to either:
# #
# - pass +new_value+ to +type_cast_for_database+ and compare it to # - pass +new_value+ to Value#type_cast_for_database and compare it to
# +raw_old_value+ # +raw_old_value+
# #
# or # or
# #
# - pass +raw_old_value+ to +type_cast_from_database+ and compare it to # - pass +raw_old_value+ to Value#type_cast_from_database and compare it to
# +new_value+ # +new_value+
# #
# +raw_old_value+ The original value, before being passed to # +raw_old_value+ The original value, before being passed to
@ -104,17 +105,16 @@ module ActiveRecord
private private
# Convenience method. If you don't need separate behavior for # Convenience method. If you don't need separate behavior for
# +type_cast_from_database+ and +type_cast_from_user+, you can override # Value#type_cast_from_database and Value#type_cast_from_user, you can override
# this method instead. The default behavior of both methods is to call # this method instead. The default behavior of both methods is to call
# this one. See also +cast_value+ # this one. See also Value#cast_value.
def type_cast(value) # :doc: def type_cast(value) # :doc:
cast_value(value) unless value.nil? cast_value(value) unless value.nil?
end end
# Convenience method for types which do not need separate type casting # Convenience method for types which do not need separate type casting
# behavior for user and database inputs. Called by # behavior for user and database inputs. Called by Value#type_cast for
# +type_cast_from_database+ and +type_cast_from_user+ for all values # values except +nil+.
# except +nil+.
def cast_value(value) # :doc: def cast_value(value) # :doc:
value value
end end