rend-acl 0.0.4 → 0.0.5

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "1.9.2"
+  - jruby-19mode
+  - rbx-19mode

data/Changelog.md

@@ -1,5 +1,16 @@
 # Change Log
 
+### Version 0.0.5 - June 24th, 2013
+
+* Testing
+    * Added `Minitest` gem as development dependency
+    * Removed `Turn` gem development dependency.
+    * Added Travis CI.
+    * Added Coveralls.
+
+* Documentation
+    * Added `/wiki/pages` directories.
+
 ### Version 0.0.4 - June 11th, 2013
 
 * Assertions
@@ -20,7 +31,7 @@
 
     * `:role`
     * `:resource`
-    * `:prilvilege`
+    * `:privilege`
     * `:assertion` -- _Not utilized in `.allowed?()` method._
 
 ### Version <= 0.0.3

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in rend-acl.gemspec
 gemspec
+
+gem 'coveralls', :require => false
+
+

data/README.md

@@ -1,25 +1,112 @@
 # Rend Acl
 
+[![Build Status](https://travis-ci.org/veloper/rend-acl.png?branch=master)](https://travis-ci.org/veloper/rend-acl)
+[![Coverage Status](https://coveralls.io/repos/veloper/rend-acl/badge.png)](https://coveralls.io/r/veloper/rend-acl)
+[![Dependency Status](https://gemnasium.com/veloper/rend-acl.png)](https://gemnasium.com/veloper/rend-acl)
+
 Rend-Acl is a port of [Zend_Acl](http://framework.zend.com/manual/1.12/en/zend.acl.html) with modifications made to bring the api more inline with Ruby conventions.
 
+## Introduction
+Rend-Acl provides a lightweight and flexible access control list (ACL) implementation for privileges management. In general, an application may utilize such ACL's to control access to certain protected objects by other requesting objects.
+
+For the purposes of this documentation:
+
+* A **Role** is an object that may request access to a Resource or Privilege.
+    * _(e.g., "Passenger", "Driver", "Mechanic")_
+* A **Resource** is an object to which access is controlled.
+    * _(e.g., "Car", "Boat", "Train")_
+* A **Privilege** is an _(optional)_ level of control which enables further refinement.
+    * _(e.g., "Drive", "Sell", "Repair")_
+
+Through use of an ACL an application may control how roles are granted access to resources and privilages.
+
+### Still Lost?
+These terms and concepts become easier to understand when translated into plain english...
+
+```ruby
+@acl.allow! :role => "Driver", :resource => "Car"
+```
+> __Translation:__ Allow a **Driver** full-access to the **Car**.
+
+```ruby
+@acl.allow! :role => "Driver", :resource => "Car", :privilege => "Sell"
+```
+> __Translation:__ Allow a **Driver** to **Sell** the **Car**.
+
+```ruby
+@acl.allow! :role => "Mechanic", :privilege => "Repair"
+```
+> __Translation:__ Allow a **Mechanic** to **Repair** anything.
+
+
+## Basic Usage Example
+
+```ruby
+# ==> Require Rend ACL
+require 'rend/acl'
+
+# ==> Initialize ACL Object
+@acl = Rend::Acl.new
+
+# ==> Add Roles & Resources to ACL
+@acl.add! :role     => ["Passenger", "Driver", "Mechanic"],
+          :resource => ["Car", "Boat", "Train"]
+
+# ==> Declare Rules - Note: When conflicts occur the last rule always wins!
+
+# Translation: Allow the "Driver" Role full-access to the "Car" Resource.
+@acl.allow! :role => "Driver", :resource => "Car"
+
+# Translation: Allow the "Mechanic" Role the privilege to "Repair" any Resource.
+@acl.allow! :role => "Mechanic", :privilege => "Repair"
+
+# Translation: Allow all Roles the privilege to "Look" at any Resource.
+@acl.allow! :privilege => "Look"
+
+# Translation: Deny all Roles any access to the "Train" Resource.
+@acl.deny! :resource => "Train"
+
+# ==> Querying
+@acl.allowed?(:role => "Driver",    :resource => "Car")                           # TRUE
+@acl.allowed?(:role => "Passenger", :resource => "Car")                           # FALSE
+@acl.allowed?(:role => "Mechanic",  :resource => "Car")                           # FALSE
+@acl.allowed?(:role => "Mechanic",  :privilege => "Repair")                       # TRUE
+@acl.allowed?(:role => "Passenger", :privilege => "Look")                         # TRUE
+@acl.allowed?(:role => "Passenger", :resource => "Train")                         # FALSE
+@acl.allowed?(:role => "Mechanic",  :resource => "Train", :privilege => "Repair") # FALSE
+```
+
 ## Installation
 
+Install this gem directly using...
+
     gem install rend-acl
 
+... or simply include it in your project's `Gemfile` ...
+
+    gem 'rend-acl', '~> 0.0.5'
+
+## Requirements
+
+* Ruby >= 1.9.2
+
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
+3. Commit your changes **(with passing tests please!)** (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+6. ???
+7. Profit!
 
 ## Licensing
 
-* All ported Ruby code and assoicated 'Rend' gems are under a simple [New-BSD License](http://dan.doezema.com/licenses/new-bsd).
+* All ported Ruby code and associated 'Rend' gems are under a simple [New-BSD License](http://dan.doezema.com/licenses/new-bsd).
 * Original PHP code is licensed under [Zend's New-BSD License](http://framework.zend.com/license/).
     * This license can be found in `./ZEND_FRAMEWORK_LICENSE.txt`
 
 ## Acknowledgements
-* This project is **not** associated with, or endorsed by, Zend Technologies USA, Inc., nor any of its contributors.
-* Rend's modular design was heavily influced by [RSpec](https://github.com/rspec/rspec)'s approach.
+
+* This project is **NOT** associated with, or endorsed by, Zend Technologies USA, Inc., nor any of its contributors.
+* Rend's modular design was heavily influenced by [RSpec](https://github.com/rspec/rspec)'s approach.

data/lib/rend/acl.rb

@@ -372,9 +372,6 @@ module Rend
         privileges  = options.fetch(:privilege, nil)
         assertion   = options.fetch(:assertion, nil)
       end
-      roles      = nil if roles      == :all
-      resources  = nil if resources  == :all
-      privileges = nil if privileges == :all
 
       type_hint! Rend::Acl::Assertion, assertion
 
@@ -397,9 +394,6 @@ module Rend
         privileges  = options.fetch(:privilege, nil)
         assertion   = options.fetch(:assertion, nil)
       end
-      roles      = nil if roles      == :all
-      resources  = nil if resources  == :all
-      privileges = nil if privileges == :all
 
       type_hint! Rend::Acl::Assertion, assertion
 
@@ -421,9 +415,6 @@ module Rend
         privileges  = options.fetch(:privilege, nil)
         assertion   = options.fetch(:assertion, nil)
       end
-      roles      = nil if roles      == :all
-      resources  = nil if resources  == :all
-      privileges = nil if privileges == :all
 
       set_rule!(OP_REMOVE, TYPE_ALLOW, roles, resources, privileges, assertion)
     end
@@ -443,9 +434,6 @@ module Rend
         privileges  = options.fetch(:privilege, nil)
         assertion   = options.fetch(:assertion, nil)
       end
-      roles      = nil if roles      == :all
-      resources  = nil if resources  == :all
-      privileges = nil if privileges == :all
 
       set_rule!(OP_REMOVE, TYPE_DENY, roles, resources, privileges, assertion)
     end
@@ -491,166 +479,38 @@ module Rend
     # @uses   Rend::Acl::get!()
     # @return Rend::Acl Provides a fluent interface
     def set_rule!(operation, type, roles = nil, resources = nil, privileges = nil, assertion = nil)
-        type_hint! Rend::Acl::Assertion, assertion
+      type_hint! Rend::Acl::Assertion, assertion
 
-        # ensure that the rule type is valid normalize input to uppercase
-        type = type.upcase
-        if type != TYPE_ALLOW && type != TYPE_DENY
-          raise Rend::Acl::Exception, "Unsupported rule type must be either '#{TYPE_ALLOW}' or '#{TYPE_DENY}'"
-        end
+      # ensure that the rule type is valid normalize input to uppercase
+      if type != TYPE_ALLOW && type != TYPE_DENY
+        raise Rend::Acl::Exception, "Unsupported rule type must be either '#{TYPE_ALLOW}' or '#{TYPE_DENY}'"
+      end
 
-        # ensure that all specified Roles exist normalize input to array of Role objects or nil
-        if !roles.is_a?(Array)
-          roles = [roles]
-        elsif roles.empty?
-          roles = [nil]
-        end
-        roles = roles.reduce([]) do |seed, role|
-          seed << (role ? role_registry.get!(role) : nil)
-        end
+      # ensure that all specified Roles exist normalize input to array of Role objects or nil
+      roles = Array(roles)
+      roles << nil if roles.empty?
+      roles = roles.reduce([]) {|seed, role| seed << (role ? role_registry.get!(role) : nil)}
 
-        # ensure that all specified Resources exist normalize input to array of Resource objects or nil
-        if resources
-          resources = Array(resources)
-          resources << nil if resources.empty?
-          resources = resources.reduce([]) do |seed, resource|
-            seed << (resource ? resource!(resource) : nil)
-          end
-        else
-          # this might be used later if resource iteration is required
-          all_resources = @_resources.values.reduce([]) do |seed, r_target|
-            seed << r_target[:instance]
-          end
-        end
-
-        # normalize privileges to array
-        if privileges.nil?
-          privileges = []
-        elsif !privileges.is_a?(Array)
-          privileges = [privileges]
-        end
+      # ensure that all specified Resources exist normalize input to array of Resource objects or nil
+      if resources
+        resources = Array(resources)
+        resources << nil if resources.empty?
+        resources = resources.reduce([]) {|seed, resource| seed << (resource ? resource!(resource) : nil)}
+      end
 
-        case operation
-
-        # add to the rules
-        when OP_ADD
-          if resources
-            # this block will iterate the provided resources
-            resources.each do |resource|
-              roles.each do |role|
-                rules = _rules(resource, role, true)
-                if privileges.empty?
-                  rules[:all_privileges] = {
-                    :type       => type,
-                    :assertion  => assertion
-                  }
-                  rules[:by_privilege_id] = {} unless rules.has_key?(:by_privilege_id)
-                else
-                  privileges.each do |privilege|
-                    rules[:by_privilege_id][privilege] = {
-                      :type       => type,
-                      :assertion  => assertion
-                    }
-                  end
-                end
-              end
-            end
-          else
-            # this block will apply to all resources in a global rule
-            roles.each do |role|
-              rules = _rules(nil, role, true)
-              if privileges.empty?
-                rules[:all_privileges] = {
-                  :type       => type,
-                  :assertion  => assertion
-                }
-              else
-                privileges.each do |privilege|
-                  rules[:by_privilege_id][privilege] = {
-                    :type       => type,
-                    :assertion  => assertion
-                  }
-                end
-              end
-            end
-          end
-        # remove from the rules
-        when OP_REMOVE
-          if resources
-            # this block will iterate the provided resources
-            resources.each do |resource|
-              roles.each do |role|
-                rules = _rules(resource, role)
-                next if rules.nil?
-                if privileges.empty?
-                  if resource.nil? && role.nil?
-                    if rules[:all_privileges][:type] == type
-                      rules.replace({
-                        :all_privileges => {
-                          :type       => TYPE_DENY,
-                          :assertion  => nil
-                        },
-                        :by_privilege_id  => {}
-                      })
-                    end
-                    next
-                  end
-                  if rules[:all_privileges].has_key?(:type) && rules[:all_privileges][:type] == type
-                    rules.delete(:all_privileges)
-                  end
-                else
-                  privileges.each do |privilege|
-                    if rules[:by_privilege_id].has_key?(privilege) && rules[:by_privilege_id][privilege][:type] == type
-                      rules[:by_privilege_id].delete(privilege)
-                    end
-                  end
-                end
-              end
-            end
-          else
-            # this block will apply to all resources in a global rule
-            roles.each do |role|
-
-              # since nil (all resources) was passed to this set_role!() call, we need
-              # clean up all the rules for the global allResources, as well as the indivually
-              # set resources (per privilege as well)
-              [nil].concat(all_resources).each do |resource|
-                rules = _rules(resource, role, true)
-                next if rules.nil?
-                if privileges.empty?
-                  if role.nil?
-                    if rules[:all_privileges][:type] == type
-                      rules.replace({
-                        :all_privileges => {
-                          :type       => TYPE_DENY,
-                          :assertion  => nil
-                        },
-                        :by_privilege_id  => {}
-                      })
-                    end
-                    next
-                  end
-
-                  if rules[:all_privileges].has_key?(:type) && rules[:all_privileges][:type] == type
-                    rules.delete(:all_privileges)
-                  end
-                else
-                  privileges.each do |privilege|
-                    if rules[:by_privilege_id].has_key?(privilege) && rules[:by_privilege_id][privilege][:type] == type
-                      rules[:by_privilege_id].delete(privilege)
-                    end
-                  end
-                end
-              end
-            end
-          end
-        else
-          raise Rend::Acl::Exception, "Unsupported operation must be either '#{OP_ADD}' or '#{OP_REMOVE}'"
-        end
+      # normalize privileges to array
+      privileges = Array(privileges).compact
 
-        self
+      case operation
+      when OP_ADD     then _add_rule!(type, roles, resources, privileges, assertion)
+      when OP_REMOVE  then _remove_rule!(type, roles, resources, privileges, assertion)
+      else
+        raise Rend::Acl::Exception, "Unsupported operation must be either '#{OP_ADD}' or '#{OP_REMOVE}'"
       end
 
+      self
+    end
+
     # Returns true if and only if the Role has access to the Resource
     #
     # The role and resource parameters may be references to, or the string identifiers for,
@@ -691,11 +551,6 @@ module Rend
         privilege = options.fetch(:privilege, nil)
       end
 
-      # Readability
-      role      = nil if role      == :all
-      resource  = nil if resource  == :all
-      privilege = nil if privilege == :all
-
       if role
         # keep track of originally called role
         @_is_allowed_role = role
@@ -758,6 +613,11 @@ module Rend
       end
     end
 
+    # Inverse of allowed? method
+    def denied?(*args)
+      !allowed?(*args)
+    end
+
     # Returns the Role registry for this ACL
     #
     # If no Role registry has been created yet, a new default Role registry
@@ -768,6 +628,27 @@ module Rend
       @_role_registry ||= Rend::Acl::Role::Registry.new
     end
 
+    # Returns an array of registered roles.
+    #
+    # Note that this method does not return instances of registered roles,
+    # but only the role identifiers.
+    #
+    # @return array of registered roles
+    def roles
+      role_registry.roles.keys
+    end
+
+    # @return array of registered resources
+    def resources
+      @_resources.keys
+    end
+
+    # == PROTECTED ================================================================================
+
+    protected
+
+    # =============================================================================================
+
     # Performs a depth-first search of the Role DAG, starting at role, in order to find a rule
     # allowing/denying role access to all privileges upon resource
     #
@@ -1000,19 +881,101 @@ module Rend
       visitor[:by_role_id][role.id]
     end
 
-    # Returns an array of registered roles.
-    #
-    # Note that this method does not return instances of registered roles,
-    # but only the role identifiers.
-    #
-    # @return array of registered roles
-    def roles
-      role_registry.roles.keys
+    def _add_rule!(type, roles, resources, privileges, assertion)
+      if resources
+        # this block will iterate the provided resources
+        resources.each do |resource|
+          roles.each do |role|
+            rules = _rules(resource, role, true)
+            if privileges.empty?
+              rules[:all_privileges]  = {:type => type, :assertion => assertion}
+              rules[:by_privilege_id] = {} unless rules.has_key?(:by_privilege_id)
+            else
+              privileges.each do |privilege|
+                rules[:by_privilege_id][privilege] = {:type => type, :assertion => assertion}
+              end
+            end
+          end
+        end
+      else
+        # this block will apply to all resources in a global rule
+        roles.each do |role|
+          rules = _rules(nil, role, true)
+          if privileges.empty?
+            rules[:all_privileges] = {:type => type, :assertion => assertion}
+          else
+            privileges.each do |privilege|
+              rules[:by_privilege_id][privilege] = {:type => type, :assertion => assertion}
+            end
+          end
+        end
+      end
     end
 
-    # @return array of registered resources
-    def resources
-      @_resources.keys
+    def _remove_rule!(type, roles, resources, privileges, assertion)
+      if resources
+        # this block will iterate the provided resources
+        resources.each do |resource|
+          roles.each do |role|
+            rules = _rules(resource, role)
+            next if rules.nil?
+            if privileges.empty?
+              if resource.nil? && role.nil?
+                if rules[:all_privileges][:type] == type
+                  rules.replace({
+                    :all_privileges => {
+                      :type       => TYPE_DENY,
+                      :assertion  => nil
+                    },
+                    :by_privilege_id  => {}
+                  })
+                end
+                next
+              end
+              rules.delete(:all_privileges) if rules[:all_privileges][:type] == type
+            else
+              privileges.each do |privilege|
+                if rules[:by_privilege_id].has_key?(privilege) && rules[:by_privilege_id][privilege][:type] == type
+                  rules[:by_privilege_id].delete(privilege)
+                end
+              end
+            end
+          end
+        end
+      else
+        all_resources = @_resources.values.reduce([]) {|seed, r_target| seed << r_target[:instance]}
+
+        # this block will apply to all resources in a global rule
+        roles.each do |role|
+
+          # since nil (all resources) was passed to this set_role!() call, we need
+          # clean up all the rules for the global all_resources, as well as the indivually
+          # set resources (per privilege as well)
+          [nil].concat(all_resources).each do |resource|
+            rules = _rules(resource, role, true)
+            next if rules.nil?
+            if privileges.empty?
+              if role.nil?
+                if rules[:all_privileges][:type] == type
+                  rules.replace(:all_privileges => {:type => TYPE_DENY, :assertion => nil}, :by_privilege_id => {})
+                end
+                next
+              end
+
+              if rules[:all_privileges].has_key?(:type) && rules[:all_privileges][:type] == type
+                rules.delete(:all_privileges)
+              end
+            else
+              privileges.each do |privilege|
+                if rules[:by_privilege_id].has_key?(privilege) && rules[:by_privilege_id][privilege][:type] == type
+                  rules[:by_privilege_id].delete(privilege)
+                end
+              end
+            end
+          end
+        end
+      end
     end
+
   end
 end

data/lib/rend/acl/mock_assertion.rb

@@ -1,28 +0,0 @@
-# Not a required file -- used for testing
-module Rend
-  class Acl
-    class MockAssertion < Rend::Acl::Assertion
-
-      attr_reader   :last_acl
-      attr_reader   :last_role
-      attr_reader   :last_resource
-      attr_reader   :last_privilege
-
-      attr_accessor :pass
-
-      def initialize(pass = nil, &block)
-        self.pass = block_given? ? block : pass
-      end
-
-      def pass=(value)
-        @pass = value.is_a?(Proc) ? value : lambda {|acl, role, resource, privilege| value}
-      end
-
-      def pass?(acl, role = nil, resource = nil, privilege = nil)
-        @last_acl, @last_role, @last_resource, @last_privilege = acl, role, resource, privilege
-        pass.call(acl, role, resource, privilege)
-      end
-
-    end
-  end
-end

data/lib/rend/acl/version.rb

@@ -1,7 +1,7 @@
 module Rend
   class Acl
     module Version
-      STRING = "0.0.4"
+      STRING = "0.0.5"
     end
   end
 end

data/rend-acl.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.version       = Rend::Acl::Version::STRING
   spec.authors       = ["Daniel Doezema"]
   spec.email         = ["daniel.doezema@gmail.com"]
-  spec.description   = "A port of Zend_Acl with modifications made to bring the api more inline with Ruby conventions."
+  spec.description   = "A port of Zend_Acl with modifications made to bring the API more inline with Ruby conventions."
   spec.summary       = "rend-acl-#{Rend::Acl::Version::STRING}"
   spec.homepage      = "https://github.com/veloper/rend-acl"
   spec.license       = "New-BSD"
@@ -21,10 +21,10 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "turn"
+  spec.add_development_dependency "minitest", "~> 5.0.5"
 
-  dependency_gems = ['rend-core']
 
+  dependency_gems = ['rend-core']
   dependency_gems.each do |gem_name|
     if Rend::Acl::Version::STRING =~ /[a-zA-Z]+/
       spec.add_runtime_dependency "#{gem_name}", "= #{Rend::Acl::Version::STRING}"

data/test/helper.rb

@@ -0,0 +1,14 @@
+# https://coveralls.io Integration
+require 'coveralls'
+Coveralls.wear!
+
+# Gem
+require 'rend/acl'
+
+# Testing Support
+require 'support/mock_assertion'
+require 'support/passing_assertion'
+require 'support/failing_assertion'
+
+# Autorun tests
+require "minitest/autorun"

data/test/support/failing_assertion.rb

@@ -0,0 +1,7 @@
+class FailingAssertion < Rend::Acl::Assertion
+
+  def pass?(acl, role = nil, resource = nil, privilege = nil)
+    false
+  end
+
+end

data/test/support/mock_assertion.rb

@@ -0,0 +1,23 @@
+class MockAssertion < Rend::Acl::Assertion
+
+  attr_reader :last_acl
+  attr_reader :last_role
+  attr_reader :last_resource
+  attr_reader :last_privilege
+
+  attr_accessor :pass
+
+  def initialize(pass = nil, &block)
+    self.pass = block_given? ? block : pass
+  end
+
+  def pass=(value)
+    @pass = value.is_a?(Proc) ? value : lambda {|acl, role, resource, privilege| value}
+  end
+
+  def pass?(acl, role = nil, resource = nil, privilege = nil)
+    @last_acl, @last_role, @last_resource, @last_privilege = acl, role, resource, privilege
+    pass.call(acl, role, resource, privilege)
+  end
+
+end

data/test/support/passing_assertion.rb

@@ -0,0 +1,7 @@
+class PassingAssertion < Rend::Acl::Assertion
+
+  def pass?(acl, role = nil, resource = nil, privilege = nil)
+    true
+  end
+
+end

data/test/test_acl.rb

@@ -1,28 +1,35 @@
-require 'test/unit'
-require 'rend/acl'
-require 'rend/acl/mock_assertion'
-require 'yaml'
-begin; require 'turn/autorun'; rescue LoadError; end
+require 'helper'
 
-
-class AclTest < Test::Unit::TestCase
+class AclTest < Minitest::Test
 
   def setup
     @acl = Rend::Acl.new
   end
 
+  def test_access_is_limited_by_privilege
+    @acl.add! :role => "driver", :resource => "car"
+    @acl.allow! :role => "driver", :resource => "car", :privilege => "sell"
+    assert_equal false, @acl.allowed?("driver", "car")
+    assert_equal true, @acl.allowed?("driver", "car", "sell")
+  end
+
   def test_storing_acl_data_for_persistence_with_marshal
-    assert_use_case_1 Marshal.load( Marshal.dump(use_case_1) )
+    assert_use_case_2 Marshal.load( Marshal.dump(use_case_2) )
   end
 
   def test_storing_acl_data_for_persistence_with_yaml
-    assert_use_case_1 YAML.load( YAML.dump(use_case_1) )
+    require 'yaml'
+    assert_use_case_2 YAML.load( YAML.dump(use_case_2) )
   end
 
   def test_use_case_1
     assert_use_case_1(use_case_1)
   end
 
+  def test_use_case_2
+    assert_use_case_2(use_case_2)
+  end
+
   def test_add_raises_argument_error_with_no_args
     assert_raises ArgumentError do
       @acl.add!
@@ -138,7 +145,54 @@ class AclTest < Test::Unit::TestCase
     assert @acl.inherits_resource? "room", "building"
   end
 
-  # == Orignal Zend_Acl Tests Below ==
+  def test_alternate_syntax_hash_syntax
+    @acl.add!(
+      :resource  => %w[car motorcycle plane boat bike],
+      :role      => ["valet", "owner", "thief", "me"]
+    )
+    @acl.allow! :resource => "bike"
+    @acl.allow! :privilege => "clean"
+    @acl.allow! :role => "valet", :resource => %w[car motorcycle], :privilege => %w[park open]
+    @acl.allow! :role => "thief", :resource => %w[car motorcycle boat]
+    @acl.allow! :role => "owner"
+
+    # Nil permutations for :role, :resource, :privilege
+    assert_equal true, @acl.allowed?(:role => "owner")
+    assert_equal true, @acl.allowed?(:role => "owner", :resource => nil)
+    assert_equal true, @acl.allowed?(:role => "owner", :resource => nil, :privilege => nil)
+    assert_equal true, @acl.allowed?(:resource => "bike")
+    assert_equal true, @acl.allowed?(:resource => "bike", :role => nil)
+    assert_equal true, @acl.allowed?(:resource => "bike", :role => nil, :privilege => nil)
+    assert_equal true, @acl.allowed?(:privilege => "clean")
+    assert_equal true, @acl.allowed?(:privilege => "clean", :resource => nil)
+    assert_equal true, @acl.allowed?(:privilege => "clean", :resource => nil, :role => nil)
+
+    # Spot Checks
+    assert_equal true,  @acl.allowed?(:role => "valet", :privilege => "clean")
+    assert_equal true,  @acl.allowed?(:role => "valet", :resource => "bike")
+    assert_equal true,  @acl.allowed?(:role => "valet", :resource => "car", :privilege => "park")
+    assert_equal true,  @acl.allowed?(:role => "valet", :resource => "car", :privilege => "open")
+    assert_equal true,  @acl.allowed?(:role => "valet", :resource => "motorcycle", :privilege => "park")
+    assert_equal true,  @acl.allowed?(:role => "valet", :resource => "motorcycle", :privilege => "open")
+    assert_equal false, @acl.allowed?(:role => "valet", :privilege => "park")
+    assert_equal false, @acl.allowed?(:role => "valet", :privilege => "open")
+    assert_equal false, @acl.allowed?(:role => "valet", :resource => "plane", :privilege => "park")
+    assert_equal false, @acl.allowed?(:role => "valet", :resource => "plane", :privilege => "open")
+  end
+
+  def test_denied_method_is_inverse_of_allowed_method
+    acl = use_case_1
+    assert_equal true,  acl.denied?('staff'         , 'newsletter'   , 'publish') # allowed
+    assert_equal false, acl.denied?('marketing'     , 'newsletter'   , 'publish') # denied
+    assert_equal true,  acl.denied?('staff'         , 'latest'       , 'publish') # allowed
+    assert_equal false, acl.denied?('marketing'     , 'latest'       , 'publish') # denied
+    assert_equal false, acl.denied?('marketing'     , 'latest'       , 'archive') # denied
+    assert_equal true,  acl.denied?('marketing'     , 'latest'       , 'revise')  # allowed
+    assert_equal true,  acl.denied?('editor'        , 'announcement' , 'archive') # allowed
+    assert_equal true,  acl.denied?('administrator' , 'announcement' , 'archive') # allowed
+  end
+
+  # == Tests From Zend_Acl Suite Below ==
 
   # Ensures that basic addition and retrieval of a single Role works
   def test_role_registry_add_and_get_one
@@ -616,6 +670,26 @@ class AclTest < Test::Unit::TestCase
     assert_equal false, @acl.allowed?(nil, 'area')
   end
 
+  def test_basic_example
+    @acl = Rend::Acl.new
+
+    @acl.add! :role => ["Passenger", "Driver", "Mechanic"], :resource => ["Car", "Boat", "Train"]
+
+    @acl.allow! :role => "Driver", :resource => "Car"
+    @acl.allow! :role => "Mechanic", :privilege => "Repair"
+    @acl.allow! :privilege  => "Look"  # Allow any role the ability to Look at any resource.
+    @acl.deny!  :resource   => "Train" # Deny all roles access to the Train resource.
+
+
+    assert_equal true,  @acl.allowed?(:role => "Driver",    :resource => "Car")
+    assert_equal false, @acl.allowed?(:role => "Passenger", :resource => "Car")
+    assert_equal false, @acl.allowed?(:role => "Mechanic",  :resource => "Car")
+    assert_equal true,  @acl.allowed?(:role => "Mechanic",  :privilege => "Repair")
+    assert_equal true,  @acl.allowed?(:role => "Passenger", :privilege => "Look")
+    assert_equal false, @acl.allowed?(:role => "Passenger", :resource => "Train")
+    assert_equal false, @acl.allowed?(:role => "Mechanic",  :resource => "Train", :privilege => "Repair")
+  end
+
   # Ensures that an example for a content management system is operable
   def test_cms_example
     # Add some roles to the Role registry
@@ -777,7 +851,7 @@ class AclTest < Test::Unit::TestCase
 
   # Ensures that the default rule obeys its assertion
   def test_default_assert
-    @acl.deny!(nil, nil, nil, Rend::Acl::MockAssertion.new(false))
+    @acl.deny!(nil, nil, nil, MockAssertion.new(false))
     assert_equal true, @acl.allowed?
     assert_equal true, @acl.allowed?(nil, nil, 'some_privilege')
   end
@@ -958,10 +1032,10 @@ class AclTest < Test::Unit::TestCase
 
   # Ensures that assertions on privileges work properly
   def test_privilege_assert
-    @acl.allow!(nil, nil, 'some_privilege', Rend::Acl::MockAssertion.new(true))
+    @acl.allow!(nil, nil, 'some_privilege', MockAssertion.new(true))
     assert_equal true, @acl.allowed?(nil, nil, 'some_privilege')
 
-    @acl.allow!(nil, nil, 'some_privilege', Rend::Acl::MockAssertion.new(false))
+    @acl.allow!(nil, nil, 'some_privilege', MockAssertion.new(false))
     assert_equal false, @acl.allowed?(nil, nil, 'some_privilege')
   end
 
@@ -970,16 +1044,16 @@ class AclTest < Test::Unit::TestCase
     role_guest = Rend::Acl::Role.new('guest')
     @acl.add_role!(role_guest)
 
-    @acl.allow!(role_guest, nil, 'some_privilege', Rend::Acl::MockAssertion.new(true))
+    @acl.allow!(role_guest, nil, 'some_privilege', MockAssertion.new(true))
     assert_equal true, @acl.allowed?(role_guest, nil, 'some_privilege')
 
-    @acl.allow!(role_guest, nil, 'some_privilege', Rend::Acl::MockAssertion.new(false))
+    @acl.allow!(role_guest, nil, 'some_privilege', MockAssertion.new(false))
     assert_equal false, @acl.allowed?(role_guest, nil, 'some_privilege')
   end
 
   # # Ensures that removing the default deny rule results in assertion method being removed
   def test_remove_default_deny_assert
-    @acl.deny!(nil, nil, nil, Rend::Acl::MockAssertion.new(false))
+    @acl.deny!(nil, nil, nil, MockAssertion.new(false))
     assert_equal true, @acl.allowed?
     @acl.remove_deny!
     assert_equal false, @acl.allowed?
@@ -988,7 +1062,7 @@ class AclTest < Test::Unit::TestCase
 
   # @group ZF-1721
   def test_acl_assertions_get_proper_role_when_inheritence_is_used
-    assertion = Rend::Acl::MockAssertion.new(true)
+    assertion = MockAssertion.new(true)
 
     @acl.add! :role => ['guest', {'contributor' => 'guest'}, {'publisher' => 'contributor'}, 'admin'], :resource => 'blog_post'
 
@@ -1008,7 +1082,7 @@ class AclTest < Test::Unit::TestCase
 
   # @group ZF-7973
   def test_acl_passes_privilege_to_assert_class
-    assertion = Rend::Acl::MockAssertion.new do |acl, role, resource, privilege|
+    assertion = MockAssertion.new do |acl, role, resource, privilege|
       privilege == "read"
     end
 
@@ -1078,4 +1152,18 @@ class AclTest < Test::Unit::TestCase
     assert_equal false, acl.allowed?('editor'        , 'announcement' , 'archive') # denied
     assert_equal false, acl.allowed?('administrator' , 'announcement' , 'archive') # denied
   end
+
+  def use_case_2
+    acl = use_case_1
+    acl.allow! :privilege => 'passing_assertion', :assertion => PassingAssertion.new
+    acl.allow! :privilege => 'failing_assertion', :assertion => FailingAssertion.new
+    acl
+  end
+
+  def assert_use_case_2(acl)
+    assert_use_case_1(acl)
+    assert_equal true,  acl.allowed?(nil, nil, 'passing_assertion') # allowed
+    assert_equal false, acl.allowed?(nil, nil, 'failing_assertion') # denied
+  end
+
 end

data/test/test_documentation_examples.rb

@@ -0,0 +1,25 @@
+require 'helper'
+
+class DocumentationExamplesTest < Minitest::Test
+
+  def setup
+    @acl = Rend::Acl.new
+  end
+
+  def test_wiki_resource_inheritance_example
+      city_resource     = Rend::Acl::Resource.new("city")
+      building_resource = Rend::Acl::Resource.new("building")
+
+      @acl.add_resource!(city_resource)
+      @acl.add_resource!(building_resource, city_resource)
+
+      mayor_role = Rend::Acl::Role.new("mayor")
+      @acl.add_role!(mayor_role)
+
+      @acl.allow! :role => mayor_role, :resource => city_resource
+
+      assert_equal true, @acl.allowed?(:role => mayor_role, :resource => city_resource)
+      assert_equal true, @acl.allowed?(:role => mayor_role, :resource => building_resource)
+    end
+
+end

data/wiki/pages/resources.md

@@ -0,0 +1,37 @@
+A ***Resource*** is simply an object to which access is controlled.
+
+## Resource Class
+Rend-Acl provides the `Rend::Acl::Resource` class as a basic resource implementation for developers to use and/or extend as needed.
+
+
+## Tree Structure
+Rend-Acl provides a tree structure to which multiple resources can be added. Since resources are stored in such a tree structure, they can be organized from the general (toward the tree root) to the specific (toward the tree leaves). Queries on a specific resource will automatically search the resource's hierarchy for rules assigned to ancestor resources, allowing for simple inheritance of rules.
+
+
+## Resource Inheritance
+For example, if a default ***rule*** is to be applied to each ***building*** in a ***city***, one would simply assign the ***rule*** to the ***city***, instead of assigning the same ***rule*** to each ***building***. Some ***building***s may require exceptions to such a ***rule***, however, and this can be achieved in Rend-Acl by assigning such exception ***rule***s to each ***building*** that requires such an exception. A ***resource*** may inherit from only one parent ***resource***, though this parent ***resource*** can have its own parent ***resource***, etc.
+
+### Example
+```ruby
+@acl = Rend::Acl.new
+
+# Define Resources
+city_resource     = Rend::Acl::Resource.new("city")
+building_resource = Rend::Acl::Resource.new("building")
+
+# Add Resources to ACL
+@acl.add_resource!(city_resource)
+@acl.add_resource!(building_resource, city_resource) # Inheritance from city_resource
+
+# Define & Add Roles
+mayor_role = Rend::Acl::Role.new("mayor")
+@acl.add_role!(mayor_role)
+
+# Define Rules
+@acl.allow! :role => mayor_role, :resource => city_resource
+
+# Querying
+@acl.allowed? :role => mayor_role, :resource => city_resource     # => TRUE, via explicitly set rule.
+@acl.allowed? :role => mayor_role, :resource => building_resource # => TRUE, via resource rule inheritance
+```
+> **Associated Test:** `rend-acl/test/test_documentation_examples.rb#test_wiki_resource_inheritance_example`

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rend-acl
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-11 00:00:00.000000000 Z
+date: 2013-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -44,21 +44,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: turn
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 5.0.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 5.0.5
 - !ruby/object:Gem::Dependency
   name: rend-core
   requirement: !ruby/object:Gem::Requirement
@@ -75,7 +75,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.0.0
-description: A port of Zend_Acl with modifications made to bring the api more inline
+description: A port of Zend_Acl with modifications made to bring the API more inline
   with Ruby conventions.
 email:
 - daniel.doezema@gmail.com
@@ -83,7 +83,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .coveralls.yml
 - .gitignore
+- .travis.yml
 - Changelog.md
 - Gemfile
 - LICENSE.txt
@@ -100,7 +102,13 @@ files:
 - lib/rend/acl/role/registry/exception.rb
 - lib/rend/acl/version.rb
 - rend-acl.gemspec
+- test/helper.rb
+- test/support/failing_assertion.rb
+- test/support/mock_assertion.rb
+- test/support/passing_assertion.rb
 - test/test_acl.rb
+- test/test_documentation_examples.rb
+- wiki/pages/resources.md
 homepage: https://github.com/veloper/rend-acl
 licenses:
 - New-BSD
@@ -116,7 +124,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2809420582677817181
+      hash: 4151355783385604233
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -125,12 +133,17 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2809420582677817181
+      hash: 4151355783385604233
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
-summary: rend-acl-0.0.4
+summary: rend-acl-0.0.5
 test_files:
+- test/helper.rb
+- test/support/failing_assertion.rb
+- test/support/mock_assertion.rb
+- test/support/passing_assertion.rb
 - test/test_acl.rb
+- test/test_documentation_examples.rb