assertion 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a42bd3404b1c576172d51bb68c60070e5d0a11f
-  data.tar.gz: 652283f21156545c9aae42912cf06911e988f141
+  metadata.gz: d9fbab813ababd1c0224226d00aa2144dc682b6d
+  data.tar.gz: 30d48a47833d65670e480b29196caa1aec783040
 SHA512:
-  metadata.gz: 569103f1216ac675a37aa875464c988775f6b5ed8a03150da75db092b6e44b9e35467f192091025168004d7b53efa06cc648d1b45983d6e602ff80bd0a2b63d5
-  data.tar.gz: 22d4e650d8cdd775a479e92a66eca1b3e466cd61ebc650900910c1386ba6688525b2ff2fb1edbc2fa3e6076a02059921c2f589d48f448e51c543d28eaeda719a
+  metadata.gz: 521a9d990f59e2236344f712df369f211e3635c9f6828da4883135962b2f6e51a0e006e0fc18612d9e3474c24a5bdf3681585982c665eec6e8caa21de58961e4
+  data.tar.gz: 3e3dacb62cc68dd317e674cbad9424607d4b4a12638445e54a41534f747f9c0af7c07edf1a13728d9b2223349b713f72d716cb9f6cb7525dd7f8e332b46a8978

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+## v0.1.0 2015-06-20
+
+### Added
+
+* New `Guard` base class for guarding objects (nepalez)
+* New `Assertion.guards` builder method to provide specific guards (nepalez)
+* Custom `Assertion::InvalidError#inspect` method that shows `#messages` (nepalez)
+
+### Deleted
+
+* Removed `Assertion::NotImplementedError` (use `NoMethodError` instead) (nepalez)
+* Removed `Assertion::NameError` (use generic `NameError` instead) (nepalez)
+
+### Internal
+
+* Moved all message-related features to the `Assertion::Messages` (nepalez)
+* Removed `Assertion::I18n` (not the part of public API) (nepalez)
+* Extracted attribute DSL from `Assertion::Base` to `Assertion::Attributes` (nepalez)
+
+[Compare v0.0.1...v0.1.0](https://github.com/nepalez/assertion/compare/v0.0.1...v0.1.0)

data/README.md

@@ -20,38 +20,38 @@ Immutable assertions and validations for PORO.
 Synopsis
 --------
 
-The primary goal of the gem is to decouple assertions about the objects, and their validations, from the data.
+The primary goal of the gem is to make assertions about <decoupled> objects.
 
 No `ActiveSupport`, no mutation of any instances.
 
 ### Basic Usage
 
-Define the assertion by inheriting it from the `Assertion::Base` class with attributes to which it should be applied.
-Then implement the method `check` that should return the boolean value.
+Define an assertion by inheriting it from the `Assertion::Base` class with attributes to which it should be applied.
+Then implement the method `check` that should return a boolean value.
 
-You can do it either in a classic style:
+You can do it either in the classic style:
 
 ```ruby
 class IsAdult < Assertion::Base
   attribute :age, :name
 
   def check
-    age >= 18
+    age.to_i >= 18
   end
 end
 ```
 
-or using a builder for verbosity with the same result:
+or with more verbose builder:
 
 ```ruby
 IsAdult = Assertion.about :age, :name do
-  age >= 18
+  age.to_i >= 18
 end
 ```
 
-Define translations for both the *right* and *wrong* states of the assertion.
+Define translations to describe both the *right* and *wrong* states of the assertion.
 
-All the declared attributes are available (that's why we declared a `name` as an attribute):
+All the attributes are available in translations (that's why we declared the `name` as an attribute):
 
 ```yaml
 # config/locales/en.yml
@@ -63,7 +63,7 @@ en:
       wrong: "%{name} is a child yet (age %{age})"
 ```
 
-Check a state of a assertion for some argument(s), using class method `[]`:
+Check a state of an assertion for some argument(s), using class method `[]`:
 
 ```ruby
 john = { name: 'John', age: 10, gender: :male }
@@ -81,9 +81,10 @@ state.messages  # => ["John is a child yet (age 10)"]
 state.validate! # => #<Assertion::InvalidError @messages=["John is a child yet (age 10)"]>
 ```
 
-### Assertion Inversion
+Inversion
+---------
 
-Use the `.not` *class* method to negate a assertion:
+Use the `.not` *class* method to negate the assertion:
 
 ```ruby
 jack = { name: 'Jack', age: 21, gender: :male }
@@ -92,7 +93,8 @@ IsAdult.not[jack]
 # => #<Assertion::State @state=false, @messages=["Jack is already an adult (age 21)"]>
 ```
 
-### Composition of States
+Composition
+-----------
 
 You can compose assertion states (results):
 
@@ -121,54 +123,63 @@ state = IsAdult[jane] & IsMale[jane]
 # => #<Assertion::State @state=false, @messages=["Jane is a child yet (age 16)", "Jane is a female"]>
 ```
 
-Object Validation
------------------
-
-If you are used to "rails style" validations, provide a validator from assertions:
+Guards
+------
 
-```ruby
-class User
-  include Virtus.model
+The guard class is a lean wrapper around the state of its object.
 
-  attribute :name, String
-  attribute :age, Integer
-  attribute :gender, Symbol
-end
+It defines the `#state` for the object and checks if the state is valid:
 
-class Women < User
-  def validate!
-    state.validate!
-  end
+```ruby
+class VoterOnly < Assertion::Guard
+  alias_method :user, :object
 
   def state
-    IsAdult[attributes] & IsMale.not[attributes]
+    IsAdult[user.attributes] & IsCitizen[user.attributes]
   end
 end
-
-judy = Women.new(name: "Judy", age: 15, gender: :female)
-judy.valdate!
-# => #<Assertion::InvalidError @messages=["Judy is a child yet (age 15)"]>
 ```
 
-Edge Cases
-----------
+Or using the verbose builder `Assertion.guards`:
 
-You're expected to declare the `check` method for the assertion before applying it to some data.
+```ruby
+VoterOnly = Assertion.guards :user do
+  IsAdult[user.attributes] & IsCitizen[user.attributes]
+end
+```
 
-Otherwise `Assertion::NotImplementedError` is raised:
+When the guard is called for some object, its calls `#validate!` and then returns the source object. That simple.
 
 ```ruby
-IsAdult = Assertion.about :name, :age
+jack = OpenStruct.new(name: "Jack", age: 15, citizen: true)
+john = OpenStruct.new(name: "John", age: 34, citizen: true)
+
+voter = VoterOnly[jack]
+# => #<Assertion::InvalidError @messages=["Jack is a child yet (age 15)"]
 
-IsAdult[name: "Jane", age: 10]
-# => #<Assertion::NotImplementedError @message="IsAdult#check method not implemented">
+voter = VoterOnly[john]
+# => #<OpenStruct @name="John", @age=34>
 ```
 
-You cannot define attributes with names, that are already used as an istance methods:
+Naming Convention
+-----------------
+
+This is not necessary, but for verbosity you could follow the rules:
+
+* use the prefix `Is` for assertions (like `IsAdult`)
+* use the suffix `Only` for guards (like `AdultOnly`)
+
+Edge Cases
+----------
+
+You cannot define attributes with names already defined as istance methods:
 
 ```ruby
-IsAdult = Assertion.about :check, :call
-# => #<Assertion::NameError @message="Wrong name(s) for attribute(s): check, call">
+IsAdult = Assertion.about :check
+# => #<Assertion::NameError @message="Wrong name(s) for attribute(s): check">
+
+AdultOnly = Assertion.guards :state
+# => #<Assertion::NameError @message="Wrong name(s) for attribute(s): state">
 ```
 
 Installation

data/lib/assertion.rb

@@ -1,20 +1,19 @@
 # encoding: utf-8
 
 require "transproc"
-require "i18n"
 
 require_relative "assertion/transprocs/inflector"
-require_relative "assertion/transprocs/i18n"
 require_relative "assertion/transprocs/list"
 
-require_relative "assertion/exceptions/name_error"
-require_relative "assertion/exceptions/not_implemented_error"
-require_relative "assertion/exceptions/invalid_error"
+require_relative "assertion/invalid_error"
+require_relative "assertion/attributes"
+require_relative "assertion/messages"
 
 require_relative "assertion/state"
 require_relative "assertion/base"
 require_relative "assertion/inversion"
 require_relative "assertion/inverter"
+require_relative "assertion/guard"
 
 # The module allows declaring assertions (assertions) about various objects,
 # and apply (validate) them to concrete data.
@@ -66,7 +65,7 @@ module Assertion
   # @param [Proc] block
   #   The content for the `check` method
   #
-  # @return [Assertion::Base]
+  # @return [Class] The specific assertion class
   #
   def self.about(*attributes, &block)
     klass = Class.new(Base)
@@ -76,4 +75,36 @@ module Assertion
     klass
   end
 
+  # Builds the subclass of `Assertion::Guard` with given attribute
+  # (alias for the `object`) and implementation of the `#state` method.
+  #
+  # @example
+  #   VoterOnly = Assertion.guards :user do
+  #     IsAdult[user.attributes] & IsCitizen[user.attributes]
+  #   end
+  #
+  #   # This is the same as:
+  #   class VoterOnly < Assertion::Guard
+  #     alias_method :user, :object
+  #
+  #     def state
+  #       IsAdult[user.attributes] & IsCitizen[user.attributes]
+  #     end
+  #   end
+  #
+  # @param [Symbol] attribute
+  #   The alias for the `object` attribute
+  # @param [Proc] block
+  #   The content for the `state` method
+  #
+  # @return [Class] The specific guard class
+  #
+  def self.guards(attribute = nil, &block)
+    klass = Class.new(Guard)
+    klass.public_send(:attribute, attribute) if attribute
+    klass.__send__(:define_method, :state, &block) if block_given?
+
+    klass
+  end
+
 end # module Assertion

data/lib/assertion/attributes.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+module Assertion
+
+  # Module Attributes provides features to define and store a list of attributes
+  # shared by the [Assertion::Base] and [Assertion::Guard] classes
+  #
+  module Attributes
+
+    # List of attributes, defined for the class
+    #
+    # @return [Array<Symbol>]
+    #
+    def attributes
+      @attributes ||= []
+    end
+
+    # Adds a new attribute or a list of attributes to the class
+    #
+    # @param [Symbol, Array<Symbol>] names
+    #
+    # @return [undefined]
+    #
+    # @raise [NameError]
+    #   When the name is either used by instance attribute,
+    #   or forbidden as a name of the method to be implemented later
+    #   (not as an attribute)
+    #
+    def attribute(*names)
+      @attributes = List[:symbolize][attributes + names]
+      __check_attributes__
+    end
+
+    private
+
+    # Names of the methods that should be reserved to be used later
+    #
+    # @return [Array<Symbol>]
+    #
+    # @abstract
+    #
+    def __forbidden_attributes__
+      []
+    end
+
+    def __check_attributes__
+      names = attributes & (instance_methods + __forbidden_attributes__)
+      return if names.empty?
+      fail NameError.new "Wrong name(s) for attribute(s): #{names.join(", ")}"
+    end
+
+  end # module Attributes
+
+end # module Assertion

data/lib/assertion/base.rb

@@ -35,33 +35,14 @@ module Assertion
   #
   class Base
 
+    extend  Attributes
+    include Messages
+
     # Class DSL
     #
     class << self
 
-      # List of attributes, defined for the class
-      #
-      # @return [Array<Symbol>]
-      #
-      def attributes
-        @attributes ||= []
-      end
-
-      # Adds a new attribute or a list of attributes to the class
-      #
-      # @param [Symbol, Array<Symbol>] names
-      #
-      # @return [undefined]
-      #
-      # @raise [Assertion::NameError]
-      #   When the name is already used by instance attribute
-      #
-      def attribute(*names)
-        @attributes = List[:symbolize][attributes + names]
-        __check__
-      end
-
-      # Initializes a assertion with some attributes (data) and then calls it
+      # Initializes an assertion with some attributes (data) and then calls it
       #
       # @param [Hash] hash
       #
@@ -96,10 +77,8 @@ module Assertion
 
       private
 
-      # Checks if all the attributes have valid names
-      def __check__
-        wrong = attributes & instance_methods
-        fail(NameError.new wrong) if wrong.any?
+      def __forbidden_attributes__
+        [:check]
       end
 
     end # eigenclass
@@ -126,28 +105,6 @@ module Assertion
       freeze
     end
 
-    # Returns the translated message about the current state of the assertion
-    # applied to its attributes
-    #
-    # @param [Symbol] state The state to be described
-    #
-    # @return [String] The message
-    #
-    def message(state = nil)
-      I18n[:translate, __scope__, attributes][state ? :right : :wrong]
-    end
-
-    # Checks whether the assertion is right for the current attributes
-    #
-    # @return [Boolean]
-    #
-    # @raise [Check::NotImplementedError]
-    #   When the [#check] method hasn't been implemented
-    #
-    def check
-      fail NotImplementedError.new(self.class, :check)
-    end
-
     # Calls the assertion checkup and returns the state of the assertion having
     # been applied to the current attributes
     #
@@ -156,26 +113,11 @@ module Assertion
     #
     def call
       state = check
-      State.new state, message
+      State.new state, message(false)
     end
 
     private
 
-    # The scope for translating messages using the `I18n` module
-    #
-    # @return [Array<Symbol>]
-    #
-    def __scope__
-      I18n[:scope][self.class.name]
-    end
-
-    # Defines the object attribute and assigns given value to it
-    #
-    # @param [Symbol] name The name of the attribute
-    # @param [Object] value The value of the attribute
-    #
-    # @return [undefined]
-    #
     def __set_attribute__(name, value)
       attributes[name] = value
       singleton_class.__send__(:define_method, name) { value }

data/lib/assertion/guard.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+module Assertion
+
+  # The base class for object guards
+  #
+  # The guard defines a desired state for the object and checks
+  # if that state is valid.
+  #
+  # Its `call` method either returns the guarded object, or
+  # (when its state is invalid) raises an exception
+  #
+  # The class DSL also defines a `.[]` shortcut to initialize
+  # and call the guard for given object immediately.
+  #
+  # @example
+  #   class AdultOnly < Assertion::Guard
+  #     alias_method :user, :object
+  #
+  #     def state
+  #       IsAdult[user.attributes]
+  #     end
+  #   end
+  #
+  #   jack = User.new name: "Jack", age: 10
+  #   john = User.new name: "John", age: 59
+  #
+  #   AdultOnly[jack]
+  #   # => #<Assertion::InvalidError @messages=["Jack is a child (age 10)"]>
+  #   AdultOnly[john]
+  #   # => #<User @name="John", @age=59>
+  #
+  class Guard
+
+    extend Attributes
+
+    class << self
+
+      # Initializes and guard for the provided object and calls it immediately
+      #
+      # @param [Object] object The object whose state should be tested
+      #
+      # @return (see #call)
+      #
+      # @raise (see #call)
+      #
+      def [](object)
+        new(object).call
+      end
+
+      private
+
+      def __forbidden_attributes__
+        [:state]
+      end
+
+    end # eigenclass
+
+    # @!attribute [r] object
+    #
+    # @return [Object] The object whose state should be tested
+    #
+    attr_reader :object
+
+    # @!scope class
+    # @!method new(object)
+    # Creates the guard instance for the provided object
+    #
+    # @param [Object] object
+    #
+    # @return [Assertion::Guard]
+
+    # @private
+    def initialize(object)
+      @object = object
+      self.class.attributes.each(&method(:__set_attribute__))
+      freeze
+    end
+
+    # Validates the state of the [#object] and returns valid object back
+    #
+    # @return (see #object)
+    #
+    # @raise [Assertion::InvalidError] if the [#object] is invalid
+    #
+    def call
+      state.validate!
+      object
+    end
+
+    private
+
+    def __set_attribute__(name)
+      singleton_class.instance_eval { alias_method name, :object }
+    end
+
+  end # class Guard
+
+end # module Assertion