cancan 1.1.1 → 1.2.0

data/lib/cancan/controller_additions.rb

@@ -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,117 @@ 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]
-      #   
+      #
+      # [:+name+]
+      #   The name of the resource if it cannot be determined from controller (string or symbol).
+      #
+      #     load_resource :name => :article
+      #
       # [:+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.
-      # 
+      #
+      # [:+name+]
+      #   The name of the resource if it cannot be determined from controller (string or symbol).
+      #
+      #     load_resource :name => :article
+      #
       # [:+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 +160,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

data/lib/cancan/controller_resource.rb

@@ -1,4 +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
@@ -8,13 +11,17 @@ 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
-      if @options[:resource].nil?
+      resource_class = @options[:resource]
+      if resource_class.nil?
         @name.to_s.camelize.constantize
-      elsif @options[:resource].kind_of? String
-        @options[:resource].constantize
+      elsif resource_class.kind_of? String
+        resource_class.constantize
       else
-        @options[:resource]
+        resource_class # could be a symbol
       end
     end
     
@@ -22,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
@@ -40,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

data/lib/cancan/exceptions.rb

@@ -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

data/lib/cancan/resource_authorization.rb

@@ -1,44 +1,46 @@
 module CanCan
+  # Handle the load and authorization controller logic so we don't clutter up all controllers with non-interface methods.
+  # This class is used internally, so you do not need to call methods directly on it.
   class ResourceAuthorization # :nodoc:
-    attr_reader :params
-    
     def self.add_before_filter(controller_class, method, options = {})
       controller_class.before_filter(options.slice(:only, :except)) do |controller|
         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
-          resource.build(params[model_name.to_sym])
-        elsif params[:id]
-          resource.find(params[:id])
+      if collection_actions.include? @params[:action].to_sym
+        parent_resource
+      else
+        if new_actions.include? @params[:action].to_sym
+          resource.build(@params[model_name.to_sym])
+        elsif @params[:id]
+          resource.find(@params[:id])
         end
       end
     end
-    
+
     def authorize_resource
-      @controller.authorize!(params[:action].to_sym, resource.model_instance || resource.model_class)
+      @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 +54,15 @@ module CanCan
       end
       parent
     end
-    
+
     def model_name
-      params[:controller].sub("Controller", "").underscore.split('/').last.singularize
+      @options[: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

data/spec/cancan/ability_spec.rb

@@ -5,17 +5,17 @@ describe CanCan::Ability do
     @ability = Object.new
     @ability.extend(CanCan::Ability)
   end
-  
+
   it "should be able to :read anything" do
     @ability.can :read, :all
     @ability.can?(:read, String).should be_true
     @ability.can?(:read, 123).should be_true
   end
-  
+
   it "should not have permission to do something it doesn't know about" do
     @ability.can?(:foodfight, String).should be_false
   end
-  
+
   it "should return what block returns on a can call" do
     @ability.can :read, :all
     @ability.can :read, Symbol do |sym|
@@ -24,21 +24,21 @@ describe CanCan::Ability do
     @ability.can?(:read, Symbol).should be_nil
     @ability.can?(:read, :some_symbol).should == :some_symbol
   end
-  
+
   it "should pass class with object if :all objects are accepted" do
     @ability.can :preview, :all do |object_class, object|
       [object_class, object]
     end
     @ability.can?(:preview, 123).should == [Fixnum, 123]
   end
-  
+
   it "should pass class with no object if :all objects are accepted and class is passed directly" do
     @ability.can :preview, :all do |object_class, object|
       [object_class, object]
     end
     @ability.can?(:preview, Hash).should == [Hash, nil]
   end
-  
+
   it "should pass action and object for global manage actions" do
     @ability.can :manage, Array do |action, object|
       [action, object]
@@ -46,14 +46,14 @@ describe CanCan::Ability do
     @ability.can?(:stuff, [1, 2]).should == [:stuff, [1, 2]]
     @ability.can?(:stuff, Array).should == [:stuff, nil]
   end
-  
+
   it "should alias update or destroy actions to modify action" do
     @ability.alias_action :update, :destroy, :to => :modify
     @ability.can(:modify, :all) { :modify_called }
     @ability.can?(:update, 123).should == :modify_called
     @ability.can?(:destroy, 123).should == :modify_called
   end
-  
+
   it "should return block result for action, object_class, and object for any action" do
     @ability.can :manage, :all do |action, object_class, object|
       [action, object_class, object]
@@ -61,56 +61,56 @@ describe CanCan::Ability do
     @ability.can?(:foo, 123).should == [:foo, Fixnum, 123]
     @ability.can?(:bar, Fixnum).should == [:bar, Fixnum, nil]
   end
-  
+
   it "should automatically alias index and show into read calls" do
     @ability.can :read, :all
     @ability.can?(:index, 123).should be_true
     @ability.can?(:show, 123).should be_true
   end
-  
+
   it "should automatically alias new and edit into create and update respectively" do
     @ability.can(:create, :all) { :create_called }
     @ability.can(:update, :all) { :update_called }
     @ability.can?(:new, 123).should == :create_called
     @ability.can?(:edit, 123).should == :update_called
   end
-  
+
   it "should not respond to prepare (now using initialize)" do
     @ability.should_not respond_to(:prepare)
   end
-  
+
   it "should offer cannot? method which is simply invert of can?" do
     @ability.cannot?(:tie, String).should be_true
   end
-  
+
   it "should be able to specify multiple actions and match any" do
     @ability.can [:read, :update], :all
     @ability.can?(:read, 123).should be_true
     @ability.can?(:update, 123).should be_true
     @ability.can?(:count, 123).should be_false
   end
-  
+
   it "should be able to specify multiple classes and match any" do
     @ability.can :update, [String, Array]
     @ability.can?(:update, "foo").should be_true
     @ability.can?(:update, []).should be_true
     @ability.can?(:update, 123).should be_false
   end
-  
+
   it "should support custom objects in the can definition" do
     @ability.can :read, :stats
     @ability.can?(:read, :stats).should be_true
     @ability.can?(:update, :stats).should be_false
     @ability.can?(:read, :nonstats).should be_false
   end
-  
+
   it "should support 'cannot' method to define what user cannot do" do
     @ability.can :read, :all
     @ability.cannot :read, Integer
     @ability.can?(:read, "foo").should be_true
     @ability.can?(:read, 123).should be_false
   end
-  
+
   it "should support block on 'cannot' method" do
     @ability.can :read, :all
     @ability.cannot :read, Integer do |int|
@@ -120,19 +120,19 @@ describe CanCan::Ability do
     @ability.can?(:read, 3).should be_true
     @ability.can?(:read, 123).should be_false
   end
-  
+
   it "should append aliased actions" do
     @ability.alias_action :update, :to => :modify
     @ability.alias_action :destroy, :to => :modify
     @ability.aliased_actions[:modify].should == [:update, :destroy]
   end
-  
+
   it "should clear aliased actions" do
     @ability.alias_action :update, :to => :modify
     @ability.clear_aliased_actions
     @ability.aliased_actions[:modify].should be_nil
   end
-  
+
   it "should pass additional arguments to block from can?" do
     @ability.can :read, Integer do |int, x|
       int > x
@@ -140,52 +140,64 @@ describe CanCan::Ability do
     @ability.can?(:read, 2, 1).should be_true
     @ability.can?(:read, 2, 3).should be_false
   end
-  
+
   it "should use conditions as third parameter and determine abilities from it" do
     @ability.can :read, Array, :first => 1, :last => 3
     @ability.can?(:read, [1, 2, 3]).should be_true
     @ability.can?(:read, [1, 2, 3, 4]).should be_false
     @ability.can?(:read, Array).should be_true
   end
-  
+
   it "should allow an array of options in conditions hash" do
     @ability.can :read, Array, :first => [1, 3, 5]
     @ability.can?(:read, [1, 2, 3]).should be_true
     @ability.can?(:read, [2, 3]).should be_false
     @ability.can?(:read, [3, 4]).should be_true
   end
-  
+
   it "should allow a range of options in conditions hash" do
     @ability.can :read, Array, :first => 1..3
     @ability.can?(:read, [1, 2, 3]).should be_true
     @ability.can?(:read, [3, 4]).should be_true
     @ability.can?(:read, [4, 5]).should be_false
   end
-  
+
   it "should allow nested hashes in conditions hash" do
     @ability.can :read, Array, :first => { :length => 5 }
     @ability.can?(:read, ["foo", "bar"]).should be_false
     @ability.can?(:read, ["test1", "foo"]).should be_true
   end
-  
+
+  it "should allow nested hash of arrays and match any element" do
+    @ability.can :read, Array, :first => { :to_i => 3 }
+    @ability.can?(:read, [[1, 2, 3]]).should be_true
+    @ability.can?(:read, [[4, 5, 6]]).should be_false
+  end
+
   it "should return conditions for a given ability" do
     @ability.can :read, Array, :first => 1, :last => 3
     @ability.conditions(:show, Array).should == {:first => 1, :last => 3}
   end
-  
+
   it "should raise an exception when a block is used on condition" do
     @ability.can :read, Array do |a|
       true
     end
     lambda { @ability.conditions(:show, Array) }.should raise_error(CanCan::Error, "Cannot determine ability conditions from block for :show Array")
   end
-  
+
   it "should return an empty hash for conditions when there are no conditions" do
     @ability.can :read, Array
     @ability.conditions(:show, Array).should == {}
   end
-  
+
   it "should return false when performed on an action which isn't defined" do
     @ability.conditions(:foo, Array).should == false
   end
+
+  it "should has eated cheezburger" do
+    lambda {
+      @ability.can? :has, :cheezburger
+    }.should raise_exception(CanCan::Error, "Nom nom nom. I eated it.")
+  end
 end