railties 3.0.0.rc → 3.0.0.rc2

data/guides/source/active_record_basics.textile

@@ -16,7 +16,7 @@ Active Record is the M in "MVC":getting_started.html#the-mvc-architecture - the
 
 h4. The Active Record Pattern
 
-Active Record was described by Martin Fowler in his book _Patterns of Enterprise Application Architecture_. In Active Record, objects carry both persistent data and behavior which operates on that data. Active Record takes the opinion that ensuring data access logic is part of the object will educate users of that object on how to write to and read from the database. 
+Active Record was described by Martin Fowler in his book _Patterns of Enterprise Application Architecture_. In Active Record, objects carry both persistent data and behavior which operates on that data. Active Record takes the opinion that ensuring data access logic is part of the object will educate users of that object on how to write to and read from the database.
 
 h4. Object Relational Mapping
 
@@ -132,7 +132,7 @@ CRUD is an acronym for the four verbs we use to operate on data: *C*reate, *R*ea
 
 h4. Create
 
-Active Record objects can be created from a hash, a block or have its attributes manually set after creation. The _new_ method will return a new object while _create_ will return the object and save it to the database. 
+Active Record objects can be created from a hash, a block or have its attributes manually set after creation. The _new_ method will return a new object while _create_ will return the object and save it to the database.
 
 For example, given a model +User+ with attributes of +name+ and +occupation+, the _create_ method call will create and save a new record into the database:
 

data/guides/source/active_record_querying.textile

@@ -153,7 +153,7 @@ SELECT * FROM clients WHERE (clients.id IN (1,10))
 
 h4. Retrieving Multiple Objects in Batches
 
-Sometimes you need to iterate over a large set of records. For example to send a newsletter to all users, to export some data, etc. 
+Sometimes you need to iterate over a large set of records. For example to send a newsletter to all users, to export some data, etc.
 
 The following may seem very straight forward at first:
 
@@ -674,7 +674,7 @@ Post.joins(:category, :comments)
 This produces:
 
 <sql>
-SELECT posts.* FROM posts 
+SELECT posts.* FROM posts
   INNER JOIN categories ON posts.category_id = categories.id
   INNER JOIN comments ON comments.post_id = posts.id
 </sql>
@@ -753,7 +753,7 @@ h4. Eager Loading Multiple Associations
 
 Active Record lets you eager load any number of associations with a single +Model.find+ call by using an array, hash, or a nested hash of array/hash with the +includes+ method.
 
-h5. Array of Multiple Associations 
+h5. Array of Multiple Associations
 
 <ruby>
 Post.includes(:category, :comments)
@@ -764,14 +764,14 @@ This loads all the posts and the associated category and comments for each post.
 h5. Nested Associations Hash
 
 <ruby>
-Category.find(1).includes(:posts => [{:comments => :guest}, :tags])
+Category.includes(:posts => [{:comments => :guest}, :tags]).find(1)
 </ruby>
 
 This will find the category with id 1 and eager load all of the associated posts, the associated posts' tags and comments, and every comment's guest association.
 
 h4. Specifying Conditions on Eager Loaded Associations
 
-Even though Active Record lets you specify conditions on the eager loaded associations just like +joins+, the recommended way is to use "joins":#joining-tables instead. 
+Even though Active Record lets you specify conditions on the eager loaded associations just like +joins+, the recommended way is to use "joins":#joining-tables instead.
 
 h3. Dynamic Finders
 
@@ -807,8 +807,8 @@ h3. Finding by SQL
 If you'd like to use your own SQL to find records in a table you can use +find_by_sql+. The +find_by_sql+ method will return an array of objects even if the underlying query returns just a single record. For example you could run this query:
 
 <ruby>
-Client.find_by_sql("SELECT * FROM clients 
-  INNER JOIN orders ON clients.id = orders.client_id 
+Client.find_by_sql("SELECT * FROM clients
+  INNER JOIN orders ON clients.id = orders.client_id
   ORDER clients.created_at desc")
 </ruby>
 

data/guides/source/active_record_validations_callbacks.textile

@@ -16,7 +16,7 @@ endprologue.
 
 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 life cycle</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.
 
@@ -33,7 +33,7 @@ There are several ways to validate data before it is saved into your database, i
 * Database constraints and/or stored procedures make the validation mechanisms database-dependent and can make testing and maintenance more difficult. However, if your database is used by other applications, it may be a good idea to use some constraints at the database level. Additionally, database-level validations can safely handle some things (such as uniqueness in heavily-used tables) that can be difficult to implement otherwise.
 * Client-side validations can be useful, but are generally unreliable if used alone. If they are implemented using JavaScript, they may be bypassed if JavaScript is turned off in the user's browser. However, if combined with other techniques, client-side validation can be a convenient way to provide users with immediate feedback as they use your site.
 * Controller-level validations can be tempting to use, but often become unwieldy and difficult to test and maintain. Whenever possible, it's a good idea to "keep your controllers skinny":http://weblog.jamisbuck.org/2006/10/18/skinny-controller-fat-model, as it will make your application a pleasure to work with in the long run.
-* Model-level validations are the best way to ensure that only valid data is saved into your database. They are database agnostic, cannot be bypassed by end users, and are convenient to test and maintain. Rails makes them easy to use, provides built-in helpers for common needs, and allows you to create your own validation methods as well. 
+* Model-level validations are the best way to ensure that only valid data is saved into your database. They are database agnostic, cannot be bypassed by end users, and are convenient to test and maintain. Rails makes them easy to use, provides built-in helpers for common needs, and allows you to create your own validation methods as well.
 
 h4. When Does Validation Happen?
 
@@ -116,7 +116,7 @@ end
 => #<Person id: nil, name: nil>
 >> p.errors
 => {}
-  
+
 >> p.valid?
 => false
 >> p.errors
@@ -126,7 +126,7 @@ end
 => #<Person id: nil, name: nil>
 >> p.errors
 => {:name=>["can't be blank"]}
-  
+
 >> p.save
 => false
 
@@ -368,7 +368,7 @@ class LineItem < ActiveRecord::Base
 end
 </ruby>
 
-Since +false.blank?+ is true, if you want to validate the presence of a boolean field you should use +validates_inclusion_of :field_name, :in => [true, false]+. 
+Since +false.blank?+ is true, if you want to validate the presence of a boolean field you should use +validates_inclusion_of :field_name, :in => [true, false]+.
 
 The default error message for +validates_presence_of+ is "_can't be empty_".
 
@@ -550,9 +550,9 @@ end
 
 h3. Creating Custom Validation Methods
 
-When the built-in validation helpers are not enough for your needs, you can write your own validation methods. 
+When the built-in validation helpers are not enough for your needs, you can write your own validation methods.
 
-Simply create methods that verify the state of your models and add messages to the +errors+ collection when they are invalid. You must then register these methods by using one or more of the +validate+, +validate_on_create+ or +validate_on_update+ class methods, passing in the symbols for the validation methods' names. 
+Simply create methods that verify the state of your models and add messages to the +errors+ collection when they are invalid. You must then register these methods by using one or more of the +validate+, +validate_on_create+ or +validate_on_update+ class methods, passing in the symbols for the validation methods' names.
 
 You can pass more than one symbol for each class method and the respective validations will be run in the same order as they were registered.
 
@@ -593,7 +593,7 @@ end
 
 h3. Working with Validation Errors
 
-In addition to the +valid?+ and +invalid?+ methods covered earlier, Rails provides a number of methods for working with the +errors+ collection and inquiring about the validity of objects. 
+In addition to the +valid?+ and +invalid?+ methods covered earlier, Rails provides a number of methods for working with the +errors+ collection and inquiring about the validity of objects.
 
 The following is a list of the most commonly used methods. Please refer to the +ActiveRecord::Errors+ documentation for a list of all the available methods.
 
@@ -611,7 +611,7 @@ person = Person.new
 person.valid? # => false
 person.errors
  # => {:name => ["can't be blank", "is too short (minimum is 3 characters)"]}
- 
+
 person = Person.new(:name => "John Doe")
 person.valid? # => true
 person.errors # => []
@@ -660,7 +660,7 @@ person.errors[:name]
 person.errors.full_messages
  # => ["Name cannot contain the characters !@#%*()_-+="]
 </ruby>
-  
+
 Another way to do this is using +[]=+ setter
 
 <ruby>
@@ -739,7 +739,7 @@ person.errors.size # => 0
 
 h3. Displaying Validation Errors in the View
 
-Rails provides built-in helpers to display the error messages of your models in your view templates. 
+Rails provides built-in helpers to display the error messages of your models in your view templates.
 
 h4. +error_messages+ and +error_messages_for+
 
@@ -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 +field_with_errors+ 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:
 
@@ -865,7 +865,7 @@ The macro-style class methods can also receive a block. Consider using this styl
 class User < ActiveRecord::Base
   validates_presence_of :login, :email
 
-  before_create {|user| user.name = user.login.capitalize 
+  before_create {|user| user.name = user.login.capitalize
 	if user.name.blank?}
 end
 </ruby>
@@ -967,7 +967,7 @@ The +after_initialize+ callback is triggered every time a new object of the clas
 
 h3. Skipping Callbacks
 
-Just as with validations, it's also possible to skip callbacks. These methods should be used with caution, however, because important business rules and application logic may be kept in callbacks. Bypassing them without understanding the potential implications may lead to invalid data. 
+Just as with validations, it's also possible to skip callbacks. These methods should be used with caution, however, because important business rules and application logic may be kept in callbacks. Bypassing them without understanding the potential implications may lead to invalid data.
 
 * +decrement+
 * +decrement_counter+
@@ -982,7 +982,7 @@ Just as with validations, it's also possible to skip callbacks. These methods sh
 
 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. 
+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 <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.
 
@@ -990,11 +990,11 @@ WARNING. Raising an arbitrary exception may break code that expects +save+ and f
 
 h3. Relational Callbacks
 
-Callbacks work through model relationships, and can even be defined by them. Let's take an example where a user has many posts. In our example, a user's posts should be destroyed if the user is destroyed. So, we'll add an +after_destroy+ callback to the +User+ model by way of its relationship to the +Post+ model. 
+Callbacks work through model relationships, and can even be defined by them. Let's take an example where a user has many posts. In our example, a user's posts should be destroyed if the user is destroyed. So, we'll add an +after_destroy+ callback to the +User+ model by way of its relationship to the +Post+ model.
 
 <ruby>
 class User < ActiveRecord::Base
-  has_many :posts, :dependent => :destroy    
+  has_many :posts, :dependent => :destroy
 end
 
 class Post < ActiveRecord::Base
@@ -1069,7 +1069,7 @@ Here's an example where we create a class with an +after_destroy+ callback for a
 <ruby>
 class PictureFileCallbacks
   def after_destroy(picture_file)
-    File.delete(picture_file.filepath) 
+    File.delete(picture_file.filepath)
       if File.exists?(picture_file.filepath)
   end
 end
@@ -1088,7 +1088,7 @@ Note that we needed to instantiate a new +PictureFileCallbacks+ object, since we
 <ruby>
 class PictureFileCallbacks
   def self.after_destroy(picture_file)
-    File.delete(picture_file.filepath) 
+    File.delete(picture_file.filepath)
       if File.exists?(picture_file.filepath)
   end
 end
@@ -1144,7 +1144,7 @@ By default, Rails will simply strip "Observer" from an observer's name to find t
 <ruby>
 class MailerObserver < ActiveRecord::Observer
   observe :registration, :user
-  
+
   def after_create(model)
     # code to send confirmation email...
   end

data/guides/source/active_support_core_extensions.textile

@@ -1,8 +1,10 @@
 h2. Active Support Core Extensions
 
-Active Support is the Rails component responsible for providing Ruby language extensions, utilities, and other transversal stuff. It offers a richer bottom-line at the language level, targeted both at the development of Rails applications, and at the development of Rails itself.
+Active Support is the Ruby on Rails component responsible for providing Ruby language extensions, utilities, and other transversal stuff.
 
-By referring to this guide you will learn the extensions to the Ruby core classes and modules provided by Rails.
+It offers a richer bottom-line at the language level, targeted both at the development of Rails applications, and at the development of Ruby on Rails itself.
+
+By referring to this guide you will learn the extensions to the Ruby core classes and modules provided by Active Support.
 
 endprologue.
 
@@ -84,32 +86,25 @@ The following values are considered to be blank in a Rails application:
 
 WARNING: Note that numbers are not mentioned, in particular 0 and 0.0 are *not* blank.
 
-For example, this method from +ActionDispatch::Response+ uses +blank?+ to easily be robust to +nil+ and whitespace strings in one shot:
+For example, this method from +ActionDispatch::Session::AbstractStore+ uses +blank?+ for checking whether a session key is present:
 
 <ruby>
-def charset
-  charset = String(headers["Content-Type"] || headers["type"]).split(";")[1]
-  charset.blank? ? nil : charset.strip.split("=")[1]
+def ensure_session_key!
+  if @key.blank?
+    raise ArgumentError, 'A key is required...'
+  end
 end
 </ruby>
 
-That's a typical use case for +blank?+.
-
-Here, the method Rails runs to instantiate observers upon initialization has nothing to do if there are none:
+The method +present?+ is equivalent to +!blank?+. This example is taken from +ActionDispatch::Http::Cache::Response+:
 
 <ruby>
-def instantiate_observers
-  return if @observers.blank?
-  # ...
+def set_conditional_cache_control!
+  return if self["Cache-Control"].present?
+  ...
 end
 </ruby>
 
-The method +present?+ is equivalent to +!blank?+:
-
-<ruby>
-assert @response.body.present? # same as !@response.body.blank?
-</ruby>
-
 NOTE: Defined in +active_support/core_ext/object/blank.rb+.
 
 h4. +presence+
@@ -151,28 +146,17 @@ Active Support provides +duplicable?+ to programmatically query an object about
 false.duplicable?  # => false
 </ruby>
 
-By definition all objects are +duplicable?+ except +nil+, +false+, +true+, symbols, numbers, and class objects.
+By definition all objects are +duplicable?+ except +nil+, +false+, +true+, symbols, numbers, and class and module objects.
 
-WARNING. Using +duplicable?+ is discouraged because it depends on a hard-coded list. Classes have means to disallow duplication like removing +dup+ and +clone+ or raising exceptions from them, only +rescue+ can tell.
+WARNING. Any class can disallow duplication removing +dup+ and +clone+ or raising exceptions from them, only +rescue+ can tell whether a given arbitrary object is duplicable. +duplicable?+ depends on the hard-coded list above, but it is much faster than +rescue+. Use it only if you know the hard-coded list is enough in your use case.
 
 NOTE: Defined in +active_support/core_ext/object/duplicable.rb+.
 
 h4. +try+
 
-Sometimes you want to call a method provided the receiver object is not +nil+, which is something you usually check first.
-
-For instance, note how this method of +ActiveRecord::ConnectionAdapters::AbstractAdapter+ checks if there's a +@logger+:
+Sometimes you want to call a method provided the receiver object is not +nil+, which is something you usually check first. +try+ is like +Object#send+ except that it returns +nil+ if sent to +nil+.
 
-<ruby>
-def log_info(sql, name, ms)
-  if @logger && @logger.debug?
-    name = '%s (%.1fms)' % [name || 'SQL', ms]
-    @logger.debug(format_log_entry(name, sql.squeeze(' ')))
-  end
-end
-</ruby>
-
-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:
+For instance, in this code from +ActiveRecord::ConnectionAdapters::AbstractAdapter+ +@logger+ could be +nil+, but you save the check and write in an optimistic style:
 
 <ruby>
 def log_info(sql, name, ms)
@@ -364,7 +348,7 @@ That idiom may convey _grouping_ to the reader as well. For example, say you wan
 <ruby>
 I18n.with_options :locale => user.locale, :scope => "newsletter" do |i18n|
   subject i18n.t :subject
-  body    i18n.t :body, :user_name => user.name 
+  body    i18n.t :body, :user_name => user.name
 end
 </ruby>
 
@@ -667,129 +651,6 @@ end
 
 NOTE: Defined in +active_support/core_ext/module/attribute_accessors.rb+.
 
-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 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:
-
-<ruby>
-class User
-  has_one :profile
-
-  def age
-    profile.age
-  end
-end
-</ruby>
-
-But with +delegate+ you can make that shorter and the intention even more obvious:
-
-<ruby>
-class User
-  has_one :profile
-
-  delegate :age, to => :profile
-end
-</ruby>
-
-The macro accepts more than one method:
-
-<ruby>
-class User
-  has_one :profile
-
-  delegate :age, :avatar, :twitter_username, to => :profile
-end
-</ruby>
-
-Methods can be delegated to objects returned by methods, as in the examples above, but also to instance variables, class variables, and constants. Just pass their names as symbols or strings, including the at signs in the last cases.
-
-For example, +ActionView::Base+ delegates +erb_trim_mode=+:
-
-<ruby>
-module ActionView
-  class Base
-    delegate :erb_trim_mode=, :to => 'ActionView::Template::Handlers::ERB'
-  end
-end
-</ruby>
-
-In fact, you can delegate to any expression passed as a string. It will be evaluated in the context of the receiver. Controllers for example delegate alerts and notices to the current flash:
-
-<ruby>
-delegate :alert, :notice, :to => "request.flash"
-</ruby>
-
-If the target is +nil+ calling any delegated method will raise an exception even if +nil+ responds to such method. You can override this behavior setting the option +:allow_nil+ to true, in which case the forwarded call will simply return +nil+.
-
-If the target is a method, the name of delegated methods can also be prefixed. If the +:prefix+ option is set to (exactly) the +true+ object, the value of the +:to+ option is prefixed:
-
-<ruby>
-class Invoice
-  belongs_to :customer
-
-  # defines a method called customer_name
-  delegate :name, :to => :customer, :prefix => true
-end
-</ruby>
-
-And a custom prefix can be set as well, in that case it does not matter wheter the target is a method or not:
-
-<ruby>
-class Account
-  belongs_to :user
-
-  # defines a method called admin_email
-  delegate :email, :to => :user, :prefix => 'admin'
-end
-</ruby>
-
-NOTE: Defined in +active_support/core_ext/module/delegation.rb+.
-
-h4. Method Removal
-
-h5. +remove_possible_method+
-
-The method +remove_possible_method+ is like the standard +remove_method+, except it silently returns on failure:
-
-<ruby>
-class A; end
-
-A.class_eval do
-  remove_method(:nonexistent)          # raises NameError
-  remove_possible_method(:nonexistent) # no problem, continue
-end
-</ruby>
-
-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
 
 h5. +parent+
@@ -901,7 +762,7 @@ class Counter
 end
 </ruby>
 
-The method receives the name of an action, and a +:with+ option with code. The code is evaluated in the context of the receiver each time the method is invoked, and it should evaluate to a +Mutex+ instance or any other object that responds to +synchronize+ and accepts a block. 
+The method receives the name of an action, and a +:with+ option with code. The code is evaluated in the context of the receiver each time the method is invoked, and it should evaluate to a +Mutex+ instance or any other object that responds to +synchronize+ and accepts a block.
 
 NOTE: Defined in +active_support/core_ext/module/synchronization.rb+.
 
@@ -984,6 +845,121 @@ though an anonymous module is unreachable by definition.
 
 NOTE: Defined in +active_support/core_ext/module/anonymous.rb+.
 
+h4. Method Delegation
+
+The macro +delegate+ offers an easy way to forward methods.
+
+Let's imagine that users in some application have login information in the +User+ model but name and other data in a separate +Profile+ model:
+
+<ruby>
+class User < ActiveRecord::Base
+  has_one :profile
+end
+</ruby>
+
+With that configuration you get a user's name via his profile, +user.profile.name+, but it could be handy to still be able to access such attribute directly:
+
+<ruby>
+class User < ActiveRecord::Base
+  has_one :profile
+
+  def name
+    profile.name
+  end
+end
+</ruby>
+
+That is what +delegate+ does for you:
+
+<ruby>
+class User < ActiveRecord::Base
+  has_one :profile
+
+  delegate :name, :to => :profile
+end
+</ruby>
+
+It is shorter, and the intention more obvious.
+
+The macro accepts several methods:
+
+<ruby>
+delegate :name, :age, :address, :twitter, :to => :profile
+</ruby>
+
+When interpolated into a string, the +:to+ option should become an expression that evaluates to the object the method is delegated to. Typically a string or symbol. Such a expression is evaluated in the context of the receiver:
+
+<ruby>
+# delegates to the Rails constant
+delegate :logger, :to => :Rails
+
+# delegates to the receiver's class
+delegate :table_name, :to => 'self.class'
+</ruby>
+
+WARNING: If the +:prefix+ option is +true+ this is less generic, see below.
+
+By default, if the delegation raises +NoMethodError+ and the target is +nil+ the exception is propagated. You can ask that +nil+ is returned instead with the +:allow_nil+ option:
+
+<ruby>
+delegate :name, :to => :profile, :allow_nil => true
+</ruby>
+
+With +:allow_nil+ the call +user.name+ returns +nil+ if the user has no profile.
+
+The option +:prefix+ adds a prefix to the name of the generated method. This may be handy for example to get a better name:
+
+<ruby>
+delegate :street, :to => :address, :prefix => true
+</ruby>
+
+The previous example generates +address_street+ rather than +street+.
+
+WARNING: Since in this case the name of the generated method is composed of the target object and target method names, the +:to+ option must be a method name.
+
+A custom prefix may also be configured:
+
+<ruby>
+delegate :size, :to => :attachment, :prefix => :avatar
+</ruby>
+
+In the previous example the macro generates +avatar_size+ rather than +size+.
+
+NOTE: Defined in +active_support/core_ext/module/delegation.rb+
+
+h4. Method Names
+
+The builtin methods +instance_methods+ and +methods+ return method names as strings or symbols depending on the Ruby version. Active Support defines +instance_method_names+ and +method_names+ to be equivalent to them, respectively, but always getting strings back.
+
+For example, +ActionView::Helpers::FormBuilder+ knows this array difference is going to work no matter the Ruby version:
+
+<ruby>
+self.field_helpers = (FormHelper.instance_method_names - ['form_for'])
+</ruby>
+
+NOTE: Defined in +active_support/core_ext/module/method_names.rb+
+
+h4. Redefining Methods
+
+There are cases where you need to define a method with +define_method+, but don't know whether a method with that name already exists. If it does, a warning is issued if they are enabled. No big deal, but not clean either.
+
+The method +redefine_method+ prevents such a potential warning, removing the existing method before if needed. Rails uses it in a few places, for instance when it generates an association's API:
+
+<ruby>
+redefine_method("#{reflection.name}=") do |new_value|
+  association = association_instance_get(reflection.name)
+
+  if association.nil? || association.target != new_value
+    association = association_proxy_class.new(self, reflection)
+  end
+
+  association.replace(new_value)
+  association_instance_set(reflection.name, new_value.nil? ? nil : association)
+end
+</ruby>
+
+NOTE: Defined in +active_support/core_ext/module/remove_method.rb+
+
 h3. Extensions to +Class+
 
 h4. Class Attributes
@@ -1131,25 +1107,10 @@ module ActiveRecord
 end
 </ruby>
 
-Since values are copied when a subclass is defined, if the base class changes the attribute after that, the subclass does not see the new value. That's the point. 
+Since values are copied when a subclass is defined, if the base class changes the attribute after that, the subclass does not see the new value. That's the point.
 
 NOTE: Defined in +active_support/core_ext/class/inheritable_attributes.rb+.
 
-There's a related macro called +superclass_delegating_accessor+, however, that does not copy the value when the base class is subclassed. Instead, it delegates reading to the superclass as long as the attribute is not set via its own writer. For example, +ActionMailer::Base+ defines +delivery_method+ this way:
-
-<ruby>
-module ActionMailer
-  class Base
-    superclass_delegating_accessor :delivery_method
-    self.delivery_method = :smtp
-  end
-end
-</ruby>
-
-If for whatever reason an application loads the definition of a mailer class and after that sets +ActionMailer::Base.delivery_method+, the mailer class will still see the new value. In addition, the mailer class is able to change the +delivery_method+ without affecting the value in the parent using its own inherited class attribute writer.
-
-NOTE: Defined in +active_support/core_ext/class/delegating_attributes.rb+.
-
 h4. Subclasses & Descendants
 
 h5. +subclasses+
@@ -1178,7 +1139,7 @@ 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: 
+The +descendants+ method returns all classes that are <tt>&lt;</tt> than its receiver:
 
 <ruby>
 class C; end
@@ -1299,7 +1260,7 @@ Pass a +:separator+ to truncate the string at a natural break:
 
 <ruby>
 "Oh dear! Oh dear! I shall be late!".truncate(18)
-# => "Oh dear! Oh dea..." 
+# => "Oh dear! Oh dea..."
 "Oh dear! Oh dear! I shall be late!".truncate(18, :separator => ' ')
 # => "Oh dear! Oh..."
 </ruby>
@@ -1790,7 +1751,7 @@ The methods +to_date+, +to_time+, and +to_datetime+ are basically convenience wr
 <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 
+"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:
@@ -2229,7 +2190,27 @@ 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 behavior for enumerables:
+The method +Array.wrap+ wraps its argument in an array unless it is already an array (or array-like).
+
+Specifically:
+
+* If the argument is +nil+ an empty list is returned.
+* Otherwise, if the argument responds to +to_ary+ it is invoked, and its result returned.
+* Otherwise, returns an array with the argument as its single element.
+
+<ruby>
+Array.wrap(nil)       # => []
+Array.wrap([1, 2, 3]) # => [1, 2, 3]
+Array.wrap(0)         # => [0]
+</ruby>
+
+This method is similar in purpose to <tt>Kernel#Array</tt>, but there are some differences:
+
+* If the argument responds to +to_ary+ the method is invoked. <tt>Kernel#Array</tt> moves on to try +to_a+ if the returned value is +nil+, but <tt>Arraw.wrap</tt> returns such a +nil+ right away.
+* If the returned value from +to_ary+ is neither +nil+ nor an +Array+ object, <tt>Kernel#Array</tt> raises an exception, while <tt>Array.wrap</tt> does not, it just returns the value.
+* It does not call +to_a+ on the argument, though special-cases +nil+ to return an empty array.
+
+The last point is particularly worth comparing for some enumerables:
 
 <ruby>
 Array.wrap(:foo => :bar) # => [{:foo => :bar}]
@@ -2239,6 +2220,16 @@ Array.wrap("foo\nbar")   # => ["foo\nbar"]
 Array("foo\nbar")        # => ["foo\n", "bar"], in Ruby 1.8
 </ruby>
 
+There's also a related idiom that uses the splat operator:
+
+<ruby>
+[*object]
+</ruby>
+
+which returns +[nil]+ for +nil+, and calls to <tt>Array(object)</tt> otherwise
+
+Thus, in this case the behavior is different for +nil+, and the differences with <tt>Kernel#Array</tt> explained above apply to the rest of +object+s.
+
 NOTE: Defined in +active_support/core_ext/array/wrap.rb+.
 
 h4. Grouping
@@ -2964,11 +2955,11 @@ Note in the previous example that increments may be negative.
 
 To perform the computation the method first increments years, then months, then weeks, and finally days. This order is important towards the end of months. Say for example we are at the end of February of 2010, and we want to move one month and one day forward.
 
-The method +advance+ advances first one month, and the one day, the result is:
+The method +advance+ advances first one month, and then one day, the result is:
 
 <ruby>
-Date.new(2010, 2, 28).advance(:months => 1, :day => 1)
-# => Sun, 28 Mar 2010
+Date.new(2010, 2, 28).advance(:months => 1, :days => 1)
+# => Sun, 29 Mar 2010
 </ruby>
 
 While if it did it the other way around the result would be different:
@@ -2994,6 +2985,26 @@ Date.new(2010, 1, 31).change(:month => 2)
 # => ArgumentError: invalid date
 </ruby>
 
+h5. Durations
+
+Durations can be added and substracted to dates:
+
+<ruby>
+d = Date.current
+# => Mon, 09 Aug 2010
+d + 1.year
+# => Tue, 09 Aug 2011
+d - 3.hours
+# => Sun, 08 Aug 2010 21:00:00 UTC +00:00
+</ruby>
+
+They translate to calls to +since+ or +advance+. For example here we get the correct jump in the calendar reform:
+
+<ruby>
+Date.new(1582, 10, 4) + 1.day
+# => Fri, 15 Oct 1582
+</ruby>
+
 h5. Timestamps
 
 INFO: The following methods return a +Time+ object if possible, otherwise a +DateTime+. If set, they honor the user time zone.
@@ -3021,14 +3032,14 @@ 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 = 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 = Date.current # => Fri, 11 Jun 2010
 date.since(1)       # => Fri, 11 Jun 2010 00:00:01 EDT -04:00
 </ruby>
 
@@ -3038,30 +3049,30 @@ h4(#date-conversions). Conversions
 
 h3. Extensions to +DateTime+
 
-NOTE: All the following methods are defined in +active_support/core_ext/date_time/calculations.rb+.
-
 WARNING: +DateTime+ is not aware of DST rules and so some of these methods have edge cases when a DST change is going on. For example +seconds_since_midnight+ might not return the real amount in such a day.
 
 h4(#calculations-datetime). Calculations
 
+NOTE: All the following methods are defined in +active_support/core_ext/date_time/calculations.rb+.
+
 The class +DateTime+ is a subclass of +Date+ so by loading +active_support/core_ext/date/calculations.rb+ you inherit these methods and their aliases, except that they will always return datetimes:
 
 <ruby>
 yesterday
 tomorrow
-beginning_of_week
-end_on_week
+beginning_of_week (monday, at_beginning_of_week)
+end_on_week (at_end_of_week)
 next_week
 months_ago
 months_since
-beginning_of_month
-end_of_month
+beginning_of_month (at_beginning_of_month)
+end_of_month (at_end_of_month)
 prev_month
 next_month
-beginning_of_quarter
-end_of_quarter
-beginning_of_year
-end_of_year
+beginning_of_quarter (at_beginning_of_quarter)
+end_of_quarter (at_end_of_quarter)
+beginning_of_year (at_beginning_of_year)
+end_of_year (at_end_of_year)
 years_ago
 years_since
 prev_year
@@ -3071,10 +3082,10 @@ next_year
 The following methods are reimplemented so you do *not* need to load +active_support/core_ext/date/calculations.rb+ for these ones:
 
 <ruby>
-beginning_of_day
+beginning_of_day (midnight, at_midnight, at_beginning_of_day)
 end_of_day
 ago
-since
+since (in)
 </ruby>
 
 On the other hand, +advance+ and +change+ are also defined and support more options, they are documented below.
@@ -3117,6 +3128,37 @@ now.utc?           # => false
 now.utc.utc?       # => true
 </ruby>
 
+h6(#datetime-advance). +advance+
+
+The most generic way to jump to another datetime is +advance+. This method receives a hash with keys +:years+, +:months+, +:weeks+, +:days+, +:hours+, +:minutes+, and +:seconds+, and returns a datetime advanced as much as the present keys indicate.
+
+<ruby>
+d = DateTime.current
+# => Thu, 05 Aug 2010 11:33:31 +0000
+d.advance(:years => 1, :months => 1, :days => 1, :hours => 1, :minutes => 1, :seconds => 1)
+# => Tue, 06 Sep 2011 12:34:32 +0000
+</ruby>
+
+This method first computes the destination date passing +:years+, +:months+, +:weeks+, and +:days+ to +Date#advance+ documented above. After that, it adjusts the time calling +since+ with the number of seconds to advance. This order is relevant, a different ordering would give different datetimes in some edge-cases. The example in +Date#advance+ applies, and we can extend it to show order relevance related to the time bits.
+
+If we first move the date bits (that have also a relative order of processing, as documented before), and then the time bits we get for example the following computation:
+
+<ruby>
+d = DateTime.new(2010, 2, 28, 23, 59, 59)
+# => Sun, 28 Feb 2010 23:59:59 +0000
+d.advance(:months => 1, :seconds => 1)
+# => Mon, 29 Mar 2010 00:00:00 +0000
+</ruby>
+
+but if we computed them the other way around, the result would be different:
+
+<ruby>
+d.advance(:seconds => 1).advance(:months => 1)
+# => Thu, 01 Apr 2010 00:00:00 +0000
+</ruby>
+
+WARNING: Since +DateTime+ is not DST-aware you can end up in a non-existing point in time with no warning or error telling you so.
+
 h5(#datetime-changing-components). Changing Components
 
 The method +change+ allows you to get a new datetime which is the same as the receiver except for the given options, which may include +:year+, +:month+, +:day+, +:hour+, +:min+, +:sec+, +:offset+, +:start+:
@@ -3149,15 +3191,144 @@ DateTime.current.change(:month => 2, :day => 30)
 # => ArgumentError: invalid date
 </ruby>
 
-h4(#datetime-conversions). Conversions
+h5. Durations
+
+Durations can be added and substracted to datetimes:
+
+<ruby>
+now = DateTime.current
+# => Mon, 09 Aug 2010 23:15:17 +0000
+now + 1.year
+# => Tue, 09 Aug 2011 23:15:17 +0000
+now - 1.week
+# => Mon, 02 Aug 2010 23:15:17 +0000
+</ruby>
+
+They translate to calls to +since+ or +advance+. For example here we get the correct jump in the calendar reform:
+
+<ruby>
+DateTime.new(1582, 10, 4, 23) + 1.hour
+# => Fri, 15 Oct 1582 00:00:00 +0000
+</ruby>
 
 h3. Extensions to +Time+
 
-...
+h4(#time-calculations). Calculations
+
+NOTE: All the following methods are defined in +active_support/core_ext/date_time/calculations.rb+.
+
+Active Support adds to +Time+ many of the methods available for +DateTime+:
+
+<ruby>
+past?
+today?
+future?
+yesterday
+tomorrow
+seconds_since_midnight
+change
+advance
+ago
+since (in)
+beginning_of_day (midnight, at_midnight, at_beginning_of_day)
+end_of_day
+beginning_of_week (monday, at_beginning_of_week)
+end_on_week (at_end_of_week)
+next_week
+months_ago
+months_since
+beginning_of_month (at_beginning_of_month)
+end_of_month (at_end_of_month)
+prev_month
+next_month
+beginning_of_quarter (at_beginning_of_quarter)
+end_of_quarter (at_end_of_quarter)
+beginning_of_year (at_beginning_of_year)
+end_of_year (at_end_of_year)
+years_ago
+years_since
+prev_year
+next_year
+</ruby>
+
+They are analogous. Please refer to their documentation above and take into account the following differences:
+
+* +change+ accepts an additional +:usec+ option.
+* +Time+ understands DST, so you get correct DST calculations as in
+
+<ruby>
+Time.zone_default
+# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...>
+
+# In Barcelona, 2010/03/28 02:00 +0100 becomes 2010/03/28 03:00 +0200 due to DST.
+t = Time.local_time(2010, 3, 28, 1, 59, 59)
+# => Sun Mar 28 01:59:59 +0100 2010
+t.advance(:seconds => 1)
+# => Sun Mar 28 03:00:00 +0200 2010
+</ruby>
+
+* If +since+ or +ago+ jump to a time that can't be expressed with +Time+ a +DateTime+ object is returned instead.
+
+h4. Time Constructors
+
+Active Support defines +Time.current+ to be +Time.zone.now+ if there's a user time zone defined, with fallback to +Time.now+:
+
+<ruby>
+Time.zone_default
+# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...>
+Time.current
+# => Fri, 06 Aug 2010 17:11:58 CEST +02:00
+</ruby>
+
+Analogously to +DateTime+, the predicates +past?+, and +future?+ are relative to +Time.current+.
+
+Use the +local_time+ class method to create time objects honoring the user time zone:
+
+<ruby>
+Time.zone_default
+# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...>
+Time.local_time(2010, 8, 15)
+# => Sun Aug 15 00:00:00 +0200 2010
+</ruby>
+
+The +utc_time+ class method returns a time in UTC:
+
+<ruby>
+Time.zone_default
+# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...>
+Time.utc_time(2010, 8, 15)
+# => Sun Aug 15 00:00:00 UTC 2010
+</ruby>
+
+Both +local_time+ and +utc_time+ accept up to seven positional arguments: year, month, day, hour, min, sec, usec. Year is mandatory, month and day default to 1, and the rest default to 0.
+
+If the time to be constructed lies beyond the range supported by +Time+ in the runtime platform, usecs are discarded and a +DateTime+ object is returned instead.
+
+h5. Durations
+
+Durations can be added and substracted to time objects:
+
+<ruby>
+now = Time.current
+# => Mon, 09 Aug 2010 23:20:05 UTC +00:00
+now + 1.year
+#  => Tue, 09 Aug 2011 23:21:11 UTC +00:00
+now - 1.week
+# => Mon, 02 Aug 2010 23:21:11 UTC +00:00
+</ruby>
+
+They translate to calls to +since+ or +advance+. For example here we get the correct jump in the calendar reform:
+
+<ruby>
+Time.utc_time(1582, 10, 3) + 5.days
+# => Mon Oct 18 00:00:00 UTC 1582
+</ruby>
 
 h3. Extensions to +Process+
 
-...
+h4. +daemon+
+
+Ruby 1.9 provides +Process.daemon+, and Active Support defines it for previous versions. It accepts the same two arguments, whether it should chdir to the root directory (default, true), and whether it should inherit the standard file descriptors from the parent (default, false).
 
 h3. Extensions to +File+
 
@@ -3233,4 +3404,5 @@ h3. Changelog
 
 "Lighthouse ticket":https://rails.lighthouseapp.com/projects/16213/tickets/67
 
+* August 10, 2010: Starts to take shape, added to the index.
 * April 18, 2009: Initial version by "Xavier Noria":credits.html#fxn