railties 3.0.0.beta4 → 3.0.0.rc

data/guides/source/{activerecord_validations_callbacks.textile → active_record_validations_callbacks.textile}

@@ -1,22 +1,22 @@
 h2. Active Record Validations and Callbacks
 
-This guide teaches you how to hook into the lifecycle of your Active Record objects. You will learn how to validate the state of objects before they go into the database, and how to perform custom operations at certain points in the object lifecycle.
+This guide teaches you how to hook into the life cycle of your Active Record objects. You will learn how to validate the state of objects before they go into the database, and how to perform custom operations at certain points in the object life cycle.
 
 After reading this guide and trying out the presented concepts, we hope that you'll be able to:
 
-* Understand the lifecycle of Active Record objects
+* Understand the life cycle of Active Record objects
 * Use the built-in Active Record validation helpers
 * Create your own custom validation methods
 * Work with the error messages generated by the validation process
-* Create callback methods that respond to events in the object lifecycle
+* Create callback methods that respond to events in the object life cycle
 * Create special classes that encapsulate common behavior for your callbacks
-* Create Observers that respond to lifecycle events outside of the original class
+* Create Observers that respond to life cycle events outside of the original class
 
 endprologue.
 
-h3. The Object Lifecycle
+h3. The Object Life Cycle
 
-During the normal operation of a Rails application objects may be created, updated, and destroyed. Active Record provides hooks into this <em>object lifecycle</em> so that you can control your application and its data. 
+During the normal operation of a Rails application, objects may be created, updated, and destroyed. Active Record provides hooks into this <em>object life cycle</em> so that you can control your application and its data. 
 
 Validations allow you to ensure that only valid data is stored in your database. Callbacks and observers allow you to trigger logic before or after an alteration of an object's state.
 
@@ -57,7 +57,7 @@ We can see how it works by looking at some +rails console+ output:
 => false
 </shell>
 
-Creating and saving a new record will send an SQL +INSERT+ operation to the database. Updating an existing record will send an SQL +UPDATE+ operation instead. Validations are typically run before these commands are sent to the database. If any validations fail, the object will be marked as invalid and Active Record will not perform the +INSERT+ or +UPDATE+ operation. This helps to avoid storing an invalid object in the database. You can choose to have specific validations run when an object is created, saved, or updated.
+Creating and saving a new record will send a SQL +INSERT+ operation to the database. Updating an existing record will send a SQL +UPDATE+ operation instead. Validations are typically run before these commands are sent to the database. If any validations fail, the object will be marked as invalid and Active Record will not perform the +INSERT+ or +UPDATE+ operation. This helps to avoid storing an invalid object in the database. You can choose to have specific validations run when an object is created, saved, or updated.
 
 CAUTION: There are many ways to change the state of an object in the database. Some methods will trigger validations, but some will not. This means that it's possible to save an object in the database in an invalid state if you aren't careful.
 
@@ -71,7 +71,7 @@ The following methods trigger validations, and will save the object to the datab
 * +update_attributes+
 * +update_attributes!+
 
-The bang versions (e.g. +save!+) raise an exception if the record is invalid. The non-bang versions don't: +save+ and +update_attributes+ return +false+, +create+ and +update+ just return the object/s.
+The bang versions (e.g. +save!+) raise an exception if the record is invalid. The non-bang versions don't: +save+ and +update_attributes+ return +false+, +create+ and +update+ just return the objects.
 
 h4. Skipping Validations
 
@@ -86,9 +86,9 @@ The following methods skip validations, and will save the object to the database
 * +update_attribute+
 * +update_counters+
 
-Note that +save+ also has the ability to skip validations if passed +false+ as argument. This technique should be used with caution.
+Note that +save+ also has the ability to skip validations if passed +:validate => false+ as argument. This technique should be used with caution.
 
-* +save(false)+
+* +save(:validate => false)+
 
 h4. +valid?+ and +invalid?+
 
@@ -240,9 +240,9 @@ class Account < ActiveRecord::Base
 end
 </ruby>
 
-The +validates_exclusion_of+ helper has an option +:in+ that receives the set of values that will not be accepted for the validated attributes. The +:in+ option has an alias called +:within+  that you can use for the same purpose, if you'd like to. This example uses the +:message+ option to show how you can include the attribute's value.
+The +validates_exclusion_of+ helper has an option +:in+ that receives the set of values that will not be accepted for the validated attributes. The +:in+ option has an alias called +:within+ that you can use for the same purpose, if you'd like to. This example uses the +:message+ option to show how you can include the attribute's value.
 
-The default error message for +validates_exclusion_of+  is "_is reserved_".
+The default error message for +validates_exclusion_of+ is "_is reserved_".
 
 h4. +validates_format_of+
 
@@ -270,7 +270,7 @@ end
 
 The +validates_inclusion_of+ helper has an option +:in+ that receives the set of values that will be accepted. The +:in+ option has an alias called +:within+ that you can use for the same purpose, if you'd like to. The previous example uses the +:message+ option to show how you can include the attribute's value.
 
-The default error message for +validates_inclusion_of+  is "_is not included in the list_".
+The default error message for +validates_inclusion_of+ is "_is not included in the list_".
 
 h4. +validates_length_of+
 
@@ -343,7 +343,7 @@ Besides +:only_integer+, the +validates_numericality_of+ helper also accepts the
 * +:greater_than_or_equal_to+ - Specifies the value must be greater than or equal to the supplied value. The default error message for this option is "_must be greater than or equal to %{count}_".
 * +:equal_to+ - Specifies the value must be equal to the supplied value. The default error message for this option is "_must be equal to %{count}_".
 * +:less_than+ - Specifies the value must be less than the supplied value. The default error message for this option is "_must be less than %{count}_".
-* +:less_than_or_equal_to+ - Specifies the value must be less than or equal the supplied value. The default error message for this option is "_must be less or equal to %{count}_".
+* +:less_than_or_equal_to+ - Specifies the value must be less than or equal the supplied value. The default error message for this option is "_must be less than or equal to %{count}_".
 * +:odd+ - Specifies the value must be an odd number if set to true. The default error message for this option is "_must be odd_".
 * +:even+ - Specifies the value must be an even number if set to true. The default error message for this option is "_must be even_".
 
@@ -374,7 +374,7 @@ The default error message for +validates_presence_of+ is "_can't be empty_".
 
 h4. +validates_uniqueness_of+
 
-This helper validates that the attribute's value is unique right before the object gets saved. It does not create a uniqueness constraint in the database, so it may happen that two different database connections create two records with the same value for a column that you intend to be unique. To avoid that, you must create an unique index in your database.
+This helper validates that the attribute's value is unique right before the object gets saved. It does not create a uniqueness constraint in the database, so it may happen that two different database connections create two records with the same value for a column that you intend to be unique. To avoid that, you must create a unique index in your database.
 
 <ruby>
 class Account < ActiveRecord::Base
@@ -423,14 +423,14 @@ class GoodnessValidator < ActiveRecord::Validator
 end
 </ruby>
 
-The +validates_with+ helper takes a class, or a list of classes to use for validation.  There is no default error message for +validates_with+.  You must manually add errors to the record's errors collection in the validator class.
+The +validates_with+ helper takes a class, or a list of classes to use for validation. There is no default error message for +validates_with+. You must manually add errors to the record's errors collection in the validator class.
 
 The validator class has two attributes by default:
 
 * +record+ - the record to be validated
 * +options+ - the extra options that were passed to +validates_with+
 
-Like all other validations, +validates_with+ takes the +:if+, +:unless+ and +:on+ options.  If you pass any other options, it will send those options to the validator class as +options+:
+Like all other validations, +validates_with+ takes the +:if+, +:unless+ and +:on+ options. If you pass any other options, it will send those options to the validator class as +options+:
 
 <ruby>
 class Person < ActiveRecord::Base
@@ -494,7 +494,7 @@ As you've already seen, the +:message+ option lets you specify the message that
 
 h4. +:on+
 
-The +:on+ option lets you specify when the validation should happen. The default behavior for all the built-in validation helpers is to be ran on save (both when you're creating a new record and when you're updating it). If you want to change it, you can use +:on => :create+ to run the validation only when a new record is created or +:on => :update+ to run the validation only when a record is updated.
+The +:on+ option lets you specify when the validation should happen. The default behavior for all the built-in validation helpers is to be run on save (both when you're creating a new record and when you're updating it). If you want to change it, you can use +:on => :create+ to run the validation only when a new record is created or +:on => :update+ to run the validation only when a record is updated.
 
 <ruby>
 class Person < ActiveRecord::Base
@@ -573,7 +573,7 @@ class Invoice < ActiveRecord::Base
 end
 </ruby>
 
-You can even create your own validation helpers and reuse them in several different models. For example, an application that manages surveys may find useful to express that a certain field corresponds to a set of choices:
+You can even create your own validation helpers and reuse them in several different models. For example, an application that manages surveys may find it useful to express that a certain field corresponds to a set of choices:
 
 <ruby>
 ActiveRecord::Base.class_eval do
@@ -599,7 +599,7 @@ The following is a list of the most commonly used methods. Please refer to the +
 
 h4(#working_with_validation_errors-errors). +errors+
 
-Returns an OrderedHash with all errors. Each key is the attribute name and value is an array of strings with all errors.
+Returns an OrderedHash with all errors. Each key is the attribute name and the value is an array of strings with all errors.
 
 <ruby>
 class Person < ActiveRecord::Base
@@ -619,7 +619,7 @@ person.errors # => []
 
 h4(#working_with_validation_errors-errors-2). +errors[]+
 
-+errors[]+ is used when you want to check the error messages for a specific attribute. It returns an array of strings with all error messages for the given attribute, each string with one error message. If there are no errors related to the attribute returns an empty array.
++errors[]+ is used when you want to check the error messages for a specific attribute. It returns an array of strings with all error messages for the given attribute, each string with one error message. If there are no errors related to the attribute, it returns an empty array.
 
 <ruby>
 class Person < ActiveRecord::Base
@@ -681,7 +681,7 @@ Another way to do this is using +[]=+ setter
 
 h4. +errors[:base]+
 
-You can add errors messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since +errors[:base]+ is an array, you can simply add a string to the array and uses it as the error message.
+You can add error messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since +errors[:base]+ is an array, you can simply add a string to the array and uses it as the error message.
 
 <ruby>
 class Person < ActiveRecord::Base
@@ -789,7 +789,7 @@ Both the +form.error_messages+ and the +error_messages_for+ helpers accept optio
   :header_tag => :h3 %>
 </erb>
 
-Which results in the following content
+Which results in the following content:
 
 !images/customized_error_messages.png(Customized error messages)!
 
@@ -799,7 +799,7 @@ h4. Customizing the Error Messages CSS
 
 The selectors to customize the style of error messages are:
 
-* +.fieldWithErrors+ - Style for the form fields and labels with errors.
+* +.field_with_errors+ - Style for the form fields and labels with errors.
 * +#errorExplanation+ - Style for the +div+ element with the error messages.
 * +#errorExplanation h2+ - Style for the header of the +div+ element.
 * +#errorExplanation p+ - Style for the paragraph that holds the message that appears right below the header of the +div+ element.
@@ -811,7 +811,7 @@ The name of the class and the id can be changed with the +:class+ and +:id+ opti
 
 h4. Customizing the Error Messages HTML
 
-By default, form fields with errors are displayed enclosed by a +div+ element with the +fieldWithErrors+ CSS class. However, it's possible to override that. 
+By default, form fields with errors are displayed enclosed by a +div+ element with the +field_with_errors+ CSS class. However, it's possible to override that. 
 
 The way form fields with errors are treated is defined by +ActionView::Base.field_error_proc+. This is a +Proc+ that receives two parameters:
 
@@ -838,7 +838,7 @@ This will result in something like the following:
 
 h3. Callbacks Overview
 
-Callbacks are methods that get called at certain moments of an object's lifecycle. With callbacks it's possible to write code that will run whenever an Active Record object is created, saved, updated, deleted, validated, or loaded from the database.
+Callbacks are methods that get called at certain moments of an object's life cycle. With callbacks it's possible to write code that will run whenever an Active Record object is created, saved, updated, deleted, validated, or loaded from the database.
 
 h4. Callback Registration
 
@@ -984,7 +984,7 @@ h3. Halting Execution
 
 As you start registering new callbacks for your models, they will be queued for execution. This queue will include all your model's validations, the registered callbacks, and the database operation to be executed. 
 
-The whole callback chain is wrapped in a transaction. If any before callback method returns exactly +false+ or raises an exception the execution chain gets halted and a ROLLBACK is issued. After callbacks can only accomplish that by raising an exception.
+The whole callback chain is wrapped in a transaction. If any <em>before</em> callback method returns exactly +false+ or raises an exception the execution chain gets halted and a ROLLBACK is issued; <em>after</em> callbacks can only accomplish that by raising an exception.
 
 WARNING. Raising an arbitrary exception may break code that expects +save+ and friends not to fail like that. The +ActiveRecord::Rollback+ exception is thought precisely to tell Active Record a rollback is going on. That one is internally captured but not reraised.
 
@@ -1020,7 +1020,7 @@ Like in validations, we can also make our callbacks conditional, calling them on
 
 h4. Using +:if+ and +:unless+ with a Symbol
 
-You can associate the +:if+ and +:unless+ options with a symbol corresponding to the name of a method that will get called right before the callback. If this method returns +false+ the callback won't be executed. This is the most common option. Using this form of registration it's also possible to register several different methods that should be called to check if the callback should be executed.
+You can associate the +:if+ and +:unless+ options with a symbol corresponding to the name of a method that will get called right before the callback. When using the +:if+ option, the callback won't be executed if the method returns false; when using the +:unless+ option, the callback won't be executed if the method returns true. This is the most common option. Using this form of registration it's also possible to register several different methods that should be called to check if the callback should be executed.
 
 <ruby>
 class Order < ActiveRecord::Base
@@ -1135,7 +1135,7 @@ Observers are conventionally placed inside of your +app/models+ directory and re
 config.active_record.observers = :user_observer
 </ruby>
 
-As usual, settings in +config/environments+ take precedence over those in +config/environment.rb+. So, if you prefer that an observer not run in all environments, you can simply register it in a specific environment instead.
+As usual, settings in +config/environments+ take precedence over those in +config/environment.rb+. So, if you prefer that an observer doesn't run in all environments, you can simply register it in a specific environment instead.
 
 h4. Sharing Observers
 
@@ -1162,6 +1162,7 @@ h3. Changelog
 
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213/tickets/26-active-record-validations-and-callbacks
 
+* July 20, 2010: Fixed typos and rephrased some paragraphs for clarity. "Jaime Iniesta":http://jaimeiniesta.com
 * May 24, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
 * May 15, 2010: Validation Errors section updated by "Emili Parreño":http://www.eparreno.com
 * March 7, 2009: Callbacks revision by Trevor Turk

data/guides/source/active_support_core_extensions.textile

@@ -24,7 +24,7 @@ h5. Cherry-picking a Definition
 
 The most lightweight way to get +blank?+ is to cherry-pick the file that defines it.
 
-For every single method defined as a core extension this guide has a note that says where is such a method defined. In the case of +blank?+ the note reads:
+For every single method defined as a core extension this guide has a note that says where such a method is defined. In the case of +blank?+ the note reads:
 
 NOTE: Defined in +active_support/core_ext/object/blank.rb+.
 
@@ -124,7 +124,7 @@ NOTE: Defined in +active_support/core_ext/object/blank.rb+.
 
 h4. +duplicable?+
 
-A few fundamental objects in Ruby are singletons. For example, in the whole live of a program the integer 1 refers always to the same instance:
+A few fundamental objects in Ruby are singletons. For example, in the whole life of a program the integer 1 refers always to the same instance:
 
 <ruby>
 1.object_id                 # => 3
@@ -157,21 +157,6 @@ WARNING. Using +duplicable?+ is discouraged because it depends on a hard-coded l
 
 NOTE: Defined in +active_support/core_ext/object/duplicable.rb+.
 
-h4. +returning+
-
-The method +returning+ yields its argument to a block and returns it. You tipically use it with a mutable object that gets modified in the block:
-
-<ruby>
-def html_options_for_form(url_for_options, options, *parameters_for_url)
-  returning options.stringify_keys do |html_options|
-    html_options["enctype"] = "multipart/form-data" if html_options.delete("multipart")
-    html_options["action"]  = url_for(url_for_options, *parameters_for_url)
-  end
-end
-</ruby>
-
-NOTE: Defined in +active_support/core_ext/object/returning.rb+.
-
 h4. +try+
 
 Sometimes you want to call a method provided the receiver object is not +nil+, which is something you usually check first.
@@ -187,7 +172,7 @@ def log_info(sql, name, ms)
 end
 </ruby>
 
-You can shorten that using +Object#try+. This method is a synonim for +Object#send+ except that it returns +nil+ if sent to +nil+. The previous example could then be rewritten as:
+You can shorten that using +Object#try+. This method is a synonym for +Object#send+ except that it returns +nil+ if sent to +nil+. The previous example could then be rewritten as:
 
 <ruby>
 def log_info(sql, name, ms)
@@ -209,8 +194,7 @@ String.singleton_class     # => #<Class:String>
 String.new.singleton_class # => #<Class:#<String:0x17a1d1c>>
 </ruby>
 
-WARNING: Fixnums and symbols have no singleton classes, +singleton_class+
-raises +TypeError+ on them. Moreover, the singleton classes of +nil+, +true+, and +false+, are +NilClass+, +TrueClass+, and +FalseClass+, respectively.
+WARNING: Fixnums and symbols have no singleton classes, +singleton_class+ raises +TypeError+ on them. Moreover, the singleton classes of +nil+, +true+, and +false+, are +NilClass+, +TrueClass+, and +FalseClass+, respectively.
 
 NOTE: Defined in +active_support/core_ext/kernel/singleton_class.rb+.
 
@@ -256,7 +240,7 @@ NOTE: Defined in +active_support/core_ext/object/acts_like.rb+.
 
 h4. +to_param+
 
-All objects in Rails respond to the method +to_param+, which is meant to return something that represents them as values in a query string, or as a URL fragments.
+All objects in Rails respond to the method +to_param+, which is meant to return something that represents them as values in a query string, or as URL fragments.
 
 By default +to_param+ just calls +to_s+:
 
@@ -294,7 +278,7 @@ we get:
 user_path(@user) # => "/users/357-john-smith"
 </ruby>
 
-WARNING. Controllers need to be aware of any redifinition of +to_param+ because when a request like that comes in "357-john-smith" is the value of +params[:id]+.
+WARNING. Controllers need to be aware of any redefinition of +to_param+ because when a request like that comes in "357-john-smith" is the value of +params[:id]+.
 
 NOTE: Defined in +active_support/core_ext/object/to_param.rb+.
 
@@ -332,7 +316,7 @@ Arrays return the result of applying +to_query+ to each element with <tt>_key_[]
 # => "sample%5B%5D=3.4&sample%5B%5D=-45.6"
 </ruby>
 
-Hashes also respond to +to_query+ but with a different signature. If no argument is passed a call generates a sorted series of key/value assigments calling +to_query(key)+ on its values. Then it joins the result with "&":
+Hashes also respond to +to_query+ but with a different signature. If no argument is passed a call generates a sorted series of key/value assignments calling +to_query(key)+ on its values. Then it joins the result with "&":
 
 <ruby>
 {:c => 3, :b => 2, :a => 1}.to_query # => "a=1&b=2&c=3"
@@ -388,40 +372,6 @@ TIP: Since +with_options+ forwards calls to its receiver they can be nested. Eac
 
 NOTE: Defined in +active_support/core_ext/object/with_options.rb+.
 
-h5. +subclasses_of+
-
-The method +subclasses_of+ receives an arbitrary number of class objects and returns all their anonymous or reachable descendants as a single array:
-
-<ruby>
-class C; end
-subclasses_of(C) # => []
-
-subclasses_of(Integer) # => [Bignum, Fixnum]
-
-module M
-  class A; end
-  class B1 < A; end
-  class B2 < A; end
-end
-
-module N
-  class C < M::B1; end
-end
-
-subclasses_of(M::A) # => [N::C, M::B2, M::B1]
-</ruby>
-
-The order in which these classes are returned is unspecified. The returned collection may have duplicates:
-
-<ruby>
-subclasses_of(Numeric, Integer)
-# => [Bignum, Float, Fixnum, Integer, Date::Infinity, Rational, BigDecimal, Bignum, Fixnum]
-</ruby>
-
-See also +Class#subclasses+ in "Extensions to +Class+ FIX THIS LINK":FIXME.
-
-NOTE: Defined in +active_support/core_ext/object/extending.rb+.
-
 h4. Instance Variables
 
 Active Support provides several methods to ease access to instance variables.
@@ -656,9 +606,9 @@ h5. Internal Attributes
 
 When you are defining an attribute in a class that is meant to be subclassed name collisions are a risk. That's remarkably important for libraries.
 
-Active Support defines the macros +attr_internal_reader+, +attr_internal_writer+, and +attr_internal_accessor+. They behave like their Ruby builtin +attr_*+ counterparts, except they name the unerlying instace variable in a way that makes collisions less likely.
+Active Support defines the macros +attr_internal_reader+, +attr_internal_writer+, and +attr_internal_accessor+. They behave like their Ruby builtin +attr_*+ counterparts, except they name the underlying instance variable in a way that makes collisions less likely.
 
-The macro +attr_internal+ is a synonim for +attr_internal_accessor+:
+The macro +attr_internal+ is a synonym for +attr_internal_accessor+:
 
 <ruby>
 # library
@@ -721,7 +671,7 @@ h4. Method Delegation
 
 The class method +delegate+ offers an easy way to forward methods.
 
-For example, if +User+ has some details like the age factored out to +Profile+, it could be handy to still be able to acces such attribute directly, <tt>user.age</tt>, instead of having to explicit the chain <tt>user.profile.age</tt>.
+For example, if +User+ has some details like the age factored out to +Profile+, it could be handy to still be able to access such attributes directly, <tt>user.age</tt>, instead of having to explicit the chain <tt>user.profile.age</tt>.
 
 That can be accomplished by hand:
 
@@ -816,6 +766,28 @@ end
 
 This may come in handy if you need to define a method that may already exist, since redefining a method issues a warning "method redefined; discarding old redefined_method_name".
 
+h5. +redefine_method(method_name, &block)+
+
+The method first removes method with given name (using +remove_possible_method+) and then defines new one.
+
+<ruby>
+class A; end
+
+A.class_eval do
+  redefine_method(:foobar) do |foo|
+    #do something here
+  end
+  
+  #Code above does the same as this:
+  
+  method_name = :foobar
+  remove_possible_method(method_name)
+  define_method(method_name) do |foo|
+    #do something here
+  end
+end
+</ruby>
+
 NOTE: Defined in +active_support/core_ext/module/remove_method.rb+.
 
 h4. Parents
@@ -935,7 +907,7 @@ NOTE: Defined in +active_support/core_ext/module/synchronization.rb+.
 
 h4. Reachable
 
-A named module is reachable if it is stored in its correspoding constant. It means you can reach the module object via the constant.
+A named module is reachable if it is stored in its corresponding constant. It means you can reach the module object via the constant.
 
 That is what ordinarily happens, if a module is called "M", the +M+ constant exists and holds it:
 
@@ -1016,7 +988,9 @@ h3. Extensions to +Class+
 
 h4. Class Attributes
 
-The method +Class#class_attribute+ declares one or more inheritable class attributes that can be overriden at any level down the hierarchy:
+h5. +class_attribute+
+
+The method +class_attribute+ declares one or more inheritable class attributes that can be overridden at any level down the hierarchy:
 
 <ruby>
 class A
@@ -1040,17 +1014,50 @@ A.x # => :a
 B.x # => :b
 </ruby>
 
-For example that's the way the +allow_forgery_protection+ flag is implemented for controllers:
+For example +ActionMailer::Base+ defines:
 
 <ruby>
-class_attribute :allow_forgery_protection
-self.allow_forgery_protection = true
+class_attribute :default_params
+self.default_params = {
+  :mime_version => "1.0",
+  :charset      => "UTF-8",
+  :content_type => "text/plain",
+  :parts_order  => [ "text/plain", "text/enriched", "text/html" ]
+}.freeze
 </ruby>
 
-For convenience +class_attribute+ defines also a predicate, so that declaration also generates +allow_forgery_protection?+. Such predicate returns the double boolean negation of the value.
+They can be also accessed and overridden at the instance level:
+
+<ruby>
+A.x = 1
+
+a1 = A.new
+a2 = A.new
+a2.x = 2
+
+a1.x # => 1, comes from A
+a2.x # => 2, overridden in a2
+</ruby>
+
+The generation of the writer instance method can be prevented by setting the option +:instance_writer+ to false, as in
+
+<ruby>
+module AcitveRecord
+  class Base
+    class_attribute :table_name_prefix, :instance_writer => false
+    self.table_name_prefix = ""
+  end
+end
+</ruby>
+
+A model may find that option useful as a way to prevent mass-assignment from setting the attribute.
+
+For convenience +class_attribute+ defines also an instance predicate which is the double negation of what the instance reader returns. In the examples above it would be called +x?+.
 
 NOTE: Defined in +active_support/core_ext/class/attribute.rb+
 
+h5. +cattr_reader+, +cattr_writer+, and +cattr_accessor+
+
 The macros +cattr_reader+, +cattr_writer+, and +cattr_accessor+ are analogous to their +attr_*+ counterparts but for classes. They initialize a class variable to +nil+ unless it already exists, and generate the corresponding class methods to access it:
 
 <ruby>
@@ -1061,17 +1068,18 @@ class MysqlAdapter < AbstractAdapter
 end
 </ruby>
 
-Instance methods are created as well for convenience. For example given
+Instance methods are created as well for convenience, they are just proxies to the class attribute. So, instances can change the class attribute, but cannot override it as it happens with +class_attribute+ (see above). For example given
 
 <ruby>
-module ActionController
+module ActionView
   class Base
-    cattr_accessor :logger
+    cattr_accessor :field_error_proc
+    @@field_error_proc = Proc.new{ ... }
   end
 end
 </ruby>
 
-we can access +logger+ in actions. The generation of the writer instance method can be prevented setting +:instance_writer+ to +false+ (not any false value, but exactly +false+):
+we can access +field_error_proc+ in views. The generation of the writer instance method can be prevented by setting +:instance_writer+ to +false+ (not any false value, but exactly +false+):
 
 <ruby>
 module ActiveRecord
@@ -1082,13 +1090,13 @@ module ActiveRecord
 end
 </ruby>
 
-A model may find that option useful as a way to prevent mass-assignment from setting the attribute. 
+A model may find that option useful as a way to prevent mass-assignment from setting the attribute.
 
 NOTE: Defined in +active_support/core_ext/class/attribute_accessors.rb+.
 
 h4. Class Inheritable Attributes
 
-Class variables are shared down the inheritance tree. Class instance variables are not shared, but they are not inherited either. The macros +class_inheritable_reader+, +class_inheritable_writer+, and +class_inheritable_accessor+ provide accesors for class-level data which is inherited but not shared with children:
+Class variables are shared down the inheritance tree. Class instance variables are not shared, but they are not inherited either. The macros +class_inheritable_reader+, +class_inheritable_writer+, and +class_inheritable_accessor+ provide accessors for class-level data which is inherited but not shared with children:
 
 <ruby>
 module ActionController
@@ -1142,36 +1150,51 @@ If for whatever reason an application loads the definition of a mailer class and
 
 NOTE: Defined in +active_support/core_ext/class/delegating_attributes.rb+.
 
-h4. Descendants
+h4. Subclasses & Descendants
 
 h5. +subclasses+
 
-The +subclasses+ method returns the names of all the anonymous or reachable descendants of its receiver as an array of strings:
+The +subclasses+ method returns the subclasses of the receiver:
 
 <ruby>
 class C; end
 C.subclasses # => []
 
-Integer.subclasses # => ["Bignum", "Fixnum"]
-
-module M
-  class A; end
-  class B1 < A; end
-  class B2 < A; end
-end
+class B < C; end
+C.subclasses # => [B]
 
-module N
-  class C < M::B1; end
-end
+class A < B; end
+C.subclasses # => [B]
 
-M::A.subclasses # => ["N::C", "M::B2", "M::B1"]
+class D < C; end
+C.subclasses # => [B, D]
 </ruby>
 
-The order in which these class names are returned is unspecified.
+The order in which these classes are returned is unspecified.
+
+WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1.
+
+NOTE: Defined in +active_support/core_ext/class/subclasses.rb+.
+
+h5. +descendants+
+
+The +descendants+ method returns all classes that are <tt>&lt;</tt> than its receiver: 
+
+<ruby>
+class C; end
+C.descendants # => []
+
+class B < C; end
+C.descendants # => [B]
 
-See also +Object#subclasses_of+ in "Extensions to All Objects FIX THIS LINK":FIXME.
+class A < B; end
+C.descendants # => [B, A]
+
+class D < C; end
+C.descendants # => [B, A, D]
+</ruby>
 
-WARNING: This method is redefined in some Rails core classes.
+The order in which these classes are returned is unspecified.
 
 NOTE: Defined in +active_support/core_ext/class/subclasses.rb+.
 
@@ -1204,7 +1227,7 @@ s.html_safe? # => true
 s            # => "<script>...</script>"
 </ruby>
 
-It is your responsability to ensure calling +html_safe+ on a particular string is fine.
+It is your responsibility to ensure calling +html_safe+ on a particular string is fine.
 
 NOTE: For performance reasons safe strings are implemented in a way that cannot offer an in-place +html_safe!+ variant.
 
@@ -1377,7 +1400,7 @@ The method +pluralize+ returns the plural of its receiver:
 "equipment".pluralize # => "equipment"
 </ruby>
 
-As the previous example shows, Active Support knows some irregular plurals and uncountable nouns. Builtin rules can be extended in +config/initializers/inflections.rb+. That file is generated by the +rails+ command and has instructions in comments.
+As the previous example shows, Active Support knows some irregular plurals and uncountable nouns. Built-in rules can be extended in +config/initializers/inflections.rb+. That file is generated by the +rails+ command and has instructions in comments.
 
 Active Record uses this method to compute the default table name that corresponds to a model:
 
@@ -1453,13 +1476,15 @@ end
 
 That may be handy to compute method names in a language that follows that convention, for example JavaScript.
 
+INFO: As a rule of thumb you can think of +camelize+ as the inverse of +underscore+, though there are cases where that does not hold: <tt>"SSLError".underscore.camelize</tt> gives back <tt>"SslError"</tt>.
+
 +camelize+ is aliased to +camelcase+.
 
 NOTE: Defined in +active_support/core_ext/string/inflections.rb+.
 
 h5. +underscore+
 
-The method +underscore+ is the inverse of +camelize+, explained above:
+The method +underscore+ goes the other way around, from camel case to paths:
 
 <ruby>
 "Product".underscore   # => "product"
@@ -1492,6 +1517,8 @@ def load_missing_constant(from_mod, const_name)
 end
 </ruby>
 
+INFO: As a rule of thumb you can think of +underscore+ as the inverse of +camelize+, though there are cases where that does not hold. For example, <tt>"SSLError".underscore.camelize</tt> gives back <tt>"SslError"</tt>.
+
 NOTE: Defined in +active_support/core_ext/string/inflections.rb+.
 
 h5. +titleize+
@@ -1697,6 +1724,90 @@ foreign_key = options[:foreign_key] || reflection.active_record.name.foreign_key
 
 NOTE: Defined in +active_support/core_ext/string/inflections.rb+.
 
+h4. Conversions
+
+h5. +constantize+
+
+The method +constantize+ expects the receiver to contain the name of a constant, and tries to get you the object stored in there, assuming it is defined:
+
+<ruby>
+"ActiveRecord::Base".constantize # => ActiveRecord::Base
+</ruby>
+
+The name is assumed to be top-level, no matter whether it starts with "::" or not. No lexical context is taken into account:
+
+<ruby>
+C = 1
+module M
+  C = 2
+  "C".constantize # => 1, same as "::C".constantize
+end
+</ruby>
+
+NOTE: Defined in +active_support/core_ext/string/conversions.rb+.
+
+h5. +ord+
+
+Ruby 1.9 defines +ord+ to be the codepoint of the first character of the receiver. Active Support backports +ord+ for single-byte encondings like ASCII or ISO-8859-1 in Ruby 1.8:
+
+<ruby>
+"a".ord # => 97
+"à".ord # => 224, in ISO-8859-1
+</ruby>
+
+In Ruby 1.8 +ord+ doesn't work in general in UTF8 strings, use the multibyte support in Active Support for that:
+
+<ruby>
+"a".mb_chars.ord # => 97
+"à".mb_chars.ord # => 224, in UTF8
+</ruby>
+
+Note that the 224 is different in both examples. In ISO-8859-1 "à" is represented as a single byte, 224. Its single-character representattion in UTF8 has two bytes, namely 195 and 160, but its Unicode codepoint is 224. If we call +ord+ on the UTF8 string "à" the return value will be 195 in Ruby 1.8. That is not an error, because UTF8 is unsupported, the call itself would be bogus.
+
+INFO: +ord+ is equivalent to +getbyte(0)+.
+
+NOTE: Defined in +active_support/core_ext/string/conversions.rb+.
+
+h5. +getbyte+
+
+Active Support backports +getbyte+ from Ruby 1.9:
+
+<ruby>
+"foo".getbyte(0)  # => 102, same as "foo".ord
+"foo".getbyte(1)  # => 111
+"foo".getbyte(9)  # => nil
+"foo".getbyte(-1) # => 111
+</ruby>
+
+INFO: +getbyte+ is equivalent to +[]+.
+
+NOTE: Defined in +active_support/core_ext/string/conversions.rb+.
+
+h5. +to_date+, +to_time+, +to_datetime+
+
+The methods +to_date+, +to_time+, and +to_datetime+ are basically convenience wrappers around +Date._parse+:
+
+<ruby>
+"2010-07-27".to_date              # => Tue, 27 Jul 2010
+"2010-07-27 23:37:00".to_time     # => Tue Jul 27 23:37:00 UTC 2010
+"2010-07-27 23:37:00".to_datetime # => Tue, 27 Jul 2010 23:37:00 +0000 
+</ruby>
+
++to_time+ receives an optional argument +:utc+ or +:local+, to indicate which time zone you want the time in:
+
+<ruby>
+"2010-07-27 23:42:00".to_time(:utc)   # => Tue Jul 27 23:42:00 UTC 2010
+"2010-07-27 23:42:00".to_time(:local) # => Tue Jul 27 23:42:00 +0200 2010
+</ruby>
+
+Default is +:utc+.
+
+Please refer to the documentation of +Date._parse+ for further details.
+
+INFO: The three of them return +nil+ for blank receivers.
+
+NOTE: Defined in +active_support/core_ext/string/conversions.rb+.
+
 h3. Extensions to +Numeric+
 
 h4. Bytes
@@ -1760,7 +1871,7 @@ h3. Extensions to +Float+
 
 h4. +round+
 
-The builtin method +Float#round+ rounds a float to the nearest integer. Active Support adds an optional parameter to let you specify a precision:
+The built-in method +Float#round+ rounds a float to the nearest integer. Active Support adds an optional parameter to let you specify a precision:
 
 <ruby>
 Math::E.round(4) # => 2.7183
@@ -1776,9 +1887,7 @@ h3. Extensions to +Enumerable+
 
 h4. +group_by+
 
-Ruby 1.8.7 and up define +group_by+, and Active Support does it for previous versions.
-
-This iterator takes a block and builds an ordered hash with its return values as keys. Each key is mapped to the array of elements for which the block returned that value:
+Active Support redefines +group_by+ in Ruby 1.8.7 so that it returns an ordered hash as in 1.9:
 
 <ruby>
 entries_by_surname_initial = address_book.group_by do |entry|
@@ -1786,7 +1895,7 @@ entries_by_surname_initial = address_book.group_by do |entry|
 end
 </ruby>
 
-WARNING. Active Support redefines +group_by+ in Ruby 1.8.7 so that it still returns an ordered hash.
+Distinct block return values are added to the hash as they come, so that's the resulting order.
 
 NOTE: Defined in +active_support/core_ext/enumerable.rb+.
 
@@ -1925,7 +2034,7 @@ Similarly, +from+ returns the tail from the element at the passed index on:
 [].from(0)           # => []
 </ruby>
 
-The methods +second+, +third+, +fourth+, and +fifth+ return the corresponding element (+first+ is builtin). Thanks to social wisdom and positive constructiveness all around, +forty_two+ is also available.
+The methods +second+, +third+, +fourth+, and +fifth+ return the corresponding element (+first+ is built-in). Thanks to social wisdom and positive constructiveness all around, +forty_two+ is also available.
 
 NOTE: Defined in +active_support/core_ext/array/access.rb+.
 
@@ -2120,7 +2229,7 @@ NOTE: Defined in +active_support/core_ext/array/conversions.rb+.
 
 h4. Wrapping
 
-The class method +Array.wrap+ behaves like the function +Array()+ except that it does not try to call +to_a+ on its argument. That changes the behaviour for enumerables:
+The class method +Array.wrap+ behaves like the function +Array()+ except that it does not try to call +to_a+ on its argument. That changes the behavior for enumerables:
 
 <ruby>
 Array.wrap(:foo => :bar) # => [{:foo => :bar}]
@@ -2282,7 +2391,7 @@ NOTE: Defined in +active_support/core_ext/hash/conversions.rb+.
 
 h4. Merging
 
-Ruby has a builtin method +Hash#merge+ that merges two hashes:
+Ruby has a built-in method +Hash#merge+ that merges two hashes:
 
 <ruby>
 {:a => 1, :b => 1}.merge(:a => 0, :c => 2)
@@ -2511,7 +2620,7 @@ NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
 
 h4. Slicing
 
-Ruby has builtin support for taking slices out of strings and arrays. Active Support extends slicing to hashes:
+Ruby has built-in support for taking slices out of strings and arrays. Active Support extends slicing to hashes:
 
 <ruby>
 {:a => 1, :b => 2, :c => 3}.slice(:a, :c)
@@ -2625,7 +2734,7 @@ Active Support extends this method so that the argument may be another range in
 (1...9).include?(3..9)  # => false
 </ruby>
 
-WARNING: The orginal +Range#include?+ is still the one aliased to +Range#===+.
+WARNING: The original +Range#include?+ is still the one aliased to +Range#===+.
 
 NOTE: Defined in +active_support/core_ext/range/include_range.rb+.
 
@@ -2885,11 +2994,9 @@ Date.new(2010, 1, 31).change(:month => 2)
 # => ArgumentError: invalid date
 </ruby>
 
-h5. Named Times
-
-WARNING: The following methods do not take into account the user time zone. They return timestamps in localtime.
+h5. Timestamps
 
-INFO: The following methods return a +Time+ object if possible, otherwise a +DateTime+.
+INFO: The following methods return a +Time+ object if possible, otherwise a +DateTime+. If set, they honor the user time zone.
 
 h6. +beginning_of_day+, +end_of_day+
 
@@ -2907,7 +3014,25 @@ date = Date.new(2010, 6, 7)
 date.end_of_day # => Sun Jun 06 23:59:59 +0200 2010
 </ruby>
 
-+beginning_of_day+ is aliased to +at_beginning_of_day+, +midnight+, +at_midnight+
++beginning_of_day+ is aliased to +at_beginning_of_day+, +midnight+, +at_midnight+.
+
+h6. +ago+, +since+
+
+The method +ago+ receives a number of seconds as argument and returns a timestamp those many seconds ago from midnight:
+
+<ruby>
+date = Date.current # => Fri, 11 Jun 2010 
+date.ago(1)         # => Thu, 10 Jun 2010 23:59:59 EDT -04:00
+</ruby>
+
+Similarly, +since+ moves forward:
+
+<ruby>
+date = Date.current # => Fri, 11 Jun 2010 
+date.since(1)       # => Fri, 11 Jun 2010 00:00:01 EDT -04:00
+</ruby>
+
+h5. Other Time Computations
 
 h4(#date-conversions). Conversions
 
@@ -3064,7 +3189,7 @@ Active Support adds +missing_name?+ to +NameError+, which tests whether the exce
 
 The name may be given as a symbol or string. A symbol is tested against the bare constant name, a string is against the fully-qualified constant name.
 
-TIP: A symbol can represent a fully-qualified constant name as in +:"ActiveRecord::Base"+, so the behaviour for symbols is defined for convenience, not because it has to be that way technically.
+TIP: A symbol can represent a fully-qualified constant name as in +:"ActiveRecord::Base"+, so the behavior for symbols is defined for convenience, not because it has to be that way technically.
 
 For example, when an action of +PostsController+ is called Rails tries optimistically to use +PostsHelper+. It is OK that the helper module does not exist, so if an exception for that constant name is raised it should be silenced. But it could be the case that +posts_helper.rb+ raises a +NameError+ due to an actual unknown constant. That should be reraised. The method +missing_name?+ provides a way to distinguish both cases: