makandra-aegis 1.1.1 → 1.1.2

data/README.rdoc

@@ -1,8 +1,19 @@
 = Aegis - role-based permissions for your user models
 
-Aegis allows you to managed fine-grained and complex permission for user accounts in a central place.
+Aegis allows you to manage fine-grained, complex permission for user accounts in a central place.
 
-=== Example 
+== Installation
+
+Add the following to your <tt>Initializer.run</tt> block in your <tt>environment.rb</tt>:
+    config.gem 'makandra-aegis', :lib => 'aegis', :source => 'http://gems.github.com'
+Then do a 
+    sudo rake gems:install
+
+Alternatively, use
+    sudo gem sources -a http://gems.github.com
+    sudo gem install makandra-aegis
+
+== Example 
 
 First, let's define some roles:
 
@@ -64,3 +75,97 @@ These permissions may be used in views and controllers:
       end
 
     end
+
+== Details
+
+=== Roles
+
+To equip a (user) model with any permissions, you simply call *has_role* within
+the model:
+    class User < ActiveRecord::Base
+      has_role
+    end
+Aegis assumes that the corresponding database table has a string-valued column
+called +role_name+. You may override the name with the <tt>:name_accessor =>
+:my_role_column</tt> option.
+
+The roles and permissions themselves are defined in a class inheriting from
+<b>Aegis::Permissions</b>. To define roles you create a model <tt>permissions.rb</tt>
+and use the *role* method:
+    class Permissions < Aegis::Permissions
+      role 'role_name'
+    end
+
+By default, users belonging to this role are not permitted anything. You may
+override this with <tt>:default_permission => :allow</tt>, e.g.
+    role 'admin', :default_permission => :allow
+
+=== Permissions
+
+Permissions are specified with the *permission* method and *allow* and *deny*
+    permission :do_something do
+        allow :role_a, :role_b
+        deny :role_c
+    end
+
+Your user model just received two methods called <b>User#may_do_something?</b>
+and <b>User#may_do_something!</b>. The first one with the ? returns true for users with
++role_a+ and +role_b+, and false for users with +role_c+. The second one with the ! raises an
+Aegis::PermissionError for +role_c+.
+
+=== Normalization
+
+Aegis will perform some normalization. For example, the permissions
++edit_something+ and +update_something+ will be the same, each granting both 
+<tt>may_edit_something?</tt> and <tt>may_update_something?</tt>. The following normalizations
+are active:
+* edit = update
+* show = list = view = read
+* delete = remove = destroy
+
+=== Complex permissions (with parameters)
+ 
+*allow* and *deny* can also take a block that may return +true+ or +false+
+indicating if this really applies. So
+    permission :pull_april_fools_prank do
+      allow :everyone do
+        Date.today.month == 4 and Date.today.day == 1
+      end
+    end
+will generate a <tt>may_pull_april_fools_prank?</tt> method that only returns true on
+April 1.
+
+This becomes more useful if you pass parameters to a <tt>may_...?</tt> method, which
+are passed through to the permission block (together with the user object). This
+way you can define more complex permissions like
+    permission :edit_post do |current_user, post|
+      allow :registered_user do
+        post.owner == current_user
+      end
+      allow :admin
+    end
+which will permit admins and post owners to edit posts.
+
+=== For your convenience
+
+As a convenience, if you create a permission ending in a plural 's', this
+automatically includes the singular form. That is, after
+    permission :read_posts do
+      allow :everyone
+    end
+<tt>.may_read_post? @post</tt> will return true, as well.
+
+If you want to grant +create_something+, +read_something+, +update_something+
+and +destroy_something+ permissions all at once, just use
+    permission :crud_something do
+      allow :admin
+    end
+
+If several permission blocks (or several allow and denies) apply to a certain
+role, the later one always wins. That is
+    permission :do_something do
+      deny :everyone
+      allow :admin
+    end
+will work as expected.
+

data/VERSION

@@ -1 +1 @@
-1.1.1
+1.1.3

data/aegis.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{aegis}
-  s.version = "1.1.1"
+  s.version = "1.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Henning Koch"]
-  s.date = %q{2009-05-29}
+  s.date = %q{2009-06-25}
   s.description = %q{Aegis is a role-based permission system, where all users are given a role. It is possible to define detailed and complex permissions for each role very easily.}
   s.email = %q{github@makandra.de}
   s.extra_rdoc_files = [

data/lib/aegis/permissions.rb

@@ -3,30 +3,27 @@ module Aegis
   
     def self.inherited(base)
       base.class_eval do
+        @roles_by_name = {}
+        @permission_blocks = Hash.new { |hash, key| hash[key] = [] }
         extend ClassMethods
       end
     end    
 
     module ClassMethods
     
-      @@roles_by_name = {}
-
-      # Example: @@permission_blocks[:update_users] = 
-	  #         [proc { allow :admin; deny :guest }, proc { deny :student }]
-	  @@permission_blocks = Hash.new { |hash, key| hash[key] = [] }
  
       def role(role_name, options = {})
         role_name = role_name.to_sym
         role_name != Aegis::Constants::EVERYONE_ROLE_NAME or raise "Cannot define a role named: #{Aegis::Constants::EVERYONE_ROLE_NAME}"
-        @@roles_by_name[role_name] = Aegis::Role.new(role_name, self, options)
+        @roles_by_name[role_name] = Aegis::Role.new(role_name, self, options)
       end
       
       def find_all_role_names
-        @@roles_by_name.keys
+        @roles_by_name.keys
       end
       
       def find_all_roles
-        @@roles_by_name.values.sort
+        @roles_by_name.values.sort
       end
       
       def find_role_by_name(name)
@@ -34,7 +31,7 @@ module Aegis
         if name.blank?
           nil
         else
-          @@roles_by_name[name.to_sym]
+          @roles_by_name[name.to_sym]
         end
       end
       
@@ -51,13 +48,13 @@ module Aegis
       
       def may?(role_or_role_name, permission, *args)
         role = role_or_role_name.is_a?(Aegis::Role) ? role_or_role_name : find_role_by_name(role_or_role_name)
-        blocks = @@permission_blocks[permission.to_sym]
+        blocks = @permission_blocks[permission.to_sym]
         evaluate_permission_blocks(role, blocks, *args)
       end
       
       def evaluate_permission_blocks(role, blocks, *args)
-		evaluator = Aegis::PermissionEvaluator.new(role)
-		evaluator.evaluate(blocks, args)
+    evaluator = Aegis::PermissionEvaluator.new(role)
+    evaluator.evaluate(blocks, args)
       end
       
       def denied?(*args)
@@ -89,8 +86,8 @@ module Aegis
           singular_target = target.singularize
           if singular_target.length < target.length
             singular_block = lambda do |*args|
-		      args.delete_at 1
-			  instance_exec(*args, &block)
+        args.delete_at 1
+        instance_exec(*args, &block)
             end
             singular_permission_name = "#{verb}_#{singular_target}"
             add_permission(singular_permission_name, &singular_block)
@@ -101,7 +98,7 @@ module Aegis
       
       def add_permission(permission_name, &block)
         permission_name = permission_name.to_sym
-        @@permission_blocks[permission_name] << block
+        @permission_blocks[permission_name] << block
       end
  
     end # module ClassMethods

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: makandra-aegis
 version: !ruby/object:Gem::Version 
-  version: 1.1.1
+  version: 1.1.2
 platform: ruby
 authors: 
 - Henning Koch
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-29 00:00:00 -07:00
+date: 2009-06-25 00:00:00 -07:00
 default_executable: 
 dependencies: []