be9-acl9 0.10.0 → 0.11.0

data/CHANGELOG.textile

@@ -1,3 +1,11 @@
+h2. 0.11.0 (16-Sep-2009)
+
+* :protect_global_roles
+* Subject#roles renamed to Subject#role_objects
+* Fix namespaced models in roles backend (thanks goes to Tomas Jogin)
+* Action name override in boolean methods.
+* @:query_method@ option for @access_control@.
+
 h2. 0.10.0 (03-May-2009)
 
 * Use context+matchy combo for testing

data/README.textile

@@ -1,4 +1,4 @@
-h1. Acl9
+h1. Introduction
 
 Acl9 is yet another solution for role-based authorization in Rails. It consists of two
 subsystems which can be used separately.
@@ -38,6 +38,17 @@ An example:
   end
 </code></pre>
 
+h1. Contacts
+
+Acl9 is hosted "on the GitHub":http://github.com/be9/acl9.
+
+You may find tutorials and additional docs on the "wiki page":http://wiki.github.com/be9/acl9.
+
+Rdocs are available "here":http://rdoc.info/projects/be9/acl9.
+
+If you have questions, please post to the 
+"acl9-discuss group":http://groups.google.com/group/acl9-discuss
+
 h1. Installation
 
 Acl9 can be installed as a gem from "GitHub":http://github.com.
@@ -875,5 +886,3 @@ An imaginary view:
 </code></pre>
 
 Copyright (c) 2009 Oleg Dashevskii, released under the MIT license.
-
-Contact me at "#{%w(Oleg Dashevskii).join('').downcase}@gmail.com"

data/Rakefile

@@ -27,3 +27,13 @@ Rake::TestTask.new(:test) do |test|
   test.pattern = 'test/**/*_test.rb'
   test.verbose = false
 end
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb']
+    #t.options = ['--any', '--extra', '--opts'] # optional
+  end
+rescue LoadError
+end

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:minor: 10
+:minor: 11
 :patch: 0
 :major: 0

data/lib/acl9/config.rb

@@ -3,6 +3,7 @@ module Acl9
     :default_role_class_name => 'Role',
     :default_subject_class_name => 'User',
     :default_subject_method => :current_user,
+    :protect_global_roles => false,
   }
 
   mattr_reader :config

data/lib/acl9/controller_extensions.rb

@@ -46,18 +46,39 @@ module Acl9
 
         method = opts[:as_method]
 
+        query_method_available = true
         generator = case
                     when method && filter
                       Acl9::Dsl::Generators::FilterMethod.new(subject_method, method)
                     when method && !filter
+                      query_method_available = false
                       Acl9::Dsl::Generators::BooleanMethod.new(subject_method, method)
                     else
                       Acl9::Dsl::Generators::FilterLambda.new(subject_method)
                     end
 
         generator.acl_block!(&block)
-        
+
         generator.install_on(self, opts)
+
+        if query_method_available && (query_method = opts.delete(:query_method))
+          case query_method
+          when true
+            if method
+              query_method = "#{method}?"
+            else
+              raise ArgumentError, "You must specify :query_method as Symbol"
+            end
+          when Symbol, String
+            # okay here
+          else
+            raise ArgumentError, "Invalid value for :query_method"
+          end
+
+          second_generator = Acl9::Dsl::Generators::BooleanMethod.new(subject_method, query_method)
+          second_generator.acl_block!(&block)
+          second_generator.install_on(self, opts)
+        end
       end
     end
   end

data/lib/acl9/controller_extensions/dsl_base.rb

@@ -95,9 +95,13 @@ module Acl9
 
       alias action actions
 
+      def logged_in; false end
       def anonymous; nil   end
       def all;       true  end
-      def logged_in; false end
+
+      alias everyone all
+      alias everybody all
+      alias anyone all
 
       def _parse_and_add_rule(*args)
         options = args.extract_options!
@@ -108,9 +112,9 @@ module Acl9
 
         role_checks = args.map do |who|
           case who
-          when nil   then "#{_subject_ref}.nil?"    # anonymous
-          when false then "!#{_subject_ref}.nil?"   # logged_in
-          when true  then "true"                # all
+          when anonymous() then "#{_subject_ref}.nil?"
+          when logged_in() then "!#{_subject_ref}.nil?"
+          when all()       then "true"
           else
             "!#{_subject_ref}.nil? && #{_subject_ref}.has_role?('#{who.to_s.singularize}', #{object})"
           end

data/lib/acl9/controller_extensions/generators.rb

@@ -1,7 +1,35 @@
 require File.join(File.dirname(__FILE__), 'dsl_base')
 
 module Acl9
+  ##
+  # This exception is raised whenever ACL block finds that the current user
+  # is not authorized for the controller action he wants to execute.
+  # @example How to catch this exception in ApplicationController
+  #   class ApplicationController < ActionController::Base
+  #     rescue_from 'Acl9::AccessDenied', :with => :access_denied
+  #
+  #     # ...other stuff...
+  #     private
+  #
+  #     def access_denied
+  #       if current_user
+  #         # It's presumed you have a template with words of pity and regret
+  #         # for unhappy user who is not authorized to do what he wanted
+  #         render :template => 'home/access_denied'
+  #       else
+  #         # In this case user has not even logged in. Might be OK after login.
+  #         flash[:notice] = 'Access denied. Try to log in first.'
+  #         redirect_to login_path
+  #       end
+  #     end
+  #   end
+  #
   class AccessDenied < StandardError; end
+
+  ##
+  # This exception is raised when acl9 has generated invalid code for the
+  # filtering method or block. Should never happen, and it's a bug when it
+  # happens.
   class FilterSyntaxError < StandardError; end
 
   module Dsl
@@ -49,7 +77,7 @@ module Acl9
           logger.debug self.to_s
           logger.debug "======"
         end
-        
+
         def logger
           ActionController::Base.logger
         end
@@ -76,13 +104,15 @@ module Acl9
               end
             end
           RUBY
-          
+
           self.instance_eval(code, __FILE__, __LINE__)
         rescue SyntaxError
           raise FilterSyntaxError, code
         end
       end
-      
+
+      ################################################################
+
       class FilterMethod < BaseGenerator
         def initialize(subject_method, method_name)
           super
@@ -90,7 +120,7 @@ module Acl9
           @method_name = method_name
           @controller = nil
         end
-        
+
         def install_on(controller_class, options)
           super
           _add_method(controller_class)
@@ -105,7 +135,7 @@ module Acl9
         rescue SyntaxError
           raise FilterSyntaxError, code
         end
-        
+
         def to_method_code
           <<-RUBY
             def #{@method_name}
@@ -116,7 +146,9 @@ module Acl9
           RUBY
         end
       end
-      
+
+      ################################################################
+
       class BooleanMethod < FilterMethod
         def install_on(controller_class, opts)
           debug_dump(controller_class) if opts[:debug]
@@ -128,12 +160,20 @@ module Acl9
           end
         end
 
-        protected 
-        
+        protected
+
         def to_method_code
           <<-RUBY
-            def #{@method_name}(options = {})
-              #{allowance_expression}
+            def #{@method_name}(*args)
+              options = args.extract_options!
+
+              unless args.size <= 1
+                raise ArgumentError, "call #{@method_name} with 0, 1 or 2 arguments"
+              end
+
+              action_name = args.empty? ? self.action_name : args.first.to_s
+
+              return #{allowance_expression}
             end
           RUBY
         end
@@ -143,6 +183,8 @@ module Acl9
         end
       end
 
+      ################################################################
+
       class HelperMethod < BooleanMethod
         def initialize(subject_method, method)
           super

data/lib/acl9/helpers.rb

@@ -8,9 +8,9 @@ module Acl9
       def access_control(method, opts = {}, &block)
         subject_method = opts.delete(:subject_method) || Acl9::config[:default_subject_method]
         raise ArgumentError, "Block must be supplied to access_control" unless block
-      
+
         generator = Acl9::Dsl::Generators::HelperMethod.new(subject_method, method)
-        
+
         generator.acl_block!(&block)
         generator.install_on(self, opts)
       end

data/lib/acl9/model_extensions.rb

@@ -2,29 +2,75 @@ require File.join(File.dirname(__FILE__), 'model_extensions', 'subject')
 require File.join(File.dirname(__FILE__), 'model_extensions', 'object')
 
 module Acl9
-  module ModelExtensions
+  module ModelExtensions  #:nodoc:
     def self.included(base)
       base.extend(ClassMethods)
     end
 
     module ClassMethods
+      # Add #has_role? and other role methods to the class.
+      # Makes a class a auth. subject class.
+      #
+      # @param [Hash] options the options for tuning
+      # @option options [String] :role_class_name (Acl9::config[:default_role_class_name])
+      #                           Class name of the role class (e.g. 'AccountRole')
+      # @option options [String] :join_table_name (Acl9::config[:default_join_table_name])
+      #                           Join table name (e.g. 'accounts_account_roles')
+      # @example
+      #   class User < ActiveRecord::Base
+      #     acts_as_authorization_subject
+      #   end
+      #
+      #   user = User.new
+      #   user.roles             #=> returns Role objects, associated with the user
+      #   user.has_role!(...)
+      #   user.has_no_role!(...)
+      #
+      #   # other functions from Acl9::ModelExtensions::Subject are made available
+      #
+      # @see Acl9::ModelExtensions::Subject
+      #
       def acts_as_authorization_subject(options = {})
         role = options[:role_class_name] || Acl9::config[:default_role_class_name]
-        has_and_belongs_to_many :roles, :class_name => role
+        join_table = options[:join_table_name] || Acl9::config[:default_join_table_name] ||
+                    join_table_name(undecorated_table_name(self.to_s), undecorated_table_name(role))
+
+        has_and_belongs_to_many :role_objects, :class_name => role, :join_table => join_table
 
         cattr_accessor :_auth_role_class_name
         self._auth_role_class_name = role
 
-        include Acl9::ModelExtensions::Subject 
+        include Acl9::ModelExtensions::Subject
       end
 
+      # Add role query and set methods to the class (making it an auth object class).
+      #
+      # @param [Hash] options the options for tuning
+      # @option options [String] :subject_class_name (Acl9::config[:default_subject_class_name])
+      #                          Subject class name (e.g. 'User', or 'Account)
+      # @option options [String] :role_class_name (Acl9::config[:default_role_class_name])
+      #                          Role class name (e.g. 'AccountRole')
+      # @example
+      #   class Product < ActiveRecord::Base
+      #     acts_as_authorization_object
+      #   end
+      #
+      #   product = Product.new
+      #   product.accepted_roles #=> returns Role objects, associated with the product
+      #   product.users          #=> returns User objects, associated with the product
+      #   product.accepts_role!(...)
+      #   product.accepts_no_role!(...)
+      #   # other functions from Acl9::ModelExtensions::Object are made available
+      #
+      # @see Acl9::ModelExtensions::Object
+      #
       def acts_as_authorization_object(options = {})
         subject = options[:subject_class_name] || Acl9::config[:default_subject_class_name]
-        subj_table = subject.tableize
+        subj_table = subject.constantize.table_name
         subj_col = subject.underscore
 
         role       = options[:role_class_name] || Acl9::config[:default_role_class_name]
-        role_table = role.tableize
+        role_table = role.constantize.table_name
 
         sql_tables = <<-EOS
           FROM #{subj_table}
@@ -36,21 +82,49 @@ module Acl9
           WHERE authorizable_type = '#{self.class.base_class.to_s}'
           AND authorizable_id = #{id}
         EOS
-        
+
         has_many :accepted_roles, :as => :authorizable, :class_name => role, :dependent => :destroy
 
         has_many :"#{subj_table}",
           :finder_sql  => ("SELECT DISTINCT #{subj_table}.*" + sql_tables + sql_where),
           :counter_sql => ("SELECT COUNT(DISTINCT #{subj_table}.id)" + sql_tables + sql_where),
           :readonly => true
-        
+
         include Acl9::ModelExtensions::Object
       end
 
+      # Make a class an auth role class.
+      #
+      # You'll probably never create or use objects of this class directly.
+      # Various auth. subject and object methods will do that for you
+      # internally.
+      #
+      # @param [Hash] options the options for tuning
+      # @option options [String] :subject_class_name (Acl9::config[:default_subject_class_name])
+      #                          Subject class name (e.g. 'User', or 'Account)
+      # @option options [String] :join_table_name (Acl9::config[:default_join_table_name])
+      #                           Join table name (e.g. 'accounts_account_roles')
+      #
+      # @example
+      #   class Role < ActiveRecord::Base
+      #     acts_as_authorization_role
+      #   end
+      #
+      # @see Acl9::ModelExtensions::Subject#has_role!
+      # @see Acl9::ModelExtensions::Subject#has_role?
+      # @see Acl9::ModelExtensions::Subject#has_no_role!
+      # @see Acl9::ModelExtensions::Object#accepts_role!
+      # @see Acl9::ModelExtensions::Object#accepts_role?
+      # @see Acl9::ModelExtensions::Object#accepts_no_role!
       def acts_as_authorization_role(options = {})
         subject = options[:subject_class_name] || Acl9::config[:default_subject_class_name]
+        join_table = options[:join_table_name] || Acl9::config[:default_join_table_name] ||
+                     join_table_name(undecorated_table_name(self.to_s), undecorated_table_name(subject))
+
+        has_and_belongs_to_many subject.demodulize.tableize.to_sym,
+          :class_name => subject,
+          :join_table => join_table
 
-        has_and_belongs_to_many subject.tableize.to_sym
         belongs_to :authorizable, :polymorphic => true
       end
     end

data/lib/acl9/model_extensions/object.rb

@@ -1,24 +1,56 @@
 module Acl9
   module ModelExtensions
     module Object
+      ##
+      # Role check.
+      #
+      # @return [Boolean] Returns true if +subject+ has a role +role_name+ on this object.
+      #
+      # @param [Symbol,String] role_name Role name
+      # @param [Subject] subject Subject to add role for
+      # @see Acl9::ModelExtensions::Subject#has_role?
       def accepts_role?(role_name, subject)
         subject.has_role? role_name, self
       end
 
+      ##
+      # Add role on the object to specified subject.
+      #
+      # @param [Symbol,String] role_name Role name
+      # @param [Subject] subject Subject to add role for
+      # @see Acl9::ModelExtensions::Subject#has_role!
       def accepts_role!(role_name, subject)
         subject.has_role! role_name, self
       end
 
+      ##
+      # Free specified subject of a role on this object.
+      #
+      # @param [Symbol,String] role_name Role name
+      # @param [Subject] subject Subject to remove role from
+      # @see Acl9::ModelExtensions::Subject#has_no_role!
       def accepts_no_role!(role_name, subject)
         subject.has_no_role! role_name, self
       end
 
+      ##
+      # Are there any roles for the specified +subject+ on this object?
+      #
+      # @param [Subject] subject Subject to query roles
+      # @return [Boolean] Returns true if +subject+ has any roles on this object.
+      # @see Acl9::ModelExtensions::Subject#has_roles_for?
       def accepts_roles_by?(subject)
         subject.has_roles_for? self
       end
 
       alias :accepts_role_by? :accepts_roles_by?
 
+      ##
+      # Which roles does +subject+ have on this object?
+      #
+      # @return [Array<Role>] Role instances, associated both with +subject+ and +object+
+      # @param [Subject] subject Subject to query roles
+      # @see Acl9::ModelExtensions::Subject#roles_for
       def accepted_roles_by(subject)
         subject.roles_for self
       end