roleable 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - ree
+  - 1.9.2
+  - 1.9.3

data/CHANGELOG

@@ -0,0 +1,3 @@
+## v0.0.1
+
+* Initial release

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Mitch Crowe
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,123 @@
+# Roleable
+
+[![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). 
+
+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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'roleable'
+```
+
+And then execute:
+
+    $ bundle
+
+Run the generator to create the `Role` and `UserRole` models and migrations:
+
+    $ rails g roleable:install
+    
+And then run the migrations:
+
+    $ rake db:migrate
+    
+(This will create the `roles` and `user_roles` tables, together with the appropriate database indices.)
+
+## Setup
+    
+Include `Roleable::Subject` into your user (subject) model, e.g.:
+
+```ruby
+class User < ActiveRecord::Base
+  include Roleable::Subject
+  ...
+end
+```  
+
+Include `Roleable::Resource` into any models you want to relate a user role to (resource), e.g.:
+
+```ruby
+class Page < ActiveRecord::Base
+  include Roleable::Resource
+  ...
+end
+```
+
+## Usage
+
+### Subject
+
+Add a role:
+
+```ruby
+# global
+user.add_role(:admin)
+
+# resource-scoped
+user.add_role(:editor, page)
+```
+
+Remove a role:
+
+```ruby
+# global
+user.remove_role(:admin)
+  
+# resource-scoped
+user.remove_role(:editor, page)
+```
+  
+Query a role:
+
+```ruby
+# global
+user.has_role?(:admin)
+
+# resource-scoped
+user.has_role?(:editor, page)
+```
+  
+Find the resources of a given class for which a user has a given role:
+
+```ruby
+user.resources_with_role(:editor, Page)
+```  
+
+Find a user's roles for a given resource:
+
+```ruby
+user.roles_for_resource(page)
+```
+
+Or, all the global roles for a user:
+
+```ruby
+user.roles_for_resource(nil)
+```
+  
+### Resource
+
+Find users with a given role:
+
+```ruby
+page.users_with_role(:editor)
+```
+
+For more details check out the [API documentation](http://rubydoc.info/github/mcrowe/roleable/master/frames) on rubydoc.info.
+ 
+## Requirements
+
+Rails 3, ActiveRecord, Ruby >= 1.8.7
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/generators/roleable/install/USAGE

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

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

@@ -0,0 +1,22 @@
+require 'rails/generators/migration'
+
+module Roleable
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      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.'
+      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'
+      end
+      
+      def self.next_migration_number(path)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+      
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+class RoleableCreateRolesAndUserRoles < ActiveRecord::Migration
+  
+  def change
+    create_table :roles do |t|
+      t.string :name      
+      t.timestamps
+    end
+
+    create_table :user_roles do |t|
+      t.references :user
+      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]
+  end
+  
+end

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

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

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

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

data/lib/roleable.rb

@@ -0,0 +1,5 @@
+require 'roleable/version'
+require 'roleable/subject'
+require 'roleable/resource'
+require 'roleable/role'
+require 'roleable/user_role'

data/lib/roleable/resource.rb

@@ -0,0 +1,18 @@
+module Roleable::Resource
+
+  def self.included(base)
+    base.has_many :user_roles, :as => :resource
+  end
+
+  # Return a list of users that have the given role for this resource.
+  #
+  # ==== Examples
+  #
+  #   page.users_with_role(:editor)   # => [user1, user2, ...]
+  #
+  def users_with_role(role_name)
+    user_roles = ::UserRole.with_role_name(role_name)
+    User.joins(:user_roles).merge(user_roles)
+  end
+  
+end

data/lib/roleable/role.rb

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

data/lib/roleable/subject.rb

@@ -0,0 +1,78 @@
+module Roleable::Subject
+  
+  def self.included(base)
+    base.has_many :user_roles
+  end
+
+  # Add a role to the user 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
+  # the given role.
+  #
+  # ==== Examples
+  #
+  #   user.add_role(:editor, page)    # Add the editor role to user, scoped to page
+  #   user.add_role(:admin)           # Add the admin role to user, globally
+  #
+  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)    
+  end
+
+  # Check if the user 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.
+  #
+  # ==== Examples
+  #
+  #   user.has_role?(:editor, page)   # True if the user has the editor role for page
+  #   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?    
+  end
+  
+  # Remove the given role from the user 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.
+  #
+  # ==== Examples
+  #
+  #   user.remove_role(:editor, page)   # Remove the editor role from the user for page
+  #   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)
+    
+    deleted_count = user_roles.delete_all
+        
+    deleted_count > 0
+  end
+  
+  # Return a list of resources of the given class, for which the user has the given role.
+  #
+  # ==== Examples
+  #
+  #   user.resources_with_role(:editor, 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)
+  end
+  
+  # Return a list of roles that the user 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)
+  end
+  
+end

data/lib/roleable/user_role.rb

@@ -0,0 +1,60 @@
+module Roleable::UserRole
+  
+  def self.extended(base)
+    base.belongs_to :user
+    base.belongs_to :role
+    base.belongs_to :resource, :polymorphic => true
+    
+    base.attr_accessible :role, :user, :resource
+  end
+
+  def with_user(user)
+    where(:user_id => user && user.id)
+  end
+
+  def with_resource(resource)
+    where(:resource_id => resource && resource.id, :resource_type => resource && resource_type(resource))
+  end
+
+  def with_role_name(role_name)
+    role = ::Role.find_by_name(role_name)
+    with_role(role)
+  end
+
+  def with_role(role)
+    where(:role_id => role && role.id)
+  end
+
+  def with_resource_class(resource_class)
+    where(:resource_type => resource_type_from_class(resource_class))
+  end
+  
+  # Create a record with the given attributes if there are no records
+  # that already have those attributes.
+  #
+  # 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| 
+      %w(id updated_at created_at).include?(k)
+    end
+    
+    if !exists?(record_attributes) && user_role.save
+      user_role
+    else
+      nil
+    end
+  end
+
+  private
+
+  def resource_type(resource)
+    resource_type_from_class(resource.class)
+  end
+
+  def resource_type_from_class(resource_class)
+    resource_class.name
+  end
+  
+end

data/lib/roleable/version.rb

@@ -0,0 +1,3 @@
+module Roleable
+  VERSION = '0.0.1'
+end

data/roleable.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/roleable/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Mitch Crowe"]
+  gem.email         = ["crowe.mitch@gmail.com"]
+  gem.description   = %q{Roles solution for active-record-backed Rails 3 applications}
+  gem.summary       = %q{Roles solution for active-record-backed Rails 3 applications}
+  gem.homepage      = "https://github.com/mcrowe/roleable"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "roleable"
+  gem.require_paths = ["lib"]
+  gem.version       = Roleable::VERSION
+  
+  gem.add_development_dependency 'rake', '~> 0.9'
+  gem.add_development_dependency 'rspec', '~> 2.8'
+  gem.add_development_dependency 'sqlite3', '~> 1.3'
+  gem.add_development_dependency 'activerecord', '~> 3.0'
+  gem.add_development_dependency 'with_model', '~> 0.2'
+  
+end

data/spec/roleable/resource_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe Roleable::Resource do
+
+  include_context 'with models'
+  
+  describe '#users_with_role' do
+    
+    before do
+      @page = Page.create
+      @editor_role = Role.create(:name => 'editor')
+    end
+    
+    context 'with a role that doesnt exist' do
+      it 'returns an empty list' do
+        @page.users_with_role(:notarole).should be_empty
+      end
+    end
+    
+    context 'when multiple users have the given role' do
+      it 'returns a list of the users' do
+        3.times do
+          user = User.create
+          user.add_role(:editor, @page)
+        end
+        
+        users = @page.users_with_role(:editor)
+        
+        users.length.should == 3
+        users.first.should be_a(User)
+      end
+    end
+    
+  end
+  
+end

data/spec/roleable/subject_spec.rb

@@ -0,0 +1,197 @@
+require 'spec_helper'
+
+describe Roleable::Subject do
+
+  include_context 'with models'
+    
+  before do
+    @user = User.create
+    @admin_role = Role.create(:name => 'admin')
+    @editor_role = Role.create(:name => 'editor')
+  end
+
+  describe '#add_role' do
+  
+    context 'with a role that doesnt exist' do
+    
+      before do
+        @result = @user.add_role(:notarole)
+      end
+    
+      it 'returns false' do
+        @result.should be_false
+      end
+    
+      it 'doesnt create a new user_role' do
+        UserRole.count.should == 0
+      end
+    
+    end
+  
+    context 'without a resource' do
+  
+      before do
+        @user_role = @user.add_role(:admin)
+      end
+  
+      it 'creates a new user role' do
+        UserRole.count.should == 1
+      end
+    
+      it 'associates the user role with the given user' do
+        @user_role.user.should == @user
+      end          
+
+      it 'associates the user role with the given role' do
+        @user_role.role.should == @admin_role
+      end
+    
+      it 'sets the resource to nil' do
+        @user_role.resource.should == nil
+      end
+      
+    end
+  
+    context 'with a resource' do
+    
+      before do
+        @page = Page.create
+        @user_role = @user.add_role(:admin, @page)
+      end
+    
+      it 'associates the user role with the given resource' do
+        @user_role.resource.should == @page
+      end
+      
+      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)
+        end
+      end
+          
+    end
+  
+  end
+
+  describe '#has_role?' do
+
+    context 'when the given role doesnt exist' do
+      it 'is false' do
+        @user.has_role?(:notarole).should be_false
+      end
+    end
+
+    context 'without a resource' do
+    
+      context 'when the user DOESNT have the given role' do    
+        it 'is false' do
+          @user.has_role?(:admin).should be_false
+        end
+      end
+    
+      context 'when the user DOES have the given role' do
+        it 'is true' do
+          @user.add_role(:admin)
+          @user.has_role?(:admin).should be_true
+        end
+      end
+    
+    end
+  
+    context 'with a resource' do
+ 
+      before do
+        @page = Page.create
+      end
+    
+      context 'when the user DOESNT have the role for that resource' do
+        it 'is false' do
+          @user.has_role?(:editor, @page).should be_false
+        end
+      end
+    
+      context 'when the user DOES have the role for that resource' do
+        it 'is true' do
+          @user.add_role(:editor, @page)
+          @user.has_role?(:editor, @page).should be_true
+        end
+      end
+    
+    end
+  
+  end
+
+  describe '#remove_role' do
+  
+    context 'global' do
+
+      context 'when the user doesnt have the role' do
+        it 'is false' do
+          @user.remove_role(:admin).should be_false
+        end
+      end
+      
+      context 'when the role doesnt exist' do
+        it 'is false' do
+          @user.remove_role(:notarole).should be_false
+        end
+      end
+    
+      context 'when the user has the given role' do
+      
+        before do
+          @user.add_role(:admin)
+          @result = @user.remove_role(:admin)
+        end
+      
+        it 'is true' do
+          @result.should be_true
+        end
+      
+        it 'removes the given role' do
+          @user.has_role?(:admin).should be_false
+        end
+      
+      end
+    
+    end
+  
+  end
+
+  describe '#resources_with_role' do
+  
+    context 'when the user has the given role for several resources of the given class' do
+      it 'returns a list containing those resources' do
+        3.times do 
+          page = Page.create
+          @user.add_role(:editor, page)
+        end
+      
+        pages = @user.resources_with_role(:editor, Page)
+        
+        pages.length.should == 3
+        pages.first.should be_a(Page)
+      end
+    end
+  
+    context 'when the user doesnt have the given role for any resources of the given class' do
+      it 'returns an empty list' do
+        @user.resources_with_role(:editor, Page).should be_empty        
+      end
+    end
+  
+  end
+
+  describe '#roles_for_resource' do
+    it 'returns a list of role objects for the roles this user has for the given resource' do
+      page = Page.create
+      @user.add_role(:editor, page)
+      @user.add_role(:admin, page)
+    
+      roles = @user.roles_for_resource(page)
+      roles.length.should == 2
+      roles.first.should be_a(Role)
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'sqlite3'
+require 'active_record'
+require 'with_model'
+require 'roleable'
+
+Dir['spec/support/**/*.rb'].each { |f| require File.expand_path("../../#{f}", __FILE__) }
+
+RSpec.configure do |config|
+  config.extend WithModel
+  
+  ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+end

data/spec/support/shared_contexts.rb

@@ -0,0 +1,28 @@
+shared_context 'with models' do
+
+  with_model :User do
+    model { include Roleable::Subject }
+  end
+
+  with_model :Page do
+    model { include Roleable::Resource }
+  end
+
+  with_model :Role do
+    table { |t| t.string :name }
+    model { extend Roleable::Role }
+  end
+
+  with_model :UserRole do
+    table do |t|
+      t.integer :user_id
+      t.integer :role_id
+      t.integer :resource_id
+      t.string :resource_type
+      
+      t.timestamps
+    end
+    model { extend Roleable::UserRole }
+  end
+  
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: roleable
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Mitch Crowe
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-14 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2156383080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: *2156383080
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2156382260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: *2156382260
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &2156381480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: *2156381480
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: &2156380900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: *2156380900
+- !ruby/object:Gem::Dependency
+  name: with_model
+  requirement: &2156380280 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: *2156380280
+description: Roles solution for active-record-backed Rails 3 applications
+email:
+- crowe.mitch@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/generators/roleable/install/USAGE
+- lib/generators/roleable/install/install_generator.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/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
+homepage: https://github.com/mcrowe/roleable
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1300429085112405941
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1300429085112405941
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Roles solution for active-record-backed Rails 3 applications
+test_files:
+- spec/roleable/resource_spec.rb
+- spec/roleable/subject_spec.rb
+- spec/spec_helper.rb
+- spec/support/shared_contexts.rb