troles 0.5.1 → 0.5.2

data/README.textile

@@ -13,75 +13,6 @@ The roles list cache of a role subject (fx a user) is only updated (retrieved fr
 
 Note: Troles is a full redesign of _roles generic_ and company, using lessons learned. Troles uses a much cleaner design. It is aimed at being easy to extend and easy to create adapters for etc.
 
-h2. Status June 7, 2011 
-
-I'm now in the process of implementing TroleGroups! Finally a fully integrated role groups solution for Ruby and Rails ;)
-Due to the flexible design ot troles and trole, I can reuse the same infrastructure/design/architecture to implement trole_groups! 
-*Yiii...haaa!*   
-                 
-"A RoleGroup is simply another role_subject and can thus be configured with a given role strategy!" 
-
-Simple and Sweet :)
-
-h2. The Ruby Class Decorator (RCD) pattern is born!!!
-
-I realized a while ago that I had come upon a very cool kind of "class decorator" design pattern that can be generalized to any gem that "decorates" a class (or perhaps multiple classes) with certain behavior. Gems such as _act_as_xxx_ come to mind fx.
-
-I will soon try to generalize this pattern into a separate project and then have trole, troles and trole_groups all use this to leverage their functionality. Also, I will make use of an idea that I just had while taking a cold shower (try it sometime if you have a mind block!). 
-The idea is to have an internal default API, and an exposed API that by default is a reflection of the internal API. However the user is free to block parts of the API from being loaded or define his own external API that utilizes the inner API.
-
-Since this is a general purpose decorator pattern, there should also be a kind of Index where you can see which decorators have been applied to an object and what API each such decorator exposes! Cool stuff!!!!  
-
-Some example usage:
-<pre>
-return if !User.has_decorator?(:troles_group)
-# do some trole group stuff!!!
-
-# later ...
-
-# list all decorators currently applied to the User class
-puts User.decorators
-
-# print the methods of the public Write API for the :troles_group decorator :)
-puts User.decorator(:troles_group).public_api(:write).methods.sort
-
-# print the methods of the internal Write API for the :troles_group decorator :)
-puts User.decorator(:troles_group).internal_api(:write).methods.sort
-</pre>
-
-I will use the new Decorator API very soon... sth like this:
-
-<pre>
-User.decorator(:trole_groups).configure(:strategy) :ref_one do |strategy|
-  strategy.orm = :mongoid
-  strategy.auto_load = true
-end.configure!  
-</pre>
-
-Awesome! 
-
-h3. Yard documentation
-
-I'm using "Yard":http://rubydoc.info/docs/yard/file/docs/GettingStarted.md for documentation.
-
-<pre>$ yard server
-
-From browser, go to: http://0.0.0.0:8808/  # then you can enjoy! the nice documentation :) 
-</pre>
-
-There is now support for Caching and invalidation of the _role_list_ when the roles change. 
-The specs now validate that caching works as it should.
-
-Please help out to finalize this project! :)
-
-h2. Bug hunting by running specs
-
-Run specs for at most one strategy at the time for now...
-
-@$ rspec spec/troles/strategies/bit_many_spec.rb@ 
-
-Please see the document _spec/Guide to running specs.textile_ where I advise on how best to do "bug hunting" to help get this project off the ground!
-
 h2. Role strategies
 
 The following lists the role strategies to be supported
@@ -131,47 +62,47 @@ These strategies can be implemented for any data store using any schema format.
 
 h3. Using roles strategies with Users and User accounts
 
-Roles are assigned to role subject classes such as _User_ or _UserAccount_ (YES, Devise can have multiple user accounts!). The class that has a role strategy assigned is referred to as the _role subject class_. 
-Different role subject classes can have different role strategies! 
+Roles are assigned to role subject classes such as _User_ or _UserAccount_ (YES, Devise can have multiple user accounts!). The class that has a role strategy assigned is referred to as the _role subject class_. Different role subject classes can have different role strategies! 
 
 When using Devise this could translate fx into a UserAccount with a "many roles" strategy and an AdminAccount with a "single role" strategy (or vice versa). 
 
 Example:
 
-<pre> 
-  require 'troles'
-  require 'troles/macros'
-  
-  class UserAccount
-    troles_strategy(:string_many).configure!
-  end
+<pre>require 'troles'
+require 'troles/macros'
 
-  class AdminAccount
-    troles_strategy(:bit_one, :static => true).configure!
-  end  
+class UserAccount
+  troles_strategy(:string_many).configure!
+end
+
+class AdminAccount
+  troles_strategy(:bit_one, :static => true).configure!
+end  
 </pre>
 
-The special troles macros must be enabled my requiring the _trole/macros_ file. 
+The special troles macros must currently be enabled my requiring the _troles/macros_ file. 
+If the troles macros are not included like this, the troles DSL can be made available for an individual class by including a specific Strategy.
+Using the macros like in the above example is much easier and is recommended.
 
 h3. Macro options
 
 The @:static => true@ options is used to indicate, that the role can not be changed after being initially set. 
-But we are getting ahead of ourselves... (more on this later).
-Troles can easily be extended to support other macro options if needed.
+But we are getting ahead of ourselves... (more on this later). Troles can easily be extended to support other macro options if needed.
+Note: This static roles functionality is currently in-progress... (used to work but under change).
 
 h2. Roles API
 
 The Roles API can be divided into:
 
 * Core
-* Event/Cache
+* Event
+* Cache
 * Read
 * Write
-* Store
 * Validation
 * Operations object
 
-There is an equivalen Trole API for single role strategies.
+There is an equivalent Trole API for single role strategies.
 
 h3. Event/Cache API
 
@@ -181,46 +112,33 @@ can have subscribers to events.
 
 Also any write event to the datastore should be predicated on _#static_roles?_ not being true for the user (thus ensuring guest roles are never updated).
 
-Save triggers call to Event#update_roles
-<pre>
-User
-  after_save: update_roles # event handler
-</pre>
-
-<pre>
-module Troles::Api::Event
-  def update_roles
-  def publish_change event
-</pre>
+@User.after_save: update_roles # event handler@
 
 h3. Roles Read API
 
 This API operates directly on a user, fx _user#has_role?_
 
-<pre>  
-  user.has_role? :admin
-  user.is_role? :editor
-  user.has_any_roles? :editor, :admin  
+<pre>user.has_role? :admin
+user.is_role? :editor
+user.has_any_roles? :editor, :admin  
 </pre>
 
 h3. Roles Write API
 
 This API operates directly on a user, fx _user#has_role?_
 
-<pre>
-  user.add_role :admin
-  user.remove_role :editor
+<pre>user.add_role :admin
+user.remove_role :editor
 </pre>
 
 h3. Roles Operations object
 
 The Roles Operations object is available on user#roles
 
-<pre>
-  user.roles + :admin
-  user.roles - :editor
-  user.roles << [:editor, :admin]
-  user.roles.clear!  
+<pre>user.roles + :admin
+user.roles - :editor
+user.roles << [:editor, :admin]
+user.roles.clear!  
 </pre>
 
 h3. Creating a custom Data Store Adapter (DSA)
@@ -231,11 +149,9 @@ Note that :single role strategies always have the namespace 'Trole' whereas for
 
 A custom Config class for _:single_ role strategies using _Mongoid_ could look sth. like this:
 
-<pre>
-module Trole::Mongoid
+<pre>module Trole::Mongoid
   class Config < Troles::Common::Config  
-
-    def initialize subject_class, options = {}
+    def initialize subject, options = {}
       super
     end
   
@@ -265,8 +181,7 @@ See the _schema_helpers.rb_ file for more details!
 
 Example: Config class for :many roles strategies with _Mongoid_
 
-<pre>
-module Troles::Mongoid
+<pre>module Troles::Mongoid
   class Config < Troles::Common::Config  
 
     def initialize subject_class, options = {}
@@ -305,8 +220,7 @@ Note: #set_role is only required for :single role strategies. In this case #set_
 
 Example custom SSA (encrypted role string):
 
-<pre>
-module Trole::Storage
+<pre>module Trole::Storage
   module EncryptedStringOne < BaseOne
     def initialize role_subject        
       super
@@ -344,8 +258,7 @@ h3. Custom Storage for an ORM (or data store)
 
 In some cases it is useful to rewrite part of the base Storage functionality. One such method is #find_roles.
 
-<pre>
-module Troles::Storage
+<pre>module Troles::Storage
   class BaseMany < Troles::Common::Storage
     def find_roles *roles
       role_model.where(:name => roles.flatten).all
@@ -357,8 +270,7 @@ end
 Active Record and Mongoid both implement the above API, so no need to customize this method in the Storage adapter.
 For most other ORMs/data stores you will likely have to write your own logic to achieve this.
 
-<pre>
-module Troles::MongoidStorage
+<pre>module Troles::MongoidStorage
   class RefMany < Troles::Storage::BaseMany
 
     def find_roles *roles
@@ -371,10 +283,9 @@ h3. Custom data marshaller
 
 You can also use a custom "Marshaller":http://en.wikipedia.org/wiki/Marshalling_%28computer_science%29 to store the roles in a non-standard format. This is used for the _BitMany_ strategy, which has a special _Marshaller::BitMask_ class which handles conversion between a list of symbols to an _Integer_ bitmap representing it (relative to a valid roles list!). You can create your own _Marshaller_, fx to encrypt the roles info or whatever you like!
 
-<pre>
-module Troles::Marshaller
+<pre>module Troles::Marshaller
   class Encryption < Generic
-    def initialize role_subject
+    def initialize subject
       super
     end
 
@@ -395,8 +306,7 @@ h3. Using a custom Marshaller in a Storage implementation
 
 The following example is taken from the BitOne Storage implementation that is part of troles:
 
-<pre>
-require 'troles/common/marshaller'
+<pre>require 'troles/common/marshaller'
 
 module Trole::Storage 
   class BitOne < BaseOne
@@ -432,10 +342,9 @@ Note that the same _BitMask_ marshaller is also reused in the _BitMany_ storage!
 
 The _#bitmask_ method returns an instance of the _Bitmask_ marshaller, instantiated with the _role_subject_ (the instance that has the #role_list method, typically the user or user account). To use the _Encryption_ marshaller in an Encryption storage we could create a _#marshaller_ method:
 
-<pre>
-  def marshaller
-    @marshaller ||= Troles::Marshaller::Encryption.new role_subject
-  end  
+<pre>def marshaller
+  @marshaller ||= Troles::Marshaller::Encryption.new role_subject
+end  
 </pre>
 
 Then use @marshaller.write(*roles)@ in the _set_xxxx_ methods and @marshaller.read@ in _#display_roles_ method of the storage, as needed.
@@ -456,8 +365,7 @@ You rarely need to implement a custom Strategy module or custom API implementati
 Here is an example of a custom Strategy implementation for _EncryptedStringMany_ that simply wraps the _BaseMany_ strategy implementation.
 This example demonstrates how you can easily override functionality with custom implementations by including modules "on top".
 
-<pre>
-module Troles::Strategy
+<pre>module Troles::Strategy
   module EncryptedStringMany
 
     # What to add to the role subject class when this role strategy is included
@@ -485,28 +393,25 @@ In some cases you need a custom Base strategy that contains common functionality
 
 Example: _BaseMany_, used as the base for all Many roles strategies
 
-<pre>
-  module Troles::Mongoid
-    module Strategy    
-      module BaseMany
-        # @param [Class] the role subject class for which to include the Role strategy (fx User Account)
-        #
-        def self.included(base)
-          base.send :include, Troles::Strategy::BaseMany        
-
-          # base.send :include, InstanceMethods      
-          # base.extend ClassMethods            
-        end
+<pre>module Troles::Mongoid
+  module Strategy    
+    module BaseMany
+      # @param [Class] the role subject class for which to include the Role strategy (fx User Account)
+      #
+      def self.included(base)
+        base.send :include, Troles::Strategy::BaseMany        
+
+        # base.send :include, InstanceMethods      
+        # base.extend ClassMethods            
       end
     end
   end
+end
 </pre>
   
 To use your adapter, simply pass an extra option to the _troles_strategy_ macro:
 
-<pre>
-  User.troles_strategy(:bit_one, :orm => :mongoid).configure!
-</pre> 
+@User.troles_strategy(:bit_one, :orm => :mongoid).configure!@
 
 This even allows you to use different ORM role strategies/storages for different user accounts simultaneously!!!
 
@@ -514,22 +419,17 @@ Using the :auto_load option will 'auto load' (i.e require) the orm adapter from
 You can include a specific custom (or 3rd party) adapter manually. In the future it will be possible to configure troles with adapters 
 and specify how/where to load them from as part of this configuration!
 
-<pre>
-  User.troles_strategy(:bit_one, :orm => :mongoid, :auto_load => true).configure!
-</pre> 
+@User.troles_strategy(:bit_one, :orm => :mongoid, :auto_load => true).configure!@
 
 You can also specify some of the options relevant to model configuration on the call to #configure if you like ;) 
 
-<pre>
-  User.troles_strategy(:bit_one, :orm => :active_record, :auto_load => true).configure! :role_model => 'Troll'
-</pre> 
+@User.troles_strategy(:bit_one, :orm => :active_record, :auto_load => true).configure! :role_model => 'Troll'@
 
 The _troles_strategy_ macro will yield the Config object if you pass it a block. 
 This allows you to configure your stategy with troles inside the block and then call _configure!_ on end of the block.
 Using all this in combination, you could configure it all doing sth. like this:
 
-<pre>  
-require 'my/own/active_record/adapter'  
+<pre>require 'my/own/active_record/adapter'  
   
 User.troles_strategy :bit_one, :orm => :active_record do |c|
   c.auto_load = false
@@ -591,14 +491,13 @@ _troles_ will be part of a larger project under development that will go under t
 
 h3. Guest users
 
-From the Devise wiki: https://github.com/plataformatec/devise/wiki/How-To:-Create-a-guest-user
+From the "Devise wiki":https://github.com/plataformatec/devise/wiki/How-To:-Create-a-guest-user
 
 "In some applications, it's useful to have a guest User object to pass around even before the (human) user has registered or logged in. Normally, you want this guest user to persist as long as the browser session persists.
 
 Our approach is to create a guest user object in the database and store its id in session[:guest_user_id]. When (and if) the user registers or logs in, we delete the guest user and clear the session variable. A helper function, current_or_guest_user, returns guest_user if the user is not logged in and current_user if the user is logged in."
 
-<pre>
-module ApplicationHelper
+<pre>module ApplicationHelper
   ...
   # if user is logged in, return current_user, else return guest_user
   def current_or_guest_user
@@ -631,9 +530,7 @@ end
 
 In the new system, I propose the following:
 
-<pre>
-
-# this will make the current user the guest user account for the given scope!
+<pre># this will make the current user the guest user account for the given scope!
 def sign_in_guest scope, options = {}
   warden.set_user(guest_user.account, options.merge!(:scope => scope))
 end
@@ -665,8 +562,7 @@ def guest_user
 end  
 </pre>
 
-<pre>     
-class GuestUserAccount
+<pre>class GuestUserAccount
   troles_strategy(:static_one, :role => :guest) do |c|
     # c.valid_roles = [:guest] not needed!
   end.configure!
@@ -685,8 +581,7 @@ end
 
 Here the special _:static_many_ strategy is used, which means that whatever the _role_list_ is first set to can never change for that user.
 
-<pre>
-module BaseAccount
+<pre>module BaseAccount
   # transfer guest settings to logged_in user/account
   def transfer_guest(guest_user)
   end  
@@ -711,8 +606,7 @@ end
 
 And here the User setup:
 
-<pre>
-module BaseUser
+<pre>module BaseUser
 end
 
 class User
@@ -726,8 +620,7 @@ class User
 end  
 </pre>
 
-<pre>
-class GuestUser
+<pre>class GuestUser
   include BaseUser
 
   def account

data/VERSION

@@ -1 +1 @@
-0.5.1
+0.5.2

data/lib/trole.rb

@@ -5,6 +5,6 @@ module Trole
   autoload :Config,         'trole/config'
   autoload :Api,            'trole/api'
   autoload :Operations,     'trole/operations'
-  autoload :Strategy,       'trole/strategy'      
+  autoload :Strategy,       'trole/strategy'
   autoload :Storage,        'trole/storage'
-end
+end

data/lib/trole_groups/storage/base_many.rb

@@ -28,7 +28,11 @@ module TroleGroups
       # 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
-        return if ds_field_value == value
+        return if ds_field_value == value 
+        if Troles::Common::Config.log_on?
+          puts "TroleGroups::Storage::BaseMany.set_ds_field:"
+          puts "#{rolegroup_subject}.#{ds_field_name} = #{value}"
+        end
         rolegroup_subject.send(:"#{ds_field_name}=", value)
         persist_role_changes!
       end
@@ -42,15 +46,22 @@ module TroleGroups
       # the current value of the role field
       # @return [Object] the value
       def ds_field_value
+        # puts "#{rolegroup_subject}.#{ds_field_name}" if Troles::Common::Config.log_on?
         rolegroup_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 !rolegroup_subject.respond_to? :save!
-        rolegroup_subject.save!
-        rolegroup_subject.publish_change :role_groups
+      def persist_role_changes!
+        puts "TroleGroups::Storage::BaseMany.persist_role_changes!" if Troles::Common::Config.log_on?
+        if !rolegroup_subject.respond_to? :save
+          puts "could not save since no #save method on subject: #{rolegroup_subject}" if Troles::Common::Config.log_on?
+          return false 
+        else      
+          puts "#{rolegroup_subject}.save" if Troles::Common::Config.log_on?         
+          rolegroup_subject.save
+          rolegroup_subject.publish_change :role_groups
+        end
       end 
 
       protected

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

@@ -7,8 +7,10 @@ module Troles::ActiveRecord
     
     def configure_relation
       case strategy
+      when :join_ref_many
+        configure_join_model
       when :ref_many
-        return configure_join_model if role_join_model
+        return configure_join_model if join_model
         has_and_belongs_many subject_class, object_model, :key => :accounts         
       when :embed_many
         raise "Embed many configuration not yet implemented for ActiveRecord" 
@@ -25,6 +27,11 @@ module Troles::ActiveRecord
       role_model
     end
 
+    def join_model
+      role_join_model
+    end
+
+
     def role_join_model
       @join_model_found ||= begin
         models = [@join_model, join_model_best_guess].select do |class_name|
@@ -50,10 +57,17 @@ module Troles::ActiveRecord
       make_key role_join_model
     end
     
-    def configure_join_model
+    def configure_join_model           
+      if Troles::Common::Config.log_on?
+        puts "configuring join model..." 
+        puts "Subject class: #{subject_class}"
+        puts "Role class: #{object_model}"
+        puts "Join class: #{join_model}"
+      end
+
       # UserAccount
       # has_many :troles, :class_name => 'Role', :through => :users_roles
-      has_many_for subject_class, role_model, :through => join_key 
+      has_many_for subject_class, object_model, :opts => {:through => join_key.to_sym}
       # has_many :user_roles, :class_name => 'UserRole'
       has_many_for subject_class, role_join_model, :key => join_key
 
@@ -65,10 +79,10 @@ module Troles::ActiveRecord
 
       # Role
       # has_many :accounts, :class_name => 'User', :through => :user_roles      
-      has_many_for role, subject_class, :through => join_key, :key => :accounts
+      has_many_for object_model, subject_class, :key => :accounts, :opts => {:through => join_key.to_sym}
 
       # has_many :user_roles, :class_name => 'UserRole'
-      has_many_for role, role_join_model, :key => join_key      
+      has_many_for object_model, role_join_model, :key => join_key      
     end
   end
 end

data/lib/troles/api/config.rb

@@ -5,5 +5,5 @@
 #
 module Troles::Api
   module Config
-  end  
+  end
 end

data/lib/troles/api/core.rb

@@ -1,9 +1,9 @@
 module Troles::Api
-  module Core    
-    module ClassMethods      
+  module Core
+    module ClassMethods
       def role_field
         troles_config.role_field
-      end      
+      end
     end
   end
-end
+end

data/lib/troles/common/api/core.rb

@@ -5,18 +5,18 @@
 #
 module Troles::Common::Api
   module Core
-    
+
     # Access to the Troles operations API
     # @return [Troles::Operations] the operations API object 
     def roles
       @roles ||= Troles::Operations.new(self)
-    end       
+    end
 
     # Sets the roles of the subject
     # (see #set_roles)
     def roles= *new_roles
       roles.set_roles new_roles
-    end       
+    end
 
     # If this role subject instance should have static (immutable) roles
     # @return [true, false] defaults to false so a role subject is allowed to change roles 
@@ -25,28 +25,27 @@ module Troles::Common::Api
     end
 
     def troles_config
-      self.class.troles_config      
+      self.class.troles_config
     end
-        
-    module ClassMethods            
-      
+
+    module ClassMethods
+
       def valid_roles
         troles_config.valid_roles
       end
 
-      # # TODO: make sure alphanumeric only
-      # def valid_roles= *roles
-      #   troles_config.valid_roles = *roles
-      # end
+      def valid_roles= *roles
+        troles_config.valid_roles = roles.flatten.map{|r| r.to_s.alpha_numeric}.map(&:to_sym).uniq
+      end
 
       # If all role subjects using this strategy should have static (immutable) roles
       #
-      # @note Should also proxy Config object?      
+      # @note Should also proxy Config object?
       #
       # @return [true, false] if role subjects have static roles or not (default: false)
       def static_roles?
         troles_config.static_roles?
-      end           
+      end
     end
   end
-end
+end

data/lib/troles/common/api/read.rb

@@ -39,6 +39,12 @@ module Troles::Common::Api
     # (see #has_roles?)
     def has_any_role? *roles
       !(role_list & roles.to_symbols).empty?
+    end
+
+    # Checks if the role subject has any of the listed roles
+    # (see #has_roles?)
+    def has_all_roles? *roles
+      (roles.to_symbols - role_list).empty?
     end    
   end
 end

data/lib/troles/common/api.rb

@@ -15,14 +15,15 @@ module Troles::Common
       end
 
       def included(base)
+        puts "Included #{base}"
         apis.each do |api|
           begin
             base.include_and_extend :"#{api.to_s.camelize}"
           rescue
           end
-        end      
+        end
       end
     end
     extend ClassMethods
   end
-end
+end