troles 0.5.0

data/Rakefile

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "troles"
+  gem.homepage = "http://github.com/kristianmandrup/troles"
+  gem.license = "MIT"
+  gem.summary = %Q{Complete roles solution that is easy to integrate with any Rack app, including Rails 3+}
+  gem.description = %Q{Ruby roles solution that has an easy to extend API, configuration and nice Adapter interface to ORMs and data stores}
+  gem.email = "kmandrup@gmail.com"
+  gem.authors = ["Kristian Mandrup"]
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "mongoid_geo #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.0

data/config/database.yml

@@ -0,0 +1,4 @@
+adapter: sqlite3
+database: development.sqlite3
+pool: 5
+timeout: 5000

data/lib/trole/adapters/active_record/config.rb

@@ -0,0 +1,23 @@
+module Trole::ActiveRecord
+  class Config < Troles::Common::Config  
+    
+    def initialize clazz, options = {}
+      super
+    end
+    
+    def configure_relation
+      case strategy
+      when :ref_one
+        belongs_to_for clazz, role_model, :key => role_field 
+        has_many_for role_model, clazz
+      when :embed_one
+        raise "EmbedOne is currently not supported by the Active Record adapter. It will be soon..."
+        #clazz.send(:embeds_many, role_model_key, :class_name => role_model_class_name)      
+      end
+    end
+    
+    # AR sets this up ont its own using DB Table info    
+    def configure_field
+    end       
+  end
+end

data/lib/trole/adapters/active_record.rb

@@ -0,0 +1,8 @@
+module Trole
+  module ActiveRecord
+    autoload :Config,     'trole/adapters/active_record/config'
+    # autoload :Api,        'troles/adapters/active_record/api'
+    # autoload :Storage,    'trole/adapters/active_record/storage'
+    # autoload :Strategy,   'trole/adapters/active_record/strategy'
+  end
+end

data/lib/trole/adapters/mongoid/config.rb

@@ -0,0 +1,34 @@
+module Trole::Mongoid
+  class Config < Troles::Common::Config  
+    
+    def initialize clazz, options = {}
+      super
+    end
+    
+    def configure_relation
+      case strategy
+      when :ref_one
+        has_one_for clazz, :role
+        belongs_to_for role_model, :user
+      when :embed_one
+        embeds_one clazz, :role
+      end
+    end
+    
+    def configure_field
+      type = case strategy
+      when :bit_one
+        Boolean
+      when :string_one
+        String
+      end
+      clazz.send(:field, role_field, type) if type      
+    end   
+    
+    protected
+    
+    def embeds_one from, to
+      make_relationship :embeds_one, from, to
+    end        
+  end
+end

data/lib/trole/api/cache.rb

@@ -0,0 +1,9 @@
+# 
+# @author Kristian Mandrup
+#
+# Single role Cache Api
+#
+module Trole::Api
+  module Cache
+  end  
+end

data/lib/trole/api/config.rb

@@ -0,0 +1,12 @@
+# 
+# @author Kristian Mandrup
+#
+# Single role Config Api
+#
+module Trole::Api
+  module Config
+    def troles_config
+      @troles_config ||= Trole::Config.new self
+    end    
+  end  
+end

data/lib/trole/api/core.rb

@@ -0,0 +1,20 @@
+# 
+# @author Kristian Mandrup
+#
+# Single role Core Api
+#
+module Trole::Api
+  module Core        
+    # Access to the Trole operations API
+    # @return [Trole::Operations] the operations API object 
+    def role
+      Trole::Operations.new(self)
+    end
+        
+    module ClassMethods                        
+      def role_field
+        troles_config.role_field
+      end      
+    end
+  end
+end

data/lib/trole/api/event.rb

@@ -0,0 +1,9 @@
+# 
+# @author Kristian Mandrup
+#
+# Single role Event Api
+#
+module Trole::Api
+  module Event
+  end
+end

data/lib/trole/api/read.rb

@@ -0,0 +1,14 @@
+# 
+# @author Kristian Mandrup
+#
+# Single role Read Api
+#
+module Trole::Api
+  module Read
+    # the role name
+    # @return [Symbol] the name of the role 
+    def role_name
+      role_list.first      
+    end
+  end
+end

data/lib/trole/api/validation.rb

@@ -0,0 +1,9 @@
+# 
+# @author Kristian Mandrup
+#
+# Single role Validation Api
+#
+module Trole::Api
+  module Validation
+  end
+end

data/lib/trole/api/write.rb

@@ -0,0 +1,25 @@
+# @author Kristian Mandrup
+#
+# Single role Write Api
+# @note all write methods should operate on the data store via #store
+#
+module Trole::Api
+  module Write
+
+    # Set the role of the subject to a new role
+    # @param  [Symbol] the role to set
+    # @return [true, false, Error] true if ok, false if not valid, Error on some error
+    def set_role new_role
+      value = make_valid_role new_role 
+      return false if !value
+      store.set_role(value)      
+    end 
+    alias_method :role=, :set_role 
+    
+    # Clears the role of the user
+    # @return (see #set_role)
+    def clear_role!
+      store.clear!
+    end    
+  end
+end

data/lib/trole/api.rb

@@ -0,0 +1,41 @@
+# 
+# @author Kristian Mandrup
+#
+# Single role Api to be included directly on the role subject class (fx User or User Account)
+#
+module Trole
+  module Api
+    autoload :Core,        'trole/api/core'
+    autoload :Config,      'trole/api/config'
+    autoload :Cache,       'trole/api/cache'
+    
+    autoload :Event,       'trole/api/event'
+    autoload :Read,        'trole/api/read'
+    autoload :Write,       'trole/api/write'
+    autoload :Validation,  'trole/api/validation'        
+
+    #
+    # When the Trole::Api is included by the Role Subject class (fx a User Account)
+    # first include methods from Troles Common API      
+    # then include Trole API on top
+    #
+    # @param [Class] the role subject class (fx User or UserAccount)
+    #
+    module ClassMethods
+      def included(base)
+        base.send :include, Troles::Common::Api
+        self.extend Troles::Common::Api::ClassMethods # draws in the #apis method from Common Api
+
+        apis.each do |api|
+          begin
+            base.send :include, "Trole::Api::#{api.to_s.camelize}".constantize
+            base.extend "Trole::Api::#{api.to_s.camelize}::ClassMethods".constantize            
+            # base.include_and_extend :"#{api.to_s.camelize}"
+          rescue
+          end
+        end
+      end
+    end
+    extend ClassMethods    
+  end
+end

data/lib/trole/config.rb

@@ -0,0 +1,15 @@
+module Trole
+  class Config < Troles::Common::Config    
+    def initialize clazz, options = {}
+      super
+    end
+
+    def configure_role_field
+      super
+    end       
+        
+    def generic?
+      super
+    end
+  end
+end

data/lib/trole/macros.rb

@@ -0,0 +1,5 @@
+module Trole  
+  module Macros
+  end  
+end
+

data/lib/trole/operations/read.rb

@@ -0,0 +1,12 @@
+#
+# @author Kristian Mandrup
+# 
+# Trole specific operations on the #role of a role subject
+module Trole
+  class Operations      
+    module Read
+    end
+  end
+end
+
+

data/lib/trole/operations/write.rb

@@ -0,0 +1,11 @@
+#
+# @author Kristian Mandrup
+# 
+# Trole specific operations on the #role of a role subject
+#
+module Trole
+  class Operations
+    module Write
+    end
+  end
+end

data/lib/trole/operations.rb

@@ -0,0 +1,34 @@
+#
+# @author Kristian Mandrup
+# 
+# Trole operations object API, for performing operations on #roles
+#
+# Usage:
+#   - user.roles + :admin
+#   - user.roles.clear!
+#
+module Trole
+  class Operations
+    autoload :Read,     'trole/operations/read'
+    autoload :Write,    'trole/operations/write'  
+
+    include Read
+    include Write
+
+    include Enumerable
+
+    attr_reader :role_subject
+
+    # constructor
+    # @param [Object] the role subject, fx a User or UserAccount
+    def initialize role_subject
+      @role_subject = role_subject
+    end
+
+    # required method to act as enumerable
+    # iterates and yields all roles in the role list (Symbols)
+    def each
+      list.each { |role| yield role }
+    end       
+  end
+end

data/lib/trole/storage/base_one.rb

@@ -0,0 +1,46 @@
+#
+# @author Kristian Mandrup
+#
+# Single role base storage (common, reusable functionality) 
+#
+
+module Trole::Storage
+  class BaseOne < Troles::Common::Storage
+
+    # constructor
+    # @param [Symbol] the role subject
+    def initialize role_subject
+      super
+    end      
+    
+    # get Role instance by name
+    # @param  [Symbol] list of role names to find Roles for
+    # @return [Role] reference to Role instances
+    def find_role role
+      raise ArgumentError, "Must be a role label" if !role.kind_of_label?
+      role_model.where(:name => role.to_s)
+    end
+
+    # get embedded Role instances
+    # @param  [Array<Symbol>] list of role names
+    # @return [Array<Role>] Role instances generated      
+    def role_to_embed
+      raise "Must be implemented by embed storage to generate a set of roles to embed"
+    end                 
+    
+    def role_model
+      role_subject.class.troles_config.role_model
+    end
+
+    # saves the role for the user in the data store
+    def set_roles *roles
+      raise ArgumentError, "A single role strategy can only allow setting a single role, was: #{roles}" if (roles.size > 1)
+      set_role roles.flat_uniq.first
+    end  
+    
+    # sets the role to its default state    
+    def set_default_role!
+      clear!
+    end    
+  end        
+end

data/lib/trole/storage/bit_one.rb

@@ -0,0 +1,43 @@
+require 'troles/common/marshaller'
+
+#
+# @author Kristian Mandrup
+#
+# Single role storage that stores role as a boolean value (false, true)
+#
+module Trole::Storage 
+  class BitOne < BaseOne
+
+    # constructor
+    # @param [Symbol] the role subject
+    def initialize role_subject
+      super
+    end
+
+    # display the role as a list of one symbol
+    # see Troles::Marshaller::Bitmask    
+    # @return [Array<Symbol>] roles list
+    def display_roles
+      raise "BitOne requires exactly two valid roles, was: #{valid_roles}" if !(valid_roles.size == 2)
+      [bitmask.read].flatten
+    end
+        
+    # saves the role for the role subject in the data store
+    # @param [Symbol] role name
+    def set_role role
+      num = bitmask.write role
+      set_ds_field(num == 1 ? false : true) # boolean field in Data store
+    end  
+
+    # Clears the role state of the role subject 
+    def clear!
+      set_ds_field false
+    end
+    
+    protected
+
+    def bitmask
+      @bitmask ||= Troles::Common::Marshaller::Bitmask.new role_subject
+    end    
+  end
+end

data/lib/trole/storage/embed_one.rb

@@ -0,0 +1,36 @@
+#
+# @author Kristian Mandrup
+#
+# Single role storage that stores role as an embedded Role instance
+#
+module Trole::Storage 
+  class EmbedOne < BaseOne
+
+    # constructor
+    # @param [Symbol] the role subject
+    def initialize api        
+      super
+    end
+
+    # display the role as a list of one symbol
+    # @return [Array<Symbol>] roles list
+    def display_roles
+      return [] if !ds_field_value?
+      [ds_field_value.first.name.to_sym]
+    end
+
+    def ds_field_value?
+      ds_field_value && !ds_field_value.empty?
+    end    
+
+    # saves the role for the user in the data store
+    def set_role role
+      set_ds_field Role.create :name => role
+    end  
+
+    # Clears the role state of the role subject 
+    def clear!
+      set_ds_field []
+    end
+  end      
+end

data/lib/trole/storage/ref_one.rb

@@ -0,0 +1,39 @@
+#
+# @author Kristian Mandrup
+#
+# Sngle role storage that stores a role as a Role instance reference
+#
+module Trole::Storage
+  class RefOne < BaseOne        
+
+    # constructor
+    # @param [Symbol] the role subject
+    def initialize role_subject
+      super
+    end
+
+    # display the role as a list of one symbol
+    # @return [Array<Symbol>] roles list
+    def display_roles 
+      return [] if !ds_field_value?
+      [ds_field_value.name.to_sym]
+    end    
+
+    # is it set?
+    def ds_field_value?
+      ds_field_value
+    end      
+
+    # saves the role of the role subject in the data store
+    # @param [Symbol] the role name
+    def set_role role
+      role_to_set = role_model.where(:name => role).first
+      set_ds_field role_to_set
+    end  
+
+    # Clears the role state of the role subject 
+    def clear!
+      set_ds_field nil
+    end
+  end
+end

data/lib/trole/storage/string_one.rb

@@ -0,0 +1,50 @@
+#
+# @author Kristian Mandrup
+#
+# Storage that stores role as a single String
+#
+module Trole::Storage
+  class StringOne < BaseOne        
+
+    # constructor
+    # @param [Symbol] the role subject
+    def initialize role_subject        
+      super
+    end
+
+    # display the role as a list of one symbol
+    # see Troles::Marshaller::Bitmask    
+    # @return [Array<Symbol>] roles list
+    # display the role as a list of one symbol
+    # @return [Array<Symbol>] roles list
+    def display_roles
+      return [] if ds_field_value?
+      [ds_field_value.to_sym]
+    end
+
+    # is it set?
+    def ds_field_value?
+      ds_field_value && !!ds_field_value.empty?
+    end      
+
+    # saves the roles for the role subject in the data store
+    # see Troles::Marshaller::Bitmask
+    # @param [Array<Symbol>] roles list        
+    def set_roles *roles
+      roles = roles.flatten
+      raise ArgumentError, "For a single role strategy you can only set one role, was: #{roles.flatten}" if roles.empty? || (roles.size > 1)
+      set_role roles.first
+    end  
+
+    # saves the role of the role subject in the data store
+    # @param [Symbol] the role name
+    def set_role role
+      set_ds_field role.to_s
+    end  
+
+    # Clears the role state of the role subject 
+    def clear!
+      set_ds_field ""
+    end
+  end
+end

data/lib/trole/storage.rb

@@ -0,0 +1,14 @@
+#
+# @author Kristian Mandrup
+#
+# Container for Single role Storages
+#
+module Trole
+  module Storage
+    autoload :BaseOne,   'trole/storage/base_one'
+    autoload :BitOne,    'trole/storage/bit_one'
+    autoload :EmbedOne,  'trole/storage/embed_one'
+    autoload :RefOne,    'trole/storage/ref_one'
+    autoload :StringOne, 'trole/storage/string_one'        
+  end
+end

data/lib/trole/strategy.rb

@@ -0,0 +1,35 @@
+#
+# @author Kristian Mandrup
+#
+# Base module for Single role strategies
+#
+module Trole::Strategy
+  module BaseOne
+    #
+    # a Many role strategy is included by a role subject (fx a UserAccount class) 
+    # a Many role strategy should always include BaseMany
+    # when BaseMany is included, it ensures that the complete 
+    # Trole Api is also included into the role subject                                              
+    #
+    # @note the Trole::Api also includes the Troles::Common::Api
+    #
+    # @param [Class] the role subject class for which to include the Role strategy (fx User Account)
+    #
+    #
+    def self.included(base)
+      base.send :include, Trole::Api
+    end      
+
+    # The storage to use
+    # @return [Troles::Storage] a storage subclass instance matching the needs of the strategy
+    def store
+      @store ||= storage.new self
+    end
+
+    # The storage strategy class
+    # @return [Class] a storage subclass
+    def storage 
+      Trole::Storage::BaseOne
+    end
+  end
+end

data/lib/trole.rb

@@ -0,0 +1,10 @@
+# require 'troles'
+require 'troles/common'
+
+module Trole
+  autoload :Config,         'trole/config'
+  autoload :Api,            'trole/api'
+  autoload :Operations,     'trole/operations'
+  autoload :Strategy,       'trole/strategy'      
+  autoload :Storage,        'trole/storage'
+end

data/lib/troles/adapters/active_record/Design Notes.textile

@@ -0,0 +1,4 @@
+h1. Design Notes for Active Record adapter
+
+The generic strategies and storages should expect a basic Active Model interface for the models, so no need to redefine these for Active Record.
+Only the embed strategy has to be handles specifically, since Relation DBs don't naturally support the concept of embedding.