TEST_CODEOWNERS/rails
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki 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
# See ActiveRecord::Attributes::ClassMethods for documentation
module Attributes
extend ActiveSupport::Concern
# :nodoc:
Type = ActiveRecord::Type
included do
@ -14,7 +16,7 @@ module ClassMethods
# 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
# 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
# rely on implementation details or monkey patching.
#
@ -31,9 +33,9 @@ module ClassMethods
# is not passed, the previous default value (if any) will be used.
# 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
#
@ -84,19 +86,20 @@ module ClassMethods
# ==== Creating Custom Types
#
# 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
# your type object will be called with values both from the database, and
# from your controllers. See +ActiveRecord::Attributes::Type::Value+ for
# the expected API. It is recommended that your type objects inherit from
# an existing type, or the base value type.
# to the methods defined on the value type. The method
# +type_cast_from_database+ or +type_cast_from_user+ will be called on
# your type object, with raw input from the database or from your
# controllers. See ActiveRecord::Type::Value for the expected API. It is
# recommended that your type objects inherit from an existing type, or
# from ActiveRecord::Type::Value
#
# class MoneyType < ActiveRecord::Type::Integer
# def type_cast(value)
# def type_cast_from_user(value)
# if value.include?('$')
# price_in_dollars = value.gsub(/\$/, '').to_f
# price_in_dollars * 100
# super(price_in_dollars * 100)
# else
# value.to_i
# super
# end
# end
# end
@ -109,11 +112,11 @@ module ClassMethods
# store_listing.price_in_cents # => 1000
#
# For more details on creating custom types, see the documentation for
# +ActiveRecord::Type::Value+
# ActiveRecord::Type::Value
#
# ==== 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,
# calling +type_cast_for_database+ on your type object. For example:
#
@ -149,9 +152,8 @@ module ClassMethods
#
# The type of an attribute is given the opportunity to change how dirty
# tracking is performed. The methods +changed?+ and +changed_in_place?+
# will be called from +ActiveRecord::AttributeMethods::Dirty+. See the
# documentation for those methods in +ActiveRecord::Type::Value+ for more
# details.
# will be called from ActiveModel::Dirty. See the documentation for those
# methods in ActiveRecord::Type::Value for more details.
def attribute(name, cast_type, **options)
name = name.to_s
reload_schema_from_cache
@ -165,20 +167,20 @@ def attribute(name, cast_type, **options)
# This is the low level API which sits beneath +attribute+. It only
# accepts type objects, and will do its work immediately instead of
# waiting for the schema to load. Automatic schema detection and
# +attribute+ both call this under the hood. While this method is
# provided so it can be used by plugin authors, application code should
# probably use +attribute+.
# ClassMethods#attribute both call this under the hood. While this method
# is provided so it can be used by plugin authors, application code
# should probably use ClassMethods#attribute.
#
# +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
# is not passed, the previous default value (if any) will be used.
# Otherwise, the default will be +nil+.
#
# +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(
name,
cast_type,

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

@ -9,14 +9,15 @@ def initialize(precision: nil, limit: nil, scale: nil)
@limit = limit
end
def type; end # :nodoc:
def type # :nodoc:
end
# Convert a value from database input to the appropriate ruby type. The
# return value of this method will be returned from
# +ActiveRecord::AttributeMethods::Read#read_attribute+. See also
# +type_cast+ and +cast_value+
# ActiveRecord::AttributeMethods::Read#read_attribute. See also
# 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)
type_cast(value)
end
@ -27,8 +28,8 @@ def type_cast_from_database(value)
# from.
#
# The return value of this method will be returned from
# +ActiveRecord::AttributeMethods::Read#read_attribute+. See also:
# +type_cast+ and +cast_value+
# ActiveRecord::AttributeMethods::Read#read_attribute. See also:
# Value#type_cast and Value#cast_value.
#
# +value+ The raw input, as provided to the attribute setter.
def type_cast_from_user(value)
@ -38,7 +39,7 @@ def type_cast_from_user(value)
# 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
# +String+, +Numeric+, +Date+, +Time+, +Symbol+, +true+, +false+, or
# +nil+
# +nil+.
def type_cast_for_database(value)
value
end
@ -78,12 +79,12 @@ def changed?(old_value, new_value, _new_value_before_type_cast)
# which could be mutated, you should override this method. You will need
# 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+
#
# 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+
#
# +raw_old_value+ The original value, before being passed to
@ -104,17 +105,16 @@ def ==(other)
private
# 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 one. See also +cast_value+
# this one. See also Value#cast_value.
def type_cast(value) # :doc:
cast_value(value) unless value.nil?
end
# Convenience method for types which do not need separate type casting
# behavior for user and database inputs. Called by
# +type_cast_from_database+ and +type_cast_from_user+ for all values
# except +nil+.
# behavior for user and database inputs. Called by Value#type_cast for
# values except +nil+.
def cast_value(value) # :doc:
value
end