troles 0.5.0

data/lib/troles/common/operations/write.rb

@@ -0,0 +1,42 @@
+# @author Kristian Mandrup
+module Troles::Common
+  class Operations
+    module Write
+      
+      # Test roles equality
+      # @param [Array<Symbol>] roles list to test
+      def == *roles
+        role_subject.role_list == roles.flatten
+      end
+      alias_method :equal, :"=="
+      alias_method :same_as, :"=="
+
+      # Add a set of roles to the role subject
+      # @param  [Array<Symbol>] roles list to add
+      # @return [true, false, Error] true if added, false if static or invalid, Error on some error
+      def + *roles
+        role_subject.add_roles roles
+      end
+      alias_method :<<, :+
+      alias_method :add, :+
+      alias_method :add!, :+                           
+
+      # Remove a set of roles from the role subject
+      # @param  [Array<Symbol>] roles list to add
+      # @return [true, false, Error] true if removed, false if static or invalid, Error on some error
+      def - *roles
+        role_subject.remove_roles roles
+      end
+      alias_method :remove, :-
+      alias_method :remove!, :-
+
+      # Clear all the roles from the role subject
+      # @param  [Array<Symbol>] roles list to add
+      # @return [true, false, Error] true if removed, false if static or invalid, Error on some error
+      def clear
+        role_subject.clear_roles!
+      end    
+      alias_method :clear!, :clear
+    end
+  end
+end

data/lib/troles/common/operations.rb

@@ -0,0 +1,33 @@
+# @author Kristian Mandrup
+# 
+# The Operations API object
+# 
+# Usage example:
+#   - user.roles + :admin
+#   - user.roles.clear! 
+#
+module Troles::Common
+  class Operations        
+    autoload :Read,     'troles/common/operations/read'
+    autoload :Write,    'troles/common/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/troles/common/storage.rb

@@ -0,0 +1,73 @@
+# @author Kristian Mandrup
+#  
+# The Common Storage API
+# @note all methods potentially operate directly on values in the data store
+#
+module Troles::Common
+  class Storage
+    attr_reader :role_subject
+
+    # initializes storage with reference to role subject
+    # @param [Object] the role subject (fx a User or UserAccount) 
+    def initialize role_subject
+      @role_subject = role_subject
+    end      
+
+    # valid roles of the role subjects class (fx account - i.e the account rules!)
+    # @return [Array<Symbol>] the list of valid roles
+    def valid_roles
+      role_subject.class.valid_roles
+    end        
+
+    # name/type of storage
+    # @return [Symbol]
+    def name
+      :generic
+    end 
+
+    # sets the value of the role field (@trole or @troles) and persists the value (in the data store)
+    # @param [Object] the value to set on the role field of the role subject
+    def set_ds_field value
+      role_subject.send(:"#{ds_field_name}=", value)
+      persist_role_changes!
+    end
+
+    # the name of the role field
+    # @return [Symbol] the name
+    def ds_field_name
+      role_field
+    end
+
+    # the current value of the role field
+    # @return [Object] the value
+    def ds_field_value
+      role_subject.send(ds_field_name)
+    end      
+
+    # Attempts to persist the role field changes
+    # @return [true, false, error] true if saved, false if no save! method, Error on some error
+    def persist_role_changes!  
+      return false if !role_subject.respond_to? :save!
+      role_subject.save!
+      role_subject.publish_change :roles
+    end 
+
+    protected
+
+    def troles_config
+      role_subject.class.troles_config
+    end
+
+    def role_field      
+      troles_config.role_field
+    end
+
+    def role_model
+      troles_config.role_model
+    end
+
+    def role_list
+      role_subject.role_list
+    end
+  end        
+end

data/lib/troles/common.rb

@@ -0,0 +1,17 @@
+#
+# @author Kristian Mandrup
+#
+# The Common (Generic) Roles API, functionality to be reused by both Trole and Troles
+#
+require 'troles/common/dependencies'
+
+module Troles
+  module Common
+    autoload :Api,          'troles/common/api'
+    autoload :Config,       'troles/common/config'
+    autoload :Operations,   'troles/common/operations'
+    autoload :Marshaller,   'troles/common/marshaller'
+    autoload :Storage,      'troles/common/storage'
+    autoload :EventManager, 'troles/common/event_manager'
+  end  
+end

data/lib/troles/config.rb

@@ -0,0 +1,15 @@
+module Troles
+  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/troles/macros.rb

@@ -0,0 +1,7 @@
+require 'troles/common/macros'
+
+module Troles  
+  module Macros
+  end  
+end
+

data/lib/troles/meta.rb

@@ -0,0 +1,5 @@
+class Object # http://whytheluckystiff.net/articles/seeingMetaclassesClearly.html
+  def meta_def name, &blk
+    (class << self; self; end).instance_eval { define_method name, &blk }
+  end
+end

data/lib/troles/operations/read.rb

@@ -0,0 +1,6 @@
+module Troles
+  class Operations
+    module Read
+    end
+  end
+end

data/lib/troles/operations/write.rb

@@ -0,0 +1,6 @@
+module Troles
+  class Operations
+    module Write
+    end
+  end
+end

data/lib/troles/operations.rb

@@ -0,0 +1,12 @@
+module Troles
+  class Operations < Troles::Common::Operations
+    autoload :Read,     'troles/operations/read'
+    autoload :Write,    'troles/operations/write'
+    
+    # constructor
+    # @param [Object] the role subject, fx a User or UserAccount
+    def initialize role_subject
+      super
+    end    
+  end
+end

data/lib/troles/storage/base_many.rb

@@ -0,0 +1,25 @@
+# @author Kristian Mandrup
+#
+# Troles base storage for Many roles strategies
+#
+module Troles
+  module Storage
+    class BaseMany < Troles::Common::Storage
+      protected
+      
+      # get matching list of Role instances
+      # @param  [Array<Symbol>] list of role names to find Roles for
+      # @return [Array<Role>] references to Role instances
+      def find_roles *roles
+        role_model.where(:name => roles.flatten).all
+      end
+
+      # get list of embedded Role instances
+      # @param  [Array<Symbol>] list of role names
+      # @return [Array<Role>] Role instances generated      
+      def roles_to_embed *roles
+        raise "Must be implemented by embed storage to generate a set of roles to embed"
+      end           
+    end        
+  end
+end

data/lib/troles/storage/bit_many.rb

@@ -0,0 +1,56 @@
+# @author Kristian Mandrup
+#
+# Many role storage for storing roles as an Integer bitmask on the role subject
+#
+# @note all methods potentially operate directly on values in the data store
+#
+module Troles::Storage
+  class BitMany < BaseMany
+    # constructor
+    # @param [Object] the role subject
+    def initialize role_subject
+      super
+    end
+
+    # display the roles as a list of symbols
+    # see Troles::Marshaller::Bitmask    
+    # @return [Array<Symbol>] roles list
+    def display_roles
+      return [] if !ds_field_value?
+      bitmask.read
+    end
+
+    def ds_field_value?
+      ds_field_value == 0
+    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.to_symbols_uniq
+      return clear! if roles.empty?      
+      set_ds_field bitmask.write(roles.to_symbols)
+    end  
+
+    # Clears the role state of the role subject 
+    def clear!
+      set_ds_field 0
+    end
+  
+    # Sets role to default state    
+    def set_default_role!
+      clear!
+    end            
+
+    protected
+
+    def bitmask
+      @bitmask ||= bitmask_class.new role_subject
+    end
+    
+    def bitmask_class
+      Troles::Common::Marshaller::Bitmask
+    end
+  end
+end

data/lib/troles/storage/embed_many.rb

@@ -0,0 +1,58 @@
+# @author Kristian Mandrup
+#
+# Many role storage for storing (embedding) multiple Role instances in a list on the role subject
+#
+# @note all methods potentially operate directly on values in the data store
+#
+module Troles::Storage
+  class EmbedMany < BaseMany
+
+    # constructor
+    # @param [Object] the role subject
+    def initialize role_subject
+      super
+    end
+
+    def roles_to_embed *roles
+      roles.flatten.inject([]) do |res, role| 
+        res << create_role(role)
+        res
+      end
+    end           
+
+    # display the roles as a list of symbols
+    # @return [Array<Symbol>] roles list
+    def display_roles
+      return [] if !ds_field_value?
+      ds_field_value.map{|role| role.name.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
+    # @param [Array<Symbol>] roles list    
+    def set_roles *roles
+      # creates and embeds new Role instances from symbols
+      set_ds_field roles_to_embed(*roles)
+    end  
+
+    # clears the role of the user in the data store
+    def clear!
+      set_ds_field []
+    end  
+  
+    # sets the role to its default state
+    def set_default_role!
+      clear!
+    end
+    
+    protected
+    
+    def create_role name
+      role_model.create name
+    end
+  end
+end

data/lib/troles/storage/ref_many.rb

@@ -0,0 +1,44 @@
+# @author Kristian Mandrup
+# 
+# Many role storage for storing multiple Role references on the role subject
+#
+# @note all methods potentially operate directly on values in the data store
+#
+module Troles::Storage
+  class RefMany < BaseMany
+    def initialize role_subject
+      super
+    end
+
+    # display the roles as a list of symbols
+    # @return [Array<Symbol>] roles list
+    def display_roles
+      return [] if !ds_field_value?
+      ds_field_value.flatten.map do |role| 
+        role.name.to_sym 
+      end
+    end
+
+    # is it set?
+    def ds_field_value?
+      ds_field_value && !ds_field_value.empty?
+    end      
+    
+    # saves the role for the user in the data store
+    def set_roles *roles
+      # finds and sets references to existing Role instances from symbols        
+      found_roles = find_roles(*roles)
+      set_ds_field found_roles
+    end  
+
+    # clears the role of the user in the data store
+    def clear!
+      set_ds_field []
+    end
+    
+    # sets the role to default setting
+    def set_default_role!
+      clear!
+    end                            
+  end
+end

data/lib/troles/storage/string_many.rb

@@ -0,0 +1,41 @@
+# @author Kristian Mandrup
+#
+# Many role storage for storing a comma ',' seperated String of roles on the role subject
+#
+# @note all methods potentially operate directly on values in the data store
+#
+module Troles::Storage
+  class StringMany < BaseMany
+    def initialize role_subject
+      super
+    end
+
+    # display the roles as a list of symbols
+    # @return [Array<Symbol>] roles list
+    def display_roles
+      return [] if !ds_field_value?
+      ds_field_value.split(',').map{|r| r.strip }.map(&: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
+    # @param [Array<Symbol>] roles list
+    def set_roles *roles
+      value = roles.flatten.map(&:to_s).join(',')
+      set_ds_field value
+    end  
+
+    # clears the role of the user in the data store
+    def clear!
+      set_ds_field ""
+    end
+    
+    # sets the role to default setting
+    def set_default_role!
+      clear!
+    end        
+  end
+end

data/lib/troles/storage.rb

@@ -0,0 +1,13 @@
+# @author Kristian Mandrup
+#
+# @note all storage modules potentially operate directly on values in the data store
+#
+module Troles
+  module Storage
+    autoload :BaseMany,   'troles/storage/base_many'
+    autoload :BitMany,    'troles/storage/bit_many'
+    autoload :EmbedMany,  'troles/storage/embed_many'
+    autoload :RefMany,    'troles/storage/ref_many'
+    autoload :StringMany, 'troles/storage/string_many'    
+  end
+end

data/lib/troles/strategy.rb

@@ -0,0 +1,34 @@
+# @author Kristian Mandrup
+#
+# Base module for Many roles strategies
+#
+module Troles
+  module Strategy    
+    module BaseMany
+      #
+      # 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 
+      # Troles 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, Troles::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
+
+      # @return [Class] the storage strategy class
+      def storage 
+        raise "Must be implemented by subclass" # Troles::Storage::BaseMany
+      end      
+    end
+  end
+end

data/lib/troles.rb

@@ -0,0 +1,11 @@
+require 'troles/common'
+require 'troles/macros'
+
+module Troles  
+  autoload :Config,         'troles/config'
+  autoload :Common,         'troles/common'
+  autoload :Api,            'troles/api'
+  autoload :Operations,     'troles/operations'
+  autoload :Strategy,       'troles/strategy'
+  autoload :Storage,        'troles/storage'
+end

data/playbox/old_rake

@@ -0,0 +1,25 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rake/rdoctask'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Troles'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/spec/Guide to running specs.textile

@@ -0,0 +1,16 @@
+h1. Guide to running specs
+
+The specs use shared examples! See the _troles/api_spec.rb_, _trole/api_spec.rb_ and more importantly the _troles/common/api_spec.rb_.
+This is where most of the goodies are defined. Each api_spec pulls in spec examples from the /api folder in the respective location.
+To remove one or more APIs from the spec run, simply outcomment in the relevant _api_spec.rb_.
+
+To run specs, I recommend running for individual strategies:
+
+Example:
+
+@$ rspec spec/troles/strategies/bit_many_spec.rb@ 
+
+If the output is too much, remove one or more APIs from the "run" as describe above!
+
+Happy bug hunting!
+ 

data/spec/active_record/migrations/many/bit_many.rb

@@ -0,0 +1,16 @@
+class CreateBitMany < ActiveRecord::Migration
+  def self.up
+    # down
+    
+    create_table :users do |t|
+      t.string  :name
+      t.integer :troles
+      t.timestamps
+    end
+  end
+  
+  def self.down  
+    drop_table :users
+  end
+end
+    

data/spec/active_record/migrations/many/ref_many.rb

@@ -0,0 +1,31 @@
+class CreateRefMany < ActiveRecord::Migration
+  def self.up
+    # down
+
+    create_table :users do |t|
+      # implicit user_id binds to user_id of roles_users join table
+      t.string :name
+      t.timestamps
+    end
+
+    # join table
+    create_table :roles_users, :id => false do |t|
+      t.integer :user_id
+      t.integer :role_id
+    end
+
+    
+    create_table :roles do |t|
+      # implicit role_id binds to role_id of roles_users join table
+      t.string :name
+      t.timestamps
+    end    
+  end
+  
+  def self.down  
+    drop_table :users
+    drop_table :roles
+    drop_table :users_roles
+  end
+end
+

data/spec/active_record/migrations/many/string_many.rb

@@ -0,0 +1,16 @@
+class CreateStringMany < ActiveRecord::Migration
+  def self.up
+    # down
+
+    create_table :users do |t|
+      t.string :name
+      t.string :troles
+      t.timestamps
+    end
+  end
+  
+  def self.down  
+    drop_table :users
+  end
+end
+

data/spec/active_record/migrations/one/bit_one.rb

@@ -0,0 +1,14 @@
+class CreateBitOne < ActiveRecord::Migration
+  def self.up        
+    create_table :users do |t|
+      t.string :name
+      t.boolean :trole
+      t.timestamps
+    end
+  end
+  
+  def self.down
+    drop_table :users
+  end
+end
+

data/spec/active_record/migrations/one/ref_one.rb

@@ -0,0 +1,20 @@
+class CreateRefOne < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      t.string :name
+      t.integer :role_id # a user can have ONE role
+      t.timestamps
+    end
+
+    create_table :roles do |t|
+      t.string :name
+      t.timestamps
+    end
+  end
+  
+  def self.down
+    drop_table :users
+    drop_table :roles
+  end  
+end
+

data/spec/active_record/migrations/one/string_one.rb

@@ -0,0 +1,14 @@
+class CreateStringOne < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      t.string :name
+      t.string :trole
+      t.timestamps
+    end
+  end
+  
+  def self.down
+    drop_table :users
+  end
+end
+