diff --git a/actionmailer/README.rdoc b/actionmailer/README.rdoc index b52c993f56..602326eef7 100644 --- a/actionmailer/README.rdoc +++ b/actionmailer/README.rdoc @@ -65,8 +65,8 @@ simply call the method and optionally call +deliver+ on the return value. Calling the method returns a Mail Message object: - message = Notifier.welcome #=> Returns a Mail::Message object - message.deliver #=> delivers the email + message = Notifier.welcome # => Returns a Mail::Message object + message.deliver # => delivers the email Or you can just chain the methods together like: diff --git a/activemodel/README.rdoc b/activemodel/README.rdoc index 89cacbcab4..73c58a87db 100644 --- a/activemodel/README.rdoc +++ b/activemodel/README.rdoc @@ -107,8 +107,8 @@ modules: extend ActiveModel::Naming end - NamedPerson.model_name #=> "NamedPerson" - NamedPerson.model_name.human #=> "Named person" + NamedPerson.model_name # => "NamedPerson" + NamedPerson.model_name.human # => "Named person" {Learn more}[link:classes/ActiveModel/Naming.html] @@ -139,7 +139,7 @@ modules: end Person.human_attribute_name('my_attribute') - #=> "My attribute" + # => "My attribute" {Learn more}[link:classes/ActiveModel/Translation.html] @@ -157,7 +157,7 @@ modules: person = Person.new person.first_name = 'zoolander' - person.valid? #=> false + person.valid? # => false {Learn more}[link:classes/ActiveModel/Validations.html] @@ -176,9 +176,9 @@ modules: end p = ValidatorPerson.new - p.valid? #=> false - p.errors.full_messages #=> ["Name must exist"] + p.valid? # => false + p.errors.full_messages # => ["Name must exist"] p.name = "Bob" - p.valid? #=> true + p.valid? # => true {Learn more}[link:classes/ActiveModel/Validator.html] diff --git a/activemodel/lib/active_model/serializers/json.rb b/activemodel/lib/active_model/serializers/json.rb index e1dbc522de..cf1c4a0fed 100644 --- a/activemodel/lib/active_model/serializers/json.rb +++ b/activemodel/lib/active_model/serializers/json.rb @@ -18,9 +18,9 @@ module ActiveModel # Returns a JSON string representing the model. Some configuration can be # passed through +options+. # - # The option ActiveModel::Base.include_root_in_json controls the - # top-level behavior of +to_json+. If true (the default) +to_json+ will - # emit a single root node named after the object's type. For example: + # The option include_root_in_json controls the top-level behavior + # of +to_json+. If true (the default) +to_json+ will emit a single root + # node named after the object's type. For example: # # konata = User.find(1) # konata.to_json diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG index 20b2286fc0..972c907c46 100644 --- a/activerecord/CHANGELOG +++ b/activerecord/CHANGELOG @@ -966,7 +966,7 @@ during calendar reform. #7649, #7724 [fedot, Geoff Buesing] * Made increment_counter/decrement_counter play nicely with optimistic locking, and added a more general update_counters method [Jamis Buck] * Reworked David's query cache to be available as Model.cache {...}. For the duration of the block no select query should be run more then once. Any inserts/deletes/executes will flush the whole cache however [Tobias Lütke] - Task.cache { Task.find(1); Task.find(1) } #=> 1 query + Task.cache { Task.find(1); Task.find(1) } # => 1 query * When dealing with SQLite3, use the table_info pragma helper, so that the bindings can do some translation for when sqlite3 breaks incompatibly between point releases. [Jamis Buck] diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 73c0900c8b..8be36482d4 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -311,7 +311,8 @@ module ActiveRecord # You can set the :autosave option on a has_one, belongs_to, # has_many, or has_and_belongs_to_many association. Setting it # to +true+ will _always_ save the members, whereas setting it to +false+ will - # _never_ save the members. + # _never_ save the members. More details about :autosave option is available at + # autosave_association.rb . # # === One-to-one associations # @@ -956,8 +957,7 @@ module ActiveRecord # If false, don't validate the associated objects when saving the parent object. true by default. # [:autosave] # If true, always save the associated objects or destroy them if marked for destruction, - # when saving the parent object. - # If false, never save or destroy the associated objects. + # when saving the parent object. If false, never save or destroy the associated objects. # By default, only save associated objects that are new records. # [:inverse_of] # Specifies the name of the belongs_to association on the associated object diff --git a/activerecord/lib/active_record/autosave_association.rb b/activerecord/lib/active_record/autosave_association.rb index 2c7afe3c9f..131591405c 100644 --- a/activerecord/lib/active_record/autosave_association.rb +++ b/activerecord/lib/active_record/autosave_association.rb @@ -3,13 +3,13 @@ require 'active_support/core_ext/array/wrap' module ActiveRecord # = Active Record Autosave Association # - # AutosaveAssociation is a module that takes care of automatically saving - # associacted records when parent is saved. In addition to saving, it + # +AutosaveAssociation+ is a module that takes care of automatically saving + # associacted records when their parent is saved. In addition to saving, it # also destroys any associated records that were marked for destruction. - # (See mark_for_destruction and marked_for_destruction?) + # (See +mark_for_destruction+ and marked_for_destruction?). # # Saving of the parent, its associations, and the destruction of marked - # associations, all happen inside 1 transaction. This should never leave the + # associations, all happen inside a transaction. This should never leave the # database in an inconsistent state. # # If validations for any of the associations fail, their error messages will @@ -18,6 +18,9 @@ module ActiveRecord # Note that it also means that associations marked for destruction won't # be destroyed directly. They will however still be marked for destruction. # + # Note that :autosave => false is not same as not declaring :autosave. + # When the :autosave option is not present new associations are saved. + # # === One-to-one Example # # class Post @@ -28,7 +31,7 @@ module ActiveRecord # automatically _and_ atomically: # # post = Post.find(1) - # post.title # => "The current global position of migrating ducks" + # post.title # => "The current global position of migrating ducks" # post.author.name # => "alloy" # # post.title = "On the migration of ducks" @@ -36,7 +39,7 @@ module ActiveRecord # # post.save # post.reload - # post.title # => "On the migration of ducks" + # post.title # => "On the migration of ducks" # post.author.name # => "Eloy Duran" # # Destroying an associated model, as part of the parent's save action, is as @@ -46,6 +49,7 @@ module ActiveRecord # post.author.marked_for_destruction? # => true # # Note that the model is _not_ yet removed from the database: + # # id = post.author.id # Author.find_by_id(id).nil? # => false # @@ -53,40 +57,49 @@ module ActiveRecord # post.reload.author # => nil # # Now it _is_ removed from the database: + # # Author.find_by_id(id).nil? # => true # # === One-to-many Example # - # Consider a Post model with many Comments: + # When :autosave is not declared new children are saved when their parent is saved: + # + # class Post + # has_many :comments # :autosave option is no declared + # end + # + # post = Post.new(:title => 'ruby rocks') + # post.comments.build(:body => 'hello world') + # post.save # => saves both post and comment + # + # post = Post.create(:title => 'ruby rocks') + # post.comments.build(:body => 'hello world') + # post.save # => saves both post and comment + # + # post = Post.create(:title => 'ruby rocks') + # post.comments.create(:body => 'hello world') + # post.save # => saves both post and comment + # + # When :autosave is true all children is saved, no matter whether they are new records: # # class Post # has_many :comments, :autosave => true # end # - # Saving changes to the parent and its associated model can now be performed - # automatically _and_ atomically: + # post = Post.create(:title => 'ruby rocks') + # post.comments.create(:body => 'hello world') + # post.comments[0].body = 'hi everyone' + # post.save # => saves both post and comment, with 'hi everyone' as title # - # post = Post.find(1) - # post.title # => "The current global position of migrating ducks" - # post.comments.first.body # => "Wow, awesome info thanks!" - # post.comments.last.body # => "Actually, your article should be named differently." - # - # post.title = "On the migration of ducks" - # post.comments.last.body = "Actually, your article should be named differently. [UPDATED]: You are right, thanks." - # - # post.save - # post.reload - # post.title # => "On the migration of ducks" - # post.comments.last.body # => "Actually, your article should be named differently. [UPDATED]: You are right, thanks." - # - # Destroying one of the associated models members, as part of the parent's - # save action, is as simple as marking it for destruction: + # Destroying one of the associated models as part of the parent's save action + # is as simple as marking it for destruction: # # post.comments.last.mark_for_destruction # post.comments.last.marked_for_destruction? # => true # post.comments.length # => 2 # # Note that the model is _not_ yet removed from the database: + # # id = post.comments.last.id # Comment.find_by_id(id).nil? # => false # @@ -94,37 +107,13 @@ module ActiveRecord # post.reload.comments.length # => 1 # # Now it _is_ removed from the database: + # # Comment.find_by_id(id).nil? # => true # # === Validation # - # Validation is performed on the parent as usual, but also on all autosave - # enabled associations. If any of the associations fail validation, its - # error messages will be applied on the parents errors object and validation - # of the parent will fail. - # - # Consider a Post model with Author which validates the presence of its name - # attribute: - # - # class Post - # has_one :author, :autosave => true - # end - # - # class Author - # validates_presence_of :name - # end - # - # post = Post.find(1) - # post.author.name = '' - # post.save # => false - # post.errors # => #["can't be blank"]}, @base=#> - # - # No validations will be performed on the associated models when validations - # are skipped for the parent: - # - # post = Post.find(1) - # post.author.name = '' - # post.save(:validate => false) # => true + # Validations on children records are run or not depending on the :validate + # option of the association. module AutosaveAssociation extend ActiveSupport::Concern diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 8da4fbcba7..4b550eb446 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -1147,6 +1147,16 @@ MSG # class Person < ActiveRecord::Base # default_scope order('last_name, first_name') # end + # + # default_scope is also applied while creating/building a record. It is not + # applied while updating a record. + # + # class Article < ActiveRecord::Base + # default_scope where(:published => true) + # end + # + # Article.new.published # => true + # Article.create.published # => true def default_scope(options = {}) self.default_scoping << construct_finder_arel(options, default_scoping.pop) end diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb index 0e560418dc..bffc450f8e 100644 --- a/activerecord/lib/active_record/named_scope.rb +++ b/activerecord/lib/active_record/named_scope.rb @@ -88,6 +88,15 @@ module ActiveRecord # end # end # end + # + # Scopes can also be used while creating/building a record. + # + # class Article < ActiveRecord::Base + # scope :published, where(:published => true) + # end + # + # Article.published.new.published # => true + # Article.published.create.published # => true def scope(name, scope_options = {}, &block) name = name.to_sym valid_scope_name?(name) diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb index 7f47a812eb..8295fd68b3 100644 --- a/activerecord/lib/active_record/reflection.rb +++ b/activerecord/lib/active_record/reflection.rb @@ -41,7 +41,7 @@ module ActiveRecord # Returns the AggregateReflection object for the named +aggregation+ (use the symbol). # - # Account.reflect_on_aggregation(:balance) #=> the balance AggregateReflection + # Account.reflect_on_aggregation(:balance) # => the balance AggregateReflection # def reflect_on_aggregation(aggregation) reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil diff --git a/activeresource/README.rdoc b/activeresource/README.rdoc index 127ac5b4a9..ad58eaf5fd 100644 --- a/activeresource/README.rdoc +++ b/activeresource/README.rdoc @@ -34,7 +34,7 @@ lifecycle methods that operate against a persistent store. # Find a person with id = 1 ryan = Person.find(1) - Person.exists?(1) #=> true + Person.exists?(1) # => true As you can see, the methods are quite similar to Active Record's methods for dealing with database records. But rather than dealing directly with a database record, you're dealing with HTTP resources (which may or may not be database records). @@ -69,8 +69,8 @@ for a request for a single element, the XML of that item is expected in response The XML document that is received is used to build a new object of type Person, with each XML element becoming an attribute on the object. - ryan.is_a? Person #=> true - ryan.attribute1 #=> 'value1' + ryan.is_a? Person # => true + ryan.attribute1 # => 'value1' Any complex element (one that contains other elements) becomes its own object: @@ -81,8 +81,8 @@ Any complex element (one that contains other elements) becomes its own object: # for GET http://api.people.com:3000/people/1.xml # ryan = Person.find(1) - ryan.complex #=> - ryan.complex.attribute2 #=> 'value2' + ryan.complex # => + ryan.complex.attribute2 # => 'value2' Collections can also be requested in a similar fashion @@ -96,8 +96,8 @@ Collections can also be requested in a similar fashion # for GET http://api.people.com:3000/people.xml # people = Person.find(:all) - people.first #=> 'Ryan' ...> - people.last #=> 'Jim' ...> + people.first # => 'Ryan' ...> + people.last # => 'Jim' ...> ==== Create @@ -118,10 +118,10 @@ as the id of the ARes object. # Response (201): Location: http://api.people.com:3000/people/2 # ryan = Person.new(:first => 'Ryan') - ryan.new? #=> true - ryan.save #=> true - ryan.new? #=> false - ryan.id #=> 2 + ryan.new? # => true + ryan.save # => true + ryan.new? # => false + ryan.id # => 2 ==== Update @@ -139,9 +139,9 @@ server side was successful. # is expected with code (204) # ryan = Person.find(1) - ryan.first #=> 'Ryan' + ryan.first # => 'Ryan' ryan.first = 'Rizzle' - ryan.save #=> true + ryan.save # => true ==== Delete @@ -155,10 +155,10 @@ Destruction of a resource can be invoked as a class and instance method of the r # is expected with response code (200) # ryan = Person.find(1) - ryan.destroy #=> true - ryan.exists? #=> false - Person.delete(2) #=> true - Person.exists?(2) #=> false + ryan.destroy # => true + ryan.exists? # => false + Person.delete(2) # => true + Person.exists?(2) # => false You can find more usage information in the ActiveResource::Base documentation. diff --git a/activesupport/CHANGELOG b/activesupport/CHANGELOG index 8485e7d46b..53e4d19804 100644 --- a/activesupport/CHANGELOG +++ b/activesupport/CHANGELOG @@ -245,8 +245,8 @@ ActiveSupport.escape_html_entities_in_json from true to false to match previousl * Add Array#in_groups which splits or iterates over the array in specified number of groups. #579. [Adrian Mugnolo] Example: a = (1..10).to_a - a.in_groups(3) #=> [[1, 2, 3, 4], [5, 6, 7, nil], [8, 9, 10, nil]] - a.in_groups(3, false) #=> [[1, 2, 3, 4], [5, 6, 7], [8, 9, 10]] + a.in_groups(3) # => [[1, 2, 3, 4], [5, 6, 7, nil], [8, 9, 10, nil]] + a.in_groups(3, false) # => [[1, 2, 3, 4], [5, 6, 7], [8, 9, 10]] * Fix TimeWithZone unmarshaling: coerce unmarshaled Time instances to utc, because Ruby's marshaling of Time instances doesn't respect the zone [Geoff Buesing] @@ -942,7 +942,7 @@ public for compatibility. [Jeremy Kemper] * Enhance Symbol#to_proc so it works with list objects, such as multi-dimensional arrays. Closes #5295 [nov@yo.rim.or.jp]. Example: {1 => "one", 2 => "two", 3 => "three"}.sort_by(&:first).map(&:last) - #=> ["one", "two", "three"] + # => ["one", "two", "three"] * Added Hash.create_from_xml(string) which will create a hash from a XML string and even typecast if possible [David Heinemeier Hansson]. Example: diff --git a/activesupport/lib/active_support/core_ext/class/attribute.rb b/activesupport/lib/active_support/core_ext/class/attribute.rb index bfa57fe1f7..79d5c40e5f 100644 --- a/activesupport/lib/active_support/core_ext/class/attribute.rb +++ b/activesupport/lib/active_support/core_ext/class/attribute.rb @@ -29,19 +29,19 @@ class Class # In such cases, you don't want to do changes in places but use setters: # # Base.setting = [] - # Base.setting #=> [] - # Subclass.setting #=> [] + # Base.setting # => [] + # Subclass.setting # => [] # # # Appending in child changes both parent and child because it is the same object: # Subclass.setting << :foo - # Base.setting #=> [:foo] - # Subclass.setting #=> [:foo] + # Base.setting # => [:foo] + # Subclass.setting # => [:foo] # # # Use setters to not propagate changes: # Base.setting = [] # Subclass.setting += [:foo] - # Base.setting #=> [] - # Subclass.setting #=> [:foo] + # Base.setting # => [] + # Subclass.setting # => [:foo] # # For convenience, a query method is defined as well: # diff --git a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb index 4e35b1b488..a903735acf 100644 --- a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb +++ b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb @@ -12,8 +12,8 @@ require 'active_support/core_ext/array/extract_options' # end # # Person.hair_colors = [:brown, :black, :blonde, :red] -# Person.hair_colors #=> [:brown, :black, :blonde, :red] -# Person.new.hair_colors #=> [:brown, :black, :blonde, :red] +# Person.hair_colors # => [:brown, :black, :blonde, :red] +# Person.new.hair_colors # => [:brown, :black, :blonde, :red] # # To opt out of the instance writer method, pass :instance_writer => false. # To opt out of the instance reader method, pass :instance_reader => false. diff --git a/activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb b/activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb index e844cf50d1..6891c66839 100644 --- a/activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb +++ b/activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb @@ -22,8 +22,8 @@ end # end # # Person.hair_colors = [:brown, :black, :blonde, :red] -# Person.hair_colors #=> [:brown, :black, :blonde, :red] -# Person.new.hair_colors #=> [:brown, :black, :blonde, :red] +# Person.hair_colors # => [:brown, :black, :blonde, :red] +# Person.new.hair_colors # => [:brown, :black, :blonde, :red] # # To opt out of the instance writer method, pass :instance_writer => false. # To opt out of the instance reader method, pass :instance_reader => false. diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index b1ee4b8be4..fd1e7f4baf 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -550,7 +550,7 @@ build_customer create_customer -h6. _association_(force_reload = false) +h6. association(force_reload = false) The association method returns the associated object, if any. If no associated object is found, it returns +nil+. diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile index 8ce0001080..6372c606b7 100644 --- a/railties/guides/source/security.textile +++ b/railties/guides/source/security.textile @@ -371,7 +371,7 @@ The mass-assignment feature may become a problem, as it allows an attacker to se def signup - params[:user] #=> {:name => “ow3ned”, :admin => true} + params[:user] # => {:name => “ow3ned”, :admin => true} @user = User.new(params[:user]) end @@ -385,7 +385,7 @@ Mass-assignment saves you much work, because you don't have to set each value in This will set the following parameters in the controller: -params[:user] #=> {:name => “ow3ned”, :admin => true} +params[:user] # => {:name => “ow3ned”, :admin => true} So if you create a new user using mass-assignment, it may be too easy to become an administrator. @@ -423,11 +423,11 @@ attr_accessible :name If you want to set a protected attribute, you will to have to assign it individually: -params[:user] #=> {:name => "ow3ned", :admin => true} +params[:user] # => {:name => "ow3ned", :admin => true} @user = User.new(params[:user]) -@user.admin #=> false # not mass-assigned +@user.admin # => false # not mass-assigned @user.admin = true -@user.admin #=> true +@user.admin # => true A more paranoid technique to protect your whole project would be to enforce that all models whitelist their accessible attributes. This can be easily achieved with a very simple initializer: