module Dry::Types::Builder

Common API for building types and composition

@api public

Public Instance Methods

<<(constructor = nil, **options, &block)
Alias for: constructor
>>(constructor = nil, **options, &block)
Alias for: constructor
append(constructor = nil, **options, &block)
Alias for: constructor
constrained(options) click to toggle source

Turn a type into a constrained type

@param [Hash] options constraining rule (see {Types.Rule})

@return [Constrained]

@api public

# File lib/dry/types/builder.rb, line 55
def constrained(options)
  constrained_type.new(self, rule: Types.Rule(options))
end
constrained_type() click to toggle source

@return [Class]

@api private

# File lib/dry/types/builder.rb, line 16
def constrained_type
  Constrained
end
constructor(constructor = nil, **options, &block) click to toggle source

Define a constructor for the type

@param [#call,nil] constructor @param [Hash] options @param [#call,nil] block

@return [Constructor]

@api public

# File lib/dry/types/builder.rb, line 133
def constructor(constructor = nil, **options, &block)
  constructor_type[with(**options), fn: constructor || block]
end
Also aliased as: append, prepend, >>, <<
constructor_type() click to toggle source

@return [Class]

@api private

# File lib/dry/types/builder.rb, line 23
def constructor_type
  Constructor
end
default(input = Undefined, options = EMPTY_HASH, &block) click to toggle source

Turn a type into a type with a default value

@param [Object] input @option [Boolean] shared Whether it's safe to share the value across type applications @param [#call,nil] block

@raise [ConstraintError]

@return [Default]

@api public

# File lib/dry/types/builder.rb, line 70
def default(input = Undefined, options = EMPTY_HASH, &block)
  unless input.frozen? || options[:shared]
    where = Core::Deprecations::STACK.()
    Core::Deprecations.warn(
      "#{input.inspect} is mutable."\
      " Be careful: types will return the same instance of the default"\
      " value every time. Call `.freeze` when setting the default"\
      " or pass `shared: true` to discard this warning."\
      "\n#{where}",
      tag: :'dry-types'
    )
  end

  value = Undefined.default(input, block)
  type = Default[value].new(self, value)

  if !type.callable? && !valid?(value)
    raise ConstraintError.new(
      "default value #{value.inspect} violates constraints",
      value
    )
  else
    type
  end
end
enum(*values) click to toggle source

Define an enum on top of the existing type

@param [Array] values

@return [Enum]

@api public

# File lib/dry/types/builder.rb, line 103
def enum(*values)
  mapping =
    if values.length == 1 && values[0].is_a?(::Hash)
      values[0]
    else
      ::Hash[values.zip(values)]
    end

  Enum.new(constrained(included_in: mapping.keys), mapping: mapping)
end
fallback(value = Undefined, shared: false) { |output| ... } click to toggle source

Use the given value on type mismatch

@param [Object] value @option [Boolean] shared Whether it's safe to share the value across type applications @param [#call,nil] fallback

@return [Constructor]

@api public

# File lib/dry/types/builder.rb, line 150
def fallback(value = Undefined, shared: false, &_fallback)
  if Undefined.equal?(value) && !block_given?
    raise ::ArgumentError, "fallback value or a block must be given"
  end

  if !block_given? && !valid?(value)
    raise ConstraintError.new(
      "fallback value #{value.inspect} violates constraints",
      value
    )
  end

  unless value.frozen? || shared
    where = Core::Deprecations::STACK.()
    Core::Deprecations.warn(
      "#{value.inspect} is mutable."\
      " Be careful: types will return the same instance of the fallback"\
      " value every time. Call `.freeze` when setting the fallback"\
      " or pass `shared: true` to discard this warning."\
      "\n#{where}",
      tag: :'dry-types'
    )
  end

  constructor do |input, type, &_block|
    type.(input) do |output = input|
      if block_given?
        yield(output)
      else
        value
      end
    end
  end
end
lax() click to toggle source

Turn a type into a lax type that will rescue from type-errors and return the original input

@return [Lax]

@api public

# File lib/dry/types/builder.rb, line 120
def lax
  Lax.new(self)
end
maybe() click to toggle source

Turn a type into a maybe type

@return [Maybe]

@api public

# File lib/dry/types/extensions/maybe.rb, line 96
def maybe
  Maybe.new(Types["nil"] | self)
end
optional() click to toggle source

Turn a type into an optional type

@return [Sum]

@api public

# File lib/dry/types/builder.rb, line 44
def optional
  Types["nil"] | self
end
prepend(constructor = nil, **options, &block)
Alias for: constructor
|(other) click to toggle source

Compose two types into a Sum type

@param [Type] other

@return [Sum, Sum::Constrained]

@api private

# File lib/dry/types/builder.rb, line 34
def |(other)
  klass = constrained? && other.constrained? ? Sum::Constrained : Sum
  klass.new(self, other)
end