dry-types 0.15.0 → 1.2.0

data/lib/dry/types/container.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 require 'dry/container'
 
 module Dry
   module Types
+    # Internal container for the built-in types
+    #
+    # @api private
     class Container
       include Dry::Container::Mixin
     end

data/lib/dry/types/core.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 require 'dry/types/any'
 
 module Dry
   module Types
     # Primitives with {Kernel} coercion methods
-    COERCIBLE = {
+    KERNEL_COERCIBLE = {
       string: String,
       integer: Integer,
       float: Float,
@@ -12,10 +14,19 @@ module Dry
       hash: ::Hash
     }.freeze
 
-    # Primitives that are non-coercible through {Kernel} methods
+    # Primitives with coercions through by convention `to_*` methods
+    METHOD_COERCIBLE = {
+      symbol: Symbol
+    }.freeze
+
+    # By convention methods to coerce {METHOD_COERCIBLE} primitives
+    METHOD_COERCIBLE_METHODS = {
+      symbol: :to_sym
+    }.freeze
+
+    # Primitives that are non-coercible
     NON_COERCIBLE = {
       nil: NilClass,
-      symbol: Symbol,
       class: Class,
       true: TrueClass,
       false: FalseClass,
@@ -26,7 +37,10 @@ module Dry
     }.freeze
 
     # All built-in primitives
-    ALL_PRIMITIVES = COERCIBLE.merge(NON_COERCIBLE).freeze
+    ALL_PRIMITIVES = [KERNEL_COERCIBLE, METHOD_COERCIBLE, NON_COERCIBLE].reduce(&:merge).freeze
+
+    # All coercible types
+    COERCIBLE = KERNEL_COERCIBLE.merge(METHOD_COERCIBLE).freeze
 
     # All built-in primitives except {NilClass}
     NON_NIL = ALL_PRIMITIVES.reject { |name, _| name == :nil }.freeze
@@ -44,11 +58,18 @@ module Dry
       register("strict.#{name}", type)
     end
 
-    # Register {COERCIBLE} types
-    COERCIBLE.each do |name, primitive|
+    # Register {KERNEL_COERCIBLE} types
+    KERNEL_COERCIBLE.each do |name, primitive|
       register("coercible.#{name}", self["nominal.#{name}"].constructor(Kernel.method(primitive.name)))
     end
 
+    # Register {METHOD_COERCIBLE} types
+    METHOD_COERCIBLE.each_key do |name|
+      register(
+        "coercible.#{name}", self["nominal.#{name}"].constructor(&METHOD_COERCIBLE_METHODS[name])
+      )
+    end
+
     # Register optional strict {NON_NIL} types
     NON_NIL.each_key do |name|
       register("optional.strict.#{name}", self["strict.#{name}"].optional)
@@ -60,14 +81,14 @@ module Dry
     end
 
     # Register `:bool` since it's common and not a built-in Ruby type :(
-    register("nominal.bool", self["nominal.true"] | self["nominal.false"])
-    bool = self["strict.true"] | self["strict.false"]
-    register("strict.bool", bool)
-    register("bool", bool)
-
-    register("any", Any)
-    register("nominal.any", Any)
-    register("strict.any", Any)
+    register('nominal.bool', self['nominal.true'] | self['nominal.false'])
+    bool = self['strict.true'] | self['strict.false']
+    register('strict.bool', bool)
+    register('bool', bool)
+
+    register('any', Any)
+    register('nominal.any', Any)
+    register('strict.any', Any)
   end
 end
 

data/lib/dry/types/decorator.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 require 'dry/types/options'
 
 module Dry
   module Types
+    # Common API for types
+    #
+    # @api public
     module Decorator
       include Options
 
@@ -16,56 +21,76 @@ module Dry
 
       # @param [Object] input
       # @param [#call, nil] block
+      #
       # @return [Result,Logic::Result]
       # @return [Object] if block given and try fails
+      #
+      # @api public
       def try(input, &block)
         type.try(input, &block)
       end
 
-      # @param [Object] value
-      # @return [Boolean]
-      def valid?(value)
-        type.valid?(value)
-      end
-      alias_method :===, :valid?
-
       # @return [Boolean]
+      #
+      # @api public
       def default?
         type.default?
       end
 
       # @return [Boolean]
+      #
+      # @api public
       def constrained?
         type.constrained?
       end
 
       # @return [Sum]
+      #
+      # @api public
       def optional
         Types['strict.nil'] | self
       end
 
       # @param [Symbol] meth
       # @param [Boolean] include_private
+      #
       # @return [Boolean]
+      #
+      # @api public
       def respond_to_missing?(meth, include_private = false)
         super || type.respond_to?(meth)
       end
 
+      # Wrap the type with a proc
+      #
+      # @return [Proc]
+      #
+      # @api public
+      def to_proc
+        proc { |value| self.(value) }
+      end
+
       private
 
       # @param [Object] response
+      #
       # @return [Boolean]
+      #
+      # @api private
       def decorate?(response)
-        response.kind_of?(type.class)
+        response.is_a?(type.class)
       end
 
       # Delegates missing methods to {#type}
+      #
       # @param [Symbol] meth
       # @param [Array] args
       # @param [#call, nil] block
+      #
+      # @api private
       def method_missing(meth, *args, &block)
         if type.respond_to?(meth)
-          response = type.__send__(meth, *args, &block)
+          response = type.public_send(meth, *args, &block)
 
           if decorate?(response)
             __new__(response)
@@ -78,8 +103,10 @@ module Dry
       end
 
       # Replace underlying type
+      #
+      # @api private
       def __new__(type)
-        self.class.new(type, options)
+        self.class.new(type, *@__args__[1..-1], **@options)
       end
     end
   end

data/lib/dry/types/default.rb

@@ -1,16 +1,16 @@
+# frozen_string_literal: true
+
 require 'dry/types/decorator'
 
 module Dry
   module Types
+    # Default types are useful when a missing value should be replaced by a default one
+    #
+    # @api public
     class Default
-      include Type
-      include Decorator
-      include Builder
-      include Printable
-      include Dry::Equalizer(:type, :options, :value, inspect: false)
-
+      # @api private
       class Callable < Default
-        include Dry::Equalizer(:type, :options, inspect: false)
+        include Dry::Equalizer(:type, inspect: false)
 
         # Evaluates given callable
         # @return [Object]
@@ -19,13 +19,22 @@ module Dry
         end
       end
 
+      include Type
+      include Decorator
+      include Builder
+      include Printable
+      include Dry::Equalizer(:type, :value, inspect: false)
+
       # @return [Object]
       attr_reader :value
 
       alias_method :evaluate, :value
 
       # @param [Object, #call] value
+      #
       # @return [Class] {Default} or {Default::Callable}
+      #
+      # @api private
       def self.[](value)
         if value.respond_to?(:call)
           Callable
@@ -36,48 +45,71 @@ module Dry
 
       # @param [Type] type
       # @param [Object] value
+      #
+      # @api private
       def initialize(type, value, **options)
         super
         @value = value
       end
 
+      # Build a constrained type
+      #
       # @param [Array] args see {Dry::Types::Builder#constrained}
+      #
       # @return [Default]
+      #
+      # @api public
       def constrained(*args)
         type.constrained(*args).default(value)
       end
 
       # @return [true]
+      #
+      # @api public
       def default?
         true
       end
 
       # @param [Object] input
+      #
       # @return [Result::Success]
+      #
+      # @api public
       def try(input)
         success(call(input))
       end
 
+      # @return [Boolean]
+      #
+      # @api public
       def valid?(value = Undefined)
-        value.equal?(Undefined) || super
+        Undefined.equal?(value) || super
       end
 
       # @param [Object] input
+      #
       # @return [Object] value passed through {#type} or {#default} value
-      def call(input = Undefined)
+      #
+      # @api private
+      def call_unsafe(input = Undefined)
         if input.equal?(Undefined)
           evaluate
         else
-          Undefined.default(type[input]) { evaluate }
+          Undefined.default(type.call_unsafe(input)) { evaluate }
         end
       end
-      alias_method :[], :call
-
-      private
 
-      # Replace underlying type
-      def __new__(type)
-        self.class.new(type, value, options)
+      # @param [Object] input
+      #
+      # @return [Object] value passed through {#type} or {#default} value
+      #
+      # @api private
+      def call_safe(input = Undefined, &block)
+        if input.equal?(Undefined)
+          evaluate
+        else
+          Undefined.default(type.call_safe(input, &block)) { evaluate }
+        end
       end
     end
   end

data/lib/dry/types/enum.rb

@@ -1,11 +1,17 @@
+# frozen_string_literal: true
+
 require 'dry/types/decorator'
 
 module Dry
   module Types
+    # Enum types can be used to define an enum on top of an existing type
+    #
+    # @api public
     class Enum
       include Type
-      include Dry::Equalizer(:type, :options, :mapping, inspect: false)
+      include Dry::Equalizer(:type, :mapping, inspect: false)
       include Decorator
+      include Builder
 
       # @return [Array]
       attr_reader :values
@@ -19,6 +25,8 @@ module Dry
       # @param [Type] type
       # @param [Hash] options
       # @option options [Array] :values
+      #
+      # @api private
       def initialize(type, options)
         super
         @mapping = options.fetch(:mapping).freeze
@@ -27,22 +35,28 @@ module Dry
         freeze
       end
 
-      # @param [Object] input
       # @return [Object]
-      def call(input = Undefined)
-        type[map_value(input)]
+      #
+      # @api private
+      def call_unsafe(input)
+        type.call_unsafe(map_value(input))
+      end
+
+      # @return [Object]
+      #
+      # @api private
+      def call_safe(input, &block)
+        type.call_safe(map_value(input), &block)
       end
-      alias_method :[], :call
 
-      # @param [Object] input
-      # @yieldparam [Failure] failure
-      # @yieldreturn [Result]
-      # @return [Logic::Result]
-      # @return [Object] if coercion fails and a block is given
+      # @see Dry::Types::Constrained#try
+      #
+      # @api public
       def try(input)
         super(map_value(input))
       end
 
+      # @api private
       def default(*)
         raise '.enum(*values).default(value) is not supported. Call '\
               '.default(value).enum(*values) instead'
@@ -51,16 +65,15 @@ module Dry
       # Check whether a value is in the enum
       alias_method :include?, :valid?
 
-      # @api public
-      #
       # @see Nominal#to_ast
+      #
+      # @api public
       def to_ast(meta: true)
-        [:enum, [type.to_ast(meta: meta),
-                 mapping,
-                 meta ? self.meta : EMPTY_HASH]]
+        [:enum, [type.to_ast(meta: meta), mapping]]
       end
 
       # @return [String]
+      #
       # @api public
       def to_s
         PRINTER.(self)
@@ -71,8 +84,10 @@ module Dry
 
       # Maps a value
       #
-      # @param [Object]
+      # @param [Object] input
+      #
       # @return [Object]
+      #
       # @api private
       def map_value(input)
         if input.equal?(Undefined)

data/lib/dry/types/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
     extend Dry::Core::ClassAttributes
@@ -8,7 +10,62 @@ module Dry
 
     namespace self
 
-    class SchemaError < TypeError
+    # Base class for coercion errors raise by dry-types
+    #
+    class CoercionError < StandardError
+      # @api private
+      def self.handle(exception, meta: Undefined)
+        if block_given?
+          yield
+        else
+          raise new(
+            exception.message,
+            meta: meta,
+            backtrace: exception.backtrace
+          )
+        end
+      end
+
+      # Metadata associated with the error
+      #
+      # @return [Object]
+      attr_reader :meta
+
+      # @api private
+      def initialize(message, meta: Undefined, backtrace: Undefined)
+        unless message.is_a?(::String)
+          raise ArgumentError, "message must be a string, #{message.class} given"
+        end
+
+        super(message)
+        @meta = Undefined.default(meta, nil)
+        set_backtrace(backtrace) unless Undefined.equal?(backtrace)
+      end
+    end
+
+    # Collection of multiple errors
+    #
+    class MultipleError < CoercionError
+      # @return [Array<CoercionError>]
+      attr_reader :errors
+
+      # @param [Array<CoercionError>] errors
+      def initialize(errors)
+        @errors = errors
+      end
+
+      # @return string
+      def message
+        errors.map(&:message).join(', ')
+      end
+
+      # @return [Array]
+      def meta
+        errors.map(&:meta)
+      end
+    end
+
+    class SchemaError < CoercionError
       # @param [String,Symbol] key
       # @param [Object] value
       # @param [String, #to_s] result
@@ -17,26 +74,34 @@ module Dry
       end
     end
 
-    MapError = Class.new(TypeError)
+    MapError = Class.new(CoercionError)
 
-    SchemaKeyError = Class.new(KeyError)
+    SchemaKeyError = Class.new(CoercionError)
     private_constant(:SchemaKeyError)
 
     class MissingKeyError < SchemaKeyError
+      # @return [Symbol]
+      attr_reader :key
+
       # @param [String,Symbol] key
       def initialize(key)
-        super(":#{key} is missing in Hash input")
+        @key = key
+        super("#{key.inspect} is missing in Hash input")
       end
     end
 
     class UnknownKeysError < SchemaKeyError
+      # @return [Array<Symbol>]
+      attr_reader :keys
+
       # @param [<String, Symbol>] keys
-      def initialize(*keys)
+      def initialize(keys)
+        @keys = keys
         super("unexpected keys #{keys.inspect} in Hash input")
       end
     end
 
-    class ConstraintError < TypeError
+    class ConstraintError < CoercionError
       # @return [String, #to_s]
       attr_reader :result
       # @return [Object]
@@ -56,9 +121,10 @@ module Dry
       end
 
       # @return [String]
-      def to_s
+      def message
         "#{input.inspect} violates constraints (#{result} failed)"
       end
+      alias_method :to_s, :message
     end
   end
 end