railties 3.0.0.beta3 → 3.0.0.beta4

data/guides/source/action_controller_overview.textile

@@ -91,7 +91,7 @@ The +params+ hash is not limited to one-dimensional keys and values. It can cont
 GET /clients?ids[]=1&ids[]=2&ids[]=3
 </pre>
 
-NOTE: The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5b=3" as "[" and "]" are not allowed in URLs. Most of the time you don't have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind.
+NOTE: The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5d=3" as "[" and "]" are not allowed in URLs. Most of the time you don't have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind.
 
 The value of +params[:ids]+ will now be +["1", "2", "3"]+. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type.
 
@@ -653,7 +653,7 @@ class ClientsController < ApplicationController
   # Stream a file that has already been generated and stored on disk.
   def download_pdf
     client = Client.find(params[:id])
-    send_data("#{Rails.root}/files/clients/#{client.id}.pdf",
+    send_file("#{Rails.root}/files/clients/#{client.id}.pdf",
               :filename => "#{client.name}.pdf",
               :type => "application/pdf")
   end

data/guides/source/action_mailer_basics.textile

@@ -55,12 +55,12 @@ class UserMailer < ActionMailer::Base
 end
 </ruby>
 
-Here is a quick explanation of the items presented in the preceding method. For a full list of all available options, please have a look further down at the Complete List of ActionMailer user-settable attributes section.
+Here is a quick explanation of the items presented in the preceding method. For a full list of all available options, please have a look further down at the Complete List of Action Mailer user-settable attributes section.
 
 * <tt>default Hash</tt> - This is a hash of default values for any email you send, in this case we are setting the <tt>:from</tt> header to a value for all messages in this class, this can be overridden on a per email basis
-* +mail+ - The actual email message, we are passing the <tt>:to</tt> and <tt>:subject</tt> headers in|
+* +mail+ - The actual email message, we are passing the <tt>:to</tt> and <tt>:subject</tt> headers in.
 
-And instance variables we define in the method become available for use in the view.
+Just like controllers, any instance variables we define in the method become available for use in the views.
 
 h5. Create a Mailer View
 
@@ -104,9 +104,9 @@ When you call the +mail+ method now, Action Mailer will detect the two templates
 
 h5. Wire It Up So That the System Sends the Email When a User Signs Up
 
-There are three ways to achieve this. One is to send the email from the controller that sends the email, another is to put it in a +before_create+ callback in the user model, and the last one is to use an observer on the user model. Whether you use the second or third methods is up to you, but staying away from the first is recommended. Not because it's wrong, but because it keeps your controller clean, and keeps all logic related to the user model within the user model. This way, whichever way a user is created (from a web form, or from an API call, for example), we are guaranteed that the email will be sent.
+There are several ways to do this, some people create Rails Observers to fire off emails, others do it inside of the User Model.  However, in Rails 3, mailers are really just another way to render a view.  Instead of rendering a view and sending out the HTTP protocol, they are just sending it out through the Email protocols instead.  Due to this, it makes sense to just have your controller tell the mailer to send an email when a user is successfully created.
 
-Let's see how we would go about wiring it up using an observer.
+Setting this up is painfully simple.
 
 First off, we need to create a simple +User+ scaffold:
 
@@ -115,35 +115,46 @@ $ rails generate scaffold user name:string email:string login:string
 $ rake db:migrate
 </shell>
 
-Now that we have a user model to play with, edit +config/application.rb+ and register the observer:
+Now that we have a user model to play with, we will just edit the +app/controllers/users_controller.rb+ make it instruct the UserMailer to deliver an email to the newly created user by editing the create action and inserting a call to <tt>UserMailer.welcome_email</tt> right after the user is successfully saved:
 
 <ruby>
-module MailerGuideCode
-  class Application < Rails::Application
-    # ...
-    config.active_record.observers = :user_observer
+class UsersController < ApplicationController
+  # POST /users
+  # POST /users.xml
+  def create
+    @user = User.new(params[:user])
+
+    respond_to do |format|
+      if @user.save
+        # Tell the UserMailer to send a welcome Email after save
+        UserMailer.welcome_email(@user).deliver
+
+        format.html { redirect_to(@user, :notice => 'User was successfully created.') }
+        format.xml  { render :xml => @user, :status => :created, :location => @user }
+      else
+        format.html { render :action => "new" }
+        format.xml  { render :xml => @user.errors, :status => :unprocessable_entity }
+      end
+    end
   end
 end
 </ruby>
 
-You can make a +app/observers+ directory and Rails will automatically load it for you (Rails will automatically load anything in the +app+ directory as of version 3.0)
+This provides a much simpler implementation that does not require the registering of observers and the like.
 
-Now create a file called +user_observer.rb+ in +app/observers+ and make it look like:
+The method +welcome_email+ returns a Mail::Message object which can then just be told +deliver+ to send itself out.
 
-<ruby>
-class UserObserver < ActiveRecord::Observer
-  def after_create(user)
-    UserMailer.welcome_email(user).deliver
-  end
-end
-</ruby>
+NOTE: In previous versions of Rails, you would call +deliver_welcome_email+ or +create_welcome_email+ however in Rails 3.0 this has been deprecated in favour of just calling the method name itself.
 
-Notice how we call <tt>UserMailer.welcome_email(user)</tt>? Even though in the <tt>user_mailer.rb</tt> file we defined an instance method, we are calling the method_name +welcome_email(user)+ on the class.  This is a peculiarity of Action Mailer.
+WARNING: Sending out one email should only take a fraction of a second, if you are planning on sending out many emails, or you have a slow domain resolution service, you might want to investigate using a background process like delayed job.
 
-NOTE: In previous versions of Rails, you would call +deliver_welcome_email+ or +create_welcome_email+ however in Rails 3.0 this has been deprecated in favour of just calling the method name itself.
+h4. Auto encoding header values
 
-The method +welcome_email+ returns a Mail::Message object which can then just be told +deliver+ to send itself out.
+Action Mailer now handles the auto encoding of multibyte characters inside of headers and bodies.
 
+If you are using UTF-8 as your character set, you do not have to do anything special, just go ahead and send in UTF-8 data to the address fields, subject, keywords, filenames or body of the email and ActionMailer will auto encode it into quoted printable for you in the case of a header field or Base64 encode any body parts that are non US-ASCII.
+
+For more complex examples, such as defining alternate character sets or self encoding text first, please refer to the Mail library.
 
 h4. Complete List of Action Mailer Methods
 
@@ -160,21 +171,23 @@ Defining custom headers are simple, you can do it one of three ways:
 * Defining a header field as a parameter to the +mail+ method:
 
 <ruby>
-mail(:x_spam => value)
+mail("X-Spam" => value)
 </ruby>
 
 * Passing in a key value assignment to the +headers+ method:
 
 <ruby>
-headers[:x_spam] = value
+headers["X-Spam"] = value
 </ruby>
 
 * Passing a hash of key value pairs to the +headers+ method:
 
 <ruby>
-headers {:x_spam => value, :x_special => another_value}
+headers {"X-Spam" => value, "X-Special" => another_value}
 </ruby>
 
+TIP: All <tt>X-Value</tt> headers per the RFC2822 can appear more than one time. If you want to delete an <tt>X-Value</tt> header, you need to assign it a value of <tt>nil</tt>.
+
 h5. Adding Attachments
 
 Adding attachments has been simplified in Action Mailer 3.0.
@@ -198,6 +211,37 @@ attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
 
 NOTE: If you specify an encoding, Mail will assume that your content is already encoded and not try to Base64 encode it.
 
+h5. Making Inline Attachments
+
+Inline attachments are now possible in ActionMailer.  While previously in the pre 3.0 version of Rails, you could do inline attachments, it involved a lot of hacking and determination to pull it off.
+
+ActionMailer now makes inline attachments as trivial as they should be.
+
+* Firstly, to tell Mail to turn an attachment into an inline attachment, you just call <tt>#inline</tt> on the attachments method within your Mailer:
+
+<ruby>
+def welcome
+  attachments.inline['image.jpg'] = File.read('/path/to/image.jpg')
+end
+</ruby>
+
+* Then in your view, you can just reference <tt>attachments[]</tt> as a hash and specify which attachment you want to show, calling +url+ on it and then passing the result into the <tt>image_tag</tt> method:
+
+<erb>
+<p>Hello there, this is our image</p>
+
+<%= image_tag attachments['image.jpg'].url %>
+</erb>
+
+* As this is a standard call to +image_tag+ you can pass in an options hash after the attachment url as you could for any other image:
+
+<erb>
+<p>Hello there, this is our image</p>
+
+<%= image_tag attachments['image.jpg'].url, :alt => 'My Photo',
+                                            :class => 'photos' %>
+</erb>
+
 h4. Mailer Views
 
 Mailer views are located in the +app/views/name_of_mailer_class+ directory. The specific mailer view is known to the class because it's name is the same as the mailer method. So for example, in our example from above, our mailer view for the +welcome_email+ method will be in +app/views/user_mailer/welcome_email.html.erb+ for the HTML version and +welcome_email.text.erb+ for the plain text version.
@@ -325,7 +369,7 @@ class UserMailer < ActionMailer::Base
 end
 </ruby>
 
-The above will send a multipart email with an attachment, properly nested with the top level being <tt>mixed/multipart</tt> and the first part being a <tt>mixed/alternative</tt> containing the plain text and HTML email messages.
+The above will send a multipart email with an attachment, properly nested with the top level being <tt>multipart/mixed</tt> and the first part being a <tt>multipart/alternative</tt> containing the plain text and HTML email messages.
 
 h3. Receiving Emails
 

data/guides/source/action_view_overview.textile

@@ -699,7 +699,7 @@ Creates a scope around a specific model object like form_for, but doesn‘t crea
   First name: <%= person_form.text_field :first_name %>
   Last name : <%= person_form.text_field :last_name %>
 
-  <% fields_for @person.permission do |permission_fields| %>
+  <%= fields_for @person.permission do |permission_fields| %>
     Admin?  : <%= permission_fields.check_box :admin %>
   <% end %>
 <% end %>

data/guides/source/active_record_basics.textile

@@ -104,6 +104,14 @@ class Product < ActiveRecord::Base
   set_table_name "PRODUCT"
 end
 </ruby>
+If you do so, you will have to define manually the class name that is hosting the fixtures (class_name.yml) using the +set_fixture_class+ method in your test definition:
+<ruby>
+class FunnyJoke < ActiveSupport::TestCase
+  set_fixture_class :funny_jokes => 'Joke'
+  fixtures :funny_jokes
+  ...
+end
+</ruby>
 
 It's also possible to override the column that should be used as the table's primary key. Use the +ActiveRecord::Base.set_primary_key+ method for that:
 <ruby>
@@ -201,4 +209,4 @@ Active Record callbacks allow you to attach code to certain events in the life-c
 
 h3. Migrations
 
-Rails provides a domain-specific language for managing a database schema called migrations. Migrations are stored in files which are executed against any database that Active Record support using rake. Rails keeps track of which files have been committed to the database and provides rollback features. You can learn more about migrations in the "Active Record Migrations guide":migrations.html
+Rails provides a domain-specific language for managing a database schema called migrations. Migrations are stored in files which are executed against any database that Active Record support using rake. Rails keeps track of which files have been committed to the database and provides rollback features. You can learn more about migrations in the "Active Record Migrations guide":migrations.html

data/guides/source/active_record_querying.textile

@@ -17,7 +17,7 @@ If you're used to using raw SQL to find database records then, generally, you wi
 
 Code examples throughout this guide will refer to one or more of the following models:
 
-TIP: All of the following models uses +id+ as the primary key, unless specified otherwise.
+TIP: All of the following models use +id+ as the primary key, unless specified otherwise.
 
 <br />
 
@@ -802,7 +802,7 @@ will either assign an existing client object with the name "Ryan" to the client
 
 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 the underlying query returns just a single record. For example you could run this query:
+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 

data/guides/source/active_support_core_extensions.textile

@@ -1254,6 +1254,39 @@ There's also the destructive version +String#squish!+.
 
 NOTE: Defined in +active_support/core_ext/string/filters.rb+.
 
+h4. +truncate+
+
+The method +truncate+ returns a copy of its receiver truncated after a given +length+:
+
+<ruby>
+"Oh dear! Oh dear! I shall be late!".truncate(20)
+# => "Oh dear! Oh dear!..."
+</ruby>
+
+Ellipsis can be customized with the +:omission+ option:
+
+<ruby>
+"Oh dear! Oh dear! I shall be late!".truncate(20, :omission => '&hellip;')
+# => "Oh dear! Oh &hellip;"
+</ruby>
+
+Note in particular that truncation takes into account the length of the omission string.
+
+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 dear! I shall be late!".truncate(18, :separator => ' ')
+# => "Oh dear! Oh..."
+</ruby>
+
+In the above example "dear" gets cut first, but then +:separator+ prevents it.
+
+WARNING: The option +:separator+ can't be a regexp.
+
+NOTE: Defined in +active_support/core_ext/string/filters.rb+.
+
 h4. Key-based Interpolation
 
 In Ruby 1.9 the <tt>%</tt> string operator supports key-based interpolation, both formatted and unformatted:
@@ -1894,13 +1927,21 @@ Similarly, +from+ returns the tail from the element at the passed index on:
 
 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.
 
-You can pick a random element with +rand+:
+NOTE: Defined in +active_support/core_ext/array/access.rb+.
+
+h4. Random Access
+
+Active Support backports +sample+ from Ruby 1.9:
 
 <ruby>
-shape_type = [Circle, Square, Triangle].rand
+shape_type = [Circle, Square, Triangle].sample
+# => Square, for example
+
+shape_types = [Circle, Square, Triangle].sample(2)
+# => [Triangle, Circle], for example
 </ruby>
 
-NOTE: Defined in +active_support/core_ext/array/access.rb+.
+NOTE: Defined in +active_support/core_ext/array/random_access.rb+.
 
 h4. Options Extraction
 
@@ -2648,21 +2689,348 @@ NOTE: Defined in +active_support/core_ext/proc.rb+.
 
 h3. Extensions to +Date+
 
-...
+h4. Calculations
+
+NOTE: All the following methods are defined in +active_support/core_ext/date/calculations.rb+.
+
+INFO: The following calculation methods have edge cases in October 1582, since days 5..14 just do not exist. This guide does not document their behavior around those days for brevity, but it is enough to say that they do what you would expect. That is, +Date.new(1582, 10, 4).tomorrow+ returns +Date.new(1582, 10, 15)+ and so on. Please check +test/core_ext/date_ext_test.rb+ in the Active Support test suite for expected behavior.
+
+h5. +Date.current+
+
+Active Support defines +Date.current+ to be today in the current time zone. That's like +Date.today+, except that it honors the user time zone, if defined. It also defines +Date.yesterday+ and +Date.tomorrow+, and the instance predicates +past?+, +today?+, and +future?+, all of them relative to +Date.current+.
+
+h5. Named dates
+
+h6. +prev_year+, +next_year+
+
+In Ruby 1.9 +prev_year+ and +next_year+ return a date with the same day/month in the last or next year:
+
+<ruby>
+d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
+d.prev_year              # => Fri, 08 May 2009
+d.next_year              # => Sun, 08 May 2011
+</ruby>
+
+If date is the 29th of February of a leap year, you obtain the 28th:
+
+<ruby>
+d = Date.new(2000, 2, 29) # => Tue, 29 Feb 2000
+d.prev_year               # => Sun, 28 Feb 1999
+d.next_year               # => Wed, 28 Feb 2001
+</ruby>
+
+Active Support defines these methods as well for Ruby 1.8.
+
+h6. +prev_month+, +next_month+
+
+In Ruby 1.9 +prev_month+ and +next_month+ return the date with the same day in the last or next month:
+
+<ruby>
+d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
+d.prev_month             # => Thu, 08 Apr 2010
+d.next_month             # => Tue, 08 Jun 2010
+</ruby>
+
+If such a day does not exist, the last day of the corresponding month is returned:
+
+<ruby>
+Date.new(2000, 5, 31).prev_month # => Sun, 30 Apr 2000
+Date.new(2000, 3, 31).prev_month # => Tue, 29 Feb 2000
+Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000
+Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000
+</ruby>
+
+Active Support defines these methods as well for Ruby 1.8.
+
+h6. +beginning_of_week+, +end_of_week+
+
+The methods +beginning_of_week+ and +end_of_week+ return the dates for the beginning and end of week, assuming weeks start on Monday:
+
+<ruby>
+d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
+d.beginning_of_week      # => Mon, 03 May 2010
+d.end_of_week            # => Sun, 09 May 2010
+</ruby>
+
++beginning_of_week+ is aliased to +monday+ and +at_beginning_of_week+. +end_of_week+ is aliased to +sunday+ and +at_end_of_week+.
+
+h6. +next_week+
+
++next_week+ receives a symbol with a day name in English (in lowercase, default is +:monday+) and it returns the date corresponding to that day in the next week:
+
+<ruby>
+d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
+d.next_week              # => Mon, 10 May 2010
+d.next_week(:saturday)   # => Sat, 15 May 2010
+</ruby>
+
+h6. +beginning_of_month+, +end_of_month+
+
+The methods +beginning_of_month+ and +end_of_month+ return the dates for the beginning and end of the month:
+
+<ruby>
+d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
+d.beginning_of_month     # => Sat, 01 May 2010
+d.end_of_month           # => Mon, 31 May 2010
+</ruby>
+
++beginning_of_month+ is aliased to +at_beginning_of_month+, and +end_of_month+ is aliased to +at_end_of_month+.
+
+h6. +beginning_of_quarter+, +end_of_quarter+
+
+The methods +beginning_of_quarter+ and +end_of_quarter+ return the dates for the beginning and end of the quarter of the receiver's calendar year:
+
+<ruby>
+d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
+d.beginning_of_quarter   # => Thu, 01 Apr 2010
+d.end_of_quarter         # => Wed, 30 Jun 2010
+</ruby>
+
++beginning_of_quarter+ is aliased to +at_beginning_of_quarter+, and +end_of_quarter+ is aliased to +at_end_of_quarter+.
+
+h6. +beginning_of_year+, +end_of_year+
+
+The methods +beginning_of_year+ and +end_of_year+ return the dates for the beginning and end of the year:
+
+<ruby>
+d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
+d.beginning_of_year      # => Fri, 01 Jan 2010
+d.end_of_year            # => Fri, 31 Dec 2010
+</ruby>
+
++beginning_of_year+ is aliased to +at_beginning_of_year+, and +end_of_year+ is aliased to +at_end_of_year+.
+
+h5. Other Date Computations
+
+h6. +years_ago+, +years_since+
+
+The method +years_ago+ receives a number of years and returns the same date those many years ago:
+
+<ruby>
+date = Date.new(2010, 6, 7)
+date.years_ago(10) # => Wed, 07 Jun 2000
+</ruby>
+
++years_since+ moves forward in time:
+
+<ruby>
+date = Date.new(2010, 6, 7)
+date.years_since(10) # => Sun, 07 Jun 2020
+</ruby>
+
+If such a day does not exist, the last day of the corresponding month is returned:
+
+<ruby>
+Date.new(2012, 2, 29).years_ago(3)     # => Sat, 28 Feb 2009
+Date.new(2012, 2, 29).years_since(3)   # => Sat, 28 Feb 2015
+</ruby>
+
+h6. +months_ago+, +months_since+
+
+The methods +months_ago+ and +months_since+ work analogously for months:
+
+<ruby>
+Date.new(2010, 4, 30).months_ago(2)   # => Sun, 28 Feb 2010
+Date.new(2010, 4, 30).months_since(2) # => Wed, 30 Jun 2010
+</ruby>
+
+If such a day does not exist, the last day of the corresponding month is returned:
+
+<ruby>
+Date.new(2010, 4, 30).months_ago(2)    # => Sun, 28 Feb 2010
+Date.new(2009, 12, 31).months_since(2) # => Sun, 28 Feb 2010
+</ruby>
+
+h6. +advance+
+
+The most generic way to jump to other days is +advance+. This method receives a hash with keys +:years+, +:months+, +:weeks+, +:days+, and returns a date advanced as much as the present keys indicate:
+
+<ruby>
+date = Date.new(2010, 6, 6)
+date.advance(:years => 1, :weeks => 2)  # => Mon, 20 Jun 2011
+date.advance(:months => 2, :days => -2) # => Wed, 04 Aug 2010
+</ruby>
+
+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:
+
+<ruby>
+Date.new(2010, 2, 28).advance(:months => 1, :day => 1)
+# => Sun, 28 Mar 2010
+</ruby>
+
+While if it did it the other way around the result would be different:
+
+<ruby>
+Date.new(2010, 2, 28).advance(:days => 1).advance(:months => 1)
+# => Thu, 01 Apr 2010
+</ruby>
+
+h5. Changing Components
+
+The method +change+ allows you to get a new date which is the same as the receiver except for the given year, month, or day:
+
+<ruby>
+Date.new(2010, 12, 23).change(:year => 2011, :month => 11)
+# => Wed, 23 Nov 2011
+</ruby>
+
+This method is not tolerant to non-existing dates, if the change is invalid +ArgumentError+ is raised:
+
+<ruby>
+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.
+
+INFO: The following methods return a +Time+ object if possible, otherwise a +DateTime+.
+
+h6. +beginning_of_day+, +end_of_day+
+
+The method +beginning_of_day+ returns a timestamp at the beginning of the day (00:00:00):
+
+<ruby>
+date = Date.new(2010, 6, 7)
+date.beginning_of_day # => Sun Jun 07 00:00:00 +0200 2010
+</ruby>
+
+The method +end_of_day+ returns a timestamp at the end of the day (23:59:59):
+
+<ruby>
+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+
+
+h4(#date-conversions). Conversions
 
 h3. Extensions to +DateTime+
 
-...
+NOTE: All the following methods are defined in +active_support/core_ext/date_time/calculations.rb+.
 
-h3. Extensions to +Time+
+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
 
-h3. Extensions to +Process+
+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
+next_week
+months_ago
+months_since
+beginning_of_month
+end_of_month
+prev_month
+next_month
+beginning_of_quarter
+end_of_quarter
+beginning_of_year
+end_of_year
+years_ago
+years_since
+prev_year
+next_year
+</ruby>
+
+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
+end_of_day
+ago
+since
+</ruby>
+
+On the other hand, +advance+ and +change+ are also defined and support more options, they are documented below.
+
+h5. Named Datetimes
+
+h6. +DateTime.current+
+
+Active Support defines +DateTime.current+ to be like +Time.now.to_datetime+, except that it honors the user time zone, if defined. It also defines instance predicates +past?+, and +future?+ relative to +DateTime.current+.
+
+h5. Other Extensions
+
+h6. +seconds_since_midnight+
+
+The method +seconds_since_midnight+ returns the number of seconds since midnight:
+
+<ruby>
+now = DateTime.current     # => Mon, 07 Jun 2010 20:26:36 +0000
+now.seconds_since_midnight # => 73596
+</ruby>
+
+h6(#utc-datetime). +utc+
+
+The method +utc+ gives you the same datetime in the receiver expressed in UTC.
+
+<ruby>
+now = DateTime.current # => Mon, 07 Jun 2010 19:27:52 -0400
+now.utc                # => Mon, 07 Jun 2010 23:27:52 +0000
+</ruby>
+
+This method is also aliased as +getutc+.
+
+h6. +utc?+
+
+The predicate +utc?+ says whether the receiver has UTC as its time zone:
+
+<ruby>
+now = DateTime.now # => Mon, 07 Jun 2010 19:30:47 -0400
+now.utc?           # => false
+now.utc.utc?       # => true
+</ruby>
+
+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+:
+
+<ruby>
+now = DateTime.current
+# => Tue, 08 Jun 2010 01:56:22 +0000
+now.change(:year => 2011, :offset => Rational(-6, 24))
+# => Wed, 08 Jun 2011 01:56:22 -0600
+</ruby>
+
+If hours are zeroed, then minutes and seconds are too (unless they have given values):
+
+<ruby>
+now.change(:hour => 0)
+# => Tue, 08 Jun 2010 00:00:00 +0000
+</ruby>
+
+Similarly, if minutes are zeroed, then seconds are too (unless it has given a value):
+
+<ruby>
+now.change(:min => 0)
+# => Tue, 08 Jun 2010 01:00:00 +0000
+</ruby>
+
+This method is not tolerant to non-existing dates, if the change is invalid +ArgumentError+ is raised:
+
+<ruby>
+DateTime.current.change(:month => 2, :day => 30)
+# => ArgumentError: invalid date
+</ruby>
+
+h4(#datetime-conversions). Conversions
+
+h3. Extensions to +Time+
 
 ...
 
-h3. Extensions to +Pathname+
+h3. Extensions to +Process+
 
 ...