bali 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ace804a23b863182a963445bfa6c155019eb63fb
-  data.tar.gz: 35aec1c6457269fac4f5e145b7714fa1509ffa09
+  metadata.gz: bfdb9274e88935206ba786522f65dba0cb1ddfb4
+  data.tar.gz: f3dc6a29a69a526540bfd1fab705acdade594773
 SHA512:
-  metadata.gz: 8fdcf47c1d1222118e81bc425ec045729419e63ca834dced4ba9471102e29a420deb6618d111fd21324938e2c79ec3d079cc1d32161dbc52876959e608185140
-  data.tar.gz: 0d0157c91b98396a0805742f619e124cce725bac14417af71afa2300fe234885e5c35dd5695fec498b07f80182b8d14ecaca9a01ca4a2663d4bdaddd251f16df
+  metadata.gz: 4801d9b6dc47bd70b75689663485487533c82d1de7ae2cb37c8657972837f5894d03cc7598fad9f87adea0312672ccd81ce00458012ae7aa157d95895bba17a0
+  data.tar.gz: 1a0597385c6bded708cba7d9bac719921706465df49d9a29b445910e086859e3da5b0b9e123da4ce38d63d11b1c3dae033854ca76c539d5b57077da57243c709

data/README.md

@@ -85,6 +85,9 @@ class My::Employee
 
   # working experience in the company
   attr_accessor :exp_years
+
+  # role/roles of this employee
+  attr_accessor :roles
 end
 ```
 
@@ -143,6 +146,72 @@ Thus, if we have:
 
 That is, we can check `can?` and `cant?` with multiple roles by passing array of roles to it.
 
+### Using subtarget's instance for Can and Cant testing
+
+You may pass in real subtarget instance rather than (1) a symbol, (2) string or (3) array of string/symbol for can/cant testing. 
+
+In order to do so, you need to specify the field/method in the subtarget that will be used to evaluating the subtarget's role(s). To do that, we define `roles_for` as follow inside `Bali.map_rules` block:
+
+```ruby
+Bali.map_rules do 
+  roles_for My::Employee, :roles
+  roles_for My::AdminUser, :admin_roles
+  roles_for My::BankUser, :roles
+  
+  # rules definition
+  # may follow
+end
+```
+
+`roles_for` accept two parameters, namely the class of the subtarget, and the field/method that will be invoked on it to gain data about its role(s).
+
+By doing so, we can now perform authorisation testing as follow:
+
+```ruby
+  txn = My::Transaction.new
+  current_employee = My::Employee.find_by_id(1)
+  txn.can?(current_employee, :print)
+```
+
+### Rule clause if/unless
+
+Rule clause may contain `if` and `unless` (decider) proc as already seen before. This `if` and `unless` `proc` have three variants that can be used to express your rule in sufficient detail:
+
+1. Zero arity
+2. One arity
+3. Two arity
+
+When rule is very brief, use zero-arity rule clause as below:
+
+```ruby
+Bali.map_rules do 
+  rules_for My::Transaction do
+    describe(:staff) { can :cancel }
+    describe(:finance) { can :cancel }
+  end
+end
+```
+
+Say that (for staff) to cancel a transaction, the transaction must have not been settled yet, you need to define the rule by using one-arity rule clause decider:
+
+```ruby
+describe :staff do
+  can :cancel, if: { |txn| txn.is_settled? }
+end
+```
+
+Good, but, in addition to that, how to allow transaction cancellation only to staff who has 3 years or so experience in working with the company? 
+
+In order to do that, we need to resort to 2-arity decider, as follow:
+
+```ruby
+describe :staff do
+  can :cancel, if: { |txn, usr| txn.is_settled? && usr.exp_years >= 3 }
+end
+```
+
+This way, we can keep our controller/logic/model clean from unnecessary and un-DRY role-testing logic.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/saveav/bali. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
@@ -153,19 +222,23 @@ Bali is proudly available as open source under the terms of the [MIT License](ht
 
 ## Changelog
 
-### Version 1.0.0beta1
+== Version 1.0.0beta1
+
 1. Initial version
 
-### Version 1.0.0rc1
+== Version 1.0.0rc1
+
 1. Fix bug where user can't check on class
 2. Adding new clause: cant_all
 
-### Version 1.0.0rc2
+== Version 1.0.0rc2
+
 1. [Fix bug when class's name, as a constant, is reloaded](http://stackoverflow.com/questions/2509350/rails-class-object-id-changes-after-i-make-a-request) (re-allocated to different address in the memory)
 2. Allow describing rule for `nil`, useful if user is not authenticated thus role is probably `nil`
 3. Remove pry from development dependency
 
-### Version 1.0.0rc3
+== Version 1.0.0rc3
+
 1. Each target class should includes `Bali::Objector`, for the following reasons:
    - Makes it clear that class do want to include the Bali::Objector
    - Transparant, and thus less confusing as to where "can?" and "cant" come from
@@ -173,18 +246,23 @@ Bali is proudly available as open source under the terms of the [MIT License](ht
 2. Return `true` to any `can?` for undefined target/subtarget alike
 3. Return `false` to any `cant?` for undefined target/subtarget alike
 
-### Version 1.0.0
+== Version 1.0.0
+
 1. Released the stable version of this gem
 
-### Version 1.1.0rc1
+== Version 1.1.0rc1
+
 1. Ability for rule class to be parsed later by passing `later: true` to rule class definition
 2. Add `Bali.parse` and `Bali.parse!` (`Bali.parse!` executes "later"-tagged rule class, Bali.parse executes automatically after all rules are defined)
 3. Added more thorough testing specs
 4. Proc can be served under `unless` for defining the rule's decider
 
-### Version 1.1.0rc2
+== Version 1.1.0rc2
+
 1. Ability to check `can?` and `cant?` for subtarget with multiple roles
 2. Describe multiple rules at once for multiple subtarget
 
-### Version 1.1.0
-1. Respecting precedence; rule that is defined first can be replaced with later-defined rule clause for the same operation
+== Version 1.2.0
+
+1. Passing real object as subtarget's role, instead of symbol or array of symbol
+2. Clause can also yielding user, along with the object in question

data/lib/bali.rb

@@ -13,7 +13,9 @@ require_relative "bali/dsl/rules_for_dsl.rb"
 require_relative "bali/objector"
 
 # exception classes
+require_relative "bali/exceptions/bali_error"
 require_relative "bali/exceptions/dsl_error"
+require_relative "bali/exceptions/objection_error"
 
 module Bali
   # mapping class to a RuleClass
@@ -24,6 +26,12 @@ module Bali
 
   # from full class name to symbol
   REVERSE_ALIASED_RULE_CLASS_MAP = {}
+
+  # {
+  #   User: :roles,
+  #   AdminUser: :admin_roles
+  # }
+  TRANSLATED_SUBTARGET_ROLES = {}
 end
 
 module Bali

data/lib/bali/dsl/map_rules_dsl.rb

@@ -6,6 +6,7 @@ class Bali::MapRulesDsl
     @@lock = Mutex.new
   end
 
+  # defining rules
   def rules_for(target_class, target_alias_hash = {}, &block)
     @@lock.synchronize do
       self.current_rule_class = Bali::RuleClass.new(target_class)
@@ -18,7 +19,33 @@ class Bali::MapRulesDsl
     end
   end
 
+  # subtarget_class is the subtarget's class definition
+  # field_name is the field that will be consulted when instantiated object of this class is passed in can? or cant?
+  def roles_for(subtarget_class, field_name)
+    raise Bali::DslError, "Subtarget must be a class" unless subtarget_class.is_a?(Class)
+    raise Bali::DslError, "Field name must be a symbol/string" if !(field_name.is_a?(Symbol) || field_name.is_a?(String))
+
+    Bali::TRANSLATED_SUBTARGET_ROLES[subtarget_class.to_s] = field_name 
+    nil
+  end
+
   def describe(*params)
     raise Bali::DslError, "describe block must be within rules_for block"
   end
+
+  def can(*params)
+    raise Bali::DslError, "can block must be within describe block"
+  end
+
+  def cant(*params)
+    raise Bali::DslError, "cant block must be within describe block"
+  end
+
+  def can_all(*params)
+    raise Bali::DslError, "can_all block must be within describe block"
+  end
+
+  def cant_all(*params)
+    raise Bali::DslError, "cant_all block must be within describe block"
+  end
 end

data/lib/bali/exceptions/bali_error.rb

@@ -0,0 +1,2 @@
+class Bali::Error < StandardError
+end

data/lib/bali/exceptions/dsl_error.rb

@@ -1,2 +1,3 @@
-class Bali::DslError < StandardError
+# this error is thrown when there is incorrect syntax in the DSL
+class Bali::DslError < Bali::Error
 end

data/lib/bali/exceptions/objection_error.rb

@@ -0,0 +1,3 @@
+# this error is thrown when objection is cannot be executed
+class Bali::ObjectionError < Bali::Error
+end

data/lib/bali/objector.rb

@@ -16,10 +16,46 @@ end
 
 module Bali::Objector::Statics
 
+  # will return array
+  def __translate_subtarget_roles__(_subtarget_roles)
+    if _subtarget_roles.is_a?(String) || _subtarget_roles.is_a?(Symbol) || _subtarget_roles.is_a?(NilClass)
+      return [_subtarget_roles]
+    elsif _subtarget_roles.is_a?(Array)
+      return _subtarget_roles
+    else
+      # this case, _subtarget_roles is an object but not a symbol or a string
+      # let's try to deduct subtarget's roles
+
+      _subtarget = _subtarget_roles
+      _subtarget_class = _subtarget.class.to_s
+      
+      # variable to hold deducted role of the passed object
+      deducted_roles = nil
+
+      Bali::TRANSLATED_SUBTARGET_ROLES.each do |subtarget_class, roles_field_name|
+        if _subtarget_class == subtarget_class
+          deducted_roles = _subtarget.send(roles_field_name)
+          if deducted_roles.is_a?(String) || deducted_roles.is_a?(Symbol)
+            deducted_roles = [deducted_roles]
+            break
+          elsif deducted_roles.is_a?(Array)
+            break
+          else
+            # keep it nil if _subtarget_roles is not either String, Symbol or Array
+            deducted_roles = nil
+          end
+        end # if matching class
+      end # each TRANSLATED_SUBTARGET_ROLES
+
+      return deducted_roles
+    end # if
+  end
+
   ### options passable to __can__? and __cant__? are:
   ### cross_action: if set to true wouldn't call its counterpart so as to prevent
   ###   overflowing stack
-  ###
+  ### original_subtarget: the original passed to can? and cant? before 
+  ###   processed by  __translate_subtarget_roles__
 
   def __can__?(subtarget, operation, record = self, options = {})
     # if performed on a class-level, don't call its class or it will return
@@ -58,15 +94,56 @@ module Bali::Objector::Statics
       # default if can? for undefined rule is false, after related clause
       # cannot be found in cant?
       return false if options[:cross_check]
-      return !self.cant?(subtarget, operation, record, cross_check: true)
+      options[:cross_check] = true
+      return !self.cant?(subtarget, operation, record, options)
     else
       if rule.has_decider?
         # must test first
         decider = rule.decider
-        if decider.arity == 0
-          return (rule.decider_type == :if) ? decider.() == true : decider.() == false
-        else
-          return (rule.decider_type == :if) ? decider.(record) == true : decider.(record) == false
+        original_subtarget = options.fetch(:original_subtarget)
+        case decider.arity
+        when 0
+          if rule.decider_type == :if
+            if decider.()
+              return true 
+            else 
+              return false
+            end
+          elsif rule.decider_type == :unless
+            unless decider.()
+              return true 
+            else 
+              return false 
+            end
+          end
+        when 1
+          if rule.decider_type == :if
+            if decider.(record)
+              return true 
+            else 
+              return false
+            end
+          elsif rule.decider_type == :unless
+            unless decider.(record)
+              return true 
+            else 
+              return false 
+            end
+          end
+        when 2
+          if rule.decider_type == :if
+            if decider.(record, original_subtarget)
+              return true 
+            else 
+              return false
+            end
+          elsif rule.decider_type == :unless
+            unless decider.(record, original_subtarget)
+              return true 
+            else 
+              return false 
+            end
+          end
         end
       else
         # rule is properly defined
@@ -110,14 +187,55 @@ module Bali::Objector::Statics
     # can? is defined exactly for the same target, and subtarget, and record (if given)
     if rule.nil?
       return true if options[:cross_check]
-      return !self.can?(subtarget, operation, record, cross_check: true)
+      options[:cross_check] = true
+      return !self.can?(subtarget, operation, record, options)
     else
       if rule.has_decider?
         decider = rule.decider
-        if decider.arity == 0
-          return (rule.decider_type == :if) ? decider.() == true : decider.() == false
-        else
-          return (rule.decider_type == :if) ? decider.(record) == true : decider.(record) == false
+        original_subtarget = options.fetch(:original_subtarget)
+        case decider.arity
+        when 0
+          if rule.decider_type == :if
+            if decider.()
+              return true 
+            else 
+              return false
+            end
+          elsif rule.decider_type == :unless
+            unless decider.()
+              return true 
+            else 
+              return false 
+            end
+          end
+        when 1
+          if rule.decider_type == :if
+            if decider.(record)
+              return true 
+            else 
+              return false
+            end
+          elsif rule.decider_type == :unless
+            unless decider.(record)
+              return true 
+            else 
+              return false 
+            end
+          end
+        when 2
+          if rule.decider_type == :if
+            if decider.(record, original_subtarget)
+              return true 
+            else 
+              return false
+            end
+          elsif rule.decider_type == :unless
+            unless decider.(record, original_subtarget)
+              return true 
+            else 
+              return false 
+            end
+          end
         end
       else
         return true # rule is properly defined
@@ -125,23 +243,30 @@ module Bali::Objector::Statics
     end # if rule is nil
   end
 
-  def can?(subtargets, operation, record = self, options = {})
-    subs = (subtargets.is_a?(Array)) ? subtargets : [subtargets]
+  def can?(subtarget_roles, operation, record = self, options = {})
+    subs = __translate_subtarget_roles__(subtarget_roles)
+    # well, it is largely not used unless decider's is 2 arity
+    options[:original_subtarget] = options[:original_subtarget].nil? ? subtarget_roles : options[:original_subtarget]
 
     subs.each do |subtarget|
       can_value = __can__?(subtarget, operation, record, options)
       return true if can_value == true
     end
     false
+  rescue => e
+    raise Bali::ObjectionError, e.message
   end
 
-  def cant?(subtargets, operation, record = self, options = {})
-    subs = (subtargets.is_a?(Array)) ? subtargets : [subtargets]
+  def cant?(subtarget_roles, operation, record = self, options = {})
+    subs = __translate_subtarget_roles__ subtarget_roles
+    options[:original_subtarget] = options[:original_subtarget].nil? ? subtarget_roles : options[:original_subtarget]
 
     subs.each do |subtarget|
       cant_value = __cant__?(subtarget, operation, record, options)
       return false if cant_value == false
     end
     true
+  rescue => e 
+    raise Bali::ObjectionError, e.message
   end
 end

data/lib/bali/version.rb

@@ -1,3 +1,3 @@
 module Bali
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bali
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Adam Pahlevi
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-08-24 00:00:00.000000000 Z
+date: 2015-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,7 +75,9 @@ files:
 - lib/bali.rb
 - lib/bali/dsl/map_rules_dsl.rb
 - lib/bali/dsl/rules_for_dsl.rb
+- lib/bali/exceptions/bali_error.rb
 - lib/bali/exceptions/dsl_error.rb
+- lib/bali/exceptions/objection_error.rb
 - lib/bali/foundations/bali_statics.rb
 - lib/bali/foundations/rule.rb
 - lib/bali/foundations/rule_class.rb