policy 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11f8a87bec42ea9a04af224a56604ff2d690a8da
-  data.tar.gz: f8d9626c4298248ef86f91c7720afb8c26f976d0
+  metadata.gz: dfc9740968e7733a76015392220aff44505d85e3
+  data.tar.gz: bbfb0d67cbbff03aa344d1c8f2ba69dc3fd4f16d
 SHA512:
-  metadata.gz: 4a76b932814bdbf8a70eb7e5ac55dc9ad1d82f93ae8c9d6151ebdceeeea0979e616c8f70637b7a777f50ee1e7ad30013f039d33fd5329665d0e128a06f8af8bd
-  data.tar.gz: 532d978cd83c62e7374d46a00f44c6c4034f9df1e3cccbe386d4f43a1cf60fc926580dc33996bd2892a2e4ca13accd265e256bfabf828c855ac7ad4472be8bb9
+  metadata.gz: 811e7374d0b8c41cec609dd9adb42eb5cedde61e391bed53cdd6cd4b1e2c72674c5207a3d9cfe85fac99b28aa52ead898fc737625629dd07cdd8c3f6ba8bf4dc
+  data.tar.gz: c75267c516e6da655b80980ca2437878c858d33b45ac9520bccdfea981e0de2cb96e80327e612c8fbcd6bebfc8b05eedb170628deaf09c62f778267dda2228af

data/Guardfile

@@ -6,12 +6,12 @@ guard :rspec, cmd: "bundle exec rspec" do
 
   watch("lib/policy.rb") { "spec" }
 
-  watch("lib/policy/cli/*.*") { "spec/tests/policy/cli_spec.rb" }
+  watch(%r{^lib/policy/cli/}) { "spec/tests/policy/cli_spec.rb" }
 
-  watch(/^lib(.+)\.rb$/) do |m|
-    "spec/tests#{ m[1] }_spec.rb"
+  watch(/^(bin|lib)\/(.+)\.rb$/) do |m|
+    "spec/tests/#{ m[1] }/#{ m[2] }_spec.rb"
   end
 
-  watch(/^spec.+_spec\.rb$/)
+  watch(%r{^spec/tests/.+_spec\.rb$})
 
 end # guard :rspec

data/README.md

@@ -17,28 +17,36 @@ Policy
 
 A tiny library to implement a **Policy Object pattern**.
 
+**NOTE** the gem was re-written from scratch in v2.0.0 (see Changelog section below)
+
+Introduction
+------------
+
 The gem was inspired by:
-* the CodeClimate's blog post "[7 ways to decompose fat ActiveRecord module]" 
-* the part "How to Model Less Obvious Kinds of Concept" from the "[Domain-Driven Design]" by Eric Evans.
+* the CodeClimate's blog post "[7 ways to decompose fat ActiveRecord module]".
+* the Chapter 10 of the book "[Domain-Driven Design]" by Eric Evans.
+
+A **Policy Object** (assertion, invariant) encapsulates a business rule in isolation from objects (such as entities or services) following it.
 
-A **Policy Object** encapsulates a business rule in isolation from objects (such as entities or services) following it.
+Policy Objects can be combined by logical operators `and`, `or`, `xor`, `not` to provide complex policies.
 
-This separation provides a number of benefits:
+This approach gives a number of benefits:
 
 * It makes business rules **explicit** instead of spreading and hiding them inside application objects.
-* It makes the rules **reusable** in various context (think of the *transaction consistency* both in bank transfers and cach machine withdrawals).
-* It allows definition of rules for **numerous attributes** that should correspond to each other in some way.
-* It makes complex rules **testable** in isolation from even more complex objects.
+* It allows definition of rules for **numerous attributes** at once that should correspond to each other in some way.
+* It makes the rules **simple** and **reusable** in various context and combinations.
+* It makes complex rules **testable** in isolation from their parts.
 
 [7 ways to decompose fat ActiveRecord module]: http://blog.codeclimate.com/blog/2012/10/17/7-ways-to-decompose-fat-activerecord-models/
 [Domain-Driven Design]: http://www.amazon.com/dp/B00794TAUG/
 
-# Installation
+Installation
+------------
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "policy"
+gem "policy", ">= 1.0"
 ```
 
 And then execute:
@@ -53,39 +61,43 @@ Or install it yourself as:
 $ gem install policy
 ```
 
-# Usage
+Usage
+-----
 
-## The Model for Illustration
+### The Model for Illustration
 
 Suppose an over-simplified model of bank account transactions and account-to-account transfers.
 
 ```ruby
-# The account transaction (either enrollment or witdrawal)
-class Transaction < Struct.new(:sum); end
+# The account has a limit
+class Account < Struct.new(:owner, :limit); end
+
+# The transaction belongs to account and has a sum (< 0 for withdrawals)
+class Transaction < Struct.new(:account, :sum); end
 
 # The transfer, connecting two separate transactions
-# (maybe this isn't an optimal model, but helpful for the subject)
 class Transfer < Struct.new(:withdrawal, :enrollment); end
 ```
 
-What we need is to apply the simple policy (invariant):
+What we need is to apply set of policies:
 
 **The sum of withdrawal's and enrollment's sums should be 0.**
+**The sum of withdrawal doesn't exceed the accounts' limit.**
+**The sum of transfers between client's own accounts can exceed the limit.**
 
 Let's do it with Policy Objects! 
 
-## Policy Declaration
-
-Define policies with a list of necessary attributes like using [Struct].
+### Policy Declaration
 
-Tnen use [ActiveModel::Validations] methods to describe its rules:
+Define policies with `Policy::Base` module included. Tnen use [ActiveModel::Validations] methods to describe its rules:
 
 ```ruby
 # An arbitrary namespace for financial policies
-module Policies::Financial
+module Policies
 
   # Withdrawal from one account should be equal to enrollment to another
-  class Consistency < Policy.new(:withdrawal, :enrollment)
+  class Consistency < Struct.new(:withdrawal, :enrollment)
+    include Policy::Base
 
     validates :withdrawal, :enrollment, presence: true
     validates :total_sum, numericality: { equal_to: 0 }
@@ -96,119 +108,204 @@ module Policies::Financial
       withdrawal.sum + enrollment.sum
     end
   end
-end
-```
 
-Note a policy knows nothing about the complex nature of its attributes until their quack like transactions with `#sum` method defined.
+  # The sum of withdrawal doesn't exceed the accounts' limit
+  class Limited < Struct.new(:withdrawal)
+    include Policy::Base
 
-### Scaffolding a Policy
+    validate :not_exceeds_the_limit
 
-You can scaffold the policy with its specification and necessary translations using the generator:
+    private
 
-```
-policy new
-```
+    def not_exceeds_the_limit
+      return if withdrawal.sum + withdrawal.limit > 0
+      errors.add :base, :exceeds_the_limit
+    end
+  end
 
-For a list of available options call the generator with a `-h` option:
+  # The transfer is made between client's own accounts
+  class InternalTransfer < Struct.new(:withdrawal, :enrollment)
+    include Policy::Base
 
-```
-policy new -h
+    validate :the_same_client
+
+    private
+
+    def the_same_client
+      return if withdrawal.account.owner == enrollment.account.owner
+      errors.add :base, :different_owners
+    end
+  end
+
+end
 ```
 
 [Struct]: http://ruby-doc.org//core-2.2.0/Struct.html
 [ActiveModel::Validations]: http://apidock.com/rails/ActiveModel/Validations
 
-## Following a Policy
+### Combining Policies
 
-Include the `Policy::Follower` module to the class and apply policies to corresponding attributes with `follow_policy` **class** method.
+Use `and`, `or`, `xor` instance methods to provide complex policies from elementary ones.
+
+You can use factory methods:
 
 ```ruby
-class Transfer < Struct.new(:withdrawal, :enrollment)
-  include Policy::Follower # also includes ActiveModel::Validations
+module Policies
+
+  module LimitedOrInternal
+    def self.new(withdrawal, enrollment)
+      InternalTransfer.new(withdrawal, enrollment).or Limited.new(withdrawal)
+    end
+  end
 
-  follow_policy Policies::Financial::Consistency, :withdrawal, :enrollment
 end
 ```
 
-The order of attributes should correspond to the policy definition.
-
-You can swap attributes (this is ok for our example)...
+As an alternative to instance methods, use the `Policy` module's methods:
 
 ```ruby
-follow_policy Policies::Financial::Consistency, :enrollment, :withdrawal
+def self.new(withdrawal, enrollment)
+  Policy.or(
+    InternalTransfer.new(withdrawal, enrollment),
+    Limited.new(withdrawal)
+  )
+end
 ```
 
-...or use the same attribute several times when necessary (not in our example, though):
+To provide negation use `and.not`, `or.not`, `xor.not` syntax:
 
 ```ruby
-follow_policy Policies::Financial::Consistency, :withdrawal, :withdrawal
+first_policy.and.not(second_policy, third_policy)
+
+# this is equal to:
+Policy.and(first_policy, Policy.not(second_policy), Policy.not(third_policy))
 ```
 
-Applied policies can be grouped by namespaces (useful when the object should follow many policies):
+Policies can composed at any number of levels.
+
+### Following Policies
+
+Include the `Policy::Follower` module to the policies follower class.
+
+Use the **class** method `.follows_policies` to declare policies (like ActiveModel::Validations `.validate` method does).
 
 ```ruby
-use_policies Policies::Financial do
-  follow_policy :Consistency, :withdrawal, :enrollment
+class Transfer < Struct.new(:withdrawal, :enrollment)
+  include Policy::Follower
+
+  follows_policies :consistent, :limited_or_internal
+
+  private
+
+  def consistent
+    Policies::Consistency.new(withdrawal, enrollment)
+  end
+
+  def limited_or_internal
+    Policies::LimitedOrInternal.new(withdrawal, enrollment)
+  end
+
 end
 ```
 
-## Policies Verification
-
-To verify object use `#follow_policies?` or `#follow_policies!` **instance** methods.
+Surely, you can skip creating `LimitedOrInternal` builder and combine policies for current class only:
 
 ```ruby
-Transaction = Struct.new(:account, :sum)
-withdrawal  = Transaction.new(account_1, -100)
-enrollment  = Transaction.new(account_2, 1000)
-
-transfer = Transfer.new withdrawal, enrollment
+def limited_or_internal
+  limited.or internal
+end
 
-transfer.follow_policies?
-# => false
+def limited
+  Policies::Limited.new(withdrawal)
+end
 
-transfer.follow_policies!
-# => raises <Policy::ViolationError>
+def internal
+  Policies::Internal.new(withdrawal, enrollment)
+end
 ```
 
-The policies are verified one-by-one until the first break - in just the same order they were declared.
+[builder]: http://sourcemaking.com/design_patterns/builder
 
-### Asyncronous Verification
+### Checking Policies
 
-Define names for policies using `as:` option. The names should be unique in the class' scope:
+Use the **instance** method `follow_policies?` to check whether an instance follows policies.
+
+The method checks all policies and **raises** the `Policy::ViolationError` when the first followed policy is broken.
 
 ```ruby
-class Transfer < Struct.new(:withdrawal, :enrollment)
-  include Policy::Follower
+transfer = Transfer.new(
+  Transaction.new(Account.new("Alice", 50), -100),
+  Transaction.new(Account.new("Bob", 50), 100)
+)
 
-  use_policies Policies::Financial do
-    follow_policy :Consistency, :withdrawal, :enrollment, as: :consistency
-  end
-end
+transfer.follow_policies?
+# => <Policy::ViolationError ... > because Alice's limit of 50 is exceeded
 ```
 
-Check policies by names (you can also use singular forms `follow_policy?` and `follow_policy!`):
+The method doesn't mutate the follower. It collects errors inside the exception `#errors` method, not the follower's one.
 
 ```ruby
-# Checks only consistency and skips all other policies
-transfer.follow_policy? :consistency
-transfer.follow_policy! :consistency
+begin
+  transfer.follow_policies?
+rescue ViolationError => err
+  err.errors
+end
 ```
 
-The set of policies can be checked at once:
+You can check subset of policies by calling the method with policy names:
 
 ```ruby
-transaction.follow_policies? :consistency, ...
+transfer.follow_policies? :consistent
+# passes because the transfer is consistent: -100 + 100 = 0
+# this doesn't check the :limited_or_internal policy
+```
+
+The method ignores policies, not declared by `.follows_policies` class method.
+
+The method has singular alias `follow_policy?(name)` that accepts one argument.
+
+Scaffolding
+-----------
+
+You can scaffold the policy with its specification and necessary translations using the generator:
+
 ```
+policy new consistency -n policies financial -a withdrawal enrollment -l fr de
+```
+
+For a list of available options call the generator with an `-h` option:
+
+```
+policy new -h
+```
+
+Changelog
+---------
+
+Version 2 was redesigned and rewritten from scratch. The main changes are:
+
+* Instead of building policy with a `Policy.new` method, it is now created by including the `Policy::Base` module.
+
+  In the previous version building a policy was needed to define an order of policy attributes. Now the definition of policy attributes is not the responsibility of the gem.
+
+* Instead of generating policies in a class scope (in the ActiveModel `validates` style), the `.follows_policy` refers to followers' instance methods (in the ActiveModel `validate` style).
+
+  This allows combining policy objects with logical expressions. Policies themselves becames more DRY, granular and testable in isolation.
+
+* Instead of mutating the follower, `follow_policy?` method raises an exception.
+
+  This allows follower to be immutable (frozen). The follower doesn't need to be messed with `ActiveModule::Validations` at all.
 
-Now the policies are verified one-by-one in **given order** (it may differ from the order of policies declaration) until the first break.
+  This approach makes `follow_policy!` method unnecessary.
 
-# Compatibility
+Compatibility
+-------------
 
 Tested under rubies, compatible with MRI 2.0+:
 
 * MRI rubies 2.0+
 * Rubinius 2+ (2.0+ mode)
-* JRuby head (2.0+ mode)
+* JRuby 9000 (2.0+ mode)
 
 Rubies with API 1.9 are not supported.
 
@@ -220,7 +317,8 @@ Uses [RSpec] 3.0+ for testing and [hexx-suit] for dev/test tools collection.
 [hexx-suit]: https://github.com/nepalez/hexx-suit/
 [ActiveModel::Validations]: http://apidock.com/rails/v3.1.0/ActiveModel/Validations
 
-# Contributing
+Contributing
+------------
 
 * Fork the project.
 * Read the [STYLEGUIDE](config/metrics/STYLEGUIDE).
@@ -232,6 +330,7 @@ Uses [RSpec] 3.0+ for testing and [hexx-suit] for dev/test tools collection.
   in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
-# License
+License
+-------
 
 See [MIT LICENSE](LICENSE).

data/config/metrics/flay.yml

@@ -1,2 +1,2 @@
 ---
-minimum_score: 5
+minimum_score: 9

data/config/metrics/roodi.yml

@@ -7,9 +7,9 @@ ClassNameCheck:
   pattern: !ruby/regexp /^[A-Z][a-zA-Z0-9]*$/
 ClassVariableCheck:
 CyclomaticComplexityBlockCheck:
-  complexity: 2
+  complexity: 3
 CyclomaticComplexityMethodCheck:
-  complexity: 2
+  complexity: 3
 EmptyRescueBodyCheck:
 ForLoopCheck:
 MethodLineCountCheck:

data/lib/policy.rb

@@ -1,40 +1,59 @@
 # encoding: utf-8
 
-require "adamantium"
+require "active_model"
 
-# Policy Object builder
-#
-# @!parse include Policy::Interface
+require_relative "policy/version"
+
+require_relative "policy/base"
+require_relative "policy/base/node"
+require_relative "policy/base/and"
+require_relative "policy/base/or"
+require_relative "policy/base/xor"
+require_relative "policy/base/not"
+require_relative "policy/base/negator"
+
+require_relative "policy/follower"
+require_relative "policy/follower/name_error"
+require_relative "policy/follower/policies"
+require_relative "policy/follower/violation_error"
+
+# The namespace for the code of the 'policy' gem
 module Policy
 
-  require_relative "policy/version"
-  require_relative "policy/validations"
-  require_relative "policy/violation_error"
-  require_relative "policy/interface"
-  require_relative "policy/follower"
-
-  class << self
-
-    # Builds a base class for the policy object with some attributes
-    #
-    # @example
-    #   class TransactionPolicy < Policy.new(:debet, :credit)
-    #   end
-    #
-    # @param [Array<Symbol>] attributes
-    #   names for the policy object attributes
-    #
-    # @return [Struct]
-    def new(*attributes)
-      Struct.new(*attributes) do
-        include Interface
-
-        def self.name
-          "Policy"
-        end
-      end
-    end
-
-  end # Policy singleton class
+  # Builds a composite policy by applying method AND to policies
+  #
+  # @param [Policy::Base, Array<Policy::Base>] policies
+  #
+  # @return [Policy::Base]
+  def self.and(*policies)
+    Base::And.new(*policies)
+  end
+
+  # Builds a composite policy by applying method OR to policies
+  #
+  # @param [Policy::Base, Array<Policy::Base>] policies
+  #
+  # @return [Policy::Base]
+  def self.or(*policies)
+    Base::Or.new(*policies)
+  end
+
+  # Builds a composite policy by applying method XOR to policies
+  #
+  # @param [Policy::Base, Array<Policy::Base>] policies
+  #
+  # @return [Policy::Base]
+  def self.xor(*policies)
+    Base::Xor.new(*policies)
+  end
+
+  # Builds the negation of policy
+  #
+  # @param [Policy::Base] policy
+  #
+  # @return [Policy::Base]
+  def self.not(policy)
+    Base::Not.new(policy)
+  end
 
 end # module Policy