attestor 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3030abf371f99cd2d342e227e8d054fb718d0597
-  data.tar.gz: 9742b46202b9d6e2cff850f6e52243f8668bdde7
+  metadata.gz: 1b4d9f6dfa1931f69062623223fafaf32ec4d158
+  data.tar.gz: a18709a18446af9c58a71287eb9b3d923c125aed
 SHA512:
-  metadata.gz: 83ae6c32bb6be7ba47304a37ddc811ac3a22f761883dfc432f79533a2b7904860c2c81bd32e36b11d7e46e6ee445943074391dd90dab306e24548d2da58fd8d6
-  data.tar.gz: a1d2d13d9c1c7b16e942755b482dae67d8aefb1ed12ee4ca31755d4b31d787ed5db915190af62ba4ed7893b98a6ceb41d6feacd4c7b2c7e8e3ff925291528d5b
+  metadata.gz: fadf072439c8efa450e86ff37f7dd5778c67ce7a087eaea4e012e0267d9dce2b877283b76c04b1434b1ab0d17b7a00a48317ddeee766304d7ff08ebb02c66109
+  data.tar.gz: 0c5fccf30fe0cfc574d71b3235da77acc904c3f537f4d9ffb4887184925d42c57d82736f99d0af0954fe000c0bc141cc1793bd15911275485bfcfc648bb235c6

data/.travis.yml

@@ -6,5 +6,4 @@ rvm:
   - '2.0'
   - ruby-head
   - rbx-2 --2.0
-  - jruby-head-20mode
-  - jruby-head-21mode
+  - jruby-9.0.0.0.pre1

data/README.md

@@ -37,7 +37,12 @@ To solve the problem, the `attestor` gem:
 Approach
 --------
 
-Instead of collecting errors inside the object, the module's `validate` instance method just raises an exception (`Attestor::InvalidError`), that carries errors outside of the object. The object stays untouched (and can be made immutable).
+Instead of collecting errors inside the object, the module defines two instance methods:
+
+* `validate!` raises an exception (`Attestor::InvalidError`), that carries errors outside of the object.
+* `validate` - the safe version of `validate!`. It rescues an exception and returns special result object, that carries error info outside of the object.
+
+The object stays untouched (and can be made immutable).
 
 Installation
 ------------
@@ -67,18 +72,10 @@ Basic Use
 Declare validation in the same way as ActiveModel's `.validate` method does:
 
 ```ruby
-class Transfer < Struct.new(:debet, :credit)
+Transfer = Struct.new(:debet, :credit) do
   include Attestor::Validations
 
   validate :consistent
-end
-```
-
-You have to define an instance validator method (that can be private):
-
-```ruby
-class Transfer < Struct.new(:debet, :credit)
-  # ...
 
   private
 
@@ -89,7 +86,16 @@ class Transfer < Struct.new(:debet, :credit)
 end
 ```
 
-The `#invalid` method translates its argument in a current class scope and raises an exception.
+Alternatively, you can describe validation in the block (called in the scope of instance):
+
+```ruby
+class Transfer
+  # ...
+  validate { invalid :inconsistent if credit.sum != debet.sum }
+end
+```
+
+The `#invalid` method translates its argument in a current class scope and raises an exception with that method.
 
 ```yaml
 # config/locales/en.yml
@@ -101,16 +107,7 @@ en:
         inconsistent: "Credit differs from debet by %{fraud}"
 ```
 
-Alternatively, you can describe validation in the block (called in the scope of instance):
-
-```ruby
-class Transfer
-  # ...
-  validate { invalid :inconsistent if credit.sum != debet.sum }
-end
-```
-
-To run validations use the `#validate` instance method:
+To run validations use the `#validate!` instance method:
 
 ```ruby
 debet  = OpenStruct.new(sum: 100)
@@ -118,14 +115,25 @@ credit = OpenStruct.new(sum: 90)
 fraud_transfer = Transfer.new(debet, credit)
 
 begin
-  transfer.validate
-rescue => error
+  transfer.validate!       # with the bang
+rescue Attestor::InvalidError => error
   error.object == transfer # => true
-  error.messages
-  # => ["Credit differs from debet by 10"]
+  error.messages           # => ["Credit differs from debet by 10"]
 end
 ```
 
+Another option is to use the safe version `#validate`. It rescues from the exception and returns results in a separate report object:
+
+```ruby
+report = transfer.validate  # without the bang
+
+report.valid?               # => false
+report.invalid?             # => true
+report.object == transfer   # => true
+report.messages             # => ["Credit differs from debet by 10"]
+report.error                # => <Attestor::InvalidError ...>
+```
+
 Use of Contexts
 ---------------
 
@@ -134,43 +142,42 @@ Sometimes you need to validate the object agaist the subset of validations, not
 To do this use `:except` and `:only` options of the `.validate` class method.
 
 ```ruby
-class Transfer < Struct.new(:debet, :credit)
-  include Attestor::Validations
-
+class Transfer
+  # ...
   validate :consistent, except: :steal_of_money
 end
 ```
 
-Then call a validate method with that context:
+Then call a `#validate!`/`#validate` methods with that context:
 
 ```ruby
-fraud_transfer.validate                 # => InvalidError
-fraud_transfer.validate :steal_of_money # => PASSES!
+fraud_transfer.validate!                 # => InvalidError
+fraud_transfer.validate! :steal_of_money # => PASSES!
 ```
 
-You can use the same validator several times with different contexts. Any validation will be made independently from the others:
+You can use the same validator several times with different contexts.
 
 ```ruby
 class Transfer
   # ...
+
+  # validate :consistent, only: [:fair_trade, :legal]
   validate :consistent, only: :fair_trade
   validate :consistent, only: :legal
 
-  # This is the same as:
-  # validate :consistent, only: [:fair_trade, :legal]
 end
 ```
 
 Delegation
 ----------
 
-Extract validator to the external object (policy), that responds to `validate`.
+Extract validator to an external object (policy), that responds to `validate!`.
 
 ```ruby
-class ConsistentTransfer.new(:debet, :credit)
+ConsistentTransfer = Struct.new(:debet, :credit) do
   include Attestor::Validations
 
-  def validate
+  def validate!
     invalid :inconsistent unless debet.sum == credit.sum
   end
 end
@@ -197,36 +204,36 @@ class Transfer
   end
 ```
 
-The change between `validate :something` and `validates :something` is that:
-* `validate` expects `#something` to make checks and raise error by itself
-* `validates` expects `#something` to respond to `#validate`
+The difference between `.validate :something` and `.validates :something` class methods is that:
+* `.validate` expects `#something` to make checks and raise error by itself
+* `.validates` expects `#something` to respond to `#validate!`
 
 Policy Objects
 --------------
 
-Basically the policy includes `Attestor::Validations` with additional methods to allow chaining policies by logical methods.
+Basically the policy includes `Attestor::Validations` with additional methods to allow logical compositions.
 
-To create a policy as a `Struct` use the builder method:
+To create a policy as a `Struct` use the builder:
 
 ```ruby
 ConsistencyPolicy = Attestor::Policy.new(:debet, :credit) do
-  def validate
+  def validate!
     fraud = credit - debet
     invalid :inconsistent, fraud: fraud if fraud != 0
   end
 end
 ```
 
-If you doesn't need Struct, include `Attestor::Policy` to the class and initialize its arguments somehow else:
+If you doesn't need `Struct`, include `Attestor::Policy` to the class and initialize its arguments somehow else:
 
 ```ruby
-class ConsistencyPolicy < OpenStruct
+class ConsistencyPolicy
   include Attestor::Policy
   # ...
 end
 ```
 
-Policy objects can be used by `validates` method like other validatable objects:
+Policy objects can be used by `validates` method like other objects that respond to `#validate!`:
 
 ```ruby
 class Transfer
@@ -235,8 +242,6 @@ class Transfer
 end
 ```
 
-They also respond to `valid?` and `invalid?` methods (that just rescues from `vaidate` missing any error messages).
-
 Complex Policies
 ----------------
 
@@ -245,27 +250,27 @@ Policies (assertions) can be combined by logical methods.
 Suppose we have two policy objects:
 
 ```ruby
-valid_policy.valid?   # => true
-invalid_policy.valid? # => false
+valid_policy.validate.valid?   # => true
+invalid_policy.validate.valid? # => false
 ```
 
 Use factory methods to provide compositions:
 
 ```ruby
 complex_policy = valid_policy.not
-complex_policy.validate # => fails
+complex_policy.validate! # => fails
 
 complex_policy = valid_policy.and(valid_policy, invalid_policy)
-complex_policy.validate # => fails
+complex_policy.validate! # => fails
 
 complex_policy = invalid_policy.or(invalid_policy, valid_policy)
-complex_policy.validate # => passes
+complex_policy.validate! # => passes
 
 complex_policy = valid_policy.xor(valid_poicy, valid_policy)
-complex_policy.validate # => fails
+complex_policy.validate! # => fails
 
 complex_policy = valid_policy.xor(valid_poicy, invalid_policy)
-complex_policy.validate # => passes
+complex_policy.validate! # => passes
 ```
 
 The `or`, `and` and `xor` methods called without argument(s) don't provide a policy object. They return lazy composer, expecting `#not` method.
@@ -294,6 +299,15 @@ Policy.not(valid_policy)
 
 As before, you can use any number of policies (except for negation of a single policy) at any number of nesting.
 
+Latest changes
+--------------
+
+### Version 2.0.0
+
+1. The method `#validate` doesn't raise an error. It returns a validation results report. To raise an exception use the unsafe `#validate!` method (see [Basic Use](#basic-use) for details).
+
+2. Policies doesn't have `#valid?` and `#invalid?` methods any longer. Both the methods are removed to `#validate` report.
+
 Compatibility
 -------------
 

data/config/metrics/rubocop.yml

@@ -52,6 +52,10 @@ Style/FileName:
 Style/RaiseArgs:
   EnforcedStyle: compact
 
+Style/RescueModifier:
+  Exclude:
+    - '**/*_spec.rb'
+
 Style/SingleLineMethods:
   Exclude:
     - '**/*_spec.rb'

data/lib/attestor/invalid_error.rb

@@ -2,20 +2,9 @@
 
 module Attestor
 
-  # The exception to be raised when a validation fails
+  # The exception to be raised when an unsafe validation fails
   class InvalidError < RuntimeError
 
-    # @!scope class
-    # @!method new(object, messages = nil)
-    # Creates an exception for given object
-    #
-    # @param  [Object] object
-    #   The invalid object
-    # @param [String, Array<String>] messages
-    #   The list of validation error messages
-    #
-    # @return [Attestor::InvalidError]
-
     # @private
     def initialize(object, messages = nil)
       @object   = object

data/lib/attestor/policy/and.rb

@@ -4,27 +4,10 @@ module Attestor
 
   module Policy
 
-    # AND-concatenation of several policies (branches)
-    #
-    # The policy is valid if all its branches are valid.
-    #
-    # @example (see #validate)
-    #
-    # @api private
+    # @private
     class And < Node
 
-      # Checks whether every policy is valid
-      #
-      # @example
-      #   first.valid?  # => true
-      #   second.valid? # => false
-      #
-      #   composition = Attestor::Policy::And.new(first, second)
-      #   composition.validate
-      #   # => Policy::InvalidError
-      #
-      # @return [undefined]
-      def validate
+      def validate!
         return unless detect(&:invalid?)
         super
       end

data/lib/attestor/policy/negator.rb

@@ -4,47 +4,20 @@ module Attestor
 
   module Policy
 
-    # Composes a policy with an argument of its {#not} method
-    #
-    # @api private
+    # @private
     class Negator
 
-      # @!scope class
-      # @!method new(policy, composer)
-      # Creates the negator object, expecting {#not} method call
-      #
-      # @param [Policy::Base] policy
-      #   the policy to be composed with negations of other policies
-      # @param [Class] composer
-      #   the composer for policies
-      #
-      # @return [Policy::Base::Negator]
       def initialize(composer, policy)
         @policy   = policy
         @composer = composer
         freeze
       end
 
-      # Returns a composition of the {#policy} with negations of other policies
-      #
-      # @param [Policy::Base, Array<Policy::Base>] policies
-      #
-      # @return [Policy::Base]
       def not(*policies)
         composer.new policy, policies.flat_map(&Not.method(:new))
       end
 
-      # @!attribute [r] policy
-      # The the policy to be composed with negations of other policies
-      #
-      # @return [Policy::Base]
-      attr_reader :policy
-
-      # @!attribute [r] composer
-      # The the composer for policies
-      #
-      # @return [Class]
-      attr_reader :composer
+      attr_reader :policy, :composer
 
     end # class Negator
 

data/lib/attestor/policy/node.rb

@@ -4,49 +4,23 @@ module Attestor
 
   module Policy
 
-    # The base class for composite policies
-    #
-    # @api private
+    # @private
     class Node
-      include Attestor::Policy
-      include Enumerable
-
-      # @!scope class
-      # @!method new(*branches)
-      # Creates the node with branches
-      #
-      # @param [<Attestor::Policy>, Array<Attestor::Policy>] branches
-      #
-      # @return [Policy::Base::Node]
-
-      # @private
+      include Attestor::Policy, Enumerable
+
+      attr_reader :branches
+
       def initialize(*branches)
         @branches = branches.flatten
         freeze
       end
 
-      # @!attribute [r] branches
-      # The branches of the node
-      #
-      # @return [Array<Policy::Base>]
-      attr_reader :branches
-
-      # Validates the policy as invalid
-      #
-      # To be reloaded by subclasses (And, Or, Xor, Not)
-      #
-      # @raise [Policy::InvalidError]
-      #
-      # @return [undefined]
-      def validate
+      def validate!
         invalid :base
       end
 
-      # Iterates throught branches
-      #
-      # @return [Enumerator]
       def each
-        block_given? ? branches.each { |item| yield(item) } : to_enum
+        block_given? ? branches.each { |item| yield(item.validate) } : to_enum
       end
 
     end # class Node

data/lib/attestor/policy/not.rb

@@ -4,39 +4,14 @@ module Attestor
 
   module Policy
 
-    # Negation of a single policy
-    #
-    # The policy is valid if its only branch is invalid
-    #
-    # @example (see #validate)
-    #
-    # @api private
+    # @private
     class Not < Node
 
-      # @!scope class
-      # @!method new(policy)
-      # Creates the policy negation
-      #
-      # @param [Array<Policy::Base>] policy
-      #
-      # @return [Policy::Base::Node]
-
-      # @private
       def initialize(_)
         super
       end
 
-      # Checks whether every policy is valid
-      #
-      # @example
-      #   policy.valid? # => true
-      #
-      #   composition = Attestor::Policy::Not.new(policy)
-      #   composition.validate
-      #   # => Policy::InvalidError
-      #
-      # @return [undefined]
-      def validate
+      def validate!
         return unless detect(&:valid?)
         super
       end

data/lib/attestor/policy/or.rb

@@ -4,27 +4,10 @@ module Attestor
 
   module Policy
 
-    # OR-concatenation of several policies (branches)
-    #
-    # The policy is valid unless all its branches are invalid.
-    #
-    # @example (see #validate)
-    #
-    # @api private
+    # @private
     class Or < Node
 
-      # Checks whether any policy is valid
-      #
-      # @example
-      #   first.valid?  # => false
-      #   second.valid? # => false
-      #
-      #   composition = Attestor::Policy::Or.new(first, second)
-      #   composition.validate
-      #   # => Policy::InvalidError
-      #
-      # @return [undefined]
-      def validate
+      def validate!
         return if detect(&:valid?)
         super
       end

data/lib/attestor/policy/xor.rb

@@ -4,27 +4,10 @@ module Attestor
 
   module Policy
 
-    # XOR-concatenation of several policies (branches)
-    #
-    # The policy is valid when it has both valid and invalid branches.
-    #
-    # @example (see #validate)
-    #
-    # @api private
+    # @private
     class Xor < Node
 
-      # Checks whether both valid and invalid branches are present
-      #
-      # @example
-      #   first.valid?  # => true
-      #   second.valid? # => true
-      #
-      #   composition = Attestor::Policy::Xor.new(first, second)
-      #   composition.validate
-      #   # => Policy::InvalidError
-      #
-      # @return [undefined]
-      def validate
+      def validate!
         return if detect(&:valid?) && detect(&:invalid?)
         super
       end

data/lib/attestor/policy.rb

@@ -36,24 +36,6 @@ module Attestor
       end
     end
 
-    # Checks whether the policy is valid
-    #
-    # @return [Boolean]
-    def valid?
-      validate
-    rescue InvalidError
-      false
-    else
-      true
-    end
-
-    # Checks whether the policy is invalid
-    #
-    # @return [Boolean]
-    def invalid?
-      !valid?
-    end
-
     # Negates the current policy
     #
     # @return [Attestor::Policy::Not]

data/lib/attestor/report.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+module Attestor
+
+  # Describes the result, returned by safe validation
+  class Report
+
+    # @private
+    def initialize(object, error = nil)
+      @object = object
+      @error  = error
+      freeze
+    end
+
+    # @!attribute [r] object
+    # The object being validated
+    #
+    # @return [Object]
+    attr_reader :object
+
+    # @!attribute [r] error
+    # The exception raised by validation
+    #
+    # @return [Attestor::InvalidError] if validation fails
+    # @return [nil] if validation passes
+    attr_reader :error
+
+    # Checks whether validation passes
+    #
+    # @return [Boolean]
+    def valid?
+      error.blank?
+    end
+
+    # Checks whether validation fails
+    #
+    # @return [Boolean]
+    def invalid?
+      !valid?
+    end
+
+    # Returns the list of error messages
+    #
+    # @return [Array<String>]
+    def messages
+      error ? error.messages : []
+    end
+
+  end # class Report
+
+end # module Attestor

data/lib/attestor/validations/delegator.rb

@@ -4,26 +4,11 @@ module Attestor
 
   module Validations
 
-    # Describe a validator that delegates validation to instance method or block
-    #
-    # The follower not only calls an instance method (block) as validator does,
-    # but calls #validate method of the result.
-    #
-    # @example
-    #   follower = Validator.new(:foo, only: :baz) { FooPolicy.new(foo) }
-    #
-    # @api private
+    # @private
     class Delegator < Validator
 
-      # Validates an object by delegation
-      #
-      # @param [Object] object
-      #
-      # @raise [Attestor::InvalidError] if a policy isn't valid
-      #
-      # @return [undefined]
-      def validate(_)
-        super.validate
+      def validate!(_)
+        super.validate!
       end
 
     end # class Follower

data/lib/attestor/validations/message.rb

@@ -4,24 +4,9 @@ module Attestor
 
   module Validations
 
-    # Bulder for error messages
-    #
-    # @api private
+    # @private
     class Message < String
 
-      # @!scope class
-      # @!method new(value, object, options = {})
-      # Builds a string from value
-      #
-      # @param [#to_s] value
-      # @param [Object] object
-      # @param [Hash] options
-      #   options for translating symbolic value
-      #
-      # @return [String]
-      #   either translation of symbolic value or stringified value argument
-
-      # @private
       def initialize(value, object, options = {})
         @value   = value
         @object  = object