permissable 0.1.0 → 0.2.0

data/README.rdoc

@@ -4,10 +4,7 @@ Permissable creates the ability to add a permissions system to "resources" based
 It allows you to define a member using the +permissable+ method:
 
 	class User < ActiveRecord::Base
-	  permissable do |configure|
-	    configure.permission_for :read, :posts, :categories
-	    configure.permission_for [:read, :write, :moderate], :comments
-	  end
+	  has_permissions_for [:section, :category], :to => [:read, :write, :moderate]
 	end
 
 Permissable uses a single "permissions" table (and subsuquently a Permission model), with a polymorphic relationship
@@ -24,18 +21,47 @@ This documention is incomplete... I'll add more later.
 == Usage
 
 	class User < ActiveRecord::Base
-	  permissable do |configure|
-	    configure.permission_for :read, :posts, :categories
-	    configure.permission_for [:read, :write, :moderate], :comments
-	  end
+	  has_permissions_for [:section, :category], :to => [:read, :write, :moderate]
 	end
 
-The permissable method accepts a block containing permission declarations.
-Each call to permission_for accepts two attributes.
+The permissable method accepts two options:
 
 * method: The permission you want to assign (read, write, moderate, etc)
-* resources: A list of resources to assign those permissions to
+* options: A hash of options.
+
+The only required option is the :to key, which defines a number of permisssions to assign to the speficied resource(s)
+
+== Setting Permissions via Association
+
+Permissable also allows you to specify permissions via an association. For instance say your User has_many roles, and you would like the
+permissions to be based on a particular user's roles. To do this, add the :through option when setting permissions:
+
+	:through => :roles
+	
+When permissable does permission lookups on any of the resources specified in has_permissions_for it will use the assocation to define them.
+Instead of looking up User.permissions, it will now lookup user.roles.permissions.
+
+== Always allowing specific members
+
+If you would like can? to always pass for a particular member, use the :allow_with option with has_permissions_for. The allow_with option accepts a method name within your
+member model that will be called prior to checking permissions from the database.
+
+	class User < ActiveRecord::Base
+	  has_permissions_for [:section, :category], :to => [:read, :write, :moderate], :allow_with => :is_admin?
+	  
+	  def is_admin?
+	    // your logic here. If this resolves to true... can? will also be true.
+	  end
+	end
+
+== Planned Updates
+
+In the near future there are plans to add the ability to "eager_load" permissions on a user the first time it is created. When using this configuration 
+option, ALL permissions relating to that user are looked up in a single database query, and then cached to the user instance. By default I think this may be the proper way to handle it anyway.
 
+We are also planning to implement permission "chains". Basically this will define a series of "levels" to your permission. For instance a user
+who can "write" a model, would also be able to "read" a model. You would be able to tell Permissable which methods chain from each other and
+the order they should rely on.  Think about how a statemachine transitions from one state to another in a way....
 
 == Note on Patches/Pull Requests
  

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/permissable/member.rb

@@ -5,27 +5,61 @@ module Permissable
     def self.included(base)      
       base.send :include, InstanceMethods
       base.send :attr_protected, :member_identifier
+      base.send :attr_protected, :permissable_lookups
     end
      
     # This module includes methods that should exist on ALL members.
     module InstanceMethods
       
       # The can? method returns a boolen value specifying whether or not this member can perform the specific method on resource
-      def can?(method, resource)
-        permissions_for(resource, method).exists?
+      def can?(methods, resource)
+        unless allow_permission_with_method.nil?
+          if self.respond_to? "#{allow_permission_with_method}"
+            return true if (send "#{allow_permission_with_method}")
+          end
+        end
+        methods = [methods].flatten.collect{ |m| m.to_sym }
+        methods = find_methods_from_chain(methods)
+        permissions_for(resource, methods).exists?
       end
       
       # Alias to can? to get the inverse.
       def cannot?(method, resource); !can?(method, resource); end
       
+      # Assign permissions to a member if they don't already exist.
+      # TODO: There has to be a friendlier way to mass assign permissions to roles rather than
+      # looping each one for existence and then saving separately.
+      def can!(methods, resources)
+        [resources].flatten.each do |resource|
+          
+          # Kind of unecessary but since some methods allow you to specify a Classname directly, this just
+          # safegaurds against trying to do the same here.
+          next if resource.is_a?(Class)
+          
+          # Get the member identifier for this resource
+          identifier = member_identifier(resource)
+          
+          [methods].flatten.each do |method|
+            # Permission already exists, continue.
+            next if can?(method, resource)
+            
+            # Create a new permission for each member (once if its self, multiple times if its associated)
+            [identifier[:member_id]].flatten.each do |member_id|
+              perm = Permission.new(:member_id => member_id, :member_type => identifier[:member_type], :permission_type => method.to_s.downcase)
+              perm.resource = resource
+              perm.save
+            end
+          end
+        end
+        
+      end
       
       # This sets the member information for our permission lookup based on the current resource scope.
       # These attributes correspond to the correct member_id and member_type in our permissions table.
-      def member_identifier(scope)
+      def member_identifier(resource)
         
         @member_identifier ||= {}
-        # The scope should be the classname of a resource we are getting identifiers for
-        scope = scope.to_s.classify
+        scope = fetch_scope(resource)
         
         return @member_identifier[scope] unless @member_identifier[scope].nil?
         return { :member_id => self.id, :member_type => self.class.to_s } unless permissable_associations.has_key?(scope)
@@ -39,18 +73,51 @@ module Permissable
           
       # Provide an instance method to our associations
       def permissable_associations; self.class.permissable_associations; end
+      # Find our permission override if available
+      def allow_permission_with_method; self.class.permissable_options[:allow_permission_with_method]; end
+      # See if there is a permissions chain
+      def permission_chain; self.class.permissable_options[:permission_chain] || {}; end
       
       private 
       
+      def find_methods_from_chain(methods)
+        
+        return methods if permission_chain.empty?
+        allowed_methods = []
+        
+        methods.each do |method|
+          permission_chain.each_pair do |key, value|
+            value = [value].flatten.collect{ |v| v.to_sym }
+            allowed_methods << key.to_sym if value.include?(method)
+          end
+        end
+        
+        allowed_methods << methods
+        allowed_methods.flatten.uniq
+        
+      end
+      
       # Looks up permissions for a particular resource.
       def permissions_for(resource, methods = nil)
-        scope  = resource.class.to_s.classify
-        return self.permissions unless permissable_associations.has_key?(scope)
+        scope  = fetch_scope(resource)
+        return self.permissions.with_permission_to(methods) unless permissable_associations.has_key?(scope)
         relation = Permission.where(member_identifier(scope)).for_resource(resource)
         relation = relation.with_permission_to(methods) unless methods.nil?
         relation
       end
       
+      # Returns the member responsible for this resource. This can either be an instance of self, or an instance or 
+      # array of assocated instances.
+      def permissable_member(resource)
+        scope  = fetch_scope(resource)
+        (permissable_associations.has_key?(scope)) ? send("#{permissable_associations[scope]}".to_sym) : self
+      end
+      
+      def fetch_scope(resource)
+        return resource if resource.is_a?(String)
+        (resource.is_a?(Class)) ? resource.to_s : resource.class.to_s.classify
+      end
+      
     end
     
   end

data/lib/permissable/resource.rb

@@ -1,10 +1,7 @@
 module Permissable
   
   module Resource
-    
-    def self.included(base)
-    end
-        
+          
   end
   
 end

data/lib/permissable.rb

@@ -56,6 +56,7 @@ module Permissable
         raise Permissable::PermissionNotDefined, "has_permissions_for missing the :to option." unless options.has_key?(:to) and !options[:to].empty?
         
         write_inheritable_attribute(:permissable_associations, {}) if permissable_associations.nil?
+        write_inheritable_attribute(:permissable_options, {}) if permissable_options.nil?
         resources = [resources].flatten
         
         resources.each do |resource| 
@@ -69,33 +70,47 @@ module Permissable
             assoc = options[:through].to_s.classify.constantize
             
             # Our association also creates a has_many association on our permissions table.
-            assoc.class_eval do
+            assoc.class_eval do              
               has_many(:permissions, :as => :member, :conditions => { :member_type => "#{self.to_s}" }) unless respond_to? :permissions
+              include Permissable::Member
+              class_inheritable_accessor :permission_types
+              write_inheritable_attribute(:permissable_associations, {})
+              write_inheritable_attribute(:permissable_options, {}) if permissable_options.nil?
+              permissable_options[:allow_permission_with_method] = options[:allow_with] if options.has_key?(:allow_with)        
+              permissable_options[:permission_chain] = options[:chain] if options.has_key?(:chain)
+              self.send :permission_types=, options[:to]
             end
-                        
+                                    
           end
-          
+
           # Setup a has_many association of permissions on our resource.
-          resource.constantize.class_eval do 
-            include Permissable::Resource
+          resource.constantize.class_eval do             
             has_many(:permissions, :as => :resource, :conditions => { :resource_type => "#{self.to_s}" }) unless respond_to? :permissions
           end
           
+          resource.constantize.instance_eval{ include Permissable::Resource }
+          
         end
         
+        permissable_options[:allow_permission_with_method] = options[:allow_with] if options.has_key?(:allow_with)        
+        permissable_options[:permission_chain] = options[:chain] if options.has_key?(:chain)
+        
         # This class becomes a member to resources.
         include Permissable::Member
+        class_inheritable_accessor :permission_types
+        self.send :permission_types=, options[:to]
         
         # Members create a has_many association on permissions as a member.
         has_many(:permissions, :as => :member, :conditions => { :member_type => "#{self.to_s}" }) unless respond_to? :permissions
         
       end 
       
+      # Access options such as our method override, or our permission chain.
+      def permissable_options; read_inheritable_attribute(:permissable_options); end
+      
       # Each time has_permissions_for is called, different associations may exist.
-      # This provides a way to store and update them all as necessary.
-      def permissable_associations
-        read_inheritable_attribute(:permissable_associations)
-      end  
+      # This provides a way to store and update them all as necessary.      
+      def permissable_associations; read_inheritable_attribute(:permissable_associations); end 
          
     end    
 end

data/permissable.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{permissable}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Brent Kirby"]
-  s.date = %q{2010-07-26}
+  s.date = %q{2010-09-04}
   s.description = %q{Permissable lets you set a number of 'permissions' to your database models. By assigning 'members' to 'resources' (models) you can specify various permission states.}
   s.email = %q{brent@kurbmedia.com}
   s.extra_rdoc_files = [
@@ -28,7 +28,6 @@ Gem::Specification.new do |s|
      "lib/permissable/member.rb",
      "lib/permissable/permission.rb",
      "lib/permissable/resource.rb",
-     "permissable-0.0.3.gem",
      "permissable.gemspec",
      "test/helper.rb",
      "test/test_permissable.rb"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: permissable
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Brent Kirby
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-26 00:00:00 -04:00
+date: 2010-09-04 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -53,7 +53,6 @@ files:
 - lib/permissable/member.rb
 - lib/permissable/permission.rb
 - lib/permissable/resource.rb
-- permissable-0.0.3.gem
 - permissable.gemspec
 - test/helper.rb
 - test/test_permissable.rb