mirrors
/
rails
mirror of https://github.com/rails/rails
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Smattering of grammatical fixes to documentation. Closes #10083 [BobSilva] 

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8113 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
This commit is contained in:
Marcel Molina 2007-11-08 03:37:16 +00:00
parent 709dc33c92
commit 7143d80147
18 changed files with 109 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
activerecord/CHANGELOG
View File

@ -1,5 +1,7 @@
*SVN*
* Smattering of grammatical fixes to documentation. Closes #10083 [BobSilva]
* Enhance explanation with more examples for attr_accessible macro. Closes #8095 [fearoffish, Marcel Molina]
* Update association/method mapping table to refected latest collection methods for has_many :through. Closes #8772 [lifofifo]

29
activerecord/lib/active_record/associations.rb
View File

@ -243,7 +243,7 @@ module ActiveRecord
#
# == Unsaved objects and associations
#
# You can manipulate objects and associations before they are saved to the database, but there is some special behaviour you should be
# You can manipulate objects and associations before they are saved to the database, but there is some special behavior you should be
# aware of, mostly involving the saving of associated objects.
#
# === One-to-one associations
@ -267,7 +267,7 @@ module ActiveRecord
# === Association callbacks
#
# Similiar to the normal callbacks that hook into the lifecycle of an Active Record object, you can also define callbacks that get
# trigged when you add an object to or remove an object from an association collection. Example:
# triggered when you add an object to or remove an object from an association collection. Example:
#
# class Project
# has_and_belongs_to_many :developers, :after_add => :evaluate_velocity
@ -584,10 +584,10 @@ module ActiveRecord
# This will also destroy the objects if they're declared as +belongs_to+ and dependent on this model.
# * <tt>collection=objects</tt> - replaces the collections content by deleting and adding objects as appropriate.
# * <tt>collection_singular_ids</tt> - returns an array of the associated objects' ids
# * <tt>collection_singular_ids=ids</tt> - replace the collection by the objects identified by the primary keys in +ids+
# * <tt>collection_singular_ids=ids</tt> - replace the collection with the objects identified by the primary keys in +ids+
# * <tt>collection.clear</tt> - removes every object from the collection. This destroys the associated objects if they
# are associated with <tt>:dependent => :destroy</tt>, deletes them directly from the database if <tt>:dependent => :delete_all</tt>,
# or otherwise sets their foreign keys to NULL.
# otherwise sets their foreign keys to NULL.
# * <tt>collection.empty?</tt> - returns +true+ if there are no associated objects.
# * <tt>collection.size</tt> - returns the number of associated objects.
# * <tt>collection.find</tt> - finds an associated object according to the same rules as Base.find.
@ -621,8 +621,6 @@ module ActiveRecord
# SQL fragment, such as <tt>price > 5 AND name LIKE 'B%'</tt>.
# * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
# such as <tt>last_name, first_name DESC</tt>
# * <tt>:group</tt> - specify the attribute by which the associated objects are returned as a <tt>GROUP BY</tt> SQL fragment,
# such as +category+
# * <tt>:foreign_key</tt> - specify the foreign key used for the association. By default this is guessed to be the name
# of this class in lower-case and +_id+ suffixed. So a +Person+ class that makes a +has_many+ association will use +person_id+
# as the default +foreign_key+.
@ -633,13 +631,13 @@ module ActiveRecord
# * <tt>:finder_sql</tt> - specify a complete SQL statement to fetch the association. This is a good way to go for complex
# associations that depend on multiple tables. Note: When this option is used, +find_in_collection+ is _not_ added.
# * <tt>:counter_sql</tt> - specify a complete SQL statement to fetch the size of the association. If <tt>:finder_sql</tt> is
# specified but <tt>:counter_sql</tt>, <tt>:counter_sql</tt> will be generated by replacing <tt>SELECT ... FROM</tt> with <tt>SELECT COUNT(*) FROM</tt>.
# specified but not <tt>:counter_sql</tt>, <tt>:counter_sql</tt> will be generated by replacing <tt>SELECT ... FROM</tt> with <tt>SELECT COUNT(*) FROM</tt>.
# * <tt>:extend</tt> - specify a named module for extending the proxy. See "Association extensions".
# * <tt>:include</tt> - specify second-order associations that should be eager loaded when the collection is loaded.
# * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the <tt>GROUP BY</tt> SQL-clause.
# * <tt>:limit</tt>: An integer determining the limit on the number of rows that should be returned.
# * <tt>:offset</tt>: An integer determining the offset from where the rows should be fetched. So at 5, it would skip the first 4 rows.
# * <tt>:select</tt>: By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if you for example want to do a join,
# * <tt>:select</tt>: By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if you, for example, want to do a join
# but not include the joined columns.
# * <tt>:as</tt>: Specifies a polymorphic interface (See <tt>#belongs_to</tt>).
# * <tt>:through</tt>: Specifies a Join Model through which to perform the query. Options for <tt>:class_name</tt> and <tt>:foreign_key</tt>
@ -708,8 +706,8 @@ module ActiveRecord
# if the real class name is +Person+, you'll have to specify it with this option.
# * <tt>:conditions</tt> - specify the conditions that the associated object must meet in order to be included as a +WHERE+
# SQL fragment, such as <tt>rank = 5</tt>.
# * <tt>:order</tt> - specify the order from which the associated object will be picked at the top. Specified as
# an <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
# * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
# such as <tt>last_name, first_name DESC</tt>
# * <tt>:dependent</tt> - if set to <tt>:destroy</tt>, the associated object is destroyed when this object is. If set to
# <tt>:delete</tt>, the associated object is deleted *without* calling its destroy method. If set to <tt>:nullify</tt>, the associated
# object's foreign key is set to +NULL+. Also, association is assigned.
@ -721,7 +719,7 @@ module ActiveRecord
#
# Option examples:
# has_one :credit_card, :dependent => :destroy # destroys the associated credit card
# has_one :credit_card, :dependent => :nullify # updates the associated records foreign key value to null rather than destroying it
# has_one :credit_card, :dependent => :nullify # updates the associated records foreign key value to NULL rather than destroying it
# has_one :last_comment, :class_name => "Comment", :order => "posted_on"
# has_one :project_manager, :class_name => "Person", :conditions => "role = 'project_manager'"
# has_one :attachment, :as => :attachable
@ -771,12 +769,12 @@ module ActiveRecord
# if the real class name is +Person+, you'll have to specify it with this option.
# * <tt>:conditions</tt> - specify the conditions that the associated object must meet in order to be included as a +WHERE+
# SQL fragment, such as <tt>authorized = 1</tt>.
# * <tt>:order</tt> - specify the order from which the associated object will be picked at the top. Specified as
# an <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
# * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
# such as <tt>last_name, first_name DESC</tt>
# * <tt>:foreign_key</tt> - specify the foreign key used for the association. By default this is guessed to be the name
# of the associated class in lower-case and +_id+ suffixed. So a +Person+ class that makes a +belongs_to+ association to a
# +Boss+ class will use +boss_id+ as the default +foreign_key+.
# * <tt>:counter_cache</tt> - caches the number of belonging objects on the associate class through use of +increment_counter+
# * <tt>:counter_cache</tt> - caches the number of belonging objects on the associate class through the use of +increment_counter+
# and +decrement_counter+. The counter cache is incremented when an object of this class is created and decremented when it's
# destroyed. This requires that a column named <tt>#{table_name}_count</tt> (such as +comments_count+ for a belonging +Comment+ class)
# is used on the associate class (such as a +Post+ class). You can also specify a custom counter cache column by providing
@ -924,7 +922,8 @@ module ActiveRecord
# the +has_and_belongs_to_many+ association will use +project_id+ as the default association +foreign_key+.
# * <tt>:conditions</tt> - specify the conditions that the associated object must meet in order to be included as a +WHERE+
# SQL fragment, such as <tt>authorized = 1</tt>.
# * <tt>:order</tt> - specify the order in which the associated objects are returned as a <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
# * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
# such as <tt>last_name, first_name DESC</tt>
# * <tt>:uniq</tt> - if set to +true+, duplicate associated objects will be ignored by accessors and query methods
# * <tt>:finder_sql</tt> - overwrite the default generated SQL statement used to fetch the association with a manual statement
# * <tt>:delete_sql</tt> - overwrite the default generated SQL statement used to remove links between the associated

62
activerecord/lib/active_record/base.rb
View File

@ -40,7 +40,7 @@ module ActiveRecord #:nodoc:
class DangerousAttributeError < ActiveRecordError #:nodoc:
end
# Raised when you've tried to access a column, which wasn't
# Raised when you've tried to access a column which wasn't
# loaded by your finder. Typically this is because :select
# has been specified
class MissingAttributeError < NoMethodError
@ -72,7 +72,7 @@ module ActiveRecord #:nodoc:
# == Creation
#
# Active Records accept constructor parameters either in a hash or as a block. The hash method is especially useful when
# you're receiving the data from somewhere else, like a HTTP request. It works like this:
# you're receiving the data from somewhere else, like an HTTP request. It works like this:
#
# user = User.new(:name => "David", :occupation => "Code Artist")
# user.name # => "David"
@ -112,7 +112,7 @@ module ActiveRecord #:nodoc:
# end
#
# The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query and is thus susceptible to SQL-injection
# attacks if the <tt>user_name</tt> and +password+ parameters come directly from a HTTP request. The <tt>authenticate_safely</tt> and
# attacks if the <tt>user_name</tt> and +password+ parameters come directly from an HTTP request. The <tt>authenticate_safely</tt> and
# <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+ before inserting them in the query,
# which will ensure that an attacker can't escape the query and fake the login (or worse).
#
@ -137,9 +137,9 @@ module ActiveRecord #:nodoc:
#
# == Overwriting default accessors
#
# All column values are automatically available through basic accessors on the Active Record object, but some times you
# want to specialize this behavior. This can be done by either by overwriting the default accessors (using the same
# name as the attribute) calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things.
# All column values are automatically available through basic accessors on the Active Record object, but sometimes you
# want to specialize this behavior. This can be done by overwriting the default accessors (using the same
# name as the attribute) and calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things.
# Example:
#
# class Song < ActiveRecord::Base
@ -230,7 +230,7 @@ module ActiveRecord #:nodoc:
#
# == Single table inheritance
#
# Active Record allows inheritance by storing the name of the class in a column that by default is called "type" (can be changed
# Active Record allows inheritance by storing the name of the class in a column that by default is named "type" (can be changed
# by overwriting <tt>Base.inheritance_column</tt>). This means that an inheritance looking like this:
#
# class Company < ActiveRecord::Base; end
@ -251,7 +251,7 @@ module ActiveRecord #:nodoc:
#
# Connections are usually created through ActiveRecord::Base.establish_connection and retrieved by ActiveRecord::Base.connection.
# All classes inheriting from ActiveRecord::Base will use this connection. But you can also set a class-specific connection.
# For example, if Course is a ActiveRecord::Base, but resides in a different database you can just say Course.establish_connection
# For example, if Course is an ActiveRecord::Base, but resides in a different database, you can just say Course.establish_connection
# and Course *and all its subclasses* will use this connection instead.
#
# This feature is implemented by keeping a connection pool in ActiveRecord::Base that is a Hash indexed by the class. If a connection is
@ -260,12 +260,12 @@ module ActiveRecord #:nodoc:
# == Exceptions
#
# * +ActiveRecordError+ -- generic error class and superclass of all other errors raised by Active Record
# * +AdapterNotSpecified+ -- the configuration hash used in <tt>establish_connection</tt> didn't include a
# * +AdapterNotSpecified+ -- the configuration hash used in <tt>establish_connection</tt> didn't include an
# <tt>:adapter</tt> key.
# * +AdapterNotFound+ -- the <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified an non-existent adapter
# * +AdapterNotFound+ -- the <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified a non-existent adapter
# (or a bad spelling of an existing one).
# * +AssociationTypeMismatch+ -- the object assigned to the association wasn't of the type specified in the association definition.
# * +SerializationTypeMismatch+ -- the object serialized wasn't of the class specified as the second parameter.
# * +SerializationTypeMismatch+ -- the serialized object wasn't of the class specified as the second parameter.
# * +ConnectionNotEstablished+ -- no connection has been established. Use <tt>establish_connection</tt> before querying.
# * +RecordNotFound+ -- no record responded to the find* method.
# Either the row with the given ID doesn't exist or the row didn't meet the additional restrictions.
@ -360,7 +360,7 @@ module ActiveRecord #:nodoc:
@@schema_format = :ruby
# Determines whether to raise an exception on mass-assignment to protected
# attribute. Defaults to true.
# attributes. Defaults to true.
cattr_accessor :whiny_protected_attributes, :instance_writer => false
@@whiny_protected_attributes = true
@ -370,10 +370,10 @@ module ActiveRecord #:nodoc:
# * Find by id: This can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]).
# If no record can be found for all of the listed ids, then RecordNotFound will be raised.
# * Find first: This will return the first record matched by the options used. These options can either be specific
# conditions or merely an order. If no record can matched, nil is returned.
# conditions or merely an order. If no record can be matched, nil is returned.
# * Find all: This will return all the records matched by the options used. If no records are found, an empty array is returned.
#
# All approaches accept an option hash as their last parameter. The options are:
# All approaches accept an options hash as their last parameter. The options are:
#
# * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro.
# * <tt>:order</tt>: An SQL fragment like "created_at DESC, name".
@ -384,9 +384,10 @@ module ActiveRecord #:nodoc:
# Accepts named associations in the form of :include, which will perform an INNER JOIN on the associated table(s).
# The records will be returned read-only since they will have attributes that do not correspond to the table's columns.
# Pass :readonly => false to override.
# See adding joins for associations under Associations.
# * <tt>:include</tt>: Names associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer
# to already defined associations. See eager loading under Associations.
# * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not
# * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you, for example, want to do a join but not
# include the joined columns.
# * <tt>:from</tt>: By default, this is the table name of the class, but can be changed to an alternate table name (or even the name
# of a database view).
@ -398,7 +399,7 @@ module ActiveRecord #:nodoc:
# Person.find(1) # returns the object for ID = 1
# Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6)
# Person.find([7, 17]) # returns an array for objects with IDs in (7, 17)
# Person.find([1]) # returns an array for objects the object with ID = 1
# Person.find([1]) # returns an array for the object with ID = 1
# Person.find(1, :conditions => "administrator = 1", :order => "created_on DESC")
#
# Note that returned records may not be in the same order as the ids you
@ -429,6 +430,13 @@ module ActiveRecord #:nodoc:
# end
def find(*args)
options = args.extract_options!
# Note: we extract any :joins option with a non-string value from the options, and turn it into
# an internal option :ar_joins. This allows code called from here to find the ar_joins, and
# it bypasses marking the result as read_only.
# A normal string join marks the result as read-only because it contains attributes from joined tables
# which are not in the base table and therefore prevent the result from being saved.
# In the case of an ar_join, the JoinDependency created to instantiate the results eliminates these
# bogus attributes. See JoinDependency#instantiate, and JoinBase#instantiate in associations.rb.
validate_find_options(options)
set_readonly_option!(options)
@ -521,14 +529,14 @@ module ActiveRecord #:nodoc:
connection.update(sql, "#{name} Update")
end
# Destroys the objects for all the records that match the +condition+ by instantiating each object and calling
# Destroys the objects for all the records that match the +conditions+ by instantiating each object and calling
# the destroy method. Example:
# Person.destroy_all "last_login < '2004-04-04'"
def destroy_all(conditions = nil)
find(:all, :conditions => conditions).each { |object| object.destroy }
end
# Deletes all the records that match the +condition+ without instantiating the objects first (and hence not
# Deletes all the records that match the +conditions+ without instantiating the objects first (and hence not
# calling the destroy method). Example:
# Post.delete_all "person_id = 5 AND (category = 'Something' OR category = 'Else')"
def delete_all(conditions = nil)
@ -576,7 +584,7 @@ module ActiveRecord #:nodoc:
#
# This is used for caching aggregate values, so that they don't need to be computed every time.
# For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is
# shown it would have to run a SQL query to find how many posts and comments there are.
# shown it would have to run an SQL query to find how many posts and comments there are.
#
# ==== Options
#
@ -687,7 +695,7 @@ module ActiveRecord #:nodoc:
# ==== Options
#
# +attr_name+ The field name that should be serialized
# +class_name+ Optional, class name that the object should be equal to
# +class_name+ Optional, class name that the object type should be equal to
#
# ==== Example
# # Serialize a preferences attribute
@ -707,7 +715,7 @@ module ActiveRecord #:nodoc:
# Guesses the table name (in forced lower-case) based on the name of the class in the inheritance hierarchy descending
# directly from ActiveRecord. So if the hierarchy looks like: Reply < Message < ActiveRecord, then Message is used
# to guess the table name from even when called on Reply. The rules used to do the guess are handled by the Inflector class
# in Active Support, which knows almost all common English inflections (report a bug if your inflection isn't covered).
# in Active Support, which knows almost all common English inflections. You can add new inflections in config/initializers/inflections.rb.
#
# Nested classes are given table names prefixed by the singular form of
# the parent's table name. Example:
@ -964,7 +972,7 @@ module ActiveRecord #:nodoc:
connection.quote(value,column)
end
# Used to sanitize objects before they're used in an SELECT SQL-statement. Delegates to <tt>connection.quote</tt>.
# Used to sanitize objects before they're used in an SQL SELECT statement. Delegates to <tt>connection.quote</tt>.
def sanitize(object) #:nodoc:
connection.quote(object)
end
@ -1266,7 +1274,7 @@ module ActiveRecord #:nodoc:
# Enables dynamic finders like find_by_user_name(user_name) and find_by_user_name_and_password(user_name, password) that are turned into
# find(:first, :conditions => ["user_name = ?", user_name]) and find(:first, :conditions => ["user_name = ? AND password = ?", user_name, password])
# respectively. Also works for find(:all), but using find_all_by_amount(50) that are turned into find(:all, :conditions => ["amount = ?", 50]).
# respectively. Also works for find(:all) by using find_all_by_amount(50) that is turned into find(:all, :conditions => ["amount = ?", 50]).
#
# It's even possible to use all the additional parameters to find. For example, the full interface for find_all_by_amount
# is actually find_all_by_amount(amount, options).
@ -1435,7 +1443,7 @@ module ActiveRecord #:nodoc:
# end
# end
#
# You can ignore any previous scopings by using <tt>with_exclusive_scope</tt> method.
# You can ignore any previous scopings by using the <tt>with_exclusive_scope</tt> method.
#
# class Article < ActiveRecord::Base
# def self.find_with_exclusive_scope
@ -1889,7 +1897,7 @@ module ActiveRecord #:nodoc:
# Allows you to set all the attributes at once by passing in a hash with keys
# matching the attribute names (which again matches the column names). Sensitive attributes can be protected
# from this form of mass-assignment by using the +attr_protected+ macro. Or you can alternatively
# specify which attributes *can* be accessed in with the +attr_accessible+ macro. Then all the
# specify which attributes *can* be accessed with the +attr_accessible+ macro. Then all the
# attributes not included in that won't be allowed to be mass-assigned.
def attributes=(new_attributes, guard_protected_attributes = true)
return if new_attributes.nil?
@ -2120,7 +2128,7 @@ module ActiveRecord #:nodoc:
default
end
# Returns copy of the attributes hash where all the values have been safely quoted for use in
# Returns a copy of the attributes hash where all the values have been safely quoted for use in
# an SQL statement.
def attributes_with_quotes(include_primary_key = true, include_readonly_attributes = true)
quoted = attributes.inject({}) do |quoted, (name, value)|
@ -2159,7 +2167,7 @@ module ActiveRecord #:nodoc:
# So having the pairs written_on(1) = "2004", written_on(2) = "6", written_on(3) = "24", will instantiate
# written_on (a date type) with Date.new("2004", "6", "24"). You can also specify a typecast character in the
# parentheses to have the parameters typecasted before they're used in the constructor. Use i for Fixnum, f for Float,
# s for String, and a for Array. If all the values for a given attribute is empty, the attribute will be set to nil.
# s for String, and a for Array. If all the values for a given attribute are empty, the attribute will be set to nil.
def assign_multiparameter_attributes(pairs)
execute_callstack_for_multiparameter_attributes(
extract_callstack_for_multiparameter_attributes(pairs)

23
activerecord/lib/active_record/calculations.rb
View File

@ -15,14 +15,17 @@ module ActiveRecord
# The third approach, count using options, accepts an option hash as the only parameter. The options are:
#
# * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro.
# * <tt>:joins</tt>: An SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id". (Rarely needed).
# The records will be returned read-only since they will have attributes that do not correspond to the table's columns.
# * <tt>:joins</tt>: Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id". (Rarely needed).
# or names associations in the same form used for the :include option.
# If the value is a string, then the records will be returned read-only since they will have attributes that do not correspond to the table's columns.
# Pass :readonly => false to override.
# See adding joins for associations under Associations.
# * <tt>:include</tt>: Named associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer
# to already defined associations. When using named associations count returns the number DISTINCT items for the model you're counting.
# to already defined associations. When using named associations, count returns the number of DISTINCT items for the model you're counting.
# See eager loading under Associations.
# * <tt>:order</tt>: An SQL fragment like "created_at DESC, name" (really only used with GROUP BY calculations).
# * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause.
# * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not
# * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you, for example, want to do a join but not
# include the joined columns.
# * <tt>:distinct</tt>: Set this to true to make this a distinct calculation, such as SELECT COUNT(DISTINCT posts.id) ...
#
@ -44,35 +47,35 @@ module ActiveRecord
calculate(:count, *construct_count_options_from_args(*args))
end
# Calculates average value on a given column. The value is returned as a float. See #calculate for examples with options.
# Calculates the average value on a given column. The value is returned as a float. See #calculate for examples with options.
#
# Person.average('age')
def average(column_name, options = {})
calculate(:avg, column_name, options)
end
# Calculates the minimum value on a given column. The value is returned with the same data type of the column.. See #calculate for examples with options.
# Calculates the minimum value on a given column. The value is returned with the same data type of the column. See #calculate for examples with options.
#
# Person.minimum('age')
def minimum(column_name, options = {})
calculate(:min, column_name, options)
end
# Calculates the maximum value on a given column. The value is returned with the same data type of the column.. See #calculate for examples with options.
# Calculates the maximum value on a given column. The value is returned with the same data type of the column. See #calculate for examples with options.
#
# Person.maximum('age')
def maximum(column_name, options = {})
calculate(:max, column_name, options)
end
# Calculates the sum value on a given column. The value is returned with the same data type of the column.. See #calculate for examples with options.
# Calculates the sum of values on a given column. The value is returned with the same data type of the column. See #calculate for examples with options.
#
# Person.sum('age')
def sum(column_name, options = {})
calculate(:sum, column_name, options)
end
# This calculates aggregate values in the given column: Methods for count, sum, average, minimum, and maximum have been added as shortcuts.
# This calculates aggregate values in the given column. Methods for count, sum, average, minimum, and maximum have been added as shortcuts.
# Options such as :conditions, :order, :group, :having, and :joins can be passed to customize the query.
#
# There are two basic forms of output:
@ -237,7 +240,7 @@ module ActiveRecord
end
# Converts a given key to the value that the database adapter returns as
# as a usable column name.
# a usable column name.
# users.id #=> users_id
# sum(id) #=> sum_id
# count(distinct users.id) #=> count_distinct_users_id

2
activerecord/lib/active_record/callbacks.rb
View File

@ -161,7 +161,7 @@ module ActiveRecord
# == <tt>before_validation*</tt> returning statements
#
# If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be aborted and <tt>Base#save</tt> will return +false+.
# If <tt>Base#save!</tt> is called it will raise a +RecordNotSave+ exception.
# If <tt>Base#save!</tt> is called it will raise a +RecordNotSaved+ exception.
# Nothing will be appended to the errors object.
#
# == Cancelling callbacks

8
activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
View File

@ -243,7 +243,7 @@ module ActiveRecord
end
# Locate the connection of the nearest super class. This can be an
# active or defined connections: if it is the latter, it will be
# active or defined connection: if it is the latter, it will be
# opened and set as the active connection for the class it was defined
# for (not necessarily the current class).
def self.retrieve_connection #:nodoc:
@ -264,15 +264,15 @@ module ActiveRecord
conn or raise ConnectionNotEstablished
end
# Returns true if a connection that's accessible to this class have already been opened.
# Returns true if a connection that's accessible to this class has already been opened.
def self.connected?
active_connections[active_connection_name] ? true : false
end
# Remove the connection for this class. This will close the active
# connection and the defined connection (if they exist). The result
# can be used as argument for establish_connection, for easy
# re-establishing of the connection.
# can be used as an argument for establish_connection, for easily
# re-establishing the connection.
def self.remove_connection(klass=self)
spec = @@defined_connections[klass.name]
konn = active_connections[klass.name]

5
activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
View File

@ -98,7 +98,7 @@ module ActiveRecord
add_limit_offset!(sql, options) if options
end
# Appends +LIMIT+ and +OFFSET+ options to a SQL statement.
# Appends +LIMIT+ and +OFFSET+ options to an SQL statement.
# This method *modifies* the +sql+ parameter.
# ===== Examples
# add_limit_offset!('SELECT * FROM suppliers', {:limit => 10, :offset => 50})
@ -113,7 +113,8 @@ module ActiveRecord
end
end
# Appends a locking clause to a SQL statement. *Modifies the +sql+ parameter*.
# Appends a locking clause to an SQL statement.
# This method *modifies* the +sql+ parameter.
# # SELECT * FROM suppliers FOR UPDATE
# add_lock! 'SELECT * FROM suppliers', :lock => true
# add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'

4
activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
View File

@ -272,7 +272,7 @@ module ActiveRecord
end
# Represents a SQL table in an abstract way.
# Columns are stored as ColumnDefinition in the #columns attribute.
# Columns are stored as a ColumnDefinition in the #columns attribute.
class TableDefinition
attr_accessor :columns
@ -451,7 +451,7 @@ module ActiveRecord
alias :belongs_to :references
# Returns a String whose contents are the column definitions
# concatenated together. This string can then be pre and appended to
# concatenated together. This string can then be prepended and appended to
# to generate the final SQL to create the table.
def to_sql
@columns * ', '

6
activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
View File

@ -54,7 +54,7 @@ module ActiveRecord
# [<tt>:temporary</tt>]
# Make a temporary table.
# [<tt>:force</tt>]
# Set to true or false to drop the table before creating it.
# Set to true to drop the table before creating it.
# Defaults to false.
#
# ===== Examples
@ -160,13 +160,13 @@ module ActiveRecord
# Adds a new index to the table. +column_name+ can be a single Symbol, or
# an Array of Symbols.
#
# The index will be named after the table and the first column names,
# The index will be named after the table and the first column name,
# unless you pass +:name+ as an option.
#
# When creating an index on multiple columns, the first column is used as a name
# for the index. For example, when you specify an index on two columns
# [+:first+, +:last+], the DBMS creates an index for both columns as well as an
# index for the first colum +:first+. Using just the first name for this index
# index for the first column +:first+. Using just the first name for this index
# makes sense, because you will never have to create a singular index with this
# name.
#

16
activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
View File

@ -18,7 +18,7 @@ module ActiveRecord
raise ArgumentError, "No database specified. Missing argument: database."
end
# The postgres drivers don't allow to create an unconnected PGconn object,
# The postgres drivers don't allow the creation of an unconnected PGconn object,
# so just pass a nil connection object for the time being.
ConnectionAdapters::PostgreSQLAdapter.new(nil, logger, [host, port, nil, nil, database, username, password], config)
end
@ -217,8 +217,8 @@ module ActiveRecord
# * <tt>:password</tt> -- Defaults to nothing
# * <tt>:database</tt> -- The name of the database. No default, must be provided.
# * <tt>:schema_search_path</tt> -- An optional schema search path for the connection given as a string of comma-separated schema names. This is backward-compatible with the :schema_order option.
# * <tt>:encoding</tt> -- An optional client encoding that is using in a SET client_encoding TO <encoding> call on connection.
# * <tt>:min_messages</tt> -- An optional client min messages that is using in a SET client_min_messages TO <min_messages> call on connection.
# * <tt>:encoding</tt> -- An optional client encoding that is used in a SET client_encoding TO <encoding> call on the connection.
# * <tt>:min_messages</tt> -- An optional client min messages that is used in a SET client_min_messages TO <min_messages> call on the connection.
# * <tt>:allow_concurrency</tt> -- If true, use async query methods so Ruby threads don't deadlock; otherwise, use blocking query methods.
class PostgreSQLAdapter < AbstractAdapter
# Returns 'PostgreSQL' as adapter name for identification purposes.
@ -398,7 +398,7 @@ module ActiveRecord
end
end
# Executes a SQL statement, returning a PGresult object on success
# Executes an SQL statement, returning a PGresult object on success
# or raising a PGError exception otherwise.
def execute(sql, name = nil)
log(sql, name) do
@ -478,7 +478,7 @@ module ActiveRecord
# Returns the list of all column definitions for a table.
def columns(table_name, name = nil)
# Limit, precision, and scale are all handled by superclass.
# Limit, precision, and scale are all handled by the superclass.
column_definitions(table_name).collect do |name, type, default, notnull|
PostgreSQLColumn.new(name, default, type, notnull == 'f')
end
@ -669,7 +669,7 @@ module ActiveRecord
sql << order_columns * ', '
end
# Returns a ORDER BY clause for the passed order option.
# Returns an ORDER BY clause for the passed order option.
#
# PostgreSQL does not allow arbitrary ordering when using DISTINCT ON, so we work around this
# by wrapping the sql as a sub-select and ordering in that query.
@ -761,7 +761,7 @@ module ActiveRecord
end
# Executes a SELECT query and returns the results, performing any data type
# conversions that require to be performed here instead of in PostgreSQLColumn.
# conversions that are required to be performed here instead of in PostgreSQLColumn.
def select(sql, name = nil)
fields, rows = select_raw(sql, name)
result = []
@ -791,7 +791,7 @@ module ActiveRecord
# fields that call value_before_type_cast.
if res.type(cell_index) == MONEY_COLUMN_TYPE_OID
# Because money output is formatted according to the locale, there are two
# cases to consider (note the decimal seperators):
# cases to consider (note the decimal separators):
# (1) $12,345,678.12
# (2) $12.345.678,12
case column = row[cell_index]

2
activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
View File

@ -34,7 +34,7 @@ module ActiveRecord
# Allow database path relative to RAILS_ROOT, but only if
# the database path is not the special path that tells
# Sqlite build a database only in memory.
# Sqlite to build a database only in memory.
if Object.const_defined?(:RAILS_ROOT) && ':memory:' != config[:database]
config[:database] = File.expand_path(config[:database], RAILS_ROOT)
end

14
activerecord/lib/active_record/fixtures.rb
View File

@ -12,7 +12,7 @@ end
class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
end
# Fixtures are a way of organizing data that you want to test against; in short, sample data. They come in 3 flavours:
# Fixtures are a way of organizing data that you want to test against; in short, sample data. They come in 3 flavors:
#
# 1. YAML fixtures
# 2. CSV fixtures
@ -21,7 +21,7 @@ end
# = YAML fixtures
#
# This type of fixture is in YAML format and the preferred default. YAML is a file format which describes data structures
# in a non-verbose, humanly-readable format. It ships with Ruby 1.8.1+.
# in a non-verbose, human-readable format. It ships with Ruby 1.8.1+.
#
# Unlike single-file fixtures, YAML fixtures are stored in a single file per model, which are placed in the directory appointed
# by <tt>Test::Unit::TestCase.fixture_path=(path)</tt> (this is automatically configured for Rails, so you can just
@ -82,7 +82,7 @@ end
#
# = Single-file fixtures
#
# This type of fixtures was the original format for Active Record that has since been deprecated in favor of the YAML and CSV formats.
# This type of fixture was the original format for Active Record that has since been deprecated in favor of the YAML and CSV formats.
# Fixtures for this format are created by placing text files in a sub-directory (with the name of the model) to the directory
# appointed by <tt>Test::Unit::TestCase.fixture_path=(path)</tt> (this is automatically configured for Rails, so you can just
# put your files in <your-rails-app>/test/fixtures/<your-model-name>/ -- like <your-rails-app>/test/fixtures/web_sites/ for the WebSite
@ -106,7 +106,7 @@ end
# = Using Fixtures
#
# Since fixtures are a testing construct, we use them in our unit and functional tests. There are two ways to use the
# fixtures, but first let's take a look at a sample unit test found:
# fixtures, but first let's take a look at a sample unit test:
#
# require 'web_site'
#
@ -124,7 +124,7 @@ end
# fixtures :web_sites # add more by separating the symbols with commas
# ...
#
# By adding a "fixtures" method to the test case and passing it a list of symbols (only one is shown here tho), we trigger
# By adding a "fixtures" method to the test case and passing it a list of symbols (only one is shown here though), we trigger
# the testing environment to automatically load the appropriate fixtures into the database before each test.
# To ensure consistent data, the environment deletes the fixtures before running the load.
#
@ -212,7 +212,7 @@ end
# When *not* to use transactional fixtures:
# 1. You're testing whether a transaction works correctly. Nested transactions don't commit until all parent transactions commit,
# particularly, the fixtures transaction which is begun in setup and rolled back in teardown. Thus, you won't be able to verify
# the results of your transaction until Active Record supports nested transactions or savepoints (in progress.)
# the results of your transaction until Active Record supports nested transactions or savepoints (in progress).
# 2. Your database does not support transactions. Every Active Record database supports transactions except MySQL MyISAM.
# Use InnoDB, MaxDB, or NDB instead.
#
@ -260,7 +260,7 @@ end
#
# Specifying foreign keys in fixtures can be very fragile, not to
# mention difficult to read. Since ActiveRecord can figure out the ID of
# and fixture from its label, you can specify FK's by label instead of ID.
# any fixture from its label, you can specify FK's by label instead of ID.
#
# === belongs_to
#

12
activerecord/lib/active_record/migration.rb
View File

@ -32,9 +32,9 @@ module ActiveRecord
# end
# end
#
# This migration will add a boolean flag to the accounts table and remove it again, if you're backing out of the migration.
# This migration will add a boolean flag to the accounts table and remove it if you're backing out of the migration.
# It shows how all migrations have two class methods +up+ and +down+ that describes the transformations required to implement
# or remove the migration. These methods can consist of both the migration specific methods, like add_column and remove_column,
# or remove the migration. These methods can consist of both the migration specific methods like add_column and remove_column,
# but may also contain regular Ruby code for generating data needed for the transformations.
#
# Example of a more complex migration that also needs to initialize data:
@ -78,9 +78,9 @@ module ActiveRecord
# * <tt>change_column(table_name, column_name, type, options)</tt>: Changes the column to a different type using the same
# parameters as add_column.
# * <tt>remove_column(table_name, column_name)</tt>: Removes the column named +column_name+ from the table called +table_name+.
# * <tt>add_index(table_name, column_names, options)</tt>: Add a new index with the name of the column. Other options include
# * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index with the name of the column. Other options include
# :name and :unique (e.g. { :name => "users_name_index", :unique => true }).
# * <tt>remove_index(table_name, index_name)</tt>: Remove the index specified by +index_name+.
# * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified by +index_name+.
#
# == Irreversible transformations
#
@ -94,9 +94,9 @@ module ActiveRecord
# To generate a new migration, use <tt>script/generate migration MyNewMigration</tt>
# where MyNewMigration is the name of your migration. The generator will
# create a file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt>
# directory, where <tt>nnn</tt> is the next largest migration number.
# directory where <tt>nnn</tt> is the next largest migration number.
# You may then edit the <tt>self.up</tt> and <tt>self.down</tt> methods of
# n MyNewMigration.
# MyNewMigration.
#
# To run migrations against the currently configured database, use
# <tt>rake db:migrate</tt>. This will update the database by running all of the

4
activerecord/lib/active_record/reflection.rb
View File

@ -44,7 +44,7 @@ module ActiveRecord
reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil
end
# Returns an array of AssociationReflection objects for all the aggregations in the class. If you only want to reflect on a
# Returns an array of AssociationReflection objects for all the associations in the class. If you only want to reflect on a
# certain association type, pass in the symbol (:has_many, :has_one, :belongs_to) for that as the first parameter.
# Example:
#
@ -56,7 +56,7 @@ module ActiveRecord
macro ? association_reflections.select { |reflection| reflection.macro == macro } : association_reflections
end
# Returns the AssociationReflection object for the named +aggregation+ (use the symbol). Example:
# Returns the AssociationReflection object for the named +association+ (use the symbol). Example:
#
# Account.reflect_on_association(:owner) # returns the owner AssociationReflection
# Invoice.reflect_on_association(:line_items).macro # returns :has_many

4
activerecord/lib/active_record/serializers/xml_serializer.rb
View File

@ -1,7 +1,7 @@
module ActiveRecord #:nodoc:
module Serialization
# Builds an XML document to represent the model. Some configuration is
# available through +options+, however more complicated cases should use
# available through +options+, however more complicated cases should
# override ActiveRecord's to_xml.
#
# By default the generated XML document will include the processing
@ -107,7 +107,7 @@ module ActiveRecord #:nodoc:
# </creator>
# </firm>
#
# You may override the to_xml method in your ActiveRecord::Base
# You can override the to_xml method in your ActiveRecord::Base
# subclasses if you need to. The general form of doing this is
#
# class IHaveMyOwnXML < ActiveRecord::Base

4
activerecord/lib/active_record/timestamp.rb
View File

@ -1,6 +1,6 @@
module ActiveRecord
# Active Record automatically timestamps create and update if the table has fields
# created_at/created_on or updated_at/updated_on.
# Active Record automatically timestamps create and update operations if the table has fields
# named created_at/created_on or updated_at/updated_on.
#
# Timestamping can be turned off by setting
# <tt>ActiveRecord::Base.record_timestamps = false</tt>

2
activerecord/lib/active_record/transactions.rb
View File

@ -75,7 +75,7 @@ module ActiveRecord
#
# Both Base#save and Base#destroy come wrapped in a transaction that ensures that whatever you do in validations or callbacks
# will happen under the protected cover of a transaction. So you can use validations to check for values that the transaction
# depend on or you can raise exceptions in the callbacks to rollback.
# depends on or you can raise exceptions in the callbacks to rollback.
#
# == Exception handling
#

6
activerecord/lib/active_record/validations.rb
View File

@ -15,7 +15,7 @@ module ActiveRecord
end
# Active Record validation is reported to and from this object, which is used by Base#save to
# determine whether the object in a valid state to be saved. See usage example in Validations.
# determine whether the object is in a valid state to be saved. See usage example in Validations.
class Errors
include Enumerable
@ -45,7 +45,7 @@ module ActiveRecord
:even => "must be even"
}
# Holds a hash with all the default error messages, such that they can be replaced by your own copy or localizations.
# Holds a hash with all the default error messages that can be replaced by your own copy or localizations.
cattr_accessor :default_error_messages
@ -118,7 +118,7 @@ module ActiveRecord
alias :[] :on
# Returns errors assigned to base object through add_to_base according to the normal rules of on(attribute).
# Returns errors assigned to the base object through add_to_base according to the normal rules of on(attribute).
def on_base
on(:base)
end