blood_contracts-core 0.3.5 → 0.4.0

data/lib/blood_contracts/core/refined.rb

@@ -1,145 +1,168 @@
-module BloodContracts
-  module Core
-    class Refined
-      class << self
-        def or_a(other_type)
-          BC::Sum.new(self, other_type)
-        end
-        alias :or_an :or_a
-        alias :| :or_a
-
-        def and_then(other_type)
-          BC::Pipe.new(self, other_type)
-        end
-        alias :> :and_then
-
-        def match(*args, **kwargs)
-          if block_given?
-            new(*args, **kwargs).match { |*subargs| yield(*subargs) }
-          else
-            new(*args, **kwargs).match
-          end
-        end
-        alias :call :match
-
-        def ===(object)
-          return object.to_ary.any?(self) if object.is_a?(Tuple)
-          super
-        end
-
-        def set(**kwargs)
-          kwargs.each do |setting, value|
-            send(:"#{setting}=", value)
-          end
-          self
-        end
-
-        attr_accessor :failure_klass
-        def inherited(new_klass)
-          new_klass.failure_klass ||= ContractFailure
-        end
-      end
-
-      attr_accessor :context
-      attr_reader :errors, :value
-
-      def initialize(value, context: Hash.new { |h,k| h[k] = Hash.new }, **)
-        @errors = []
-        @context = context
-        @value = value
-      end
-
-      def match
-        return @match if defined? @match
-        return @match = (yield || self) if block_given?
-        return @match = (_match || self) if respond_to?(:_match)
-        self
-      end
-      alias :call :match
-
-      def valid?
-        match.errors.empty?
-      end
-      def invalid?; !valid?; end
-
-      def unpack
-        return @unpack if defined? @unpack
-        raise "This is not what you're looking for" if match.invalid?
-        return yield(match) if block_given?
-        return @unpack = _unpack(match) if respond_to?(:_unpack)
-
-        unpack_refined @value
+module BloodContracts::Core
+  # Base class for refinement type validations
+  class Refined
+    class << self
+      # Compose types in a Sum check
+      # Sum passes data from type to type in parallel, only one type
+      # have to match
+      #
+      # @return [BC::Sum]
+      #
+      def or_a(other_type)
+        BC::Sum.new(self, other_type)
+      end
+      alias or_an or_a
+      alias | or_a
+
+      # Compose types in a Pipe check
+      # Pipe passes data from type to type sequentially
+      #
+      # @return [BC::Pipe]
+      #
+      def and_then(other_type)
+        BC::Pipe.new(self, other_type)
+      end
+      alias > and_then
+
+      # Validate data over refinement type conditions
+      # Result is ALWAYS a Refined, but in cases when validation failed,
+      # we return ContractFailure ancestor  or ContractFailure itself
+      # (which is Refined anyway)
+      #
+      # @return [Refined]
+      #
+      def match(*args, **kwargs, &block)
+        instance = new(*args, **kwargs)
+        match = instance.match(&block) || instance
+        instance.instance_variable_set(:@match, match)
+        match
+      end
+      alias call match
+
+      # Override of case equality operator, to handle Tuple correctly
+      def ===(object)
+        return object.to_ary.any?(self) if object.is_a?(Tuple)
+        super
       end
 
-      def failure(error = nil, errors: @errors, **kwargs)
-        error ||= kwargs unless kwargs.empty?
-        errors << error if error
-        self.class.failure_klass.new(
-          { self.class => errors }, context: context
-        )
-      end
-
-      protected
-
-      def refined?(object)
-        object.class < BloodContracts::Core::Refined
+      # Accessor to define alternative to ContractFailure for #failure
+      # method to use
+      #
+      # @return [ContractFailure]
+      #
+      attr_accessor :failure_klass
+      def inherited(new_klass)
+        new_klass.failure_klass ||= ContractFailure
       end
+    end
 
-      def share_context_with(match)
-        match.context = @context.merge!(match.context)
-        yield(match.context)
-      end
+    # Matching context, contains extra debugging and output data
+    #
+    # @return [Hash<Symbol, Object>]
+    #
+    attr_accessor :context
+
+    # List of errors per type
+    #
+    # @return [Array<Hash<Refined, String>>]
+    #
+    attr_reader :errors
+
+    # Refinement type constructor
+    #
+    # @param [Object] value that Refined holds and should match
+    # @option [Hash<Symbol, Object>] context to share between types
+    #
+    def initialize(value, context: Hash.new { |h, k| h[k] = {} }, **)
+      @errors = []
+      @context = context
+      @value = value
+    end
 
-      def refine_value(value)
-        refined?(value) ? value.match : Anything.new(value)
-      end
+    # The type which is the result of data matching process
+    #
+    # @return [BC::Refined]
+    #
+    protected def match
+      fail NotImplementedError
+    end
+    alias call match
 
-      def unpack_refined(value)
-        refined?(value) ? value.unpack : value
-      end
+    # Transform the value before unpacking
+    protected def mapped
+      value
+    end
 
-      def errors_by_type(matches)
-        matches.map(&:errors).reduce(:+).delete_if(&:empty?)
-      end
+    # Checks whether the data matches the expectations or not
+    #
+    # @return [Boolean]
+    #
+    def valid?
+      @match.errors.empty?
     end
 
-    class ContractFailure < Refined
-      def initialize(value = nil, **)
-        super
-        return unless @value
-        @context[:errors] = (@context[:errors].to_a << @value.to_h)
-      end
+    # Checks whether the data matches the expectations or not
+    # (just negation of #valid?)
+    #
+    # @return [Boolean]
+    #
+    def invalid?
+      !valid?
+    end
 
-      def errors
-        @context[:errors].to_a
-      end
+    # Unpack the original value from the refinement type
+    #
+    # @return [Object]
+    #
+    def unpack
+      @unpack ||= mapped
+    end
 
-      def errors_h
-        errors.reduce(:merge)
-      end
-      alias :to_h :errors_h
+    protected
+
+    # Helper to build a ContractFailure with shared context
+    #
+    # @return [ContractFailure]
+    #
+    def failure(error = nil, errors: @errors, **kwargs)
+      error ||= kwargs unless kwargs.empty?
+      errors << error if error
+      self.class.failure_klass.new(
+        { self.class => errors }, context: @context
+      )
+    end
 
-      def match
-        self
-      end
+    # Helper to turn value into raw data
+    #
+    # @return [Object]
+    def value
+      unpack_refined(@value)
+    end
 
-      def unpack
-        context
-      end
+    def refined?(object)
+      object.class < BloodContracts::Core::Refined
     end
 
-    class Anything < Refined
-      def match
-        self
-      end
+    # FIXME: do we need it?
+    def share_context_with(match)
+      match.context = @context.merge!(match.context)
+      yield(match.context)
+    end
 
-      def valid?
-        true
-      end
+    # Turn data into refinement type if it is not already
+    #
+    # @return [Object]
+    #
+    def refine_value(value)
+      refined?(value) ? value.match : Anything.new(value)
+    end
 
-      def unpack
-        @value
-      end
+    # Turn value into raw data if it is refined
+    #
+    # @return [Object]
+    #
+    def unpack_refined(value)
+      refined?(value) ? value.unpack : value
     end
   end
 end

data/lib/blood_contracts/core/sum.rb

@@ -1,67 +1,99 @@
-require 'set'
+require "set"
 
-module BloodContracts
-  module Core
-    class Sum < Refined
-      class << self
-        attr_reader :sum_of, :finalized
+module BloodContracts::Core
+  # Meta refinement type, represents sum of several refinement types
+  class Sum < Refined
+    class << self
+      # Represents list of types in the sum
+      #
+      # @return [Array<Refined>]
+      #
+      attr_reader :sum_of
 
-        def new(*args)
-          return super(*args) if finalized
+      # Metaprogramming around constructor
+      # Turns input into Sum meta-class
+      #
+      # @param (see #initialze)
+      #
+      # rubocop:disable Style/SingleLineMethods
+      def new(*args)
+        return super(*args) if @finalized
 
-          new_sum = args.reduce([]) { |acc, type| type.respond_to?(:sum_of) ? acc + type.sum_of.to_a : acc << type  }
-
-          sum = Class.new(Sum) { def inspect; super; end }
-          sum.instance_variable_set(:@sum_of, ::Set.new(new_sum.compact))
-          sum.instance_variable_set(:@finalized, true)
-          sum
+        new_sum = args.reduce([]) do |acc, type|
+          type.respond_to?(:sum_of) ? acc + type.sum_of.to_a : acc << type
         end
 
-        def or_a(other_type)
-          sum = Class.new(Sum) { def inspect; super; end }
-          new_sum = self.sum_of.to_a
-          if other_type.respond_to?(:sum_of)
-            new_sum += other_type.sum_of.to_a
-          else
-            new_sum << other_type
-          end
-          sum.instance_variable_set(:@sum_of, ::Set.new(new_sum.compact))
-          sum.instance_variable_set(:@finalized, true)
-          sum
-        end
-        alias :or_an :or_a
-        alias :| :or_a
+        sum = Class.new(Sum) { def inspect; super; end }
+        finalize!(sum, new_sum)
+        sum
+      end
 
-        def inspect
-          return super if self.name
-          "Sum(#{self.sum_of.map(&:inspect).join(',')})"
+      # Compose types in a Sum check
+      # Sum passes data from type to type in parallel, only one type
+      # have to match
+      #
+      # @return [BC::Sum]
+      #
+      def or_a(other_type)
+        sum = Class.new(Sum) { def inspect; super; end }
+        new_sum = sum_of.to_a
+        if other_type.respond_to?(:sum_of)
+          new_sum += other_type.sum_of.to_a
+        else
+          new_sum << other_type
         end
+        finalize!(sum, new_sum)
+        sum
       end
+      # rubocop:enable Style/SingleLineMethods
+      alias or_an or_a
+      alias | or_a
 
-      def match
-        super do
-          or_matches = self.class.sum_of.map do |type|
-            match = type.match(@value, context: @context)
-          end
+      # @private
+      private def finalize!(new_class, new_sum)
+        new_class.instance_variable_set(:@sum_of, ::Set.new(new_sum.compact))
+        new_class.instance_variable_set(:@finalized, true)
+      end
 
-          if (match = or_matches.find(&:valid?))
-            match
-          else
-            or_matches.first
-            # just use the context
-            # ContractFailure.new(context: context)
-          end
-        end
+      # Returns text representation of Sum meta-class
+      #
+      # @return [String]
+      #
+      def inspect
+        return super if name
+        "Sum(#{sum_of.map(&:inspect).join(',')})"
       end
+    end
 
-      def errors
-        match.errors
+    # The type which is the result of data matching process
+    # For Tuple it verifies that all the attributes data are valid types
+    #
+    # @return [BC::Refined]
+    #
+    def match
+      or_matches = self.class.sum_of.map do |type|
+        type.match(@value, context: @context)
       end
 
-      def inspect
-        "#<sum #{self.class.name} is #{self.class.sum_of.to_a.join(' or ')} (value=#{@value})>"
+      if (match = or_matches.find(&:valid?))
+        match
+      else
+        failure(:no_matches)
       end
     end
-    Or = Sum
+
+    # List of errors per type during the matching
+    #
+    # @return [Array<Hash<Refined, String>>]
+    #
+    def errors
+      @context[:errors]
+    end
+
+    # @private
+    private def inspect
+      "#<sum #{self.class.name} is #{self.class.sum_of.to_a.join(' or ')}"\
+      " (value=#{@value})>"
+    end
   end
 end

data/lib/blood_contracts/core/tuple.rb

@@ -1,82 +1,167 @@
-module BloodContracts
-  module Core
-    class Tuple < Refined
-      class << self
-        attr_reader :attributes, :names, :finalized
-
-        def new(*args)
-          return super(*args) if finalized
-          if args.last.is_a?(Hash)
-            names = args.pop.delete(:names)
-          end
-
-          raise ArgumentError unless args.all?(Class)
-          tuple = Class.new(Tuple) { def inspect; super; end }
-          tuple.instance_variable_set(:@attributes, args)
-          tuple.instance_variable_set(:@names, names.to_a)
-          tuple.instance_variable_set(:@finalized, true)
-          tuple
-        end
+module BloodContracts::Core
+  # Meta refinement type, represents product of several refinement types
+  class Tuple < Refined
+    class << self
+      # List of types in the Tuple
+      #
+      # @return [Array<Refined>]
+      attr_reader :attributes
 
-        private
+      # Names of attributes
+      #
+      # @return [Array<Symbol>]
+      #
+      attr_reader :names
 
-        attr_writer :names
-      end
+      # Metaprogramming around constructor
+      # Turns input into Tuple meta-class
+      #
+      # @param (see #initialze)
+      #
+      # rubocop:disable Style/SingleLineMethods
+      def new(*args, **kwargs, &block)
+        return super(*args, **kwargs) if @finalized
+        names = args.pop.delete(:names) if args.last.is_a?(Hash)
 
-      attr_reader :values
-      def initialize(*values, context: Hash.new { |h,k| h[k] = Hash.new }, **)
-        _validate_args!(values)
-        @errors = []
-        @context = context
-        @values = values
+        raise ArgumentError unless args.all? { |type| type < Refined }
+        tuple = Class.new(Tuple) { def inspect; super; end }
+        tuple.instance_variable_set(:@attributes, args)
+        tuple.instance_variable_set(:@names, names.to_a)
+        tuple.instance_variable_set(:@finalized, true)
+        tuple.class_eval(&block) if block_given?
+        tuple
       end
+      # rubocop:enable Style/SingleLineMethods
 
-      def match
-        super do
-          @matches = self.class.attributes.zip(values).map do |(type, value)|
-            type.match(value, context: @context)
-          end
-          next self if (failure = @matches.find(&:invalid?)).nil?
-          failure
+      # Helper which registers attribute in the Tuple, also defines a reader
+      def attribute(name, type)
+        raise ArgumentError unless type < Refined
+        @attributes << type
+        @names << name
+        define_method(name) do
+          match.context.dig(:attributes, name)
         end
       end
 
-      def unpack
-        super { |match| @matches.map(&:unpack) }
-      end
-      alias :to_ary :unpack
-      alias :to_a :unpack
-
-      def unpack_h
-        @unpack_h ||= Hash[
-          unpack.map.with_index do |unpacked, index|
-            key = self.class.names[index] || index
-            [key, unpacked]
-          end
-        ]
-      end
-      alias :to_hash :unpack_h
-      alias :to_h :unpack_h
-
-      private def values_by_names
-        if self.class.names.empty?
-          self.values
-        else
-          self.class.names.zip(values).map { |k, v| [k, v].join('=') }
-        end
+      # Accessor to define alternative to ContractFailure for #failure
+      # method to use
+      #
+      # @return [ContractFailure]
+      #
+      attr_accessor :failure_klass
+      def inherited(new_klass)
+        new_klass.instance_variable_set(:@attributes, [])
+        new_klass.instance_variable_set(:@names, [])
+        new_klass.instance_variable_set(:@finalized, true)
+        new_klass.failure_klass ||= TupleContractFailure
+        super
       end
+    end
+
+
+    # List of values in Tuple
+    #
+    # @return [Array<Object>]
+    #
+    attr_reader :values
 
-      private def _validate_args!(values)
-        return if values.size == self.class.attributes.size
-        raise ArgumentError, <<~MESSAGE
-          wrong number of arguments (given #{values.size}, \
-          expected #{self.class.attributes.size})
-        MESSAGE
+    # Tuple constructor, builds Tuple from list of data values
+    #
+    # @param [Array<Object>] *values that we'll keep inside the Tuple
+    # @option [Hash<Symbol, Object>] context to share between types
+    #
+    def initialize(*values, context: Hash.new { |h, k| h[k] = {} }, **)
+      @context = context
+      @context[:attributes] ||= {}
+
+      additional_context = values.last if values.last.is_a?(Hash)
+      additional_context ||= {}
+
+      @values = parse_values_from_context(context.merge(additional_context))
+      @values ||= values
+
+      @errors = []
+    end
+
+    # The type which is the result of data matching process
+    # For Tuple it verifies that all the attributes data are valid types
+    #
+    # @return [BC::Refined]
+    #
+    def match
+      @matches = attributes_enumerator.map do |(type, value), index|
+        attribute_name = self.class.names[index]
+        attributes.store(attribute_name, type.match(value, context: @context))
       end
+      return if @matches.find(&:invalid?).nil?
+      failure(:invalid_tuple)
+    end
+
+    # Turns match into array of unpacked values
+    #
+    # @return [Array<Object>]
+    #
+    def mapped
+      @matches.map(&:unpack)
+    end
+
+    # (see #mapped)
+    alias to_ary unpack
+
+    # (see #mapped)
+    alias to_a unpack
+
+    # Unpacked value in form of a hash per attribute
+    #
+    # @return [Hash<String, ContractFailure>]
+    #
+    def unpack_h
+      @unpack_h ||= attributes.transform_values(&:unpack)
+    end
+    alias to_hash unpack_h
+    alias to_h unpack_h
+    alias unpack_attributes unpack_h
+
+    # Hash of attributes (name & type pairs)
+    #
+    # @return [Hash<String, Refined>]
+    #
+    def attributes
+      @context[:attributes]
+    end
 
-      private def inspect
-        "#<tuple #{self.class.name} of (#{values_by_names.join(',')})>"
+    # Subset of attributes which are invalid
+    #
+    # @return [Hash<String, ContractFailure>]
+    #
+    def attribute_errors
+      {}
+    end
+
+    # @private
+    private def parse_values_from_context(context)
+      return if context.empty?
+      return unless (self.class.names - context.keys).empty?
+      context.values_at(*self.class.names)
+    end
+
+    # @private
+    private def attributes_enumerator
+      self.class.attributes.zip(@values).each.with_index
+    end
+
+    # @private
+    private def values_by_names
+      if self.class.names.empty?
+        values
+      else
+        self.class.names.zip(values).map { |k, v| [k, v].join("=") }
       end
     end
+
+    # @private
+    private def inspect
+      "#<tuple #{self.class.name} of (#{values_by_names.join(', ')})>"
+    end
   end
 end