roleable 0.1.0 → 0.2.0

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://secure.travis-ci.org/mcrowe/roleable.png?branch=master)](http://travis-ci.org/mcrowe/roleable)
 
-A flexible user-roles solution for active-record-backed Rails 3 applications. Allows for multiple roles scoped to instances of any model, as well as global roles (admin, for example). 
+A flexible roles solution for active-record-backed Rails 3 applications. Allows for multiple roles scoped to instances of any model, as well as global roles (admin, for example). 
 
 Roleable is designed to be ultra simple and obvious, letting you build upon it to satisfy your needs. It is also designed to be efficient: using database indices, and well-crafted queries so that it can handle a huge number of roles.
 
@@ -18,7 +18,7 @@ And then execute:
 
     $ bundle
 
-Run the generator to create the `Role` and `UserRole` models and migrations:
+Run the generator to create the `Role` and `AppliedRole` models, migrations, and a configuration initializer:
 
     $ rails g roleable:install
     
@@ -26,11 +26,11 @@ And then run the migrations:
 
     $ rake db:migrate
     
-(This will create the `roles` and `user_roles` tables, together with the appropriate database indices.)
+(This will create the `roles` and `applied_roles` tables, together with the appropriate database indices.)
 
 ## Setup
     
-Include `Roleable::Subject` into your user (subject) model, e.g.:
+Include `Roleable::Subject` into your subject model, e.g.:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -39,7 +39,7 @@ class User < ActiveRecord::Base
 end
 ```  
 
-Include `Roleable::Resource` into any models you want to relate a user role to (resource), e.g.:
+Include `Roleable::Resource` into any models you want to relate a subject role to (resource), e.g.:
 
 ```ruby
 class Page < ActiveRecord::Base
@@ -108,10 +108,20 @@ user.roles_for_resource(nil)
   
 ### Resource
 
-Find users with a given role:
+Find subjects (users) with a given role:
 
 ```ruby
-page.users_with_role(:editor)
+page.subjects_with_role(:editor)
+```
+
+## Customization
+
+By default, roleable assumes that your subject model is called `User`. You can customize this by modifying the generated configuration intializer located at `config/initializers/roleable.rb`, e.g.:
+
+```ruby
+Roleable.configure do |config|
+  config.subject_class_name = 'principle'
+end
 ```
 
 Find users matching _any_ of a list of roles:

data/lib/generators/roleable/install/USAGE

@@ -1,2 +1,2 @@
 Description:
-  The roleable:install generator creates `Role` and `UserRole` models, and generates the necessary migrations to create their database tables.
+  The roleable:install generator creates `Role` and `AppliedRole` models, and generates the necessary migrations to create their database tables.

data/lib/generators/roleable/install/install_generator.rb

@@ -6,11 +6,12 @@ module Roleable
       include Rails::Generators::Migration
       source_root File.expand_path('../templates', __FILE__)
 
-      desc 'Generates a role and a user_role model, along with migrations for their tables.'
+      desc 'Generates a role and a applied_role model, along with migrations for their tables.'
       def generate_install
         copy_file 'role.rb', 'app/models/role.rb'
-        copy_file 'user_role.rb', 'app/models/user_role.rb'
-        migration_template 'migration.rb', 'db/migrate/roleable_create_roles_and_user_roles.rb'
+        copy_file 'applied_role.rb', 'app/models/applied_role.rb'
+        copy_file 'initializer.rb', 'config/initializers/roleable.rb'
+        migration_template 'migration.rb', 'db/migrate/roleable_create_roles_and_applied_roles.rb'
       end
       
       def self.next_migration_number(path)

data/lib/generators/roleable/install/templates/applied_role.rb

@@ -0,0 +1,5 @@
+class AppliedRole < ActiveRecord::Base
+  
+  extend Roleable::AppliedRole
+  
+end

data/lib/generators/roleable/install/templates/initializer.rb

@@ -0,0 +1,4 @@
+Roleable.configure do |config|
+  # Uncomment to customize the subject class (default: 'User').
+  # config.subject_class_name = 'Subject'
+end

data/lib/generators/roleable/install/templates/migration.rb

@@ -1,4 +1,4 @@
-class RoleableCreateRolesAndUserRoles < ActiveRecord::Migration
+class RoleableCreateRolesAndAppliedRoles < ActiveRecord::Migration
   
   def change
     create_table :roles do |t|
@@ -6,16 +6,15 @@ class RoleableCreateRolesAndUserRoles < ActiveRecord::Migration
       t.timestamps
     end
 
-    create_table :user_roles do |t|
-      t.references :user
+    create_table :applied_roles do |t|
+      t.references :subject
       t.references :role
       t.references :resource, :polymorphic => true
       t.timestamps
     end
     
-    add_index :user_roles, :user_id
-    add_index :user_roles, :role_id
-    add_index :user_roles, [:resource_type, :resource_id]
+    add_index :applied_roles, :subject_id
+    add_index :applied_roles, [:resource_type, :resource_id]
   end
   
 end

data/lib/roleable.rb

@@ -2,4 +2,17 @@ require 'roleable/version'
 require 'roleable/subject'
 require 'roleable/resource'
 require 'roleable/role'
-require 'roleable/user_role'
+require 'roleable/applied_role'
+require 'roleable/configuration'
+
+module Roleable
+  
+  def self.configuration
+    @configuration ||= Roleable::Configuration.new
+  end
+  
+  def self.configure
+    yield configuration if block_given?
+  end
+  
+end

data/lib/roleable/{user_role.rb → applied_role.rb}

@@ -1,15 +1,15 @@
-module Roleable::UserRole
+module Roleable::AppliedRole
   
   def self.extended(base)
-    base.belongs_to :user
+    base.belongs_to :subject, :class_name => Roleable.configuration.subject_class_name
     base.belongs_to :role
     base.belongs_to :resource, :polymorphic => true
     
-    base.attr_accessible :role, :user, :resource
+    base.attr_accessible :role, :subject_id, :resource
   end
 
-  def with_user(user)
-    where(:user_id => user && user.id)
+  def with_subject(subject)
+    where(:subject_id => subject && subject.id)
   end
 
   def with_resource(resource)
@@ -35,14 +35,14 @@ module Roleable::UserRole
   #
   # Returns the record if it was saved, otherwise nil.
   def create_if_unique!(attributes)  
-    user_role = new(attributes)
-    
-    record_attributes = user_role.attributes.reject do |k, v| 
+    applied_role = new(attributes)
+
+    record_attributes = applied_role.attributes.reject do |k, v| 
       %w(id updated_at created_at).include?(k)
     end
     
-    if !exists?(record_attributes) && user_role.save
-      user_role
+    if !exists?(record_attributes) && applied_role.save
+      applied_role
     else
       nil
     end

data/lib/roleable/configuration.rb

@@ -0,0 +1,9 @@
+class Roleable::Configuration
+  
+  attr_accessor :subject_class_name
+
+  def initialize
+    @subject_class_name = 'User'
+  end
+    
+end

data/lib/roleable/resource.rb

@@ -1,7 +1,7 @@
 module Roleable::Resource
 
   def self.included(base)
-    base.has_many :user_roles, :as => :resource
+    base.has_many :applied_roles, :as => :resource
   end
 
   # Return a list of users that have the given role for this resource.
@@ -9,11 +9,18 @@ module Roleable::Resource
   #
   # ==== Examples
   #
-  #   page.users_with_role(:editor)   # => [user1, user2, ...]
-  #   page.users_with_role([:editor, :author])   # => [user1, user2, ...]
+  #   page.subjects_with_role(:editor)            # => [user1, user2, ...]
+  #   page.subjects_with_role([:editor, :author]) # => [user1, user2, ...]
   #
-  def users_with_role(role_name)
-    User.joins(:user_roles).merge(::UserRole.with_role_name(role_name).with_resource(self))
+  def subjects_with_role(role_name)
+    subject_class.joins(:applied_roles).
+      merge( ::AppliedRole.with_role_name(role_name).with_resource(self) )
+  end
+  
+  private
+  
+  def subject_class
+    Roleable.configuration.subject_class_name.classify.constantize
   end
   
 end

data/lib/roleable/role.rb

@@ -1,7 +1,7 @@
 module Roleable::Role
 
   def self.extended(base) 
-    base.has_many :user_roles
+    base.has_many :applied_roles
 
     base.attr_accessible :name
   end

data/lib/roleable/subject.rb

@@ -1,12 +1,12 @@
 module Roleable::Subject
   
   def self.included(base)
-    base.has_many :user_roles
+    base.has_many :applied_roles, :foreign_key => 'subject_id'
   end
 
-  # Add a role to the user scoped to the given resource or global if no resource given.
+  # Add a role to the subject scoped to the given resource or global if no resource given.
   #
-  # Does nothing if a role with the given name doesn't exist, or if the user already has
+  # Does nothing if a role with the given name doesn't exist, or if the subject already has
   # the given role.
   #
   # ==== Examples
@@ -17,13 +17,13 @@ module Roleable::Subject
   def add_role(role_name, resource = nil)
     role = ::Role.find_by_name(role_name) or return
     
-    ::UserRole.create_if_unique!(:user => self, :role => role, :resource => resource)    
+    ::AppliedRole.create_if_unique!(:subject_id => self.id, :role => role, :resource => resource)    
   end
 
-  # Check if the user has the given role for the given resource, or if they have the role globally
+  # Check if the subject has the given role for the given resource, or if they have the role globally
   # if no resource given.
   #
-  # Returns <tt>true</tt> if the user has the role, <tt>false</tt> otherwise.
+  # Returns <tt>true</tt> if the subject has the role, <tt>false</tt> otherwise.
   #
   # ==== Examples
   #
@@ -31,12 +31,14 @@ module Roleable::Subject
   #   user.has_role?(:admin)          # True if the user has a global admin role
   #
   def has_role?(role_name, resource = nil)
-    user_roles = ::UserRole.with_user(self).with_resource(resource).with_role_name(role_name)
-    
-    user_roles.exists?    
+    ::AppliedRole.
+      with_subject(self).
+      with_resource(resource).
+      with_role_name(role_name).
+      exists?
   end
   
-  # Remove the given role from the user for the given resource, or globally if no resource given.
+  # Remove the given role from the subject for the given resource, or globally if no resource given.
   #
   # Returns <tt>true</tt> if the role was found and deleted, <tt>false</tt> otherwise.
   #
@@ -46,15 +48,15 @@ module Roleable::Subject
   #   user.remove_role(:admin)          # Remove the global admin role from the user
   #
   def remove_role(role_name, resource = nil)
-    user_roles = ::UserRole.with_user(self).with_resource(resource).with_role_name(role_name)
+    applied_roles = ::AppliedRole.with_subject(self).with_resource(resource).with_role_name(role_name)
     
-    deleted_count = user_roles.delete_all
+    deleted_count = applied_roles.delete_all
         
     deleted_count > 0
   end
   
-  # Return a list of resources of the given class, for which the user has the given role.
-  # If passed an array or roles, returns resources for which the user has any of the roles.
+  # Return a list of resources of the given class, for which the subject has the given role.
+  # If passed an array or roles, returns resources for which the subject has any of the roles.
   #
   # ==== Examples
   #
@@ -62,19 +64,19 @@ module Roleable::Subject
   #   user.resources_with_role([:editor, :author], Page)  # => [page1, page2, ...]
   #
   def resources_with_role(role_name, resource_class)
-    user_roles = ::UserRole.with_user(self).with_role_name(role_name).with_resource_class(resource_class)
-    resource_class.includes(:user_roles).merge(user_roles)
+    applied_roles = ::AppliedRole.with_subject(self).with_role_name(role_name).with_resource_class(resource_class)
+    resource_class.includes(:applied_roles).merge(applied_roles)
   end
   
-  # Return a list of roles that the user has for the given resource.
+  # Return a list of roles that the subject has for the given resource.
   #
   # ==== Examples
   #
   #   user.roles_for_resource(page)   # => [role1, role2, ...]
   #  
   def roles_for_resource(resource)
-    user_roles = ::UserRole.with_user(self).with_resource(resource)    
-    ::Role.includes(:user_roles).merge(user_roles)
+    applied_roles = ::AppliedRole.with_subject(self).with_resource(resource)    
+    ::Role.includes(:applied_roles).merge(applied_roles)
   end
   
 end

data/lib/roleable/version.rb

@@ -1,3 +1,3 @@
 module Roleable
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/spec/roleable/resource_spec.rb

@@ -4,19 +4,19 @@ describe Roleable::Resource do
 
   include_context 'with models'
   
-  describe '#users_with_role' do
+  describe '#subjects_with_role' do
     
     before do
       @page = Page.create
       @editor_role = Role.create(:name => 'editor')
       @author_role = Role.create(:name => 'author')
     end
-    
+
     context 'with a single role' do
       
       context 'with a role that doesnt exist' do
         it 'returns an empty list' do
-          @page.users_with_role(:notarole).should be_empty
+          @page.subjects_with_role(:notarole).should be_empty
         end
       end
     
@@ -26,8 +26,9 @@ describe Roleable::Resource do
           3.times { User.create.add_role(:editor, @page) }
         end        
         
+
         it 'returns a list of the users' do    
-          users = @page.users_with_role(:editor)
+          users = @page.subjects_with_role(:editor)
         
           users.length.should == 3
           users.first.should be_a(User)
@@ -36,8 +37,8 @@ describe Roleable::Resource do
         it 'doesnt return users that dont have the role' do
           other_page = Page.create
           other_user = User.create.add_role(:editor, other_page)
-        
-          users = @page.users_with_role(:editor)
+
+          users = @page.subjects_with_role(:editor)
         
           users.length.should == 3
         end
@@ -52,7 +53,7 @@ describe Roleable::Resource do
         2.times { User.create.add_role(:author, @page) }
         User.create
         
-        users = @page.users_with_role([:editor, :author])
+        users = @page.subjects_with_role([:editor, :author])
       
         users.length.should == 5
       end

data/spec/roleable/subject_spec.rb

@@ -23,8 +23,8 @@ describe Roleable::Subject do
         @result.should be_false
       end
     
-      it 'doesnt create a new user_role' do
-        UserRole.count.should == 0
+      it 'doesnt create a new applied_role' do
+        AppliedRole.count.should == 0
       end
     
     end
@@ -36,11 +36,11 @@ describe Roleable::Subject do
       end
   
       it 'creates a new user role' do
-        UserRole.count.should == 1
+        AppliedRole.count.should == 1
       end
     
       it 'associates the user role with the given user' do
-        @user_role.user.should == @user
+        @user_role.subject.should == @user
       end          
 
       it 'associates the user role with the given role' do
@@ -66,7 +66,7 @@ describe Roleable::Subject do
       
       context 'when the user already has the given role for the resource' do
         it 'doesnt create another user role' do
-          expect { @user.add_role(:admin, @page) }.to_not change(UserRole, :count)
+          expect { @user.add_role(:admin, @page) }.to_not change(AppliedRole, :count)
         end
       end
           

data/spec/support/shared_contexts.rb

@@ -13,16 +13,16 @@ shared_context 'with models' do
     model { extend Roleable::Role }
   end
 
-  with_model :UserRole do
+  with_model :AppliedRole do
     table do |t|
-      t.integer :user_id
+      t.integer :subject_id
       t.integer :role_id
       t.integer :resource_id
       t.string :resource_type
       
       t.timestamps
     end
-    model { extend Roleable::UserRole }
+    model { extend Roleable::AppliedRole }
   end
   
 end

metadata

@@ -1,108 +1,78 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: roleable
-version: !ruby/object:Gem::Version 
-  hash: 27
+version: !ruby/object:Gem::Version
+  version: 0.2.0
   prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 0
-  version: 0.1.0
 platform: ruby
-authors: 
+authors:
 - Mitch Crowe
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-05-09 00:00:00 -07:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 25
-        segments: 
-        - 0
-        - 9
-        version: "0.9"
-  prerelease: false
+date: 2012-05-11 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rake
-  version_requirements: *id001
-  type: :development
-- !ruby/object:Gem::Dependency 
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &2162720700 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 19
-        segments: 
-        - 2
-        - 8
-        version: "2.8"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
   prerelease: false
+  version_requirements: *2162720700
+- !ruby/object:Gem::Dependency
   name: rspec
-  version_requirements: *id002
-  type: :development
-- !ruby/object:Gem::Dependency 
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &2162719820 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 9
-        segments: 
-        - 1
-        - 3
-        version: "1.3"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
   prerelease: false
+  version_requirements: *2162719820
+- !ruby/object:Gem::Dependency
   name: sqlite3
-  version_requirements: *id003
-  type: :development
-- !ruby/object:Gem::Dependency 
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &2162719040 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 3
-        - 0
-        version: "3.0"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
   prerelease: false
+  version_requirements: *2162719040
+- !ruby/object:Gem::Dependency
   name: activerecord
-  version_requirements: *id004
-  type: :development
-- !ruby/object:Gem::Dependency 
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &2162718020 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 15
-        segments: 
-        - 0
-        - 2
-        version: "0.2"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
   prerelease: false
+  version_requirements: *2162718020
+- !ruby/object:Gem::Dependency
   name: with_model
-  version_requirements: *id005
+  requirement: &2162717140 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
   type: :development
+  prerelease: false
+  version_requirements: *2162717140
 description: Roles solution for active-record-backed Rails 3 applications
-email: 
+email:
 - crowe.mitch@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .rspec
 - .travis.yml
@@ -113,55 +83,53 @@ files:
 - Rakefile
 - lib/generators/roleable/install/USAGE
 - lib/generators/roleable/install/install_generator.rb
+- lib/generators/roleable/install/templates/applied_role.rb
+- lib/generators/roleable/install/templates/initializer.rb
 - lib/generators/roleable/install/templates/migration.rb
 - lib/generators/roleable/install/templates/role.rb
-- lib/generators/roleable/install/templates/user_role.rb
 - lib/roleable.rb
+- lib/roleable/applied_role.rb
+- lib/roleable/configuration.rb
 - lib/roleable/resource.rb
 - lib/roleable/role.rb
 - lib/roleable/subject.rb
-- lib/roleable/user_role.rb
 - lib/roleable/version.rb
 - roleable.gemspec
 - spec/roleable/resource_spec.rb
 - spec/roleable/subject_spec.rb
 - spec/spec_helper.rb
 - spec/support/shared_contexts.rb
-has_rdoc: true
 homepage: https://github.com/mcrowe/roleable
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 3443296545749404592
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: 3443296545749404592
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.9.4
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Roles solution for active-record-backed Rails 3 applications
-test_files: 
+test_files:
 - spec/roleable/resource_spec.rb
 - spec/roleable/subject_spec.rb
 - spec/spec_helper.rb

data/lib/generators/roleable/install/templates/user_role.rb

@@ -1,5 +0,0 @@
-class UserRole < ActiveRecord::Base
-  
-  extend Roleable::UserRole
-  
-end