railties 3.1.0.rc4 → 3.1.0.rc5

data/guides/source/active_record_validations_callbacks.textile

@@ -166,23 +166,23 @@ Each helper accepts an arbitrary number of attribute names, so with a single lin
 
 All of them accept the +:on+ and +:message+ options, which define when the validation should be run and what message should be added to the +errors+ collection if it fails, respectively. The +:on+ option takes one of the values +:save+ (the default), +:create+  or +:update+. There is a default error message for each one of the validation helpers. These messages are used when the +:message+ option isn't specified. Let's take a look at each one of the available helpers.
 
-h4. +validates_acceptance_of+
+h4. +acceptance+
 
 Validates that a checkbox on the user interface was checked when a form was submitted. This is typically used when the user needs to agree to your application's terms of service, confirm reading some text, or any similar concept. This validation is very specific to web applications and this 'acceptance' does not need to be recorded anywhere in your database (if you don't have a field for it, the helper will just create a virtual attribute).
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_acceptance_of :terms_of_service
+  validates :terms_of_service, :acceptance => true
 end
 </ruby>
 
-The default error message for +validates_acceptance_of+ is "_must be accepted_".
+The default error message for this helper is "_must be accepted_".
 
-+validates_acceptance_of+ can receive an +:accept+ option, which determines the value that will be considered acceptance. It defaults to "1", but you can change this.
+It can receive an +:accept+ option, which determines the value that will be considered acceptance. It defaults to "1" and can be easily changed.
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_acceptance_of :terms_of_service, :accept => 'yes'
+  validates :terms_of_service, :acceptance => { :accept => 'yes' }
 end
 </ruby>
 
@@ -203,13 +203,13 @@ CAUTION: Don't use +validates_associated+ on both ends of your associations. The
 
 The default error message for +validates_associated+ is "_is invalid_". Note that each associated object will contain its own +errors+ collection; errors do not bubble up to the calling model.
 
-h4. +validates_confirmation_of+
+h4. +confirmation+
 
 You should use this helper when you have two text fields that should receive exactly the same content. For example, you may want to confirm an email address or a password. This validation creates a virtual attribute whose name is the name of the field that has to be confirmed with "_confirmation" appended.
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_confirmation_of :email
+  validates :email, :confirmation => true
 end
 </ruby>
 
@@ -220,70 +220,70 @@ In your view template you could use something like
 <%= text_field :person, :email_confirmation %>
 </erb>
 
-This check is performed only if +email_confirmation+ is not +nil+. To require confirmation, make sure to add a presence check for the confirmation attribute (we'll take a look at +validates_presence_of+ later on this guide):
+This check is performed only if +email_confirmation+ is not +nil+. To require confirmation, make sure to add a presence check for the confirmation attribute (we'll take a look at +presence+ later on this guide):
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_confirmation_of :email
-  validates_presence_of :email_confirmation
+  validates :email, :confirmation => true
+  validates :email_confirmation, :presence => true
 end
 </ruby>
 
-The default error message for +validates_confirmation_of+ is "_doesn't match confirmation_".
+The default error message for this helper is "_doesn't match confirmation_".
 
-h4. +validates_exclusion_of+
+h4. +exclusion+
 
 This helper validates that the attributes' values are not included in a given set. In fact, this set can be any enumerable object.
 
 <ruby>
 class Account < ActiveRecord::Base
-  validates_exclusion_of :subdomain, :in => %w(www us ca jp),
-    :message => "Subdomain %{value} is reserved."
+  validates :subdomain, :exclusion => { :in => %w(www us ca jp),
+    :message => "Subdomain %{value} is reserved." }
 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 +exclusion+ 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 is "_is reserved_".
 
-h4. +validates_format_of+
+h4. +format+
 
 This helper validates the attributes' values by testing whether they match a given regular expression, which is specified using the +:with+ option.
 
 <ruby>
 class Product < ActiveRecord::Base
-  validates_format_of :legacy_code, :with => /\A[a-zA-Z]+\z/,
-    :message => "Only letters allowed"
+  validates :legacy_code, :format => { :with => /\A[a-zA-Z]+\z/,
+    :message => "Only letters allowed" }
 end
 </ruby>
 
-The default error message for +validates_format_of+ is "_is invalid_".
+The default error message is "_is invalid_".
 
-h4. +validates_inclusion_of+
+h4. +inclusion+
 
 This helper validates that the attributes' values are included in a given set. In fact, this set can be any enumerable object.
 
 <ruby>
 class Coffee < ActiveRecord::Base
-  validates_inclusion_of :size, :in => %w(small medium large),
-    :message => "%{value} is not a valid size"
+  validates :size, :inclusion => { :in => %w(small medium large),
+    :message => "%{value} is not a valid size" }
 end
 </ruby>
 
-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 +inclusion+ 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 this helper is "_is not included in the list_".
 
-h4. +validates_length_of+
+h4. +length+
 
 This helper validates the length of the attributes' values. It provides a variety of options, so you can specify length constraints in different ways:
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_length_of :name, :minimum => 2
-  validates_length_of :bio, :maximum => 500
-  validates_length_of :password, :in => 6..20
-  validates_length_of :registration_number, :is => 6
+  validates :name, :length => { :minimum => 2 }
+  validates :bio, :length => { :maximum => 500 }
+  validates :password, :length => { :in => 6..20 }
+  validates :registration_number, :length => { :is => 6 }
 end
 </ruby>
 
@@ -298,8 +298,8 @@ The default error messages depend on the type of length validation being perform
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_length_of :bio, :maximum => 1000,
-    :too_long => "%{count} characters is the maximum allowed"
+  validates :bio, :length => { :maximum => 1000,
+    :too_long => "%{count} characters is the maximum allowed" }
 end
 </ruby>
 
@@ -307,20 +307,21 @@ This helper counts characters by default, but you can split the value in a diffe
 
 <ruby>
 class Essay < ActiveRecord::Base
-  validates_length_of :content,
+  validates :content, :length => {
     :minimum   => 300,
     :maximum   => 400,
     :tokenizer => lambda { |str| str.scan(/\w+/) },
     :too_short => "must have at least %{count} words",
     :too_long  => "must have at most %{count} words"
+  }
 end
 </ruby>
 
-Note that the default error messages are plural (e.g., "is too short (minimum is %{count} characters)"). For this reason, when +:minimum+ is 1 you should provide a personalized message or use +validates_presence_of+ instead. When +:in+ or +:within+ have a lower limit of 1, you should either provide a personalized message or call +validates_presence_of+ prior to +validates_length_of+.
+Note that the default error messages are plural (e.g., "is too short (minimum is %{count} characters)"). For this reason, when +:minimum+ is 1 you should provide a personalized message or use +validates_presence_of+ instead. When +:in+ or +:within+ have a lower limit of 1, you should either provide a personalized message or call +presence+ prior to +length+.
 
-The +validates_size_of+ helper is an alias for +validates_length_of+.
+The +size+ helper is an alias for +length+.
 
-h4. +validates_numericality_of+
+h4. +numericality+
 
 This helper validates that your attributes have only numeric values. By default, it will match an optional sign followed by an integral or floating point number. To specify that only integral numbers are allowed set +:only_integer+ to true.
 
@@ -336,12 +337,12 @@ WARNING. Note that the regular expression above allows a trailing newline charac
 
 <ruby>
 class Player < ActiveRecord::Base
-  validates_numericality_of :points
-  validates_numericality_of :games_played, :only_integer => true
+  validates :points, :numericality => true
+  validates :games_played, :numericality => { :only_integer => true }
 end
 </ruby>
 
-Besides +:only_integer+, the +validates_numericality_of+ helper also accepts the following options to add constraints to acceptable values:
+Besides +:only_integer+, this helper also accepts the following options to add constraints to acceptable values:
 
 * +:greater_than+ - Specifies the value must be greater than the supplied value. The default error message for this option is "_must be greater than %{count}_".
 * +: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}_".
@@ -351,9 +352,9 @@ Besides +:only_integer+, the +validates_numericality_of+ helper also accepts the
 * +: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_".
 
-The default error message for +validates_numericality_of+ is "_is not a number_".
+The default error message is "_is not a number_".
 
-h4. +validates_presence_of+
+h4. +presence+
 
 This helper validates that the specified attributes are not empty. It uses the +blank?+ method to check if the value is either +nil+ or a blank string, that is, a string that is either empty or consists of whitespace.
 
@@ -368,21 +369,21 @@ If you want to be sure that an association is present, you'll need to test wheth
 <ruby>
 class LineItem < ActiveRecord::Base
   belongs_to :order
-  validates_presence_of :order_id
+  validates :order_id, :presence => true
 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 <tt>validates :field_name, :inclusion => { :in => [true, false] }</tt>.
 
-The default error message for +validates_presence_of+ is "_can't be empty_".
+The default error message is "_can't be empty_".
 
-h4. +validates_uniqueness_of+
+h4. +uniqueness+
 
 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
-  validates_uniqueness_of :email
+  validates :email, :uniqueness => true
 end
 </ruby>
 
@@ -392,8 +393,8 @@ There is a +:scope+ option that you can use to specify other attributes that are
 
 <ruby>
 class Holiday < ActiveRecord::Base
-  validates_uniqueness_of :name, :scope => :year,
-    :message => "should happen once per year"
+  validates :name, :uniqueness => { :scope => :year,
+    :message => "should happen once per year" }
 end
 </ruby>
 
@@ -401,13 +402,13 @@ There is also a +:case_sensitive+ option that you can use to define whether the
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_uniqueness_of :name, :case_sensitive => false
+  validates :name, :uniqueness => { :case_sensitive => false }
 end
 </ruby>
 
 WARNING. Note that some databases are configured to perform case-insensitive searches anyway.
 
-The default error message for +validates_uniqueness_of+ is "_has already been taken_".
+The default error message is "_has already been taken_".
 
 h4. +validates_with+
 
@@ -471,8 +472,8 @@ The +:allow_nil+ option skips the validation when the value being validated is +
 
 <ruby>
 class Coffee < ActiveRecord::Base
-  validates_inclusion_of :size, :in => %w(small medium large),
-    :message => "%{value} is not a valid size", :allow_nil => true
+  validates :size, :inclusion => { :in => %w(small medium large),
+    :message => "%{value} is not a valid size" }, :allow_nil => true
 end
 </ruby>
 
@@ -484,10 +485,10 @@ The +:allow_blank+ option is similar to the +:allow_nil+ option. This option wil
 
 <ruby>
 class Topic < ActiveRecord::Base
-  validates_length_of :title, :is => 5, :allow_blank => true
+  validates :title, :length => { :is => 5 }, :allow_blank => true
 end
 
-Topic.create("title" => "").valid? # => true
+Topic.create("title" => "").valid?  # => true
 Topic.create("title" => nil).valid? # => true
 </ruby>
 
@@ -504,10 +505,10 @@ The +:on+ option lets you specify when the validation should happen. The default
 <ruby>
 class Person < ActiveRecord::Base
   # it will be possible to update email with a duplicated value
-  validates_uniqueness_of :email, :on => :create
+  validates :email, :uniqueness => true, :on => :create
 
   # it will be possible to create the record with a non-numerical age
-  validates_numericality_of :age, :on => :update
+  validates :age, :numericality => true, :on => :update
 
   # the default (validates on both create and update)
   validates :name, :presence => true, :on => :save
@@ -524,7 +525,7 @@ You can associate the +:if+ and +:unless+ options with a symbol corresponding to
 
 <ruby>
 class Order < ActiveRecord::Base
-  validates_presence_of :card_number, :if => :paid_with_card?
+  validates :card_number, :presence => true, :if => :paid_with_card?
 
   def paid_with_card?
     payment_type == "card"
@@ -538,7 +539,7 @@ You can also use a string that will be evaluated using +eval+ and needs to conta
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates_presence_of :surname, :if => "name.nil?"
+  validates :surname, :presence => true, :if => "name.nil?"
 end
 </ruby>
 
@@ -548,7 +549,7 @@ Finally, it's possible to associate +:if+ and +:unless+ with a +Proc+ object whi
 
 <ruby>
 class Account < ActiveRecord::Base
-  validates_confirmation_of :password,
+  validates :password, :confirmation => true,
     :unless => Proc.new { |a| a.password.blank? }
 end
 </ruby>
@@ -560,8 +561,8 @@ Sometimes it is useful to have multiple validations use one condition, it can be
 <ruby>
 class User < ActiveRecord::Base
   with_options :if => :is_admin? do |admin|
-    admin.validates_length_of :password, :minimum => 10
-    admin.validates_presence_of :email
+    admin.validates :password, :length => { :minimum => 10 }
+    admin.validates :email, :presence => true
   end
 end
 </ruby>
@@ -598,7 +599,7 @@ You can even create your own validation helpers and reuse them in several differ
 <ruby>
 ActiveRecord::Base.class_eval do
   def self.validates_as_choice(attr_name, n, options={})
-    validates_inclusion_of attr_name, {:in => 1..n}.merge(options)
+    validates attr_name, :inclusion => { {:in => 1..n}.merge(options) }
   end
 end
 </ruby>
@@ -623,8 +624,7 @@ Returns an OrderedHash with all errors. Each key is the attribute name and the v
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates :name, :presence => true
-  validates_length_of :name, :minimum => 3
+  validates :name, :presence => true, :length => { :minimum => 3 }
 end
 
 person = Person.new
@@ -643,8 +643,7 @@ h4(#working_with_validation_errors-errors-2). +errors[]+
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates :name, :presence => true
-  validates_length_of :name, :minimum => 3
+  validates :name, :presence => true, :length => { :minimum => 3 }
 end
 
 person = Person.new(:name => "John Doe")
@@ -719,8 +718,7 @@ The +clear+ method is used when you intentionally want to clear all the messages
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates :name, :presence => true
-  validates_length_of :name, :minimum => 3
+  validates :name, :presence => true, :length => { :minimum => 3 }
 end
 
 person = Person.new
@@ -743,9 +741,7 @@ The +size+ method returns the total number of error messages for the object.
 
 <ruby>
 class Person < ActiveRecord::Base
-  validates :name, :presence => true
-  validates_length_of   :name, :minimum => 3
-  validates_presence_of :email
+  validates :name, :presence => true, :length => { :minimum => 3 }
 end
 
 person = Person.new
@@ -766,13 +762,14 @@ h4. Installing as a plugin
 $ rails plugin install git://github.com/joelmoss/dynamic_form.git
 </shell>
 
-h4 Installing as a Gem
-Add this line on your Gemfile:
+h4. Installing as a Gem
+
+Add this line in your Gemfile:
 <ruby>
 gem "dynamic_form"
 </ruby>
 
-Now you will have access to these two methods in your view templates:
+Now you will have access to these two methods in your view templates.
 
 h4. +error_messages+ and +error_messages_for+
 
@@ -780,8 +777,8 @@ When creating a form with the +form_for+ helper, you can use the +error_messages
 
 <ruby>
 class Product < ActiveRecord::Base
-  validates_presence_of :description, :value
-  validates_numericality_of :value, :allow_nil => true
+  validates :description, :value, :presence => true
+  validates :value, :numericality => true, :allow_nil => true
 end
 </ruby>
 
@@ -851,7 +848,7 @@ The way form fields with errors are treated is defined by +ActionView::Base.fiel
 * A string with the HTML tag
 * An instance of +ActionView::Helpers::InstanceTag+.
 
-Here is a simple example where we change the Rails behaviour to always display the error messages in front of each of the form fields with errors. The error messages will be enclosed by a +span+ element with a +validation-error+ CSS class. There will be no +div+ element enclosing the +input+ element, so we get rid of that red border around the text field. You can use the +validation-error+ CSS class to style it anyway you want.
+Here is a simple example where we change the Rails behavior to always display the error messages in front of each of the form fields with errors. The error messages will be enclosed by a +span+ element with a +validation-error+ CSS class. There will be no +div+ element enclosing the +input+ element, so we get rid of that red border around the text field. You can use the +validation-error+ CSS class to style it anyway you want.
 
 <ruby>
 ActionView::Base.field_error_proc = Proc.new do |html_tag, instance|
@@ -879,7 +876,7 @@ In order to use the available callbacks, you need to register them. You can do t
 
 <ruby>
 class User < ActiveRecord::Base
-  validates_presence_of :login, :email
+  validates :login, :email, :presence => true
 
   before_validation :ensure_login_has_a_value
 
@@ -896,7 +893,7 @@ The macro-style class methods can also receive a block. Consider using this styl
 
 <ruby>
 class User < ActiveRecord::Base
-  validates_presence_of :login, :email
+  validates :login, :email, :presence => true
 
   before_create do |user|
     user.name = user.login.capitalize if user.name.blank?
@@ -944,7 +941,7 @@ The +after_initialize+ callback will be called whenever an Active Record object
 
 The +after_find+ callback will be called whenever Active Record loads a record from the database. +after_find+ is called before +after_initialize+ if both are defined.
 
-The +after_initialize+ and +after_find+ callbacks are a bit different from the others. They have no +before_*+ counterparts, and the only way to register them is by defining them as regular methods. If you try to register +after_initialize+ or +after_find+ using macro-style class methods, they will just be ignored. This behaviour is due to performance reasons, since +after_initialize+ and +after_find+ will both be called for each record found in the database, significantly slowing down the queries.
+The +after_initialize+ and +after_find+ callbacks are a bit different from the others. They have no +before_*+ counterparts, and the only way to register them is by defining them as regular methods. If you try to register +after_initialize+ or +after_find+ using macro-style class methods, they will just be ignored. This behavior is due to performance reasons, since +after_initialize+ and +after_find+ will both be called for each record found in the database, significantly slowing down the queries.
 
 <ruby>
 class User < ActiveRecord::Base
@@ -1175,7 +1172,7 @@ As usual, settings in +config/environments+ take precedence over those in +confi
 
 h4. Sharing Observers
 
-By default, Rails will simply strip "Observer" from an observer's name to find the model it should observe. However, observers can also be used to add behaviour to more than one model, and so it's possible to manually specify the models that our observer should observe.
+By default, Rails will simply strip "Observer" from an observer's name to find the model it should observe. However, observers can also be used to add behavior to more than one model, and so it's possible to manually specify the models that our observer should observe.
 
 <ruby>
 class MailerObserver < ActiveRecord::Observer

data/guides/source/active_support_core_extensions.textile

@@ -436,20 +436,6 @@ end
 
 NOTE: Defined in +active_support/core_ext/kernel/reporting.rb+.
 
-h4. +require_library_or_gem+
-
-The convenience method +require_library_or_gem+ tries to load its argument with a regular +require+ first. If it fails loads +rubygems+ and tries again.
-
-If the first attempt is a failure and +rubygems+ can't be loaded the method raises +LoadError+. A +LoadError+ is also raised if +rubygems+ is available but the argument is not loadable as a gem.
-
-For example, that's the way the MySQL adapter loads the MySQL library:
-
-<ruby>
-require_library_or_gem('mysql')
-</ruby>
-
-NOTE: Defined in +active_support/core_ext/kernel/requires.rb+.
-
 h4. +in?+
 
 The predicate +in?+ tests if an object is included in another object. An +ArgumentError+ exception will be raised if the argument passed does not respond to +include?+.
@@ -512,7 +498,7 @@ ActionController::TestCase.class_eval do
 end
 </ruby>
 
-Rails uses +alias_method_chain+ all over the code base. For example validations are added to +ActiveRecord::Base#save+ by wrapping the method that way in a separate module specialised in validations.
+Rails uses +alias_method_chain+ all over the code base. For example validations are added to +ActiveRecord::Base#save+ by wrapping the method that way in a separate module specialized in validations.
 
 NOTE: Defined in +active_support/core_ext/module/aliasing.rb+.
 
@@ -961,7 +947,7 @@ h4. Class Attributes
 
 h5. +class_attribute+
 
-The method +class_attribute+ declares one or more inheritable class attributes that can be overridden at any level down the hierarchy:
+The method +class_attribute+ declares one or more inheritable class attributes that can be overridden at any level down the hierarchy.
 
 <ruby>
 class A
@@ -997,7 +983,7 @@ self.default_params = {
 }.freeze
 </ruby>
 
-They can be also accessed and overridden at the instance level:
+They can be also accessed and overridden at the instance level.
 
 <ruby>
 A.x = 1
@@ -1010,7 +996,7 @@ 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
+The generation of the writer instance method can be prevented by setting the option +:instance_writer+ to +false+.
 
 <ruby>
 module ActiveRecord
@@ -1023,8 +1009,20 @@ end
 
 A model may find that option useful as a way to prevent mass-assignment from setting the attribute.
 
+The generation of the reader instance method can be prevented by setting the option +:instance_reader+ to +false+.
+
+<ruby>
+class A
+  class_attribute :x, :instance_reader => false
+end
+
+A.x = 1 # NoMethodError
+</ruby>
+
 For convenience +class_attribute+ also defines an instance predicate which is the double negation of what the instance reader returns. In the examples above it would be called +x?+.
 
+When +:instance_reader+ is +false+, the instance predicate returns a +NoMethodError+ just like the reader method.
+
 NOTE: Defined in +active_support/core_ext/class/attribute.rb+
 
 h5. +cattr_reader+, +cattr_writer+, and +cattr_accessor+
@@ -1050,18 +1048,24 @@ module ActionView
 end
 </ruby>
 
-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+):
+we can access +field_error_proc+ in views.
+
+The generation of the reader instance method can be prevented by setting +:instance_reader+ to +false+ and the generation of the writer instance method can be prevented by setting +:instance_writer+ to +false+. Generation of both methods can be prevented by setting +:instance_accessor+ to +false+. In all cases, the value must be exactly +false+ and not any false value.
 
 <ruby>
-module ActiveRecord
-  class Base
-    # No pluralize_table_names= instance writer is generated.
-    cattr_accessor :pluralize_table_names, :instance_writer => false
+module A
+  class B
+    # No first_name instance reader is generated.
+    cattr_accessor :first_name, :instance_reader => false
+    # No last_name= instance writer is generated.
+    cattr_accessor :last_name, :instance_writer => false
+    # No surname instance reader or surname= writer is generated.
+    cattr_accessor :surname, :instance_accessor => false
   end
 end
 </ruby>
 
-A model may find that option useful as a way to prevent mass-assignment from setting the attribute.
+A model may find it useful to set +:instance_accessor+ to +false+ as a way to prevent mass-assignment from setting the attribute.
 
 NOTE: Defined in +active_support/core_ext/class/attribute_accessors.rb+.
 
@@ -1160,8 +1164,12 @@ h3. Extensions to +String+
 
 h4. Output Safety
 
+h5. Motivation
+
 Inserting data into HTML templates needs extra care. For example you can't just interpolate +@review.title+ verbatim into an HTML page. On one hand if the review title is "Flanagan & Matz rules!" the output won't be well-formed because an ampersand has to be escaped as "&amp;amp;". On the other hand, depending on the application that may be a big security hole because users can inject malicious HTML setting a hand-crafted review title. Check out the "section about cross-site scripting in the Security guide":security.html#cross-site-scripting-xss for further information about the risks.
 
+h5. Safe Strings
+
 Active Support has the concept of <i>(html) safe</i> strings since Rails 3. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not.
 
 Strings are considered to be <i>unsafe</i> by default:
@@ -1187,8 +1195,6 @@ s            # => "<script>...</script>"
 
 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.
-
 If you append onto a safe string, either in-place with +concat+/<tt><<</tt>, or with <tt>+</tt>, the result is a safe string. Unsafe arguments are escaped:
 
 <ruby>
@@ -1229,6 +1235,22 @@ end
 
 NOTE: Defined in +active_support/core_ext/string/output_safety.rb+.
 
+h5. Transformation
+
+As a rule of thumb, except perhaps for concatenation as explained above, any method that may change a string gives you an unsafe string. These are +donwcase+, +gsub+, +strip+, +chomp+, +underscore+, etc.
+
+In the case of in-place transformations like +gsub!+ the receiver itself becomes unsafe.
+
+INFO: The safety bit is lost always, no matter whether the transformation actually changed something.
+
+h5. Conversion and Coercion
+
+Calling +to_s+ on a safe string returns a safe string, but coercion with +to_str+ returns an unsafe string.
+
+h5. Copying
+
+Calling +dup+ or +clone+ on safe strings yields safe strings.
+
 h4. +squish+
 
 The method +squish+ strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each:
@@ -1474,7 +1496,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>.
+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>. To support cases such as this, Active Support allows you to specify acronyms in +config/initializers/inflections.rb+:
+
+<ruby>
+ActiveSupport::Inflector.inflections do |inflect|
+  inflect.acronym 'SSL'
+end
+
+"SSLError".underscore.camelize #=> "SSLError"
+</ruby>
 
 +camelize+ is aliased to +camelcase+.
 
@@ -2219,8 +2249,8 @@ The method +Array.wrap+ wraps its argument in an array unless it is already an a
 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.
+* Otherwise, if the argument responds to +to_ary+ it is invoked, and if the value of +to_ary+ is not +nil+, it is returned.
+* Otherwise, an array with the argument as its single element is returned.
 
 <ruby>
 Array.wrap(nil)       # => []
@@ -2296,7 +2326,7 @@ NOTE: Defined in +active_support/core_ext/array/grouping.rb+.
 
 h5. +in_groups(number, fill_with = nil)+
 
-The method +in_groups+ splits an array into a certain number of groups. The method returns and array with the groups:
+The method +in_groups+ splits an array into a certain number of groups. The method returns an array with the groups:
 
 <ruby>
 %w(1 2 3 4 5 6 7).in_groups(3)
@@ -2728,7 +2758,7 @@ Active Support extends the method +Range#step+ so that it can be invoked without
 (1..10).step(2) # => [1, 3, 5, 7, 9]
 </ruby>
 
-As the example shows, in that case the method returns and array with the corresponding elements.
+As the example shows, in that case the method returns an array with the corresponding elements.
 
 NOTE: Defined in +active_support/core_ext/range/blockless_step.rb+.
 
@@ -3330,6 +3360,32 @@ Active Support defines +Time.current+ to be today in the current time zone. That
 
 When making Time comparisons using methods which honor the user time zone, make sure to use +Time.current+ and not +Time.now+. There are cases where the user time zone might be in the future compared to the system time zone, which +Time.today+ uses by default. This means +Time.now+ may equal +Time.yesterday+.
 
+h5. +all_day+, +all_week+, +all_month+, +all_quarter+ and +all_year+
+
+The method +all_day+ returns a range representing the whole day of the current time.
+
+<ruby>
+now = Time.current
+# => Mon, 09 Aug 2010 23:20:05 UTC +00:00
+now.all_day
+# => Mon, 09 Aug 2010 00:00:00 UTC +00:00..Mon, 09 Aug 2010 23:59:59 UTC +00:00
+</ruby>
+
+Analogously, +all_week+, +all_month+, +all_quarter+ and +all_year+ all serve the purpose of generating time ranges.
+
+<ruby>
+now = Time.current
+# => Mon, 09 Aug 2010 23:20:05 UTC +00:00
+now.all_week
+# => Mon, 09 Aug 2010 00:00:00 UTC +00:00..Sun, 15 Aug 2010 23:59:59 UTC +00:00
+now.all_month
+# => Sat, 01 Aug 2010 00:00:00 UTC +00:00..Tue, 31 Aug 2010 23:59:59 UTC +00:00
+now.all_quarter
+# => Thu, 01 Jul 2010 00:00:00 UTC +00:00..Thu, 30 Sep 2010 23:59:59 UTC +00:00
+now.all_year
+# => Fri, 01 Jan 2010 00:00:00 UTC +00:00..Fri, 31 Dec 2010 23:59:59 UTC +00:00
+</ruby>
+
 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+: