@@ -3,3 +3,5 @@ pkg *.sw? *.log +.yardoc +doc .gitignore @@ -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 Rakefile @@ -56,7 +56,7 @@ module Acl9 end generator.acl_block!(&block) - + generator.install_on(self, opts) end end lib/acl9/controller_extensions.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 lib/acl9/controller_extensions/generators.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 lib/acl9/helpers.rb @@ -2,23 +2,68 @@ 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] - 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)) + 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 :roles, :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.constantize.table_name @@ -37,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 + 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 + belongs_to :authorizable, :polymorphic => true end end lib/acl9/model_extensions.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 lib/acl9/model_extensions/object.rb @@ -1,6 +1,14 @@ module Acl9 module ModelExtensions module Subject + ## + # Role check. + # + # @return [Boolean] Returns true if +self+ has a role +role_name+ on +object+. + # + # @param [Symbol,String] role_name Role name + # @param [Object] object Object to query a role on + # @see Acl9::ModelExtensions::Object#accepts_role? def has_role?(role_name, object = nil) !! if object.nil? self.roles.find_by_name(role_name.to_s) || @@ -11,6 +19,12 @@ module Acl9 end end + ## + # Add specified role on +object+ to +self+. + # + # @param [Symbol,String] role_name Role name + # @param [Object] object Object to add a role for + # @see Acl9::ModelExtensions::Object#accepts_role! def has_role!(role_name, object = nil) role = get_role(role_name, object) @@ -27,24 +41,53 @@ module Acl9 self.roles << role if role && !self.roles.exists?( role.id ) end + ## + # Free +self+ from a specified role on +object+. + # + # @param [Symbol,String] role_name Role name + # @param [Object] object Object to remove a role on + # @see Acl9::ModelExtensions::Object#accepts_no_role! def has_no_role!(role_name, object = nil) delete_role(get_role(role_name, object)) end + ## + # Are there any roles for +self+ on +object+? + # + # @param [Object] object Object to query roles + # @return [Boolean] Returns true if +self+ has any roles on +object+. + # @see Acl9::ModelExtensions::Object#accepts_roles_by? def has_roles_for?(object) !!self.roles.detect(&role_selecting_lambda(object)) end alias :has_role_for? :has_roles_for? + ## + # Which roles does +self+ have on +object+? + # + # @return [Array<Role>] Role instances, associated both with +self+ and +object+ + # @param [Object] object Object to query roles + # @see Acl9::ModelExtensions::Object#accepted_roles_by + # @example + # user = User.find(...) + # product = Product.find(...) + # + # user.roles_for(product).map(&:name).sort #=> role names in alphabetical order def roles_for(object) self.roles.select(&role_selecting_lambda(object)) end + ## + # Unassign any roles on +object+ from +self+. + # + # @param [Object,nil] object Object to unassign roles for. +nil+ means unassign global roles. def has_no_roles_for!(object = nil) roles_for(object).each { |role| delete_role(role) } end + ## + # Unassign all roles from +self+. def has_no_roles! # for some reason simple # lib/acl9/model_extensions/subject.rb 3215f4a571de072e383fd6a174eadfe8e0c39445 oleg dashevskii be9@be9.ru http://github.com/be9/acl9/commit/ea1643f8fd038a55503475eadd8fa1d81e8234a4 ea1643f8fd038a55503475eadd8fa1d81e8234a4 2009-06-09T02:37:28-07:00 2009-06-09T02:37:28-07:00 YARD docs have been added to the roles backend. a32865be561388f012eef3acfddbf4fd73b5b56a oleg dashevskii be9@be9.ru