diff options
Diffstat (limited to 'activerecord')
11 files changed, 279 insertions, 253 deletions
diff --git a/activerecord/README b/activerecord/README index ff3f55ee8a..d68eb28a64 100755 --- a/activerecord/README +++ b/activerecord/README @@ -169,10 +169,10 @@ A short rundown of the major features: class AddSystemSettings < ActiveRecord::Migration def self.up create_table :system_settings do |t| - t.string :name - t.string :label - t.text :value - t.string :type + t.string :name + t.string :label + t.text :value + t.string :type t.integer :position end @@ -289,16 +289,6 @@ Bi-directional associations thanks to the "belongs_to" macro thirty_seven_signals.firm.nil? # true -== Examples - -Active Record ships with a couple of examples that should give you a good feel for -operating usage. Be sure to edit the <tt>examples/shared_setup.rb</tt> file for your -own database before running the examples. Possibly also the table definition SQL in -the examples themselves. - -It's also highly recommended to have a look at the unit tests. Read more in link:files/RUNNING_UNIT_TESTS.html - - == Philosophy Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is @@ -336,7 +326,7 @@ then use: % [sudo] gem install activerecord-1.10.0.gem -You can also install Active Record the old-fashion way with the following command: +You can also install Active Record the old-fashioned way with the following command: % [sudo] ruby install.rb @@ -357,5 +347,5 @@ RubyForge page at http://rubyforge.org/projects/activerecord. And as Jim from Ra remember to update the corresponding unit tests. If fact, I prefer new feature to be submitted in the form of new unit tests. -For other information, feel free to ask on the ruby-talk mailing list -(which is mirrored to comp.lang.ruby) or contact mailto:david@loudthinking.com. +For other information, feel free to ask on the rubyonrails-talk +(http://groups.google.com/group/rubyonrails-talk) mailing list. diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 0809b271d7..fb5f1f8a8c 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -110,7 +110,7 @@ module ActiveRecord # # Don't create associations that have the same name as instance methods of ActiveRecord::Base. Since the association # adds a method with that name to its model, it will override the inherited method and break things. - # For instance, #attributes and #connection would be bad choices for association names. + # For instance, +attributes+ and +connection+ would be bad choices for association names. # # == Auto-generated methods # @@ -258,7 +258,7 @@ module ActiveRecord # order to update their primary keys - except if the parent object is unsaved (<tt>new_record? == true</tt>). # * If either of these saves fail (due to one of the objects being invalid) the assignment statement returns +false+ and the assignment # is cancelled. - # * If you wish to assign an object to a +has_one+ association without saving it, use the <tt>#association.build</tt> method (documented below). + # * If you wish to assign an object to a +has_one+ association without saving it, use the <tt>association.build</tt> method (documented below). # * Assigning an object to a +belongs_to+ association does not save the object, since the foreign key field belongs on the parent. It # does not save the parent either. # @@ -266,8 +266,8 @@ module ActiveRecord # # * Adding an object to a collection (+has_many+ or +has_and_belongs_to_many+) automatically saves that object, except if the parent object # (the owner of the collection) is not yet stored in the database. - # * If saving any of the objects being added to a collection (via <tt>#push</tt> or similar) fails, then <tt>#push</tt> returns +false+. - # * You can add an object to a collection without automatically saving it by using the <tt>#collection.build</tt> method (documented below). + # * If saving any of the objects being added to a collection (via <tt>push</tt> or similar) fails, then <tt>push</tt> returns +false+. + # * You can add an object to a collection without automatically saving it by using the <tt>collection.build</tt> method (documented below). # * All unsaved (<tt>new_record? == true</tt>) members of the collection are automatically saved when the parent is saved. # # === Association callbacks @@ -504,8 +504,8 @@ module ActiveRecord # # Address.find(:all, :include => :addressable) # INVALID # - # will raise <tt>ActiveRecord::EagerLoadPolymorphicError</tt>. The reason is that the parent model's type - # is a column value so its corresponding table name cannot be put in the FROM/JOIN clauses of that early query. + # will raise ActiveRecord::EagerLoadPolymorphicError. The reason is that the parent model's type + # is a column value so its corresponding table name cannot be put in the +FROM+/+JOIN+ clauses of that early query. # # In versions greater than 2.0.2 eager loading in polymorphic associations is supported # thanks to a change in the overall preloading strategy. @@ -575,7 +575,7 @@ module ActiveRecord # end # end # - # When <tt>Firm#clients</tt> is called, it will in turn call <tt>MyApplication::Business::Company.find(firm.id)</tt>. If you want to associate + # When Firm#clients is called, it will in turn call <tt>MyApplication::Business::Company.find(firm.id)</tt>. If you want to associate # with a class in another module scope, this can be done by specifying the complete class name. Example: # # module MyApplication @@ -603,28 +603,28 @@ module ActiveRecord # Adds the following methods for retrieval and query of collections of associated objects: # +collection+ is replaced with the symbol passed as the first argument, so # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>. - # * <tt>collection(force_reload = false)</tt> - returns an array of all the associated objects. + # * <tt>collection(force_reload = false)</tt> - Returns an array of all the associated objects. # An empty array is returned if none are found. - # * <tt>collection<<(object, ...)</tt> - adds one or more objects to the collection by setting their foreign keys to the collection's primary key. - # * <tt>collection.delete(object, ...)</tt> - removes one or more objects from the collection by setting their foreign keys to NULL. + # * <tt>collection<<(object, ...)</tt> - Adds one or more objects to the collection by setting their foreign keys to the collection's primary key. + # * <tt>collection.delete(object, ...)</tt> - Removes one or more objects from the collection by setting their foreign keys to +NULL+. # 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 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 + # * <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 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>, - # 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. - # * <tt>collection.build(attributes = {}, ...)</tt> - returns one or more new objects of the collection type that have been instantiated + # 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. + # * <tt>collection.build(attributes = {}, ...)</tt> - Returns one or more new objects of the collection type that have been instantiated # with +attributes+ and linked to this object through a foreign key, but have not yet been saved. *Note:* This only works if an # associated object already exists, not if it's +nil+! - # * <tt>collection.create(attributes = {})</tt> - returns a new object of the collection type that has been instantiated + # * <tt>collection.create(attributes = {})</tt> - Returns a new object of the collection type that has been instantiated # with +attributes+, linked to this object through a foreign key, and that has already been saved (if it passed the validation). # *Note:* This only works if an associated object already exists, not if it's +nil+! # - # Example: A +Firm+ class declares <tt>has_many :clients</tt>, which will add: + # Example: A Firm class declares <tt>has_many :clients</tt>, which will add: # * <tt>Firm#clients</tt> (similar to <tt>Clients.find :all, :conditions => "firm_id = #{id}"</tt>) # * <tt>Firm#clients<<</tt> # * <tt>Firm#clients.delete</tt> @@ -640,45 +640,45 @@ module ActiveRecord # The declaration can also include an options hash to specialize the behavior of the association. # # Options are: - # * <tt>:class_name</tt> - specify the class name of the association. Use it only if that name can't be inferred - # from the association name. So <tt>has_many :products</tt> will by default be linked to the +Product+ class, but - # if the real class name is +SpecialProduct+, you'll have to specify it with this option. - # * <tt>:conditions</tt> - specify the conditions that the associated objects must meet in order to be included as a +WHERE+ + # * <tt>:class_name</tt> - Specify the class name of the association. Use it only if that name can't be inferred + # from the association name. So <tt>has_many :products</tt> will by default be linked to the Product class, but + # if the real class name is SpecialProduct, you'll have to specify it with this option. + # * <tt>:conditions</tt> - Specify the conditions that the associated objects must meet in order to be included as a +WHERE+ # SQL fragment, such as <tt>price > 5 AND name LIKE 'B%'</tt>. Record creations from the association are scoped if a hash # is used. <tt>has_many :posts, :conditions => {:published => true}</tt> will create published posts with <tt>@blog.posts.create</tt> # or <tt>@blog.posts.build</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 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+. - # * <tt>:dependent</tt> - if set to <tt>:destroy</tt> all the associated objects are destroyed - # alongside this object by calling their destroy method. If set to <tt>:delete_all</tt> all associated - # objects are deleted *without* calling their destroy method. If set to <tt>:nullify</tt> all associated - # objects' foreign keys are set to +NULL+ *without* calling their save callbacks. *Warning:* This option is ignored when also using - # the <tt>through</tt> option. - # * <tt>:finder_sql</tt> - specify a complete SQL statement to fetch the association. This is a good way to go for complex + # * <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 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 <tt>:foreign_key</tt>. + # * <tt>:dependent</tt> - If set to <tt>:destroy</tt> all the associated objects are destroyed + # alongside this object by calling their +destroy+ method. If set to <tt>:delete_all</tt> all associated + # objects are deleted *without* calling their +destroy+ method. If set to <tt>:nullify</tt> all associated + # objects' foreign keys are set to +NULL+ *without* calling their +save+ callbacks. *Warning:* This option is ignored when also using + # the <tt>:through</tt> option. + # * <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 + # * <tt>:counter_sql</tt> - Specify a complete SQL statement to fetch the size of the association. If <tt>:finder_sql</tt> is # 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>: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 # 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> + # * <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> # are ignored, as the association uses the source reflection. You can only use a <tt>:through</tt> query through a <tt>belongs_to</tt> # or <tt>has_many</tt> association on the join model. - # * <tt>:source</tt>: Specifies the source association name used by <tt>has_many :through</tt> queries. Only use it if the name cannot be + # * <tt>:source</tt> - Specifies the source association name used by <tt>has_many :through</tt> queries. Only use it if the name cannot be # inferred from the association. <tt>has_many :subscribers, :through => :subscriptions</tt> will look for either <tt>:subscribers</tt> or - # <tt>:subscriber</tt> on +Subscription+, unless a <tt>:source</tt> is given. - # * <tt>:source_type</tt>: Specifies type of the source association used by <tt>has_many :through</tt> queries where the source + # <tt>:subscriber</tt> on Subscription, unless a <tt>:source</tt> is given. + # * <tt>:source_type</tt> - Specifies type of the source association used by <tt>has_many :through</tt> queries where the source # association is a polymorphic +belongs_to+. - # * <tt>:uniq</tt> - if set to +true+, duplicates will be omitted from the collection. Useful in conjunction with <tt>:through</tt>. - # * <tt>:readonly</tt> - if set to +true+, all the associated objects are readonly through the association. + # * <tt>:uniq</tt> - If true, duplicates will be omitted from the collection. Useful in conjunction with <tt>:through</tt>. + # * <tt>:readonly</tt> - If true, all the associated objects are readonly through the association. # # Option examples: # has_many :comments, :order => "posted_on" @@ -712,14 +712,14 @@ module ActiveRecord # Adds the following methods for retrieval and query of a single associated object: # +association+ is replaced with the symbol passed as the first argument, so # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>. - # * <tt>association(force_reload = false)</tt> - returns the associated object. +nil+ is returned if none is found. - # * <tt>association=(associate)</tt> - assigns the associate object, extracts the primary key, sets it as the foreign key, + # * <tt>association(force_reload = false)</tt> - Returns the associated object. +nil+ is returned if none is found. + # * <tt>association=(associate)</tt> - Assigns the associate object, extracts the primary key, sets it as the foreign key, # and saves the associate object. - # * <tt>association.nil?</tt> - returns +true+ if there is no associated object. - # * <tt>build_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated + # * <tt>association.nil?</tt> - Returns +true+ if there is no associated object. + # * <tt>build_association(attributes = {})</tt> - Returns a new object of the associated type that has been instantiated # with +attributes+ and linked to this object through a foreign key, but has not yet been saved. Note: This ONLY works if # an association already exists. It will NOT work if the association is +nil+. - # * <tt>create_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated + # * <tt>create_association(attributes = {})</tt> - Returns a new object of the associated type that has been instantiated # with +attributes+, linked to this object through a foreign key, and that has already been saved (if it passed the validation). # # Example: An Account class declares <tt>has_one :beneficiary</tt>, which will add: @@ -732,28 +732,28 @@ module ActiveRecord # The declaration can also include an options hash to specialize the behavior of the association. # # Options are: - # * <tt>:class_name</tt> - specify the class name of the association. Use it only if that name can't be inferred - # from the association name. So <tt>has_one :manager</tt> will by default be linked to the +Manager+ class, but - # 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+ + # * <tt>:class_name</tt> - Specify the class name of the association. Use it only if that name can't be inferred + # from the association name. So <tt>has_one :manager</tt> will by default be linked to the Manager class, but + # 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 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>: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. - # * <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_one+ association will use +person_id+ - # as the default +foreign_key+. - # * <tt>:include</tt> - specify second-order associations that should be eager loaded when this object is loaded. - # * <tt>:as</tt>: Specifies a polymorphic interface (See <tt>#belongs_to</tt>). + # * <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_one+ association will use "person_id" + # as the default <tt>:foreign_key</tt>. + # * <tt>:include</tt> - Specify second-order associations that should be eager loaded when this object is loaded. + # * <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> # are ignored, as the association uses the source reflection. You can only use a <tt>:through</tt> query through a # <tt>has_one</tt> or <tt>belongs_to</tt> association on the join model. - # * <tt>:source</tt>: Specifies the source association name used by <tt>has_one :through</tt> queries. Only use it if the name cannot be + # * <tt>:source</tt> - Specifies the source association name used by <tt>has_one :through</tt> queries. Only use it if the name cannot be # inferred from the association. <tt>has_one :favorite, :through => :favorites</tt> will look for a - # <tt>:favorite</tt> on +Favorite+, unless a <tt>:source</tt> is given. - # * <tt>:readonly</tt> - if set to +true+, the associated object is readonly through the association. + # <tt>:favorite</tt> on Favorite, unless a <tt>:source</tt> is given. + # * <tt>:readonly</tt> - If true, the associated object is readonly through the association. # # Option examples: # has_one :credit_card, :dependent => :destroy # destroys the associated credit card @@ -796,12 +796,12 @@ module ActiveRecord # Adds the following methods for retrieval and query for a single associated object for which this object holds an id: # +association+ is replaced with the symbol passed as the first argument, so # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>. - # * <tt>association(force_reload = false)</tt> - returns the associated object. +nil+ is returned if none is found. - # * <tt>association=(associate)</tt> - assigns the associate object, extracts the primary key, and sets it as the foreign key. - # * <tt>association.nil?</tt> - returns +true+ if there is no associated object. - # * <tt>build_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated + # * <tt>association(force_reload = false)</tt> - Returns the associated object. +nil+ is returned if none is found. + # * <tt>association=(associate)</tt> - Assigns the associate object, extracts the primary key, and sets it as the foreign key. + # * <tt>association.nil?</tt> - Returns +true+ if there is no associated object. + # * <tt>build_association(attributes = {})</tt> - Returns a new object of the associated type that has been instantiated # with +attributes+ and linked to this object through a foreign key, but has not yet been saved. - # * <tt>create_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated + # * <tt>create_association(attributes = {})</tt> - Returns a new object of the associated type that has been instantiated # with +attributes+, linked to this object through a foreign key, and that has already been saved (if it passed the validation). # # Example: A Post class declares <tt>belongs_to :author</tt>, which will add: @@ -814,34 +814,35 @@ module ActiveRecord # The declaration can also include an options hash to specialize the behavior of the association. # # Options are: - # * <tt>:class_name</tt> - specify the class name of the association. Use it only if that name can't be inferred - # from the association name. So <tt>has_one :author</tt> will by default be linked to the +Author+ class, but - # 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+ + # * <tt>:class_name</tt> - Specify the class name of the association. Use it only if that name can't be inferred + # from the association name. So <tt>has_one :author</tt> will by default be linked to the Author class, but + # 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 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 association with an +_id+ suffix. So a class that defines a +belongs_to :person+ association will use +person_id+ as the default +foreign_key+. - # Similarly, +belongs_to :favorite_person, :class_name => "Person"+ will use a foreign key of +favorite_person_id+. - # * <tt>:dependent</tt> - if set to <tt>:destroy</tt>, the associated object is destroyed when this object is. If set to + # * <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 association with an "_id" suffix. So a class that defines a <tt>belongs_to :person</tt> association will use + # "person_id" as the default <tt>:foreign_key</tt>. Similarly, <tt>belongs_to :favorite_person, :class_name => "Person"</tt> + # will use a foreign key of "favorite_person_id". + # * <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. This option should not be specified when # <tt>belongs_to</tt> is used in conjunction with a <tt>has_many</tt> relationship on another class because of the potential to leave # orphaned records behind. - # * <tt>:counter_cache</tt> - caches the number of belonging objects on the associate class through the 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 + # 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 # a column name instead of a +true+/+false+ value to this option (e.g., <tt>:counter_cache => :my_custom_counter</tt>.) # When creating a counter cache column, the database statement or migration must specify a default value of <tt>0</tt>, failing to do - # this results in a counter with NULL value, which will never increment. - # Note: Specifying a counter_cache will add it to that model's list of readonly attributes using #attr_readonly. - # * <tt>:include</tt> - specify second-order associations that should be eager loaded when this object is loaded. + # this results in a counter with +NULL+ value, which will never increment. + # Note: Specifying a counter cache will add it to that model's list of readonly attributes using +attr_readonly+. + # * <tt>:include</tt> - Specify second-order associations that should be eager loaded when this object is loaded. # Not allowed if the association is polymorphic. - # * <tt>:polymorphic</tt> - specify this association is a polymorphic association by passing +true+. + # * <tt>:polymorphic</tt> - Specify this association is a polymorphic association by passing +true+. # Note: If you've enabled the counter cache, then you may want to add the counter cache attribute - # to the attr_readonly list in the associated classes (e.g. class Post; attr_readonly :comments_count; end). - # * <tt>:readonly</tt> - if set to +true+, the associated object is readonly through the association. + # to the +attr_readonly+ list in the associated classes (e.g. <tt>class Post; attr_readonly :comments_count; end</tt>). + # * <tt>:readonly</tt> - If true, the associated object is readonly through the association. # # Option examples: # belongs_to :firm, :foreign_key => "client_of" @@ -926,14 +927,14 @@ module ActiveRecord end # Associates two classes via an intermediate join table. Unless the join table is explicitly specified as - # an option, it is guessed using the lexical order of the class names. So a join between +Developer+ and +Project+ - # will give the default join table name of +developers_projects+ because "D" outranks "P". Note that this precedence - # is calculated using the <tt><</tt> operator for <tt>String</tt>. This means that if the strings are of different lengths, + # an option, it is guessed using the lexical order of the class names. So a join between Developer and Project + # will give the default join table name of "developers_projects" because "D" outranks "P". Note that this precedence + # is calculated using the <tt><</tt> operator for String. This means that if the strings are of different lengths, # and the strings are equal when compared up to the shortest length, then the longer string is considered of higher - # lexical precedence than the shorter one. For example, one would expect the tables <tt>paper_boxes</tt> and <tt>papers</tt> - # to generate a join table name of <tt>papers_paper_boxes</tt> because of the length of the name <tt>paper_boxes</tt>, - # but it in fact generates a join table name of <tt>paper_boxes_papers</tt>. Be aware of this caveat, and use the - # custom <tt>join_table</tt> option if you need to. + # lexical precedence than the shorter one. For example, one would expect the tables "paper_boxes" and "papers" + # to generate a join table name of "papers_paper_boxes" because of the length of the name "paper_boxes", + # but it in fact generates a join table name of "paper_boxes_papers". Be aware of this caveat, and use the + # custom <tt>:join_table</tt> option if you need to. # # Deprecated: Any additional fields added to the join table will be placed as attributes when pulling records out through # +has_and_belongs_to_many+ associations. Records returned from join tables with additional attributes will be marked as @@ -943,23 +944,23 @@ module ActiveRecord # Adds the following methods for retrieval and query: # +collection+ is replaced with the symbol passed as the first argument, so # <tt>has_and_belongs_to_many :categories</tt> would add among others <tt>categories.empty?</tt>. - # * <tt>collection(force_reload = false)</tt> - returns an array of all the associated objects. + # * <tt>collection(force_reload = false)</tt> - Returns an array of all the associated objects. # An empty array is returned if none are found. - # * <tt>collection<<(object, ...)</tt> - adds one or more objects to the collection by creating associations in the join table + # * <tt>collection<<(object, ...)</tt> - Adds one or more objects to the collection by creating associations in the join table # (<tt>collection.push</tt> and <tt>collection.concat</tt> are aliases to this method). - # * <tt>collection.delete(object, ...)</tt> - removes one or more objects from the collection by removing their associations from the join table. + # * <tt>collection.delete(object, ...)</tt> - Removes one or more objects from the collection by removing their associations from the join table. # This does not destroy the objects. - # * <tt>collection=objects</tt> - replaces the collection's 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.clear</tt> - removes every object from the collection. This does not destroy the objects. - # * <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(id)</tt> - finds an associated object responding to the +id+ and that + # * <tt>collection=objects</tt> - Replaces the collection's 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.clear</tt> - Removes every object from the collection. This does not destroy the objects. + # * <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(id)</tt> - Finds an associated object responding to the +id+ and that # meets the condition that it has to be associated with this object. - # * <tt>collection.build(attributes = {})</tt> - returns a new object of the collection type that has been instantiated + # * <tt>collection.build(attributes = {})</tt> - Returns a new object of the collection type that has been instantiated # with +attributes+ and linked to this object through the join table, but has not yet been saved. - # * <tt>collection.create(attributes = {})</tt> - returns a new object of the collection type that has been instantiated + # * <tt>collection.create(attributes = {})</tt> - Returns a new object of the collection type that has been instantiated # with +attributes+, linked to this object through the join table, and that has already been saved (if it passed the validation). # # Example: A Developer class declares <tt>has_and_belongs_to_many :projects</tt>, which will add: @@ -978,38 +979,38 @@ module ActiveRecord # The declaration may include an options hash to specialize the behavior of the association. # # Options are: - # * <tt>:class_name</tt> - specify the class name of the association. Use it only if that name can't be inferred + # * <tt>:class_name</tt> - Specify the class name of the association. Use it only if that name can't be inferred # from the association name. So <tt>has_and_belongs_to_many :projects</tt> will by default be linked to the - # +Project+ class, but if the real class name is +SuperProject+, you'll have to specify it with this option. - # * <tt>:join_table</tt> - specify the name of the join table if the default based on lexical order isn't what you want. + # Project class, but if the real class name is SuperProject, you'll have to specify it with this option. + # * <tt>:join_table</tt> - Specify the name of the join table if the default based on lexical order isn't what you want. # WARNING: If you're overwriting the table name of either class, the +table_name+ method MUST be declared underneath any # +has_and_belongs_to_many+ declaration in order to work. - # * <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_and_belongs_to_many+ association - # will use +person_id+ as the default +foreign_key+. - # * <tt>:association_foreign_key</tt> - specify the association 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 if the associated class is +Project+, - # 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+ + # * <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_and_belongs_to_many+ association + # will use "person_id" as the default <tt>:foreign_key</tt>. + # * <tt>:association_foreign_key</tt> - Specify the association 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 if the associated class is Project, + # the +has_and_belongs_to_many+ association will use "project_id" as the default <tt>:association_foreign_key</tt>. + # * <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>. Record creations from the association are scoped if a hash is used. # <tt>has_many :posts, :conditions => {:published => true}</tt> will create published posts with <tt>@blog.posts.create</tt> # or <tt>@blog.posts.build</tt>. - # * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment, + # * <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 - # classes with a manual statement - # * <tt>:insert_sql</tt> - overwrite the default generated SQL statement used to add links between the associated classes - # with a manual statement - # * <tt>:extend</tt> - anonymous 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, for example, you want to do a join + # * <tt>:uniq</tt> - If 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 + # classes with a manual statement. + # * <tt>:insert_sql</tt> - Overwrite the default generated SQL statement used to add links between the associated classes + # with a manual statement. + # * <tt>:extend</tt> - Anonymous 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, for example, you want to do a join # but not include the joined columns. - # * <tt>:readonly</tt> - if set to +true+, all the associated objects are readonly through the association. + # * <tt>:readonly</tt> - If true, all the associated objects are readonly through the association. # # Option examples: # has_and_belongs_to_many :projects diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index b600e8ecfd..74299bd572 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -92,13 +92,15 @@ module ActiveRecord #:nodoc: class DangerousAttributeError < ActiveRecordError end - # Raised when you've tried to access a column which wasn't - # loaded by your finder. Typically this is because <tt>:select</tt> - # has been specified. + # Raised when you've tried to access a column which wasn't loaded by your finder. + # Typically this is because <tt>:select</tt> has been specified. class MissingAttributeError < NoMethodError end - class AttributeAssignmentError < ActiveRecordError #:nodoc: + # Raised when an error occured while doing a mass assignment to an attribute through the + # <tt>attributes=</tt> method. The exception has an +attribute+ property that is the name of the + # offending attribute. + class AttributeAssignmentError < ActiveRecordError attr_reader :exception, :attribute def initialize(message, exception, attribute) @exception = exception @@ -107,7 +109,10 @@ module ActiveRecord #:nodoc: end end - class MultiparameterAssignmentErrors < ActiveRecordError #:nodoc: + # Raised when there are multiple errors while doing a mass assignment through the +attributes+ + # method. The exception has an +errors+ property that contains an array of AttributeAssignmentError + # objects, each corresponding to the error while assigning to an attribute. + class MultiparameterAssignmentErrors < ActiveRecordError attr_reader :errors def initialize(errors) @errors = errors @@ -230,8 +235,8 @@ module ActiveRecord #:nodoc: # == Accessing attributes before they have been typecasted # # Sometimes you want to be able to read the raw attribute data without having the column-determined typecast run its course first. - # That can be done by using the <attribute>_before_type_cast accessors that all attributes have. For example, if your Account model - # has a balance attribute, you can call account.balance_before_type_cast or account.id_before_type_cast. + # That can be done by using the <tt><attribute>_before_type_cast</tt> accessors that all attributes have. For example, if your Account model + # has a balance attribute, you can call <tt>account.balance_before_type_cast</tt> or <tt>account.id_before_type_cast</tt>. # # This is especially useful in validation situations where the user might supply a string for an integer field and you want to display # the original string back in an error message. Accessing the attribute normally would typecast the string to 0, which isn't what you @@ -332,26 +337,26 @@ 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 an + # * 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 an # <tt>:adapter</tt> key. - # * +AdapterNotFound+ -- the <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified a 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 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. - # * +StatementInvalid+ -- the database server rejected the SQL statement. The precise error is added in the message. - # Either the record with the given ID doesn't exist or the record didn't meet the additional restrictions. - # * +MultiparameterAssignmentErrors+ -- collection of errors that occurred during a mass assignment using the - # +attributes=+ method. The +errors+ property of this exception contains an array of +AttributeAssignmentError+ + # * AssociationTypeMismatch - The object assigned to the association wasn't of the type specified in the association definition. + # * 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. Some +find+ calls do not raise this exception to signal + # nothing was found, please check its documentation for further details. + # * StatementInvalid - The database server rejected the SQL statement. The precise error is added in the message. + # * MultiparameterAssignmentErrors - Collection of errors that occurred during a mass assignment using the + # <tt>attributes=</tt> method. The +errors+ property of this exception contains an array of AttributeAssignmentError # objects that should be inspected to determine which attributes triggered the errors. - # * +AttributeAssignmentError+ -- an error occurred while doing a mass assignment through the +attributes=+ method. + # * AttributeAssignmentError - An error occurred while doing a mass assignment through the <tt>attributes=</tt> method. # You can inspect the +attribute+ property of the exception object to determine which attribute triggered the error. # # *Note*: The attributes listed are class-level attributes (accessible from both the class and instance level). - # So it's possible to assign a logger to the class through Base.logger= which will then be used by all + # So it's possible to assign a logger to the class through <tt>Base.logger=</tt> which will then be used by all # instances in the current object space. class Base # Accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed @@ -601,7 +606,7 @@ module ActiveRecord #:nodoc: # User.create(:first_name => 'Jamie') # # # Create an Array of new objects - # User.create([{:first_name => 'Jamie'}, {:first_name => 'Jeremy'}]) + # User.create([{ :first_name => 'Jamie' }, { :first_name => 'Jeremy' }]) # # # Create a single object and pass it into a block to set other attributes. # User.create(:first_name => 'Jamie') do |u| @@ -609,7 +614,7 @@ module ActiveRecord #:nodoc: # end # # # Creating an Array of new objects using a block, where the block is executed for each object: - # User.create([{:first_name => 'Jamie'}, {:first_name => 'Jeremy'}]) do |u| + # User.create([{ :first_name => 'Jamie' }, { :first_name => 'Jeremy' }]) do |u| # u.is_admin = false # end def create(attributes = nil, &block) @@ -626,18 +631,18 @@ module ActiveRecord #:nodoc: # Updates an object (or multiple objects) and saves it to the database, if validations pass. # The resulting object is returned whether the object was saved successfully to the database or not. # - # ==== Options + # ==== Attributes # - # +id+ This should be the id or an array of ids to be updated - # +attributes+ This should be a Hash of attributes to be set on the object, or an array of Hashes. + # * +id+ - This should be the id or an array of ids to be updated. + # * +attributes+ - This should be a Hash of attributes to be set on the object, or an array of Hashes. # # ==== Examples # # # Updating one record: - # Person.update(15, {:user_name => 'Samuel', :group => 'expert'}) + # Person.update(15, { :user_name => 'Samuel', :group => 'expert' }) # # # Updating multiple records: - # people = { 1 => { "first_name" => "David" }, 2 => { "first_name" => "Jeremy"} } + # people = { 1 => { "first_name" => "David" }, 2 => { "first_name" => "Jeremy" } } # Person.update(people.keys, people.values) def update(id, attributes) if id.is_a?(Array) @@ -656,9 +661,9 @@ module ActiveRecord #:nodoc: # # Objects are _not_ instantiated with this method. # - # ==== Options + # ==== Attributes # - # +id+ Can be either an Integer or an Array of Integers + # * +id+ - Can be either an Integer or an Array of Integers. # # ==== Examples # @@ -679,9 +684,9 @@ module ActiveRecord #:nodoc: # This essentially finds the object (or multiple objects) with the given id, creates a new object # from the attributes, and then calls destroy on it. # - # ==== Options + # ==== Attributes # - # +id+ Can be either an Integer or an Array of Integers + # * +id+ - Can be either an Integer or an Array of Integers. # # ==== Examples # @@ -702,12 +707,12 @@ module ActiveRecord #:nodoc: # Updates all records with details given if they match a set of conditions supplied, limits and order can # also be supplied. # - # ==== Options + # ==== Attributes # - # +updates+ A String of column and value pairs that will be set on any records that match conditions - # +conditions+ An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. - # See conditions in the intro for more info. - # +options+ Additional options are <tt>:limit</tt> and/or <tt>:order</tt>, see the examples for usage. + # * +updates+ - A String of column and value pairs that will be set on any records that match conditions. + # * +conditions+ - An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. + # See conditions in the intro for more info. + # * +options+ - Additional options are <tt>:limit</tt> and/or <tt>:order</tt>, see the examples for usage. # # ==== Examples # @@ -734,9 +739,9 @@ module ActiveRecord #:nodoc: # many records. If you want to simply delete records without worrying about dependent associations or # callbacks, use the much faster +delete_all+ method instead. # - # ==== Options + # ==== Attributes # - # +conditions+ Conditions are specified the same way as with +find+ method. + # * +conditions+ - Conditions are specified the same way as with +find+ method. # # ==== Example # @@ -752,9 +757,9 @@ module ActiveRecord #:nodoc: # calling the destroy method and invoking callbacks. This is a single SQL query, much more efficient # than destroy_all. # - # ==== Options + # ==== Attributes # - # +conditions+ Conditions are specified the same way as with +find+ method. + # * +conditions+ - Conditions are specified the same way as with +find+ method. # # ==== Example # @@ -772,9 +777,9 @@ module ActiveRecord #:nodoc: # The use of this method should be restricted to complicated SQL queries that can't be executed # using the ActiveRecord::Calculations class methods. Look into those before using this. # - # ==== Options + # ==== Attributes # - # +sql+: An SQL statement which should return a count query from the database, see the example below + # * +sql+ - An SQL statement which should return a count query from the database, see the example below. # # ==== Examples # @@ -790,12 +795,11 @@ module ActiveRecord #:nodoc: # with the given ID, altering the given hash of counters by the amount # given by the corresponding value: # - # ==== Options + # ==== Attributes # - # +id+ The id of the object you wish to update a counter on - # +counters+ An Array of Hashes containing the names of the fields - # to update as keys and the amount to update the field by as - # values + # * +id+ - The id of the object you wish to update a counter on. + # * +counters+ - An Array of Hashes containing the names of the fields + # to update as keys and the amount to update the field by as values. # # ==== Examples # @@ -821,10 +825,10 @@ module ActiveRecord #:nodoc: # For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is # shown it would have to run an SQL query to find how many posts and comments there are. # - # ==== Options + # ==== Attributes # - # +counter_name+ The name of the field that should be incremented - # +id+ The id of the object that should be incremented + # * +counter_name+ - The name of the field that should be incremented. + # * +id+ - The id of the object that should be incremented. # # ==== Examples # @@ -838,10 +842,10 @@ module ActiveRecord #:nodoc: # # This works the same as increment_counter but reduces the column value by 1 instead of increasing it. # - # ==== Options + # ==== Attributes # - # +counter_name+ The name of the field that should be decremented - # +id+ The id of the object that should be decremented + # * +counter_name+ - The name of the field that should be decremented. + # * +id+ - The id of the object that should be decremented. # # ==== Examples # @@ -886,9 +890,9 @@ module ActiveRecord #:nodoc: # overwritten by URL/form hackers. If you'd rather start from an all-open default and restrict # attributes as needed, have a look at attr_protected. # - # ==== Options + # ==== Attributes # - # <tt>*attributes</tt> A comma separated list of symbols that represent columns _not_ to be protected + # * <tt>*attributes</tt> A comma separated list of symbols that represent columns _not_ to be protected # # ==== Examples # @@ -927,10 +931,10 @@ module ActiveRecord #:nodoc: # The serialization is done through YAML. If +class_name+ is specified, the serialized object must be of that # class on retrieval or +SerializationTypeMismatch+ will be raised. # - # ==== Options + # ==== Attributes # - # +attr_name+ The field name that should be serialized - # +class_name+ Optional, class name that the object type should be equal to + # * +attr_name+ - The field name that should be serialized. + # * +class_name+ - Optional, class name that the object type should be equal to. # # ==== Example # # Serialize a preferences attribute @@ -1757,7 +1761,7 @@ module ActiveRecord #:nodoc: # class Article < ActiveRecord::Base # def self.find_with_scope # with_scope(:find => { :conditions => "blog_id = 1", :limit => 1 }, :create => { :blog_id => 1 }) do - # with_scope(:find => { :limit => 10}) + # with_scope(:find => { :limit => 10 }) # find(:all) # => SELECT * from articles WHERE blog_id = 1 LIMIT 10 # end # with_scope(:find => { :conditions => "author_id = 3" }) @@ -2238,40 +2242,53 @@ module ActiveRecord #:nodoc: save! end - # Initializes the +attribute+ to zero if nil and adds the value passed as +by+ (default is one). Only makes sense for number-based attributes. Returns self. + # Initializes +attribute+ to zero if +nil+ and adds the value passed as +by+ (default is 1). + # The increment is performed directly on the underlying attribute, no setter is invoked. + # Only makes sense for number-based attributes. Returns +self+. def increment(attribute, by = 1) self[attribute] ||= 0 self[attribute] += by self end - # Increments the +attribute+ and saves the record. - # Note: Updates made with this method aren't subjected to validation checks + # Wrapper around +increment+ that saves the record. This method differs from + # its non-bang version in that it passes through the attribute setter. + # Saving is not subjected to validation checks. Returns +true+ if the + # record could be saved. def increment!(attribute, by = 1) increment(attribute, by).update_attribute(attribute, self[attribute]) end - # Initializes the +attribute+ to zero if nil and subtracts the value passed as +by+ (default is one). Only makes sense for number-based attributes. Returns self. + # Initializes +attribute+ to zero if +nil+ and subtracts the value passed as +by+ (default is 1). + # The decrement is performed directly on the underlying attribute, no setter is invoked. + # Only makes sense for number-based attributes. Returns +self+. def decrement(attribute, by = 1) self[attribute] ||= 0 self[attribute] -= by self end - # Decrements the +attribute+ and saves the record. - # Note: Updates made with this method aren't subjected to validation checks + # Wrapper around +decrement+ that saves the record. This method differs from + # its non-bang version in that it passes through the attribute setter. + # Saving is not subjected to validation checks. Returns +true+ if the + # record could be saved. def decrement!(attribute, by = 1) decrement(attribute, by).update_attribute(attribute, self[attribute]) end - # Turns an +attribute+ that's currently true into false and vice versa. Returns self. + # Assigns to +attribute+ the boolean opposite of <tt>attribute?</tt>. So + # if the predicate returns +true+ the attribute will become +false+. This + # method toggles directly the underlying value without calling any setter. + # Returns +self+. def toggle(attribute) self[attribute] = !send("#{attribute}?") self end - # Toggles the +attribute+ and saves the record. - # Note: Updates made with this method aren't subjected to validation checks + # Wrapper around +toggle+ that saves the record. This method differs from + # its non-bang version in that it passes through the attribute setter. + # Saving is not subjected to validation checks. Returns +true+ if the + # record could be saved. def toggle!(attribute) toggle(attribute).update_attribute(attribute, self[attribute]) end diff --git a/activerecord/lib/active_record/connection_adapters/abstract/query_cache.rb b/activerecord/lib/active_record/connection_adapters/abstract/query_cache.rb index e6b8e3ae90..2afd6064ad 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/query_cache.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/query_cache.rb @@ -44,6 +44,12 @@ module ActiveRecord @query_cache_enabled = old end + # Clears the query cache. + # + # One reason you may wish to call this method explicitly is between queries + # that ask the database to randomize results. Otherwise the cache would see + # the same SQL query and repeatedly return the same result each time, silently + # undermining the randomness you were expecting. def clear_query_cache @query_cache.clear if @query_cache end diff --git a/activerecord/lib/active_record/connection_adapters/abstract_adapter.rb b/activerecord/lib/active_record/connection_adapters/abstract_adapter.rb index 5c7e9f27a5..8c286f64db 100755 --- a/activerecord/lib/active_record/connection_adapters/abstract_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract_adapter.rb @@ -73,7 +73,7 @@ module ActiveRecord # REFERENTIAL INTEGRITY ==================================== - # Override to turn off referential integrity while executing +&block+ + # Override to turn off referential integrity while executing <tt>&block</tt>. def disable_referential_integrity(&block) yield end @@ -101,7 +101,7 @@ module ActiveRecord false end - # Lazily verify this connection, calling +active?+ only if it hasn't + # Lazily verify this connection, calling <tt>active?</tt> only if it hasn't # been called for +timeout+ seconds. def verify!(timeout) now = Time.now.to_i diff --git a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb index e742d60c5f..f00a2c8950 100755 --- a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb @@ -146,19 +146,19 @@ module ActiveRecord # # Options: # - # * <tt>:host</tt> -- Defaults to localhost - # * <tt>:port</tt> -- Defaults to 3306 - # * <tt>:socket</tt> -- Defaults to /tmp/mysql.sock - # * <tt>:username</tt> -- Defaults to root - # * <tt>:password</tt> -- Defaults to nothing - # * <tt>:database</tt> -- The name of the database. No default, must be provided. - # * <tt>:encoding</tt> -- (Optional) Sets the client encoding by executing "SET NAMES <encoding>" after connection - # * <tt>:sslkey</tt> -- Necessary to use MySQL with an SSL connection - # * <tt>:sslcert</tt> -- Necessary to use MySQL with an SSL connection - # * <tt>:sslcapath</tt> -- Necessary to use MySQL with an SSL connection - # * <tt>:sslcipher</tt> -- Necessary to use MySQL with an SSL connection + # * <tt>:host</tt> - Defaults to "localhost". + # * <tt>:port</tt> - Defaults to 3306. + # * <tt>:socket</tt> - Defaults to "/tmp/mysql.sock". + # * <tt>:username</tt> - Defaults to "root" + # * <tt>:password</tt> - Defaults to nothing. + # * <tt>:database</tt> - The name of the database. No default, must be provided. + # * <tt>:encoding</tt> - (Optional) Sets the client encoding by executing "SET NAMES <encoding>" after connection. + # * <tt>:sslkey</tt> - Necessary to use MySQL with an SSL connection. + # * <tt>:sslcert</tt> - Necessary to use MySQL with an SSL connection. + # * <tt>:sslcapath</tt> - Necessary to use MySQL with an SSL connection. + # * <tt>:sslcipher</tt> - Necessary to use MySQL with an SSL connection. # - # By default, the MysqlAdapter will consider all columns of type tinyint(1) + # By default, the MysqlAdapter will consider all columns of type <tt>tinyint(1)</tt> # as boolean. If you wish to disable this emulation (which was the default # behavior in versions 0.13.1 and earlier) you can add the following line # to your environment.rb file: diff --git a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb index e3f7969cdf..2ec2d80af4 100644 --- a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb @@ -228,15 +228,15 @@ module ActiveRecord # # Options: # - # * <tt>:host</tt> -- Defaults to localhost - # * <tt>:port</tt> -- Defaults to 5432 - # * <tt>:username</tt> -- Defaults to nothing - # * <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 <tt>:schema_order</tt> option. - # * <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. + # * <tt>:host</tt> - Defaults to "localhost". + # * <tt>:port</tt> - Defaults to 5432. + # * <tt>:username</tt> - Defaults to nothing. + # * <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 <tt>:schema_order</tt> option. + # * <tt>:encoding</tt> - An optional client encoding that is used in a <tt>SET client_encoding TO <encoding></tt> call on the connection. + # * <tt>:min_messages</tt> - An optional client min messages that is used in a <tt>SET client_min_messages TO <min_messages></tt> 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. def adapter_name diff --git a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb index 8fa62c1845..8abbc6d0a4 100644 --- a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb @@ -70,7 +70,7 @@ module ActiveRecord # # Options: # - # * <tt>:database</tt> -- Path to the database file. + # * <tt>:database</tt> - Path to the database file. class SQLiteAdapter < AbstractAdapter def adapter_name #:nodoc: 'SQLite' diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb index 7d5fd35dae..9367ea523d 100755 --- a/activerecord/lib/active_record/fixtures.rb +++ b/activerecord/lib/active_record/fixtures.rb @@ -426,7 +426,7 @@ end # == Support for YAML defaults # # You probably already know how to use YAML to set and reuse defaults in -# your +database.yml+ file,. You can use the same technique in your fixtures: +# your <tt>database.yml</tt> file. You can use the same technique in your fixtures: # # DEFAULTS: &DEFAULTS # created_on: <%= 3.weeks.ago.to_s(:db) %> diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb index 61005af83f..8614ef8751 100644 --- a/activerecord/lib/active_record/reflection.rb +++ b/activerecord/lib/active_record/reflection.rb @@ -153,6 +153,17 @@ module ActiveRecord end end + # Returns the AssociationReflection object specified in the <tt>:through</tt> option + # of a HasManyThrough or HasOneThrough association. Example: + # + # class Post < ActiveRecord::Base + # has_many :taggings + # has_many :tags, :through => :taggings + # end + # + # tags_reflection = Post.reflect_on_association(:tags) + # taggings_reflection = tags_reflection.through_reflection + # def through_reflection @through_reflection ||= options[:through] ? active_record.reflect_on_association(options[:through]) : false end @@ -168,7 +179,8 @@ module ActiveRecord # Gets the source of the through reflection. It checks both a singularized and pluralized form for <tt>:belongs_to</tt> or <tt>:has_many</tt>. # (The <tt>:tags</tt> association on Tagging below.) # - # class Post + # class Post < ActiveRecord::Base + # has_many :taggings # has_many :tags, :through => :taggings # end # diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb index 50db32725d..d25e8cd0da 100755 --- a/activerecord/lib/active_record/validations.rb +++ b/activerecord/lib/active_record/validations.rb @@ -678,7 +678,7 @@ module ActiveRecord # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+). # * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+). # * <tt>:with</tt> - The regular expression used to validate the format with (note: must be supplied!). - # * <tt>:on</tt> Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>). + # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <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. @@ -784,7 +784,7 @@ module ActiveRecord # # Configuration options: # * <tt>:message</tt> - A custom error message (default is: "is invalid") - # * <tt>:on</tt> Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>) + # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <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. @@ -802,8 +802,8 @@ module ActiveRecord end # Validates whether the value of the specified attribute is numeric by trying to convert it to - # a float with Kernel.Float (if <tt>integer</tt> is false) or applying it to the regular expression - # <tt>/\A[\+\-]?\d+\Z/</tt> (if <tt>integer</tt> is set to true). + # a float with Kernel.Float (if <tt>only_integer</tt> is false) or applying it to the regular expression + # <tt>/\A[\+\-]?\d+\Z/</tt> (if <tt>only_integer</tt> is set to true). # # class Person < ActiveRecord::Base # validates_numericality_of :value, :on => :create |