Format & edit cleanup of named scope guide

1 files changed, 46 insertions, 16 deletions

diff --git a/railties/doc/guides/source/finders.txt b/railties/doc/guides/source/finders.txt
index 24d078f9e4..738db04f3e 100644
--- a/railties/doc/guides/source/finders.txt
+++ b/railties/doc/guides/source/finders.txt
@@ -78,6 +78,8 @@ SELECT * FROM +clients+ WHERE (+clients+.+id+ IN (1,2))
 
 Note that if you pass in a list of numbers that the result will be returned as an array, not as a single +Client+ object.
 
+NOTE: If +find(id)+ or +find([id1, id2])+ fails to find any records, it will raise a +RecordNotFound+ exception.
+
 If you wanted to find the first client you would simply type +Client.first+ and that would find the first client created in your clients table:
 
 -------------------------------------------------------
@@ -124,13 +126,17 @@ Be aware that +Client.first+/+Client.find(:first)+ and +Client.last+/+Client.fin
 
 == Conditions
 
+The +find+ method allows you to specify conditions to limit the records returned. You can specify conditions as a string, array, or hash.
+
 === Pure String Conditions ===
 
 If you'd like to add conditions to your find, you could just specify them in there, just like +Client.first(:conditions => "orders_count = '2'")+. This will find all clients where the +orders_count+ field's value is 2.
 
+WARNING: Building your own conditions as pure strings can leave you vulnerable to SQL injection exploits. For example, +Client.first(:conditions => "name LIKE '%#{params[:name]}%'")+ is not safe. See the next section for the preferred way to handle conditions using an array.
+
 === Array Conditions ===
 
- Now what if that number could vary, say as a parameter from somewhere, or perhaps from the user's level status somewhere? The find then becomes something like +Client.first(:conditions => ["orders_count = ?", params[:orders]])+. Active Record will go through the first element in the conditions value and any additional elements will replace the question marks (?) in the first element. If you want to specify two conditions, you can do it like +Client.first(:conditions => ["orders_count = ? AND locked = ?", params[:orders], false])+. In this example, the first question mark will be replaced with the value in params orders and the second will be replaced with true and this will find the first record in the table that has '2' as its value for the orders_count field and 'false' for its locked field.
+Now what if that number could vary, say as a parameter from somewhere, or perhaps from the user's level status somewhere? The find then becomes something like +Client.first(:conditions => ["orders_count = ?", params[:orders]])+. Active Record will go through the first element in the conditions value and any additional elements will replace the question marks (?) in the first element. If you want to specify two conditions, you can do it like +Client.first(:conditions => ["orders_count = ? AND locked = ?", params[:orders], false])+. In this example, the first question mark will be replaced with the value in params orders and the second will be replaced with true and this will find the first record in the table that has '2' as its value for the orders_count field and 'false' for its locked field.
 
 The reason for doing code like:
 
@@ -234,7 +240,7 @@ To select certain fields, you can use the select option like this: +Client.first
 
 == Limit & Offset
 
-If you want to limit the amount of records to a certain subset of all the records retreived you usually use limit for this, sometimes coupled with offset. Limit is the maximum number of records that will be retreived from a query, and offset is the number of records it will start reading from from the first record of the set. Take this code for example:
+If you want to limit the amount of records to a certain subset of all the records retrieved you usually use limit for this, sometimes coupled with offset. Limit is the maximum number of records that will be retrieved from a query, and offset is the number of records it will start reading from from the first record of the set. Take this code for example:
 
 [source, ruby]
 -------------------------------------------------------
@@ -280,14 +286,14 @@ SELECT * FROM +orders+ GROUP BY date(created_at)
 
 == Read Only
 
-Readonly is a find option that you can set in order to make that instance of the record read-only. Any attempt to alter or destroy the record will not succeed, raising an +Active Record::ReadOnlyRecord+ error. To set this option, specify it like this:
+Readonly is a find option that you can set in order to make that instance of the record read-only. Any attempt to alter or destroy the record will not succeed, raising an +Active Record::ReadOnlyRecord+ exception. To set this option, specify it like this:
 
 [source, ruby]
 -------------------------------------------------------
 Client.first(:readonly => true)
 -------------------------------------------------------
 
-If you assign this record to a variable +client+, calling the following code will raise an ActiveRecord::ReadOnlyRecord:
+If you assign this record to a variable +client+, calling the following code will raise an +ActiveRecord::ReadOnlyRecord+ exception:
 
 [source, ruby]
 -------------------------------------------------------
@@ -310,11 +316,11 @@ end
 
 == Making It All Work Together
 
-You can chain these options together in no particular order as Active Record will write the correct SQL for you. If you specify two instances of the same options inside the find statement ActiveRecord will use the latter.
+You can chain these options together in no particular order as Active Record will write the correct SQL for you. If you specify two instances of the same options inside the find statement Active Record will use the latter.
 
 == Eager Loading
 
-Eager loading is loading associated records along with any number of records in as few queries as possible. For example, if you wanted to load all the addresses associated with all the clients in a single query you could use +Client.all(:include => :address)+. If you wanted to include both the address and mailing address for the client you would use +Client.find(:all), :include => [:address, :mailing_address]). Include will first find the client records and then load the associated address records. Running script/server in one window, and executing the code through script/console in another window, the output should look similar to this:
+Eager loading is loading associated records along with any number of records in as few queries as possible. For example, if you wanted to load all the addresses associated with all the clients in a single query you could use +Client.all(:include => :address)+. If you wanted to include both the address and mailing address for the client you would use +Client.find(:all, :include => [:address, :mailing_address]). Include will first find the client records and then load the associated address records. Running script/server in one window, and executing the code through script/console in another window, the output should look similar to this:
 
 [source, sql]
 -------------------------------------------------------
@@ -386,11 +392,11 @@ If you'd like to use your own SQL to find records a table you can use +find_by_s
 Client.find_by_sql("SELECT * FROM clients INNER JOIN orders ON clients.id = orders.client_id ORDER clients.created_at desc")
 -------------------------------------------------------
 
-+find_by_sql+ provides you with a simple way of making custom calls to the database and retreiving instantiated objects.
++find_by_sql+ provides you with a simple way of making custom calls to the database and retrieving instantiated objects.
 
 == +select_all+ ==
 
-+find_by_sql+ has a close relative called +select_all+. +select_all+ will retreive objects from the database using custom SQL just like +find_by_sql+ but will not instantiate them. Instead, you will get an array of hashes where each hash indicates a record.
++find_by_sql+ has a close relative called +connection#select_all+. +select_all+ will retrieve objects from the database using custom SQL just like +find_by_sql+ but will not instantiate them. Instead, you will get an array of hashes where each hash indicates a record.
 
 [source, ruby]
 -------------------------------------------------------
@@ -399,11 +405,15 @@ Client.connection.select_all("SELECT * FROM `clients` WHERE `id` = '1'")
 
 == Working with Associations
 
-When you define a has_many association on a model you get the find method and dynamic finders also on that association. This is helpful for finding associated records within the scope of an exisiting record, for example finding all the orders for a client that have been sent and not received by doing something like +Client.find(params[:id]).orders.find_by_sent_and_received(true, false)+. Having this find method available on associations is extremely helpful when using nested controllers. 
+When you define a has_many association on a model you get the find method and dynamic finders also on that association. This is helpful for finding associated records within the scope of an existing record, for example finding all the orders for a client that have been sent and not received by doing something like +Client.find(params[:id]).orders.find_by_sent_and_received(true, false)+. Having this find method available on associations is extremely helpful when using nested controllers. 
 
 == Named Scopes
 
-Named scopes are another way to add custom finding behavior to the models in the application. Suppose want to find all clients who are male. Yould use this code:
+Named scopes are another way to add custom finding behavior to the models in the application. Named scopes provide an object-oriented way to narrow the results of a query.
+
+=== Simple Named Scopes
+
+Suppose want to find all clients who are male. You could use this code:
 
 [source, ruby]
 -------------------------------------------------------
@@ -412,7 +422,7 @@ class Client < ActiveRecord::Base
 end
 -------------------------------------------------------
 
-And you could call it like +Client.males.all+ to get all the clients who are male. Please note that if you do not specify the +all+ on the end you will get a +Scope+ object back, not a set of records which you do get back if you put the +all+ on the end.
+Then you could call +Client.males.all+ to get all the clients who are male. Please note that if you do not specify the +all+ on the end you will get a +Scope+ object back, not a set of records which you do get back if you put the +all+ on the end.
 
 If you wanted to find all the clients who are active, you could use this:
 
@@ -423,7 +433,9 @@ class Client < ActiveRecord::Base
 end
 -------------------------------------------------------
 
-You can call this new named_scope by doing +Client.active.all+ and this will do the same query as if we just used +Client.all(:conditions => ["active = ?", true])+. Please be aware that the conditions syntax in named_scope and find is different and the two are not interchangeable. If you want to find the first client within this named scope you could do +Client.active.first+. 
+You can call this new named_scope with +Client.active.all+ and this will do the same query as if we just used +Client.all(:conditions => ["active = ?", true])+. Please be aware that the conditions syntax in named_scope and find is different and the two are not interchangeable. If you want to find the first client within this named scope you could do +Client.active.first+. 
+
+=== Combining Named Scopes
 
 If you wanted to find all the clients who are active and male you can stack the named scopes like this:
 
@@ -439,6 +451,8 @@ If you would then like to do a +all+ on that scope, you can. Just like an associ
 Client.males.active.all(:conditions => ["age > ?", params[:age]])
 -------------------------------------------------------
 
+=== Runtime Evaluation of Named Scope Conditions
+
 Consider the following code:
 
 [source, ruby]
@@ -459,6 +473,8 @@ end
 
 And now every time the recent named scope is called, the code in the lambda block will be parsed, so you'll get actually 2 weeks ago from the code execution, not 2 weeks ago from the time the model was loaded.
 
+=== Named Scopes with Multiple Models
+
 In a named scope you can use +:include+ and +:joins+ options just like in find.
 
 [source, ruby]
@@ -471,6 +487,8 @@ end
 
 This method, called as +Client.active_within_2_weeks.all+, will return all clients who have placed orders in the past 2 weeks.
 
+=== Arguments to Named Scopes
+
 If you want to pass a named scope a compulsory argument, just specify it as a block parameter like this:
 
 [source, ruby]
@@ -493,7 +511,9 @@ This will work with +Client.recent(2.weeks.ago).all+ and +Client.recent.all+, wi
 
 Remember that named scopes are stackable, so you will be able to do +Client.recent(2.weeks.ago).unlocked.all+ to find all clients created between right now and 2 weeks ago and have their locked field set to false.
 
-Finally, if you wish to define named scopes on the fly you can use the scoped method:
+=== Anonymous Scopes
+
+All Active Record models come with a named scope named +scoped+, which allows you to create anonymous scopes. For example:
 
 [source, ruby]
 -------------------------------------------------------
@@ -504,6 +524,15 @@ class Client < ActiveRecord::Base
 end
 -------------------------------------------------------
 
+Anonymous scopes are most useful to create scopes "on the fly":
+
+[source, ruby]
+-------------------------------------------------------
+Client.scoped(:conditions => { :gender => "male" })
+-------------------------------------------------------
+
+Just like named scopes, anonymous scopes can be stacked, either with other anonymous scopes or with regular named scopes.
+
 == Existence of Objects
 
 If you simply want to check for the existence of the object there's a method called +exists?+. This method will query the database using the same query as find, but instead of returning an object or collection of objects it will return either true or false.
@@ -513,7 +542,7 @@ If you simply want to check for the existence of the object there's a method cal
 Client.exists?(1)
 -------------------------------------------------------
 
-The above code will check for the existance of a clients table record with the id of 1 and return true if it exists.
+The above code will check for the existence of a clients table record with the id of 1 and return true if it exists.
 
 [source, ruby]
 -------------------------------------------------------
@@ -630,8 +659,9 @@ Thanks to Mike Gunderloy for his tips on creating this guide.
 
 http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/16[Lighthouse ticket]
 
-* October 27, 2008: Added scoped section, added named params for conditions and added sub-section headers for conditions section.
-* October 27, 2008: Fixed up all points specified in http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/16-activerecord-finders#ticket-16-6[this comment] with an exception of the final point.
+* November 8, 2008: Editing pass by link:../authors.html#mgunderloy[Mike Gunderloy] . First release version.
+* October 27, 2008: Added scoped section, added named params for conditions and added sub-section headers for conditions section by Ryan Bigg
+* October 27, 2008: Fixed up all points specified in http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/16-activerecord-finders#ticket-16-6[this comment] with an exception of the final point by Ryan Bigg
 * October 26, 2008: Editing pass by link:../authors.html#mgunderloy[Mike Gunderloy] . First release version.
 * October 22, 2008: Calculations complete, first complete draft by Ryan Bigg
 * October 21, 2008: Extended named scope section by Ryan Bigg