roles_generic 0.1.1 → 0.2.0

data/README.markdown

@@ -1,14 +1,30 @@
-# Roles Model base
+# Generic Role strategies
 
 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.
 
-*Update: Now with a Rails 3 generator to instantly populate your user model of choice with a role strategy!*
+I am in the process of developing multiple *roles_xxx* gems in order to support this generic API for various popular ORMs, such as:
 
-# Install
+* Active Record (roles_ar)
+* DataMapper (roles_dm_)
+* Mongoid (roles_mongoid)
+* MongoMapper (roles_mm)
+
+Feel free to roll your own ORM extension for your favorite ORM!
+
+## Status update (4 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.
+
+Currently I'm not sure if the generator fully works. It has a dependency on *rails3_artifactor*, which should work.
+However my gem to test generators (called *generator-spec*), is currently not functioning as it has dependencies to other gems that have undergone major
+refactorings lately. Let me know if the generator works or if not, see if you can make it work using *rails3_artifactor* and let me know the fix ;) 
+
+## Install
 
 <code>gem install roles_generic</code>
 
-# Usage
+## Usage
 
 The library comes with the following role models built-in:
 
@@ -22,13 +38,15 @@ The library comes with the following role models built-in:
 
 Note: The following examples use RSpec to demonstrate usage scenarios.
 
+Examples of configuring for the other strategies can be found in the wiki pages.
+
 ## Example : admin_flag
 
 Creates and uses a binary field 'admin_flag', which when true signals that this user is an administrator and otherwise a normal user.
 
 <pre>
   class User
-    include RoleModels::Generic 
+    include Roles::Generic 
 
     attr_accessor :name, :admin_flag 
 
@@ -49,7 +67,7 @@ Data Mapper with persistent attributes :name and :admin_flag
 
 <pre>
   class User
-    include RoleModels::Generic 
+    include Roles::Generic 
     include DataMapper::Resource
 
     property :name, Boolean
@@ -66,232 +84,70 @@ Data Mapper with persistent attributes :name and :admin_flag
   end
 </pre>
 
+## Role API
 
-## Example : role_string
-
-Creates and uses a single role name, a string
-
-<pre>
-  class User
-    include RoleModels::Generic 
-
-    attr_accessor :name, :role_string
-
-    role_strategy :role_string, :default
-
-    roles :admin, :user
-
-    def initialize name, *new_roles
-      self.name = name
-      self.roles = new_roles
-    end 
-  end
-</pre>
-
-## Example : roles_string
-
-Creates and uses single comma separated String of role names
-
-<pre>
-  class User
-    include RoleModels::Generic 
-
-    attr_accessor :name, :roles_string
-
-    role_strategy :roles_string, :default
-
-    roles :admin, :user
-
-    def initialize name, *new_roles
-      self.name = name
-      self.roles = new_roles
-    end 
-  end
-</pre>
-
-## Example : role_strings
-
-Creates and uses an Set of role names as strings
-
-<pre>
-  class User
-    include RoleModels::Generic 
-
-    attr_accessor :name, :role_strings
-
-    role_strategy :role_strings, :default
-
-    roles :admin, :user
-
-    def initialize name, *new_roles
-      self.name = name
-      self.roles = new_roles
-    end 
-  end  
-</pre>
-
-## Example : roles_mask
-
-Creates and uses an Integer field where each on bit signifies a role
-
-<pre>
-  class User
-    include RoleModels::Generic 
-
-    attr_accessor :name, :roles_mask
-
-    role_strategy :roles_mask, :default
-
-    roles :admin, :user
-
-    def initialize name, *new_roles
-      self.name = name
-      self.roles = new_roles
-    end 
-  end
-</pre>
-    
-## Example : one_role
-
-Creates and uses a single relation to a Role model for each user
-
-<pre>
-  class Role
-    attr_accessor :name
-
-    def self.find_role role_name    
-      roles.to_a.select{|r| r.name == role_name}.first
-    end  
-
-    class << self
-      attr_accessor :roles
-    end    
-
-    def initialize name
-      @name = name
-      self.class.roles ||= Set.new
-      self.class.roles << self
-    end
-
-  end
-
-  class User
-    include RoleModels::Generic 
-    role_strategy :one_role, :default
-
-    role_class :role   
-
-    attr_accessor :name, :one_role
-
-    roles :admin, :user 
-
-    def initialize name, *new_roles
-      self.name = name
-      self.roles = new_roles
-    end 
-  end
-</pre>
-
-## Example : many_roles
-
-Creates and uses a single relation to a Role model for each user
+### Instance methods
 
-<pre>
-  class Role
-    attr_accessor :name
-  
-    def self.find_role role_name    
-      roles.to_a.select{|r| r.name == role_name}.first
-    end  
-
-    def self.find_roles *role_names
-      result = Set.new
-      role_names.flatten.each do |role_name| 
-        found_role = find_role(role_name)
-        result << found_role if found_role
-      end
-      result
-    end
-
-    class << self
-      attr_accessor :roles
-    end    
-  
-    def initialize name
-      @name = name
-      self.class.roles ||= Set.new
-      self.class.roles << self
-    end  
-  end     
-  
-  class User
-    include RoleModels::Generic 
-    role_strategy :many_roles, :default
+Has ALL of the given roles been assigned?
+* has_roles?(*roles) - alias: is?
 
-    role_class :role   
+Has ANY (at least ONE) of the given roles been assigned?
+* has_role? *roles - alias: has?
 
-    attr_accessor :name, :many_roles
+Is this a valid role? (can the role be found in list of valid roles?)
+* valid_role? role
 
-    roles :admin, :user 
+Is this user the admin user (and user has no other roles)
+* admin? - short for - is?(:admin)
 
-    def initialize name, *new_roles
-      self.name = name
-      self.roles = new_roles
-    end 
-  end  
-</pre>
+### Class methods
 
+* roles - list of valid roles
+* roles_attribute - get the attribute where the role is stored on the user
+* roles_attribute= - set the role(s) attribute
+       
 ## Usage of API
 
 <pre>
   before :each do
     @admin_user = User.new 'Admin user', :admin
-    @user = User.new 'User', :user
+    @guest = User.new 'Guest', :guest
   end
 
   it "user 'Admin user' should have role :admin" do
-    @admin_user.role.should == :admin
-    @admin_user.roles.should == [:admin]      
+
+    @admin_user.role.should   == :admin
+    @admin_user.roles.should  == [:admin]      
     @admin_user.admin?.should be_true
 
-    @admin_user.has_role?(:user).should be_false
+    @admin_user.has_role?   (:user).should be_false
 
-    @admin_user.has_role?(:admin).should be_true
-    @admin_user.is?(:admin).should be_true
-    @admin_user.has_roles?(:admin).should be_true
-    @admin_user.has?(:admin).should be_true      
-  end
+    @admin_user.has_role?   (:admin).should be_true
+    @admin_user.is?         (:admin).should be_true
+    @admin_user.has_roles?  (:admin).should be_true
+    @admin_user.has?        (:admin).should be_true      
 
-  it "user 'User' should have role :user" do
-    @user.roles.should == [:user]
-    @user.admin?.should be_false
-  
-    @user.has_role?(:user).should be_true    
-    @user.has_role?(:admin).should be_false
-    @user.is?(:admin).should be_false
-    
-    @user.has_roles?(:user).should be_true
-    @user.has?(:admin).should be_false
   end
-  
-  it "should set 'User' role to :admin using roles=" do
-    @user.roles = :admin      
-    @user.role.should == :admin           
-    @user.has_role?(:admin).should be_true      
-  end  
-</pre>  
-
-## Future (TODO)
 
-The following in planned to be completed before the end of August 2010.
+  it "user Guest should have role :guest" do
+    @guest.roles.should == [:guest]
+    @guest.admin?.should be_false
 
-### Clean up (DRY)
+    @guest.has_role?  (:guest).should be_true    
+    @guest.has_role?  (:admin).should be_false
+    @guest.is?        (:admin).should be_false
 
-DRY up the role strategy code a lot more! There is a lot more potential for code reuse - way too much duplication now.
+    @guest.has_roles? (:guest).should be_true
+    @guest.has?       (:admin).should be_false
+  end
 
-### Rails generator
+  it "should set role of Guest user from :guest to :admin using roles=" do
+    @guest.roles        = :admin      
+    @guest.role.should == :admin           
 
-The library will come with a Rails 3 generator that lets you populate a user model with a given role strategy 
+    @guest.has_role?(:admin).should be_true      
+  end
+</pre>  
 
 ## Note on Patches/Pull Requests
  

data/Rakefile

@@ -7,10 +7,12 @@ 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.19"
-    gem.add_development_dependency "generator-spec", ">= 0.5.1"
-    gem.add_dependency "require_all", ">= 1.1.0"
-    gem.add_dependency "activesupport", ">= 3.0.0.rc"    
+    gem.add_development_dependency "rspec", "~> 2.0.0.beta.19"
+    gem.add_development_dependency "generator-spec", "~> 0.5.1"
+    gem.add_dependency "require_all", "~> 1.1.0"
+    gem.add_dependency "activesupport", "~> 3.0.0"    
+    gem.add_dependency 'sugar-high', "~> 0.2.2" 
+    gem.add_dependency 'rails3_artifactor', '~> 0.1.1'
     # 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.1.1
+0.2.0

data/lib/generators/roles_model/roles/roles_generator.rb

@@ -1,7 +1,9 @@
+require 'rails3_artifactor'
+
 module RolesModel 
   module Generators
     class RolesGenerator < Rails::Generators::NamedBase
-      include Rails::Generators::MigrationHelper
+      include Rails3::Assist::Artifact::Model
       
       desc "Add role strategy to a model" 
       
@@ -51,7 +53,7 @@ module RolesModel
 
       def insertion_text
         %Q{  
-  include RoleModels::Generic 
+  include Roles::Generic 
   #{role_strategy_statement}
   #{roles_statement}
 }

data/lib/roles_generic/base.rb

@@ -1,26 +1,22 @@
-require 'require_all'
-require 'active_support/inflector'
-
-module RoleModels
-  module Generic
-  end
-end
-
-module RoleModels
+module Roles
   module Base
     attr_accessor :orm_name
 
+    def valid_roles
+      strategy_class.valid_roles
+    end
+
     def roles(*roles)
       strategy_class.valid_roles = Array[*roles].flatten.map { |r| r.to_sym }
     end
     
-    def role_strategy strategy, options=nil
-      include_strategy orm_name, strategy, options
+    def role_strategy strategy_name, options=nil
+      include_strategy orm_name, strategy_name, options
     end  
          
-    def include_strategy orm, strategy, options=nil 
+    def include_strategy orm, strategy_name, options=nil 
       begin     
-        constant = "RoleModels::#{orm_name.to_s.camelize}::#{strategy.to_s.camelize}".constantize
+        constant = "RoleStrategy::#{orm_name.to_s.camelize}::#{strategy_name.to_s.camelize}".constantize
 
         strategy_class_method = %Q{
           def strategy_class
@@ -37,9 +33,9 @@ module RoleModels
           include constant
         end        
       rescue
-        raise "No Role strategy module for ORM #{orm} found for strategy #{strategy}"
+        raise "No Role strategy module for ORM #{orm} found for strategy #{strategy_name}"
       end
       constant.apply_options(options) if constant.respond_to? :apply_options
     end    
   end
-end
+end

data/lib/roles_generic/generic/role.rb

@@ -0,0 +1,18 @@
+module Roles::Generic::Role
+  module InstanceMethods
+    def role_class
+      self.class.role_class_name
+    end      
+  end
+
+  module ClassMethods 
+    def role_class_name
+      @role_class_name          
+    end
+
+    def role_class class_constant
+      const = class_constant.to_s.camelize
+      @role_class_name = "#{const}".constantize
+    end
+  end    
+end

data/lib/roles_generic/generic/{class_methods.rb → user/class_methods.rb}

@@ -1,7 +1,7 @@
-module RoleModels::Generic::Base
+module Roles::Generic::User
   module ClassMethods
     def inherited(subclass) # :nodoc:
-      ::RoleModels::Base::INHERITABLE_CLASS_ATTRIBUTES.each do |attribute|
+      ::Roles::Generic::User::INHERITABLE_CLASS_ATTRIBUTES.each do |attribute|
         instance_var = "@#{attribute}"
         subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
       end
@@ -26,7 +26,6 @@ module RoleModels::Generic::Base
     #
     # declare valid roles
     def roles(*roles)
-      puts "roles: #{roles}"
       self.valid_roles = Array[*roles].flatten.map { |r| r.to_sym }
     end
   end

data/lib/roles_generic/generic/{util.rb → user/configuration.rb}

@@ -1,19 +1,19 @@
-module RoleModels::Generic::Base 
+module Roles::Generic::User 
   module Configuration
     def configure(options={})
       numericality = options[:num]
       type = options[:type]
       
       class_eval do
-        include RoleModels::Generic::Base
-        include RoleModels::Generic::Base::SingleRole if numericality == :single
-        include RoleModels::Generic::Base::RoleClass::InstanceMethods if type == :role_class
+        include Roles::Generic::User
+        include Roles::Generic::User::SingleRole if numericality == :single
+        include Roles::Generic::Role::InstanceMethods if type == :role_class
         include self::Implementation
         
         alias_method :role_symbols, :roles
       end
-      extend RoleModels::Generic::Base::ClassMethods
-      extend RoleModels::Generic::Base::DefaultRoleKeys
+      extend Roles::Generic::User::ClassMethods
+      extend Roles::Generic::User::DefaultRoleKeys
     end
   end
   

data/lib/roles_generic/generic/{implementation.rb → user/implementation.rb}

@@ -1,4 +1,4 @@
-module RoleModels::Generic::Base
+module Roles::Generic::User
   module Implementation
 
     # check if a given role has been assigned 

data/lib/roles_generic/generic/user.rb

@@ -0,0 +1,22 @@
+require_all File.dirname(__FILE__) +'/user'
+
+module Roles::Generic
+  module User
+    INHERITABLE_CLASS_ATTRIBUTES = [:roles_attribute_name, :valid_roles]
+
+    include Implementation
+
+    def self.included(base) # :nodoc:
+      base.extend ClassMethods
+      base.class_eval do       
+        class << self   
+          attr_accessor(*::Roles::Generic::User::INHERITABLE_CLASS_ATTRIBUTES)
+          
+          def apply_options options 
+            roles_attribute default_role_attribute if options == :default
+          end             
+        end
+      end
+    end
+  end
+end

data/lib/roles_generic/generic.rb

@@ -1,77 +1,12 @@
-require 'require_all'
-require 'active_support/inflector'
-require_all File.dirname(__FILE__) + '/extensions'
+require_all File.dirname(__FILE__) + '/generic'
 
-module RoleModels
-  module Base
-    attr_accessor :orm_name
-
-    def valid_roles
-      strategy_class.valid_roles
-    end
-
-    def roles(*roles)
-      strategy_class.valid_roles = Array[*roles].flatten.map { |r| r.to_sym }
-    end
-    
-    def role_strategy strategy, options=nil
-      include_strategy orm_name, strategy, options
-    end  
-         
-    def include_strategy orm, strategy, options=nil 
-      begin     
-        constant = "RoleModels::#{orm_name.to_s.camelize}::#{strategy.to_s.camelize}".constantize
-
-        strategy_class_method = %Q{
-          def strategy_class
-            #{constant} 
-          end
-        }
-        
-        class_eval do
-          eval strategy_class_method
-        end
-
-        instance_eval do        
-          eval strategy_class_method
-          include constant
-        end        
-      rescue
-        raise "No Role strategy module for ORM #{orm} found for strategy #{strategy}"
-      end
-      constant.apply_options(options) if constant.respond_to? :apply_options
-    end    
-  end
-end
-
-module RoleModels
+module Roles
   module Generic  
     def self.included(base) 
-      base.extend RoleModels::Base       
+      base.extend Roles::Base       
       base.orm_name = :generic    
     end
   end
 end
 
-require_all File.dirname(__FILE__) +'/generic'
-
-module RoleModels::Generic
-  module Base
-    INHERITABLE_CLASS_ATTRIBUTES = [:roles_attribute_name, :valid_roles]
-
-    include Implementation
 
-    def self.included(base) # :nodoc:
-      base.extend ClassMethods
-      base.class_eval do       
-        class << self   
-          attr_accessor(*::RoleModels::Generic::Base::INHERITABLE_CLASS_ATTRIBUTES)
-          
-          def apply_options options 
-            roles_attribute default_role_attribute if options == :default
-          end             
-        end
-      end
-    end
-  end
-end

data/lib/roles_generic/namespaces.rb

@@ -0,0 +1,13 @@
+require 'sugar-high/module'
+
+module Roles
+  modules :generic do
+    nested_modules :user, :role
+  end
+  modules :base, :strategy
+end   
+
+module RoleStrategy
+  module Generic
+  end
+end

data/lib/roles_generic/{many_roles.rb → strategy/multi/many_roles.rb}

@@ -1,7 +1,6 @@
-require 'roles_generic/role/class_methods'
 require 'set'
 
-module RoleModels::Generic
+module RoleStrategy::Generic
   module ManyRoles
     def self.default_role_attribute
       :many_roles
@@ -29,11 +28,11 @@ module RoleModels::Generic
       end
     end
 
-    extend RoleModels::Generic::Base::Configuration
+    extend Roles::Generic::User::Configuration
     configure :type => :role_class
     
     def self.included(base)
-      base.extend RoleModels::Generic::Base::RoleClass::ClassMethods
+      base.extend Roles::Generic::Role::ClassMethods
     end      
   end
 end

data/lib/roles_generic/{role_strings.rb → strategy/multi/role_strings.rb}

@@ -1,4 +1,6 @@
-module RoleModels::Generic
+require 'set'
+
+module RoleStrategy::Generic
   module RoleStrings    
     def self.default_role_attribute
       :role_strings
@@ -8,16 +10,20 @@ module RoleModels::Generic
       # assign roles
       def roles=(*roles)
         new_roles = roles.flatten.map{|r| r.to_s if valid_role?(r)}.compact
-        self.send("#{strategy_class.roles_attribute_name}=", Set.new(new_roles)) if new_roles && new_roles.not.empty?
+        self.send("#{strategy_class.roles_attribute_name}=", ::Set.new(new_roles)) if new_roles && new_roles.not.empty?
       end
 
       # query assigned roles
       def roles
         self.send(strategy_class.roles_attribute_name).map{|r| r.to_sym}
       end
+      
+      def roles_list     
+        [roles].flatten
+      end      
     end
 
-    extend RoleModels::Generic::Base::Configuration
+    extend Roles::Generic::User::Configuration
     configure            
   end
 end

data/lib/roles_generic/{roles_mask.rb → strategy/multi/roles_mask.rb}

@@ -1,6 +1,6 @@
 require 'set'
 
-module RoleModels::Generic
+module RoleStrategy::Generic
   module RolesMask
     def self.default_role_attribute
       :roles_mask
@@ -42,7 +42,7 @@ module RoleModels::Generic
       end
     end    
     
-    extend RoleModels::Generic::Base::Configuration
+    extend Roles::Generic::User::Configuration
     configure            
   end
 end