Permalink
Browse files

document the AR none method [ci skip]

  • Loading branch information...
vijaydev committed Feb 1, 2012
1 parent 5850ea0 commit 479f3b4054b7db8c0f9bd325c0e27c918223e02b
@@ -201,26 +201,26 @@ def lock(locks = true)
#
# The returned NullRelation inherits from Relation and implements the
# Null Object pattern so it is an object with defined null behavior:
- # it always returns an empty array of records and avoids any database query.
+ # it always returns an empty array of records and does not query the database.
#
# Any subsequent condition chained to the returned relation will continue
# generating an empty relation and will not fire any query to the database.
#
- # Used in cases where is needed a method or a scope that could return zero
- # results but the response has to be chainable.
+ # This is useful in scenarios where you need a chainable response to a method
+ # or a scope that could return zero results.
#
# For example:
#
# @posts = current_user.visible_posts.where(:name => params[:name])
- # # => the visible_post method response has to be a chainable Relation
+ # # => the visible_posts method is expected to return a chainable Relation
#
# def visible_posts
# case role
- # if 'Country Manager'
+ # when 'Country Manager'
# Post.where(:country => country)
- # if 'Reviewer'
+ # when 'Reviewer'
# Post.published
- # if 'Bad User'
+ # when 'Bad User'

This comment has been minimized.

Show comment Hide comment
@carlosantoniodasilva

carlosantoniodasilva Feb 1, 2012

Owner

I think you might have some conflict when merging docrails later on, I've done the same change there :D. Just ignore my commit if necessary.

@carlosantoniodasilva

carlosantoniodasilva Feb 1, 2012

Owner

I think you might have some conflict when merging docrails later on, I've done the same change there :D. Just ignore my commit if necessary.

This comment has been minimized.

Show comment Hide comment
@vijaydev

vijaydev Feb 1, 2012

Member

No problem :)

@vijaydev

vijaydev Feb 1, 2012

Member

No problem :)

# Post.none # => returning [] instead breaks the previous code
# end
# end
@@ -608,6 +608,30 @@ SELECT * FROM clients WHERE orders_count > 10 ORDER BY clients.id DESC
This method accepts *no* arguments.
+h3. Null Relation
+
+The +none+ method returns a chainable relation with no records. Any subsequent conditions chained to the returned relation will continue generating empty relations. This is useful in scenarios where you need a chainable response to a method or a scope that could return zero results.
+
+<ruby>
+Post.none # returns an empty Relation and fires no queries.
+</ruby>
+
+<ruby>
+# The visible_posts method below is expected to return a Relation.
+@posts = current_user.visible_posts.where(:name => params[:name])
+
+def visible_posts
+ case role
+ when 'Country Manager'
+ Post.where(:country => country)
+ when 'Reviewer'
+ Post.published
+ when 'Bad User'
+ Post.none # => returning [] or nil breaks the caller code in this case
+ end
+end
+</ruby>
+
h3. Readonly Objects
Active Record provides +readonly+ method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.

0 comments on commit 479f3b4

Please sign in to comment.