roles_generic 0.1.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/.rspec

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

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Kristian Mandrup
+
+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.markdown

@@ -0,0 +1,308 @@
+# Roles Model base
+
+Generic role strategies that share the same API and are easy to insert in any existing User model. 
+
+*Update: Now with a Rails 3 generator to instantly populate your user model of choice with a role strategy!*
+
+# Install
+
+<code>gem install roles_generic</code>
+
+# Usage
+
+The library comes with the following role models built-in:
+
+* admin_flag (Boolean flag - 'admin' or not)
+* role_string (String)
+* roles_string (Comma separated String - note: no role name must have a comma in its name!)
+* role_strings (Set of Strings)
+* roles_mask (Integer mask)
+* one_role (relation to a Role model instance)
+* many_roles(Set of Role relationships)
+
+Note: The following examples use RSpec to demonstrate usage scenarios.
+
+## 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 
+
+    attr_accessor :name, :admin_flag 
+
+    role_strategy :admin_flag, :default
+
+    roles :admin, :user
+
+    def initialize name, *new_roles
+      self.name = name
+      self.roles = new_roles
+    end 
+  end
+</pre>
+
+## Example: Using an ORM
+
+Data Mapper with persistent attributes :name and :admin_flag
+
+<pre>
+  class User
+    include RoleModels::Generic 
+    include DataMapper::Resource
+
+    property :name, Boolean
+    property :admin_flag, Boolean
+
+    role_strategy :admin_flag, :default
+
+    roles :admin, :user
+
+    def initialize name, *new_roles
+      self.name = name
+      self.roles = new_roles
+    end 
+  end
+</pre>
+
+
+## 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
+
+<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
+
+    role_class :role   
+
+    attr_accessor :name, :many_roles
+
+    roles :admin, :user 
+
+    def initialize name, *new_roles
+      self.name = name
+      self.roles = new_roles
+    end 
+  end  
+</pre>
+
+## Usage of API
+
+<pre>
+  before :each do
+    @admin_user = User.new 'Admin user', :admin
+    @user = User.new 'User', :user
+  end
+
+  it "user 'Admin user' should have role :admin" do
+    @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?(: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
+
+  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.
+
+### Clean up (DRY)
+
+DRY up the role strategy code a lot more! There is a lot more potential for code reuse - way too much duplication now.
+
+### Rails generator
+
+The library will come with a Rails 3 generator that lets you populate a user model with a given role strategy 
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,45 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "roles_generic"
+    gem.summary = %Q{Generic role strategies sharing the same API}
+    gem.description = %Q{Generic role strategies sharing the same API. Easy to insert in any model}
+    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 is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+# require 'spec/rake/spectask'
+# Spec::Rake::SpecTask.new(:spec) do |spec|
+#   spec.libs << 'lib' << 'spec'
+#   spec.spec_files = FileList['spec/**/*_spec.rb']
+# end
+# 
+# Spec::Rake::SpecTask.new(:rcov) do |spec|
+#   spec.libs << 'lib' << 'spec'
+#   spec.pattern = 'spec/**/*_spec.rb'
+#   spec.rcov = true
+# end
+# 
+# task :spec => :check_dependencies
+# 
+# task :default => :spec
+# 
+# require 'rake/rdoctask'
+# Rake::RDocTask.new do |rdoc|
+#   version = File.exist?('VERSION') ? File.read('VERSION') : ""
+# 
+#   rdoc.rdoc_dir = 'rdoc'
+#   rdoc.title = "roles_for_mm #{version}"
+#   rdoc.rdoc_files.include('README*')
+#   rdoc.rdoc_files.include('lib/**/*.rb')
+# end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

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

@@ -0,0 +1,65 @@
+module RolesModel 
+  module Generators
+    class RolesGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::MigrationHelper
+      
+      desc "Add role strategy to a model" 
+      
+      class_option :strategy, :type => :string, :aliases => "-s", :default => 'role_string', 
+                   :desc => "Role strategy to use (admin_flag, role_string, roles_string, role_strings, one_role, many_roles, roles_mask)"
+
+
+      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
+        insert_into_model name do
+          insertion_text
+        end
+      end 
+      
+      protected                  
+
+      def strategy
+        options[:strategy]
+      end
+
+      def orm
+        @orm ||= options[:orm].to_s.to_sym        
+      end
+
+      def roles
+        @roles ||= options[:roles].map{|r| ":#{r}" }
+      end
+
+      def role_strategy_statement 
+        "role_strategy :#{strategy}\n"
+      end
+
+      def roles_statement
+        roles ? "roles #{roles.join(',')}" : ''
+      end
+
+      def insertion_text
+        %Q{  
+  include RoleModels::Generic 
+  #{role_strategy_statement}
+  #{roles_statement}
+}
+      end
+
+      def role_strategy
+        options[:role_strategy]                
+      end
+    end
+  end
+end

data/lib/roles_generic/admin_flag.rb

@@ -0,0 +1,40 @@
+module RoleModels::Generic
+  module AdminFlag    
+    def self.default_role_attribute
+      :admin_flag
+    end
+
+    module Implementation  
+      # assign roles
+      def roles=(*new_roles)                                 
+        first_role = new_roles.flatten.first
+        self.send("#{strategy_class.roles_attribute_name}=", new_roles.flatten.first.admin?) if valid_role? first_role
+      end
+
+      # query assigned roles
+      def roles
+        role = self.send(strategy_class.roles_attribute_name) ? strategy_class.admin_role_key : strategy_class.default_role_key
+        [role]
+      end
+      alias_method :roles_list, :roles
+
+    end # Implementation
+    
+    extend RoleModels::Generic::Base::Configuration
+    configure :num => :single
+  end   
+end
+
+module AdminRoleCheck
+  def admin?
+    self.to_s.downcase.to_sym == :admin
+  end
+end  
+
+class String
+  include AdminRoleCheck
+end
+
+class Symbol
+  include AdminRoleCheck
+end

data/lib/roles_generic/base.rb

@@ -0,0 +1,45 @@
+require 'require_all'
+require 'active_support/inflector'
+
+module RoleModels
+  module Generic
+  end
+end
+
+module RoleModels
+  module Base
+    attr_accessor :orm_name
+
+    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

data/lib/roles_generic/extensions/core_ext.rb

@@ -0,0 +1,19 @@
+# to be replaced by Zucker gem
+
+class Object
+  define_method :not do
+    Not.new(self)
+  end
+
+  class Not
+    private *instance_methods.select { |m| m !~ /(^__|^\W|^binding$)/ }
+
+    def initialize(subject)
+      @subject = subject
+    end
+
+    def method_missing(sym, *args, &blk)
+      !@subject.send(sym,*args,&blk)
+    end
+  end
+end

data/lib/roles_generic/generic/class_methods.rb

@@ -0,0 +1,33 @@
+module RoleModels::Generic::Base
+  module ClassMethods
+    def inherited(subclass) # :nodoc:
+      ::RoleModels::Base::INHERITABLE_CLASS_ATTRIBUTES.each do |attribute|
+        instance_var = "@#{attribute}"
+        subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
+      end
+      super
+    end
+    
+    # set the bitmask attribute role assignments will be stored in
+    def roles_attribute(name)
+      self.roles_attribute = name
+    end
+
+    # alternative method signature: set the bitmask attribute role assignments will be stored in
+    def roles_attribute=(name)
+      self.roles_attribute_name = name.to_sym
+    end
+
+    # :call-seq:
+    #   roles(:role_1, ..., :role_n)
+    #   roles('role_1', ..., 'role_n')
+    #   roles([:role_1, ..., :role_n])
+    #   roles(['role_1', ..., 'role_n'])
+    #
+    # declare valid roles
+    def roles(*roles)
+      puts "roles: #{roles}"
+      self.valid_roles = Array[*roles].flatten.map { |r| r.to_sym }
+    end
+  end
+end

data/lib/roles_generic/generic/implementation.rb

@@ -0,0 +1,26 @@
+module RoleModels::Generic::Base
+  module Implementation
+
+    # 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?      
+    end
+
+    # check if any (at least ONE) of the given roles have been assigned
+    def has_role? *roles
+      (roles_list & roles.flatten).not.empty?            
+    end
+
+    def valid_role? role
+      strategy_class.valid_roles.include? role.to_sym
+    end
+
+    def admin?
+      is? :admin
+    end
+           
+    alias_method :has?, :has_role?
+    alias_method :is?, :has_roles?        
+  end
+end    

data/lib/roles_generic/generic/util.rb

@@ -0,0 +1,39 @@
+module RoleModels::Generic::Base 
+  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 self::Implementation
+        
+        alias_method :role_symbols, :roles
+      end
+      extend RoleModels::Generic::Base::ClassMethods
+      extend RoleModels::Generic::Base::DefaultRoleKeys
+    end
+  end
+  
+  module SingleRole
+    def role
+      roles.first
+    end
+
+    def role= new_role
+      self.roles = new_role
+    end
+  end
+  
+  module DefaultRoleKeys
+    def default_role_key
+      valid_roles.last || :user
+    end
+
+    def admin_role_key
+      valid_roles.first || :admin      
+    end            
+  end
+end