credentials 2.0.0 → 2.1.0

data/.gitignore

@@ -1,2 +1,3 @@
 credentials-*.gem
 coverage
+doc

data/{History.txt → HISTORY}

@@ -1,3 +1,15 @@
+=== 2.1.0 / 2009-11-12
+
+* Added support for :self
+* Added array arguments to +can+ and +cannot+
+* Put in masses of RDoc
+* Added magic method support back in
+
+=== 2.0.0 / 2009-11-11
+
+* Rewritten from first principles! Faster, smarter, leaner and with more
+  features than you can shake a very light stick at.
+
 === 1.0.1 / 2009-04-23
 
 * Now sort of framework-agnostic. I say "sort of", because what I've actually

data/README.rdoc

@@ -8,7 +8,7 @@ A generic actor/resource permission framework.
 
 == Installation
 
-* <tt>sudo gem install fauxparse-credentials --source=http://gems.github.com</tt>
+* <tt>sudo gem install credentials</tt>
 
 == Examples
 
@@ -29,9 +29,6 @@ A generic actor/resource permission framework.
   b.can_edit?(b) #=> true
   b.can_edit?(a) #=> true
   
-Check out the example application (in +spec/test_app+) for more (completely
-frivolous) examples.
-
 == Philosophy
 
 Credentials is NOT a role-based permission system. Permissions are based
@@ -85,12 +82,8 @@ and turned into a nice pretty error page.
 
 == To do
 
-* The test application is largely overkill. It does a half-decent job
-  of testing the functionality of the library, but I'd like to rewrite
-  it into a proper test suite.
-* Proper documentation of the API. It's been a while since I touched this.
+* Proper documentation of the API.
 * Better support for groups would make integration with RBA systems easier.
-* Deny permissions (+cannot+).
 
 == License
 

data/VERSION

@@ -1 +1 @@
-2.0.0
+2.1.0

data/credentials.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{credentials}
-  s.version = "2.0.0"
+  s.version = "2.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Matt Powell"]
-  s.date = %q{2009-11-11}
+  s.date = %q{2009-11-12}
   s.description = %q{A generic actor/resource permission framework based on rules, not objects.}
   s.email = %q{fauxparse@gmail.com.com}
   s.extra_rdoc_files = [
@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
   ]
   s.files = [
     ".gitignore",
-     "History.txt",
+     "HISTORY",
      "LICENSE",
      "README.rdoc",
      "Rakefile",
@@ -39,6 +39,7 @@ Gem::Specification.new do |s|
      "spec/rulebook_spec.rb",
      "spec/spec_helper.rb",
      "tasks/gems.rake",
+     "tasks/rdoc.rake",
      "tasks/spec.rake",
      "tasks/stats.rake",
      "uninstall.rb"

data/lib/credentials/object_extensions.rb

@@ -1,6 +1,35 @@
 module Credentials
-  module ObjectExtensions #:nodoc
+  module ObjectExtensions #:nodoc:
     module ClassMethods
+      # The main method for specifying and retrieving the permissions of
+      # a member of this class.
+      #
+      # When called with a block, this method yields a Credentials::Rulebook
+      # object, allowing you to specify the class's credentials
+      # in a declarative fashion. For example:
+      #
+      #     class User
+      #       credentials do |user|
+      #         user.can :edit, User, :if => :administrator?
+      #         user.can :edit, :self
+      #       end
+      #     end
+      #
+      # You can also specify options in this way:
+      #
+      #     class User
+      #       credentials(:default => :allow) do |user|
+      #         user.cannot :eat, "ice cream", :if => :lactose_intolerant?
+      #       end
+      #     end
+      #
+      # The following options are supported:
+      #
+      # [+:default+] Whether to +:allow+ or +:deny+ permissions that aren't
+      #              specified explicitly. The default default (!) is +:deny+.
+      #
+      # When called without a block, +credentials+ just returns the class's
+      # Credentials::Rulebook, creating it if necessary.
       def credentials(options = nil)
         @credentials ||= Credentials::Rulebook.new(self)
         if block_given?
@@ -12,22 +41,45 @@ module Credentials
         @credentials
       end
       
-      def inherited_with_credentials(child_class) #:nodoc
+      def inherited_with_credentials(child_class) #:nodoc:
         inherited_without_credentials(child_class) if child_class.respond_to? :inherited_without_credentials
         child_class.instance_variable_set("@credentials", Rulebook.for(child_class))
       end
     end
     
     module InstanceMethods
+      # Returns true if the receiver has access to the specified resource or action.
       def can?(*args)
         self.class.credentials.allow? self, *args
       end
       alias_method :able_to?, :can?
+
+      # Allows you to use magic methods to test permissions.
+      # For example:
+      #
+      #     class User
+      #       credentials do |user|
+      #         user.can :edit, :self
+      #       end
+      #     end
+      #     
+      #     user = User.new
+      #     user.can_edit? user #=> true
+      def method_missing_with_credentials(sym, *args)
+        if sym.to_s =~ /\Acan_(.*)\?\z/
+          can? $1.to_sym, *args
+        else
+          method_missing_without_credentials sym, *args
+        end
+      end
     end
     
     def self.included(receiver) #:nodoc
       receiver.extend         ClassMethods
       receiver.send :include, InstanceMethods
+
+      receiver.send :alias_method, :method_missing_without_credentials, :method_missing
+      receiver.send :alias_method, :method_missing, :method_missing_with_credentials
       
       class << receiver
         alias_method :inherited_without_credentials, :inherited if respond_to? :inherited

data/lib/credentials/rule.rb

@@ -1,4 +1,8 @@
 module Credentials
+  # Specifies an individual 'line' in a Rulebook.
+  # Trivially subclassed as Credentials::Rule::AllowRule
+  # and Credentials::Rule::DenyRule, but this is just
+  # to allow you to create your own, more complex rule types.
   class Rule
     attr_accessor :parameters
     attr_accessor :options
@@ -8,15 +12,49 @@ module Credentials
       self.parameters = args
     end
     
+    # Returns the number of arguments expected in a test to this
+    # rule. This is really basic, but allows a quick first-pass
+    # filtering of the rules.
     def arity
       parameters.length
     end
     
+    # Returns +true+ if the given arguments match this rule.
+    # Rules mostly use the same matching criteria as Ruby's
+    # +case+ statement: that is, the <tt>===</tt> operator.
+    # Remember:
+    #     User === User.new   # a class matches an instance
+    #     /\w+/ === "abc"     # a RegExp matches a valid string
+    #     (1..5) === 3        # a Range matches a number
+    #     :foo === :foo       # anything matches itself
+    #
+    # There are two exceptions to this behaviour. Firstly,
+    # if the rule specifies an array, then the argument will
+    # match any element of that array:
+    #     class User
+    #       credentials do |user|
+    #         user.can :fight, [ :shatner, :gandhi ]
+    #       end
+    #     end
+    #     
+    #     user.can? :fight, :gandhi  # => true
+    #
+    # Secondly, specifying <tt>:self</tt> in a rule is a nice
+    # shorthand for specifying an object's permissions on itself:
+    #     class User
+    #       credentials do |user|
+    #         user.can :fight, :self  # SPOILER ALERT
+    #       end
+    #     end
     def match?(*args)
       return false unless arity == args.length
       
       parameters.zip(args).each do |expected, actual|
-        return false unless expected === actual
+        case expected
+        when :self then return false unless actual == args.first
+        when Array then return false unless expected.any? { |item| (item === actual) || (item == :self && actual == args.first) }
+        else return false unless expected === actual
+        end
       end
       result = true
       result = result && evaluate_condition(options[:if], :|, *args) unless options[:if].nil?
@@ -24,6 +62,12 @@ module Credentials
       result
     end
     
+    # Evaluates an +if+ or +unless+ condition.
+    # [+conditions+]   One or more conditions to evaluate.
+    #                  Can be symbols or procs.
+    # [+op+]           Operator used to combine the results
+    #                  (+|+ for +if+, +&+ for +unless+).
+    # [+args+]         List of arguments to test with/against
     def evaluate_condition(conditions, op, *args)
       receiver = args.shift
       args.reject! { |arg| arg.is_a? Symbol }

data/lib/credentials/rulebook.rb

@@ -3,6 +3,10 @@ require "credentials/allow_rule"
 require "credentials/deny_rule"
 
 module Credentials
+  # Represents a collection of rules for granting and denying
+  # permissions to instances of a class.
+  # This is the return type of a call to a class's
+  # +credentials+ method.
   class Rulebook
     attr_accessor :klass
     attr_accessor :options
@@ -18,6 +22,9 @@ module Credentials
       @options = {}
     end
 
+    # Creates a Rulebook for the given class.
+    # Should not be called directly: instead,
+    # use +class.credentials+ (q.v.).
     def self.for(klass)
       rulebook = new(klass)
       if superclass && superclass.respond_to?(:credentials)
@@ -26,22 +33,138 @@ module Credentials
       rulebook
     end
 
+    # Returns +true+ if there are no rules defined in this Rulebook.
     def empty?
       rules.empty?
     end
     
+    # Declaratively specify a permission.
+    # This is usually done in the context of a +credentials+ block
+    # (see Credentials::ObjectExtensions::ClassMethods#credentials).
+    # The examples below assume that context.
+    #
+    # == Simple (intransitive) permissions
+    #     class User
+    #       credentials do |user|
+    #         user.can :log_in
+    #       end
+    #     end
+    # Permission is expressed as a symbol; usually an intransitive verb.
+    # Permission can be tested with:
+    #     user.can? :log_in
+    # or
+    #     user.can_log_in?
+    #
+    # == Resource (transitive) permissions
+    #     class User
+    #       credentials do |user|
+    #         user.can :edit, Post
+    #       end
+    #     end
+    # As above, but a resource type is specified.
+    # Permission can be tested with:
+    #     user.can? :edit, Post.first
+    # or
+    #     user.can_edit? Post.first
+    # 
+    # == +if+ and +unless+
+    # You can specify complex conditions with the +if+ and +unless+ options.
+    # These options can be either a symbol (which is assumed to be a method
+    # of the instance under test), or a proc, which is passed any non-symbol
+    # arguments from the +can?+ method.
+    #     class User
+    #       credentials do |user|
+    #         user.can :create, Post, :if => :administrator?
+    #         user.can :edit, Post, :if => lambda { |user, post| user == post.author }
+    #       end
+    #     end
+    #
+    #     user.can? :create, Post  # checks user.administrator?
+    #     user.can? :edit, post    # checks user == post.author
+    #
+    # Both +if+ and +unless+ options can be specified for the same rule:
+    #     class User
+    #       credentials do |user|
+    #         user.can :eat, "chunky bacon", :if => :hungry?, :unless => :vegetarian?
+    #       end
+    #     end
+    # So, only hungry users who are not vegetarian can eat chunky bacon.
+    #
+    # You can also specify multiple options for +if+ and +unless+.
+    # If there are multiple options for +if+, any one match will do:
+    #     class User
+    #       credentials do |user|
+    #         user.can :go_backstage, :if => [ :crew?, :good_looking? ]
+    #       end
+    #     end
+    #
+    # However, multiple options for +unless+ must _all_ match:
+    #     class User
+    #       credentials(:default => :allow) do |user|
+    #         user.cannot :record, Album, :unless => [ :talented?, :dedicated? ]
+    #       end
+    #     end
+    # You cannot record an album unless you are both talented and dedicated.
+    # Note that we have specified the default permission as +allow+ in this example:
+    # otherwise, the rule would never match.
+    #
+    # If your rules are any more complicated than that, you might want to
+    # consider using the lambda form of arguments to +if+ and/or +unless+.
+    #
+    # == Reflexive permissions (+:self+)
+    # The following two permissions are identical:
+    #     class User
+    #       credentials do |user|
+    #         user.can :edit, User, :if => lambda { |user, another| user == another }
+    #         user.can :edit, :self
+    #       end
+    #     end
     def can(*args)
       self.rules << AllowRule.new(klass, *args)
     end
     
+    # Declaratively remove a permission.
+    # This is handy to explicitly remove a permission in a child class that
+    # you have granted in a parent class.
+    # It is also useful if your default is set to +allow+ and you want to
+    # tighten up some permissions:
+    #     class User
+    #       credentials(:default => :allow) do |user|
+    #         user.cannot :delete, :self
+    #       end
+    #     end
+    # See Credentials::Rulebook#can for more on specifying permissions:
+    # just remember that everything is backwards!
     def cannot(*args)
       self.rules << DenyRule.new(klass, *args)
     end
     
+    # Determines whether to +:allow+ or +:deny+ by default.
     def default
       options[:default] && options[:default].to_sym
     end
     
+    # Decides whether to allow the requested permission.
+    #
+    # == Match algorithm
+    # 1. Set +ALLOWED+ to true if permission is specifically allowed
+    #    by any allow_rules; otherwise, false.
+    # 2. Set +DENIED+ to true if permission is specifically denied
+    #    by any deny_rules; otherwise, false.
+    # 3. The final result depends on the value of +default+:
+    #    a. if +:allow+: <tt>ALLOWED OR !DENIED</tt>
+    #    b. if +:deny+: <tt>ALLOWED AND !DENIED</tt>
+    #
+    # Expressed as a table:
+    # <table>
+    # <thead><tr><th>Matching rules</th><th>Default allow</th><th>Default deny</th></tr></thead>
+    # <tbody>
+    # <tr><td>None of the +allow+ or +deny+ rules matched.</td><td>allow</td><td>deny</td></tr>
+    # <tr><td>Some of the +allow+ rules matched, none of the +deny+ rules matched.</td><td>allow</td><td>allow</td></tr>
+    # <tr><td>None of the +allow+ rules matched, some of the +deny+ rules matched.</td><td>deny</td><td>deny</td></tr>
+    # <tr><td>Some of the +allow+ rules matched, some of the +deny+ rules matched.</td><td>allow</td><td>deny</td></tr>
+    # </tbody>
+    # </table>
     def allow?(*args)
       allowed = allow_rules.inject(false) { |memo, rule| memo || rule.allow?(*args) }
       denied = deny_rules.inject(false) { |memo, rule| memo || rule.deny?(*args) }
@@ -53,10 +176,12 @@ module Credentials
       end
     end
     
+    # Subset of rules that grant permission by exposing an +allow?+ method.
     def allow_rules
       rules.select { |rule| rule.respond_to? :allow? }
     end
     
+    # Subset of rules that deny permission by exposing an +deny?+ method.
     def deny_rules
       rules.select { |rule| rule.respond_to? :deny? }
     end

data/spec/credentials_spec.rb

@@ -14,6 +14,26 @@ describe Animal do
   it "shouldn't be able to do anything without explicit permission" do
     @cow.should_not be_able_to :jump, "Moon"
   end
+  
+  it "should be able to clean itself" do
+    @sheep.should be_able_to :clean, @sheep
+  end
+  
+  it "should not be able to clean another animal" do
+    @sheep.should_not be_able_to :clean, @cow
+  end
+  
+  it "should have magic methods for permissions" do
+    lambda {
+      @sheep.can_eat?(@cow).should == false
+    }.should_not raise_error
+  end
+  
+  it "should still do normal method_missing stuff" do
+    lambda {
+      @sheep.foo
+    }.should raise_error
+  end
 end
 
 describe Carnivore do
@@ -75,6 +95,17 @@ describe Carnivore do
   end
 end
 
+describe Bird do
+  before :each do
+    @toucan = Bird.new("Toucan")
+    @crocodile = Carnivore.new("Crocodile")
+  end
+  
+  it "should be able to clean another animal" do
+    @toucan.should be_able_to :clean, @crocodile
+  end
+end
+
 describe Man do
   before :each do
     @man = Man.new

data/spec/domain.rb

@@ -1,5 +1,6 @@
 class Animal < Struct.new(:species, :hungry, :fast)
   credentials do |animal|
+    animal.can :clean, :self
   end
   
   def edible?
@@ -22,7 +23,9 @@ class Prey < Animal
 end
 
 class Bird < Prey
-  
+  credentials do |bird|
+    bird.can :clean, Animal # they are good like that
+  end
 end
 
 class Carnivore < Animal
@@ -35,7 +38,6 @@ end
 
 class Man < Animal
   credentials :default => :allow do |man|
-
   end
 end
 

data/spec/rule_spec.rb

@@ -23,6 +23,14 @@ describe Credentials::AllowRule do
       rule.match?(lion, :jump)
     }.should raise_error(ArgumentError)
   end
+  
+  it "should match with an array" do
+    rule = Credentials::AllowRule.new Animal, :bite, [ :self, Prey ]
+    lion = Carnivore.new("lion")
+    antelope = Prey.new("antelope")
+    rule.should be_match(lion, :bite, antelope)
+    rule.should be_match(lion, :bite, lion)
+  end
 end
 
 describe Credentials::DenyRule do

data/spec/rulebook_spec.rb

@@ -1,10 +1,12 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
 describe Credentials::Rulebook do
+  it "should be empty when created" do
+    Credentials::Rulebook.new(Animal).should be_empty
+  end
+  
   it "should duplicate on inheritance" do
     Animal.credentials.should_not == Carnivore.credentials
     Animal.credentials.rules.should_not == Carnivore.credentials.rules
-    Animal.credentials.should be_empty
-    Carnivore.credentials.should_not be_empty
   end
 end

data/spec/spec_helper.rb

@@ -1,5 +1,6 @@
 $: << File.dirname(__FILE__) + "/../lib"
 require "credentials"
 require "spec"
+require "date"
 
 require File.join(File.dirname(__FILE__), "domain.rb")

data/tasks/rdoc.rake

@@ -0,0 +1,17 @@
+begin
+  require 'hanna/rdoctask'
+rescue
+  require 'rake/rdoctask'
+end
+
+desc 'Generate RDoc documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'HISTORY').
+    include('lib/**/*.rb')
+
+  rdoc.main = "README.rdoc" # page to start on
+  rdoc.title = "credentials documentation"
+
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--webcvs=http://github.com/fauxparse/credentials/'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: credentials
 version: !ruby/object:Gem::Version 
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors: 
 - Matt Powell
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-11 00:00:00 +13:00
+date: 2009-11-12 00:00:00 +13:00
 default_executable: 
 dependencies: []
 
@@ -24,7 +24,7 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - .gitignore
-- History.txt
+- HISTORY
 - LICENSE
 - README.rdoc
 - Rakefile
@@ -45,6 +45,7 @@ files:
 - spec/rulebook_spec.rb
 - spec/spec_helper.rb
 - tasks/gems.rake
+- tasks/rdoc.rake
 - tasks/spec.rake
 - tasks/stats.rake
 - uninstall.rb