roles_generic 0.2.7 → 0.3.3

data/README.markdown

@@ -1,26 +1,38 @@
-# Generic Role strategies
+# Generic Roles
 
-Generic role strategies that share the same API and are easy to insert in any existing User model. 
-Comes with a Rails 3 generator to instantly configure your Rails 3 app with a Role strategy of choice.
+Generic Roles is a common (generic) Roles API and implementation that specific Roles implementations for various ORMs can implement.
+This library also comes with a Rails 3 generator that can configure an existing user model with a Role strategy of choice.
+A similar generator should always be created for specific ORM implementations 
 
-I have developed the following *roles* gems for popular ORMs that all support the same roles generic API.
+I have developed the following *roles* gems for popular Object Mappers that all support the same Roles Generic API.
 
-* Active Record - [roles_active_record](http://github.com/kristianmandrup/roles_active_record)
-* DataMapper - [roles_data_mapper](http://github.com/kristianmandrup/roles_data_mapper)
-* Mongoid - [roles_mongoid](http://github.com/kristianmandrup/roles_mongoid)
-* MongoMapper - [roles_mongo_mapper](http://github.com/kristianmandrup/roles_mongo_mapper))
+Relational Database (SQL)
+* Active Record   - [roles_active_record](http://github.com/kristianmandrup/roles_active_record)
+* Data Mapper     - [roles_data_mapper](http://github.com/kristianmandrup/roles_data_mapper)
 
-Feel free to roll your own ORM extension for your favorite ORM!
+Mongo DB
+* Mongoid         - [roles_mongoid](http://github.com/kristianmandrup/roles_mongoid)
+* Mongo Mapper    - [roles_mongo_mapper](http://github.com/kristianmandrup/roles_mongo_mapper)  
 
+Couch DB
+* Simply Stored   - [roles_simply_stored](http://github.com/kristianmandrup/roles_simply_stored)
 
-## Status update (12 sept, 2010)
-
-Roles generic has now been refactored in order to tidy up the code base and make it even more generic, flexible and easy to extend. It should now work! Please let me know if you have any issues ;)
+Note: Feel free to roll your own ORM extension for your favorite Object Mapper!
 
 ## Install
 
 <code>gem install roles_generic</code>
 
+## Roles generator
+
+A Rails 3 generator is included to update an existing model with a roles strategy and a set of valid roles
+
+### Usage example
+
+<code>rails g roles_generic:roles --strategy admin_flag --roles guest admin</code>  
+
+This generator is currently (Oct. 10) experimental. Feel free to provide patches or bug reports ;)
+
 ## Usage
 
 The library comes with the following role models built-in:
@@ -61,7 +73,7 @@ Creates and uses a binary field 'admin_flag', which when true signals that this
   end
 </pre>
 
-## Example: Using an ORM
+## Example: Using an Object Mapper
 
 Data Mapper with persistent attributes :name and :admin_flag
 

data/Rakefile

@@ -7,13 +7,15 @@ begin
     gem.email = "kmandrup@gmail.com"
     gem.homepage = "http://github.com/kristianmandrup/roles_for_mm"
     gem.authors = ["Kristian Mandrup"]
-    gem.add_development_dependency "rspec",           "~> 2.0.0.beta.22"
-    gem.add_development_dependency "generator-spec",  "~> 0.6.5"
+    gem.add_development_dependency "rspec",           ">= 2.0.0"
+    gem.add_development_dependency "generator-spec",  ">= 0.7"
 
     gem.add_dependency "require_all",       "~> 1.2.0"
-    gem.add_dependency "activesupport",     "~> 3.0.0"    
-    gem.add_dependency 'sugar-high',        "~> 0.2.10" 
-    gem.add_dependency 'rails3_artifactor', '~> 0.2.5'
+    gem.add_dependency "activesupport",     ">= 3.0"    
+    gem.add_dependency 'sugar-high',        "~> 0.3.0" 
+    gem.add_dependency 'rails3_artifactor', '~> 0.3.1'
+    gem.add_dependency 'logging_assist',    '>= 0.1.6'
+
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.2.7
+0.3.3

data/lib/generators/{roles_model → roles_generic}/roles/roles_generator.rb

@@ -1,6 +1,6 @@
 require 'rails3_artifactor'
 
-module RolesModel 
+module RolesGeneric 
   module Generators
     class RolesGenerator < Rails::Generators::NamedBase
       include Rails3::Assist::Artifact::Model
@@ -12,18 +12,10 @@ module RolesModel
 
 
       class_option :roles, :type => :array, :aliases => "-r", :default => [], :desc => "Valid roles"
-      # TODO: Should detect ORM from file content instead!
-      class_option :orm, :type => :string, :aliases => "-o", :default => nil, :desc => "ORM of model"
-
 
       # hook_for :orm
             
-      def self.source_root
-        @source_root ||= File.expand_path("../../templates", __FILE__)
-      end
-
-      def apply_role_strategy        
-        self.class.use_orm orm if orm
+      def apply_role_strategy
         insert_into_model name do
           insertion_text
         end
@@ -31,10 +23,6 @@ module RolesModel
       
       protected                  
 
-      def orm
-        @orm ||= options[:orm].to_s.to_sym        
-      end
-
       def default_roles
         [:admin, :guest]        
       end
@@ -51,14 +39,19 @@ module RolesModel
         "strategy :#{strategy}\n"
       end
 
+      def role_class_statement
+        [:one_role, :many_roles].include?(strategy.to_sym) ? 'role_class :role' : ''
+      end
+
       def roles_statement
-        roles ? "valid_roles #{roles.join(',')}" : ''
+        roles ? "valid_roles_are #{roles.join(',')}" : ''
       end
 
       def insertion_text
         %Q{  
   include Roles::#{orm.to_s.camelize} 
   #{role_strategy_statement}
+  #{role_class_statement}
   #{roles_statement}
 }
       end

data/lib/roles_generic/base.rb

@@ -1,11 +1,23 @@
 module Roles
   module Base
     attr_accessor :orm_name
+    attr_reader :role_strategy
 
     def valid_roles_are(*role_list)
       strategy_class.valid_roles = role_list.to_symbols
     end
 
+    def valid_role? role
+      strategy_class.valid_roles.include? role.to_sym
+    end
+
+    def valid_roles? *role_names
+      role_names.each do |role|
+        return false if !strategy_class.valid_roles.include? role.to_sym
+      end
+      true
+    end
+
     def valid_roles
       strategy_class.valid_roles
     end
@@ -14,15 +26,41 @@ module Roles
       strategy_class.valid_roles = Array[*roles].flatten.map { |r| r.to_sym }
     end
     
-    def role_strategy strategy_name, options=nil
+    def set_role_strategy strategy_name, options=nil
       include_strategy orm_name, strategy_name, options
     end  
+
+    class RoleStrategyId
+      attr_accessor :name
+
+      def initialize strategy_name
+        @name = strategy_name.to_s.underscore.to_sym        
+      end
+
+      def type
+        @type ||= case name
+        when :one_role, :many_roles
+          :complex
+        else
+          return :simple if name
+        end
+      end
+
+      def multiplicity
+        @multiplicity ||= case name
+        when :many_roles, :role_strings, :roles_mask, :roles_string
+          :multi
+        when :one_role, :admin_flag, :role_string
+          :single
+        end      
+      end
+    end
          
     def include_strategy orm, strategy_name, options=nil 
       begin     
         module_name = "RoleStrategy::#{orm_name.to_s.camelize}::#{strategy_name.to_s.camelize}"
         constant = module_name.constantize
-
+        @role_strategy = RoleStrategyId.new strategy_name
         strategy_class_method = %Q{
           def strategy_class
             #{constant} 

data/lib/roles_generic/generic/role.rb

@@ -1,24 +1,10 @@
 module Roles::Generic::Role
-  module InstanceMethods
+  module InstanceMethods        
     def role_class
       self.class.role_class_name
     end  
-
-    def get_roles _roles
-      raise "Role class #{role_class} does not have a #find_role(role) method" if !role_class.respond_to? :find_role
-      _roles = _roles.flatten.compact    
-      _roles = _roles.select{|role| role.kind_of?(role_class) || role.kind_of_label?}
-      _roles.map! do |role| 
-        case role
-        when role_class
-          role.name
-        else
-          role.to_s
-        end
-      end        
-    end
   end
-
+  
   module ClassMethods 
     def role_class_name
       @role_class_name          

data/lib/roles_generic/generic/role_util.rb

@@ -0,0 +1,30 @@
+module Roles::Generic::RoleUtil
+  # extract role symbols from roles
+  # should handle symbols, strings, arrays and Role instances
+  def extract_roles *roles
+    roles.flatten.map{|role| extract_role role}.compact
+  end
+
+  def extract_role role
+    role = case role
+    when Array
+      role.flat_uniq.first
+    else
+      role
+    end
+
+    if defined?(Role) && role.kind_of?(Role)
+      raise 'Role instances should have a #name method that reflects the role name' if !role.respond_to? :name
+      return role.name.to_s.to_sym
+    end
+
+    case role
+    when String, Symbol
+      role.to_sym
+    else
+      nil
+    end
+  end
+  
+  extend self
+end

data/lib/roles_generic/generic/user/implementation.rb

@@ -1,29 +1,131 @@
 module Roles::Generic::User
-  module Implementation
+  module Implementation 
+    include Roles::Generic::RoleUtil    
+    
     def role_attribute
       strategy_class.roles_attribute_name
     end       
 
+    # set a single role
+    def role= role
+      raise ArgumentError, '#add_role takes a single role String or Symbol as the argument' if !role || role.kind_of?(Array)
+      self.roles = role
+    end
+
+    # add a single role
+    def add_role role
+      raise ArgumentError, '#add_role takes a single role String or Symbol as the argument' if !role || role.kind_of?(Array)
+      add_roles role
+    end
+
+    # remove a single role
+    def remove_role role
+      raise ArgumentError, '#remove_role takes a single role String or Symbol as the argument' if !role || role.kind_of?(Array)
+      remove_roles role
+    end
+
+    # should exchange the current role if in list with the first valid role in :with argument
+    def exchange_roles *role_names
+      options = last_option role_names
+      raise ArgumentError, "Must take an options hash as last argument with a :with option signifying which role(s) to replace with" if !options || !options.kind_of?(Hash)        
+      remove_roles(role_names.to_symbols)        
+      with_roles = options[:with]
+      add_roles(with_roles)
+    end
+    
+    def exchange_role role, options = {}
+      raise ArgumentError, '#exchange_role takes a single role String or Symbol as the first argument' if !role || role.kind_of?(Array)
+      raise ArgumentError, '#exchange_role takes a an options hash with a :with option as the last argument' if !options || !options[:with]
+      if options[:with].kind_of?(Array) && self.class.role_strategy.multiplicity == :single                                                                                          
+        raise ArgumentError, '#exchange_role should only take a single role to exchange with for a Role strategy with multiplicity of one' if options[:with].size > 1
+      end 
+      exchange_roles role, options
+    end
+
     # check if a given role has been assigned 
     # if a list of roles: check if ALL of the given roles have been assigned 
-    def has_roles?(*roles)
-      (roles_list - roles.flatten).empty?      
+    def has_roles?(*roles_names)
+      compare_roles = extract_roles(roles_names.flat_uniq)
+      (roles_list & compare_roles).not.empty?      
     end
 
     # check if any (at least ONE) of the given roles have been assigned
-    def has_role? *roles
-      (roles_list & roles.flatten).not.empty?            
+    def has_role? role_name
+      raise ArgumentError, '#has_role? should take a single role String or Symbol as the argument' if !role_name || role_name.kind_of?(Array)
+      has_roles? role_name
     end
 
     def valid_role? role
       strategy_class.valid_roles.include? role.to_sym
     end
 
+    def valid_roles? *roles
+      roles.each do |role|
+        return false if !valid_role? role
+      end
+      true
+    end
+
+    def valid_roles
+      strategy_class.valid_roles
+    end
+
     def admin?
       is? :admin
     end
+
+    # assign multiple roles
+    def roles=(*role_names)
+      role_names = role_names.flat_uniq
+      role_names = extract_roles(role_names)
+      return nil if role_names.empty?
+      set_roles(select_valid_roles role_names)
+    end
+
+    # query assigned roles
+    def roles
+      return [] if get_roles.nil?
+      x = [get_roles].flatten.map do |role|
+        role.respond_to?(:to_sym) ? role.to_sym : role
+      end    
+      x.first.kind_of?(Set) ? x.first.to_a : x
+    end
            
     alias_method :has?, :has_role?
-    alias_method :is?, :has_roles?        
+    alias_method :is?,  :has_roles? 
+    
+    protected
+
+    def set_role role
+      self.send("#{role_attribute}=", new_role(role))
+    end
+    alias_method :set_roles, :set_role
+    
+    def get_role
+      r = self.send(role_attribute)
+      respond_to?(:present_role) ? present_role(r) : r
+    end
+
+    def get_roles
+      r = self.send(role_attribute)
+      respond_to?(:present_roles) ? present_roles(r) : r
+    end
+    
+    def set_roles *roles                      
+      self.send("#{role_attribute}=", new_roles(roles))
+    end
+
+    def roles_diff *roles
+      self.roles_list - extract_roles(roles.flat_uniq)
+    end
+    
+    def select_valid_roles *role_names
+      role_names = role_names.flat_uniq.select{|role| valid_role? role }
+      has_role_class? ? role_class.find_roles(role_names).to_a : role_names
+    end           
+        
+    def has_role_class?
+      self.respond_to?(:role_class)      
+    end
   end
 end    

data/lib/roles_generic/generic/user/multi_impl.rb

@@ -0,0 +1,27 @@
+module Roles::Generic::User
+  module Implementation
+    module Multi           
+      def add_roles *roles
+        new_roles = select_valid_roles(roles)        
+        if !new_roles.empty?
+          self.roles = self.roles + new_roles
+        end
+      end      
+      
+      # should remove the current single role (set = nil) 
+      # only if it is contained in the list of roles to be removed
+      def remove_roles *role_names
+        role_names = role_names.flat_uniq
+        set_empty_roles and return if roles_diff(role_names).empty?
+        roles_to_remove = select_valid_roles(role_names)
+        self.roles = roles_diff(role_names)
+        true
+      end
+
+      def roles_list
+        my_roles = [roles].flat_uniq
+        my_roles.empty? ? [] : my_roles
+      end      
+    end
+  end
+end

data/lib/roles_generic/generic/user/single_impl.rb

@@ -0,0 +1,24 @@
+module Roles::Generic::User
+  module Implementation
+    module Single
+      # assigns first valid role from list of roles
+      def add_roles *role_names
+        new_roles = select_valid_roles(role_names)
+        self.role = new_roles.first if !new_roles.empty?
+      end
+
+      # should remove the current single role (set = nil) 
+      # only if it is contained in the list of roles to be removed
+      def remove_roles *role_names
+        roles = role_names.flat_uniq
+        set_empty_role if roles_diff(roles).empty?
+        true
+      end 
+      
+      def roles_list
+        raise 'the method #roles should be present' if !respond_to? :roles
+        roles 
+      end      
+    end
+  end
+end

data/lib/roles_generic/generic.rb

@@ -24,7 +24,7 @@ module Roles
         if options == :default && MAP[name]
           instance_eval MAP[name] 
         end
-        role_strategy name, options
+        set_role_strategy name, options
       end    
     end
   end

data/lib/roles_generic/role.rb

@@ -13,6 +13,7 @@ class Role
   attr_accessor :name
   
   def self.find_role role_name    
+    role_name = Roles::Generic::RoleUtil.extract_role(role_name)
     roles.to_a.select do |r| 
       r.name.to_sym == role_name.to_sym
     end.first

data/lib/roles_generic/rspec/api/completeness.rb

@@ -0,0 +1,22 @@
+describe 'Roles Generic API : Completeness test' do
+  before :each do
+    default_user_setup    
+  end
+
+  it "should be true that a User that includes Roles::Generic has a complete Roles::Generic interface" do
+    # mutation API
+    [:roles=, :role=, :add_roles, :add_role, :remove_role, :remove_roles, :exchange_roles, :exchange_role].each do |api_method|
+      @admin_user.respond_to?(api_method).should be_true
+    end
+
+    # inspection API
+    [:valid_role?, :valid_roles?, :has_roles?, :has_role?, :has?, :is?, :roles, :roles_list, :admin?].each do |api_method|
+      @admin_user.respond_to?(api_method).should be_true
+    end                  
+
+    # class method API
+    [:valid_role?, :valid_roles?, :valid_roles].each do |class_api_method|
+      @admin_user.class.respond_to?(class_api_method).should be_true
+    end
+  end
+end

data/lib/roles_generic/rspec/api/full.rb

@@ -0,0 +1,5 @@
+require "roles_generic/rspec/user_setup"                                           
+require "roles_generic/rspec/api/write_api"
+require "roles_generic/rspec/api/read_api"
+require "roles_generic/rspec/api/user_class_api"
+require "roles_generic/rspec/api/completeness"

data/lib/roles_generic/rspec/api/read_api.rb

@@ -0,0 +1,119 @@
+class Role
+end
+
+describe 'Roles Generic API : READ' do
+  before :each do
+    default_user_setup    
+  end
+
+  describe '#valid_role?' do
+    it "should be true that the admin user has a valid role of :guest" do      
+      @admin_user.valid_role?(:guest).should be_true
+    end
+  end
+  
+  describe '#valid_roles' do
+    it "should be true that the admin user has a valid role of :guest" do      
+      @admin_user.valid_roles.should include(:guest, :admin)
+    end  
+  end
+  
+  describe '#valid_roles?' do
+    it "should be true that the admin user has a valid role of :guest" do      
+      @admin_user.valid_roles?(:guest, :admin).should be_true
+    end
+  
+    it "should be true that the User class has a valid role of :guest" do      
+      User.valid_roles?(:guest, :admin).should be_true
+    end
+  end
+  
+  describe '#has_role?' do     
+    it "should have admin user role to :admin and not to :user" do            
+      @admin_user.has_role?(:user).should be_false
+      @admin_user.has_role?(:admin).should be_true
+    end
+  
+    it "should be true that guest user has role :user and not :admin" do      
+      @guest_user.has_role?(:guest).should be_true    
+      @guest_user.has_role?(:admin).should be_false
+    end
+  end
+  
+  describe '#has?' do    
+    it "should be true that the admin_user has the :admin role" do      
+      @admin_user.has?(:admin).should be_true      
+    end
+  
+    it "should NOT be true that the admin_user has the :admin role" do      
+      @guest_user.has?(:admin).should be_false
+    end
+  end
+  
+  describe '#has_roles?' do
+    it "should be true that the admin_user has the roles :admin" do      
+      @admin_user.has_roles?(:admin).should be_true
+    end
+  
+    it "should NOT be true that the user has the roles :admin" do
+      @guest_user.has_roles?(:admin).should be_false
+    end
+  end
+  
+  describe '#roles_list' do
+    it "should be true that the first role of admin_user is the :admin role" do      
+      @admin_user.roles_list.should include(:admin)
+    end
+  
+    it "should be true that the first role of admin_user is the :user role" do            
+      case @normal_user.class.role_strategy.multiplicity
+      when :single
+        if @normal_user.class.role_strategy.name == :admin_flag
+          @normal_user.roles_list.should include(:guest)
+        else
+          @normal_user.roles_list.should include(:user)
+        end
+      when :multi
+        @normal_user.roles_list.should include(:user, :guest)
+      end
+    end
+  end  
+  
+  describe '#roles' do
+    it "should be true that the roles of admin_user is an array with the role :admin" do      
+      roles = @admin_user.roles
+      if roles.kind_of? Role
+        roles.name.to_sym.should == :admin
+      elsif roles.kind_of? Array
+        if @normal_user.class.role_strategy.type == :complex
+          # roles.first.name.to_sym.should == :admin
+          roles.first.to_sym.should == :admin
+        else
+          roles.first.to_sym.should == :admin          
+        end
+      else       
+        roles.to_sym.should == :admin
+      end
+    end
+  end 
+  
+  describe '#admin?' do    
+    it "should be true that admin_user is in the :admin role" do      
+      @admin_user.admin?.should be_true
+    end
+  
+    it "should NOT be true that the user is in the :admin role" do      
+      @guest_user.admin?.should be_false
+    end
+  end
+  
+  describe '#is?' do          
+    it "should be true that admin_user is in the :admin role" do      
+      @admin_user.is?(:admin).should be_true
+    end
+  
+    it "should NOT be true that the user is in the :admin role" do      
+      @guest_user.is?(:admin).should be_false
+    end
+  end  
+end

data/lib/roles_generic/rspec/api/simple_check.rb

@@ -0,0 +1,11 @@
+describe 'Roles Generic API : READ' do
+  before :each do
+    default_user_setup    
+  end
+
+  describe '#valid_role?' do
+    it "should be true that the admin user has a valid role of :guest" do      
+      @admin_user.valid_role?(:guest).should be_true
+    end
+  end
+end

data/lib/roles_generic/rspec/api/user_class_api.rb

@@ -0,0 +1,31 @@
+describe 'Roles Generic API : User class' do
+  describe '#in_role' do
+    it "should return first user matching role" do        
+      if User.respond_to? :in_role
+        User.in_role(:guest).first.name.should == 'Guest user'
+        User.in_role(:admin).first.name.should == 'Admin user'
+      end
+    end
+  end
+
+  describe '#in_roles' do
+    it "should return first user matching role" do        
+      if User.respond_to? :in_roles
+        User.in_roles(:guest, :user).first.name.should == 'Guest user'      
+        User.in_roles(:admin, :guest).should be_empty
+      end
+    end
+  end
+  
+  describe '#valid_role?' do
+    it "should be true that the User class has a valid role of :guest" do      
+      User.valid_role?(:guest).should be_true
+    end
+  end  
+  
+  describe '#valid_roles' do
+    it "should be true that the User class has a valid role of :guest" do      
+      User.valid_roles.should include(:guest, :admin)
+    end
+  end  
+end