will/cancan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

improving inline documentation

Browse Source
This commit is contained in:
Ryan Bates
2010-05-21 13:41:24 -07:00
parent 7543eedd6a
commit dfd84a10ed
16 changed files with 254 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
lib/cancan/ability.rb
View File

@@ -1,8 +1,8 @@
module CanCan
# This module is designed to be included into an Ability class. This will
# provide the "can" methods for defining and checking abilities.
#
#
# class Ability
# include CanCan::Ability
#
@@ -14,179 +14,180 @@ module CanCan
# end
# end
# end
#
#
module Ability
# Use to check the user's permission for a given action and object.
#
# Use to check if the user has permission to perform a given action on an object.
#
# can? :destroy, @project
#
#
# You can also pass the class instead of an instance (if you don't have one handy).
#
#
# can? :create, Project
#
#
# Any additional arguments will be passed into the "can" block definition. This
# can be used to pass more information about the user's request for example.
#
#
# can? :create, Project, request.remote_ip
#
#
# can :create Project do |project, remote_ip|
# # ...
# end
#
# Not only can you use the can? method in the controller and view (see ControllerAdditions),
#
# Not only can you use the can? method in the controller and view (see ControllerAdditions),
# but you can also call it directly on an ability instance.
#
#
# ability.can? :destroy, @project
#
#
# This makes testing a user's abilities very easy.
#
#
# def test "user can only destroy projects which he owns"
# user = User.new
# ability = Ability.new(user)
# assert ability.can?(:destroy, Project.new(:user => user))
# assert ability.cannot?(:destroy, Project.new)
# end
#
#
# Also see the RSpec Matchers to aid in testing.
def can?(action, subject, *extra_args)
raise Error, "Nom nom nom. I eated it." if action == :has && subject == :cheezburger
can_definition = matching_can_definition(action, subject)
can_definition && can_definition.can?(action, subject, extra_args)
end
# Convenience method which works the same as "can?" but returns the opposite value.
#
#
# cannot? :destroy, @project
#
#
def cannot?(*args)
!can?(*args)
end
# Defines which abilities are allowed using two arguments. The first one is the action
# you're setting the permission for, the second one is the class of object you're setting it on.
#
#
# can :update, Article
#
#
# You can pass an array for either of these parameters to match any one.
#
# can [:update, :destroy], [Article, Comment]
#
# In this case the user has the ability to update or destroy both articles and comments.
#
#
# You can pass a hash of conditions as the third argument.
#
# can :read, Project, :active => true, :user_id => user.id
#
# Here the user can only see active projects which he owns. See ControllerAdditions#conditions for a way to
# use this in database queries.
#
#
# Here the user can only see active projects which he owns. See ActiveRecordAdditions#accessible_by
# for how to use this in database queries.
#
# If the conditions hash does not give you enough control over defining abilities, you can use a block to
# write any Ruby code you want.
#
# can :update, Project do |project|
# project && project.groups.include?(user.group)
# end
#
#
# If the block returns true then the user has that :update ability for that project, otherwise he
# will be denied access. It's possible for the passed in model to be nil if one isn't specified,
# so be sure to take that into consideration.
#
#
# The downside to using a block is that it cannot be used to generate conditions for database queries.
#
#
# You can pass :all to reference every type of object. In this case the object type will be passed
# into the block as well (just in case object is nil).
#
#
# can :read, :all do |object_class, object|
# object_class != Order
# end
#
#
# Here the user has permission to read all objects except orders.
#
# You can also pass :manage as the action which will match any action. In this case the action is
#
# You can also pass :manage as the action which will match any action. In this case the action is
# passed to the block.
#
#
# can :manage, Comment do |action, comment|
# action != :destroy
# end
#
#
# You can pass custom objects into this "can" method, this is usually done through a symbol
# and is useful if a class isn't available to define permissions on.
#
#
# can :read, :stats
# can? :read, :stats # => true
#
#
def can(action, subject, conditions = nil, &block)
can_definitions << CanDefinition.new(true, action, subject, conditions, block)
end
# Define an ability which cannot be done. Accepts the same arguments as "can".
#
# Defines an ability which cannot be done. Accepts the same arguments as "can".
#
# can :read, :all
# cannot :read, Comment
#
#
# A block can be passed just like "can", however if the logic is complex it is recommended
# to use the "can" method.
#
#
# cannot :read, Product do |product|
# product.invisible?
# end
#
#
def cannot(action, subject, conditions = nil, &block)
can_definitions << CanDefinition.new(false, action, subject, conditions, block)
end
# Alias one or more actions into another one.
#
#
# alias_action :update, :destroy, :to => :modify
# can :modify, Comment
#
#
# Then :modify permission will apply to both :update and :destroy requests.
#
#
# can? :update, Comment # => true
# can? :destroy, Comment # => true
#
#
# This only works in one direction. Passing the aliased action into the "can?" call
# will not work because aliases are meant to generate more generic actions.
#
#
# alias_action :update, :destroy, :to => :modify
# can :update, Comment
# can? :modify, Comment # => false
#
#
# Unless that exact alias is used.
#
#
# can :modify, Comment
# can? :modify, Comment # => true
#
#
# The following aliases are added by default for conveniently mapping common controller actions.
#
#
# alias_action :index, :show, :to => :read
# alias_action :new, :to => :create
# alias_action :edit, :to => :update
#
#
# This way one can use params[:action] in the controller to determine the permission.
def alias_action(*args)
target = args.pop[:to]
aliased_actions[target] ||= []
aliased_actions[target] += args
end
# Returns a hash of aliased actions. The key is the target and the value is an array of actions aliasing the key.
def aliased_actions
@aliased_actions ||= default_alias_actions
end
# Removes previously aliased actions including the defaults.
def clear_aliased_actions
@aliased_actions = {}
end
# Returns a hash of conditions which match the given ability. This is useful if you need to generate a database
# query based on the current ability.
#
#
# can :read, Article, :visible => true
# conditions :read, Article # returns { :visible => true }
#
#
# Normally you will not call this method directly, but instead go through ActiveRecordAdditions#accessible_by method.
#
#
# If the ability is not defined then false is returned so be sure to take that into consideration.
# If the ability is defined using a block then this will raise an exception since a hash of conditions cannot be
# determined from that.
@@ -199,7 +200,7 @@ module CanCan
false
end
end
# Returns the associations used in conditions. This is usually used in the :joins option for a search.
# See ActiveRecordAdditions#accessible_by for use in Active Record.
def association_joins(action, subject)
@@ -211,18 +212,18 @@ module CanCan
end
private
def can_definitions
@can_definitions ||= []
end
def matching_can_definition(action, subject)
can_definitions.reverse.detect do |can_definition|
can_definition.expand_actions(aliased_actions)
can_definition.matches? action, subject
end
end
def default_alias_actions
{
:read => [:index, :show],

12
lib/cancan/active_record_additions.rb
View File

@@ -1,5 +1,5 @@
module CanCan
# This module is automatically included into all Active Record.
# This module is automatically included into all Active Record models.
module ActiveRecordAdditions
module ClassMethods
# Returns a scope which fetches only the records that the passed ability
@@ -7,16 +7,16 @@ module CanCan
# is usually called from a controller and passed the +current_ability+.
#
# @articles = Article.accessible_by(current_ability)
#
#
# Here only the articles which the user is able to read will be returned.
# If the user does not have permission to read any articles then an empty
# result is returned. Since this is a scope it can be combined with any
# other scopes or pagination.
#
#
# An alternative action can optionally be passed as a second argument.
#
#
# @articles = Article.accessible_by(current_ability, :update)
#
#
# Here only the articles which the user can update are returned. This
# internally uses Ability#conditions method, see that for more information.
def accessible_by(ability, action = :read)
@@ -29,7 +29,7 @@ module CanCan
end
end
end
def self.included(base)
base.extend ClassMethods
end

34
lib/cancan/can_definition.rb
View File

@@ -1,9 +1,15 @@
module CanCan
# This class is used internally and should only be called through Ability.
# it holds the information about a "can" call made on Ability and provides
# helpful methods to determine permission checking and conditions hash generation.
class CanDefinition # :nodoc:
include ActiveSupport::Inflector
attr_reader :block
# The first argument when initializing is the base_behavior which is a true/false
# value. True for "can" and false for "cannot". The next two arguments are the action
# and subject respectively (such as :read, @project). The third argument is a hash
# of conditions and the last one is the block passed to the "can" call.
def initialize(base_behavior, action, subject, conditions, block)
@base_behavior = base_behavior
@actions = [action].flatten
@@ -11,27 +17,31 @@ module CanCan
@conditions = conditions || {}
@block = block
end
# Accepts a hash of aliased actions and returns an array of actions which match.
# This should be called before "matches?" and other checking methods since they
# rely on the actions to be expanded.
def expand_actions(aliased_actions)
@expanded_actions = @actions.map do |action|
aliased_actions[action] ? [action, *aliased_actions[action]] : action
end.flatten
end
def matches?(action, subject)
matches_action?(action) && matches_subject?(subject)
end
def can?(action, subject, extra_args)
result = can_without_base_behavior?(action, subject, extra_args)
@base_behavior ? result : !result
end
# Returns a hash of conditions. If the ":tableize => true" option is passed
# it will pluralize the association conditions to match the table name.
def conditions(options = {})
if options[:tableize] and @conditions.kind_of? Hash
if options[:tableize] && @conditions.kind_of?(Hash)
@conditions.inject({}) do |tableized_conditions, (name, value)|
name = tableize(name).to_sym if value.kind_of? Hash
tableized_conditions[name] = value
tableized_conditions
end
@@ -54,17 +64,17 @@ module CanCan
end
joins unless joins.empty?
end
private
def matches_action?(action)
@expanded_actions.include?(:manage) || @expanded_actions.include?(action)
end
def matches_subject?(subject)
@subjects.include?(:all) || @subjects.include?(subject) || @subjects.any? { |sub| sub.kind_of?(Class) && subject.kind_of?(sub) }
end
def can_without_base_behavior?(action, subject, extra_args)
if @block
call_block(action, subject, extra_args)
@@ -74,7 +84,7 @@ module CanCan
true
end
end
def matches_conditions?(subject, conditions = @conditions)
conditions.all? do |name, value|
attribute = subject.send(name)
@@ -91,7 +101,7 @@ module CanCan
end
end
end
def call_block(action, subject, extra_args)
block_args = []
block_args << action if @expanded_actions.include?(:manage)

102
lib/cancan/controller_additions.rb
View File

@@ -1,35 +1,35 @@
module CanCan
# This module is automatically included into all controllers.
# It also makes the "can?" and "cannot?" methods available to all views.
module ControllerAdditions
module ClassMethods
# Sets up a before filter which loads and authorizes the current resource. This performs both
# load_resource and authorize_resource and accepts the same arguments. See those methods for details.
#
#
# class BooksController < ApplicationController
# load_and_authorize_resource
# end
#
#
def load_and_authorize_resource(options = {})
ResourceAuthorization.add_before_filter(self, :load_and_authorize_resource, options)
end
# Sets up a before filter which loads the appropriate model resource into an instance variable.
# For example, given an ArticlesController it will load the current article into the @article
# instance variable. It does this by either calling Article.find(params[:id]) or
# Article.new(params[:article]) depending upon the action. It does nothing for the "index"
# action.
#
#
# Call this method directly on the controller class.
#
#
# class BooksController < ApplicationController
# load_resource
# end
#
#
# A resource is not loaded if the instance variable is already set. This makes it easy to override
# the behavior through a before_filter on certain actions.
#
#
# class BooksController < ApplicationController
# before_filter :find_book_by_permalink, :only => :show
# load_resource
@@ -40,107 +40,107 @@ module CanCan
# @book = Book.find_by_permalink!(params[:id)
# end
# end
#
#
# See load_and_authorize_resource to automatically authorize the resource too.
#
#
# Options:
# [:+only+]
# Only applies before filter to given actions.
#
#
# [:+except+]
# Does not apply before filter to given actions.
#
#
# [:+nested+]
# Specify which resource this is nested under.
#
#
# load_resource :nested => :author
#
#
# Deep nesting can be defined in an array.
#
#
# load_resource :nested => [:publisher, :author]
#
#
# [:+resource+]
# The class to use for the model (string or constant).
#
#
# [:+collection+]
# Specify which actions are resource collection actions in addition to :+index+. This
# is usually not necessary because it will try to guess depending on if an :+id+
# is present in +params+.
#
#
# load_resource :collection => [:sort, :list]
#
#
# [:+new+]
# Specify which actions are new resource actions in addition to :+new+ and :+create+.
# Pass an action name into here if you would like to build a new resource instead of
# fetch one.
#
#
# load_resource :new => :build
#
#
def load_resource(options = {})
ResourceAuthorization.add_before_filter(self, :load_resource, options)
end
# Sets up a before filter which authorizes the current resource using the instance variable.
# For example, if you have an ArticlesController it will check the @article instance variable
# and ensure the user can perform the current action on it. Under the hood it is doing
# something like the following.
#
#
# authorize!(params[:action].to_sym, @article || Article)
#
#
# Call this method directly on the controller class.
#
#
# class BooksController < ApplicationController
# authorize_resource
# end
#
#
# See load_and_authorize_resource to automatically load the resource too.
#
#
# Options:
# [:+only+]
# Only applies before filter to given actions.
#
#
# [:+except+]
# Does not apply before filter to given actions.
#
#
# [:+resource+]
# The class to use for the model (string or constant). Alternatively pass a symbol
# to represent a resource which does not have a class.
#
#
def authorize_resource(options = {})
ResourceAuthorization.add_before_filter(self, :authorize_resource, options)
end
end
def self.included(base)
base.extend ClassMethods
base.helper_method :can?, :cannot?
end
# Raises a CanCan::AccessDenied exception if the current_ability cannot
# perform the given action. This is usually called in a controller action or
# before filter to perform the authorization.
#
#
# def show
# @article = Article.find(params[:id])
# authorize! :read, @article
# end
#
#
# A :message option can be passed to specify a different message.
#
#
# authorize! :read, @article, :message => "Not authorized to read #{@article.name}"
#
#
# You can rescue from the exception in the controller to customize how unauthorized
# access is displayed to the user.
#
#
# class ApplicationController < ActionController::Base
# rescue_from CanCan::AccessDenied do |exception|
# flash[:error] = exception.message
# redirect_to root_url
# end
# end
#
#
# See the CanCan::AccessDenied exception for more details on working with the exception.
#
#
# See the load_and_authorize_resource method to automatically add the authorize! behavior
# to the default RESTful actions.
def authorize!(action, subject, *args)
@@ -150,46 +150,46 @@ module CanCan
end
raise AccessDenied.new(message, action, subject) if cannot?(action, subject, *args)
end
def unauthorized!(message = nil)
raise ImplementationRemoved, "The unauthorized! method has been removed from CanCan, use authorize! instead."
end
# Creates and returns the current user's ability and caches it. If you
# want to override how the Ability is defined then this is the place.
# Just define the method in the controller to change behavior.
#
#
# def current_ability
# # instead of Ability.new(current_user)
# @current_ability ||= UserAbility.new(current_account)
# end
#
#
# Notice it is important to cache the ability object so it is not
# recreated every time.
def current_ability
@current_ability ||= ::Ability.new(current_user)
end
# Use in the controller or view to check the user's permission for a given action
# and object.
#
#
# can? :destroy, @project
#
#
# You can also pass the class instead of an instance (if you don't have one handy).
#
#
# <% if can? :create, Project %>
# <%= link_to "New Project", new_project_path %>
# <% end %>
#
#
# This simply calls "can?" on the current_ability. See Ability#can?.
def can?(*args)
current_ability.can?(*args)
end
# Convenience method which works the same as "can?" but returns the opposite value.
#
#
# cannot? :destroy, @project
#
#
def cannot?(*args)
current_ability.cannot?(*args)
end

17
lib/cancan/controller_resource.rb
View File

@@ -1,5 +1,7 @@
module CanCan
# Used internally to load and authorize a given controller resource.
# This manages finding or building an instance of the resource. If a
# parent is given it will go through the association.
class ControllerResource # :nodoc:
def initialize(controller, name, parent = nil, options = {})
raise ImplementationRemoved, "The :class option has been renamed to :resource for specifying the class in CanCan." if options.has_key? :class
@@ -9,6 +11,9 @@ module CanCan
@options = options
end
# Returns the class used for this resource. This can be overriden by the :resource option.
# Sometimes one will use a symbol as the resource if a class does not exist for it. In that
# case "find" and "build" should not be called on it.
def model_class
resource_class = @options[:resource]
if resource_class.nil?
@@ -16,7 +21,7 @@ module CanCan
elsif resource_class.kind_of? String
resource_class.constantize
else
resource_class # likely a symbol
resource_class # could be a symbol
end
end
@@ -24,12 +29,10 @@ module CanCan
self.model_instance ||= base.find(id)
end
# Build a new instance of this resource. If it is a class we just call "new" otherwise
# it's an associaiton and "build" is used.
def build(attributes)
if base.kind_of? Class
self.model_instance ||= base.new(attributes)
else
self.model_instance ||= base.build(attributes)
end
self.model_instance ||= (base.kind_of?(Class) ? base.new(attributes) : base.build(attributes))
end
def model_instance
@@ -42,6 +45,8 @@ module CanCan
private
# The object that methods (such as "find", "new" or "build") are called on.
# If there is a parent it will be the association, otherwise it will be the model's class.
def base
@parent ? @parent.model_instance.send(@name.to_s.pluralize) : model_class
end

22
lib/cancan/exceptions.rb
View File

@@ -1,41 +1,41 @@
module CanCan
# A general CanCan exception
class Error < StandardError; end
# Raised when removed code is called, an alternative solution is provided in message.
class ImplementationRemoved < Error; end
# This error is raised when a user isn't allowed to access a given controller action.
# This usually happens within a call to ControllerAdditions#authorize! but can be
# raised manually.
#
#
# raise CanCan::AccessDenied.new("Not authorized!", :read, Article)
#
#
# The passed message, action, and subject are optional and can later be retrieved when
# rescuing from the exception.
#
#
# exception.message # => "Not authorized!"
# exception.action # => :read
# exception.subject # => Article
#
# If the message is not specified (or is nil) it will default to "You are anot authorized
#
# If the message is not specified (or is nil) it will default to "You are not authorized
# to access this page." This default can be overridden by setting default_message.
#
#
# exception.default_message = "Default error message"
# exception.message # => "Default error message"
#
#
# See ControllerAdditions#authorized! for more information on rescuing from this exception.
class AccessDenied < Error
attr_reader :action, :subject
attr_writer :default_message
def initialize(message = nil, action = nil, subject = nil)
@message = message
@action = action
@subject = subject
@default_message = "You are not authorized to access this page."
end
def to_s
@message || @default_message
end

20
lib/cancan/resource_authorization.rb
View File

@@ -7,18 +7,18 @@ module CanCan
ResourceAuthorization.new(controller, controller.params, options.except(:only, :except)).send(method)
end
end
def initialize(controller, params, options = {})
@controller = controller
@params = params
@options = options
end
def load_and_authorize_resource
load_resource
authorize_resource
end
def load_resource
unless collection_actions.include? @params[:action].to_sym
if new_actions.include? @params[:action].to_sym
@@ -28,17 +28,17 @@ module CanCan
end
end
end
def authorize_resource
@controller.authorize!(@params[:action].to_sym, resource.model_instance || resource.model_class)
end
private
def resource
@resource ||= ControllerResource.new(@controller, model_name, parent_resource, @options)
end
def parent_resource
parent = nil
[@options[:nested]].flatten.compact.each do |name|
@@ -52,15 +52,15 @@ module CanCan
end
parent
end
def model_name
@params[:controller].sub("Controller", "").underscore.split('/').last.singularize
end
def collection_actions
[:index] + [@options[:collection]].flatten
end
def new_actions
[:new, :create] + [@options[:new]].flatten
end