Module: Dry::Types::Builder

Includes:
Core::Constants
Included in:
Composition, Constrained, Default, Enum, Lax, Maybe, Nominal, Schema::Key
Defined in:
lib/dry/types/builder.rb,
lib/dry/types/extensions/maybe.rb

Overview

Common API for building types and composition

Instance Method Summary collapse

Instance Method Details

#&(other) ⇒ Intersection, Intersection::Constrained

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Compose two types into an Intersection type

Parameters:

Returns:



37
 
# File 'lib/dry/types/builder.rb', line 37

def &(other) = compose(other, Intersection)

#>(other) ⇒ Implication, Implication::Constrained

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Compose two types into an Implication type

Parameters:

Returns:



46
 
# File 'lib/dry/types/builder.rb', line 46

def >(other) = compose(other, Implication)

#constrained ⇒ Constrained

Turn a type into a constrained type

Parameters:

Returns:



62
63
64
 
# File 'lib/dry/types/builder.rb', line 62

def constrained(...)
  constrained_type.new(self, rule: Types.Rule(...))
end

#constrained_type ⇒ Class

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Class) 


14
 
# File 'lib/dry/types/builder.rb', line 14

def constrained_type = Constrained

#constructor(constructor = nil, **options, &block) ⇒ Constructor Also known as: append, prepend, >>, <<

Define a constructor for the type

Parameters:

  • constructor (#call, nil) (defaults to: nil)
  • options (Hash)
  • block (#call, nil)

Returns:



138
139
140
 
# File 'lib/dry/types/builder.rb', line 138

def constructor(constructor = nil, **options, &block)
  constructor_type[with(**options), fn: constructor || block]
end

#constructor_type ⇒ Class

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Class) 


19
 
# File 'lib/dry/types/builder.rb', line 19

def constructor_type = Constructor

#default(input = Undefined, options = EMPTY_HASH, &block) ⇒ Default

Turn a type into a type with a default value

Parameters:

  • input (Object) (defaults to: Undefined)
  • block (#call, nil)
  • [Boolean] (Hash) —

    a customizable set of options

Returns:

Raises:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/dry/types/builder.rb', line 77

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) ⇒ Enum

Define an enum on top of the existing type

Parameters:

Returns:



110
111
112
113
114
115
116
117
118
119
 
# File 'lib/dry/types/builder.rb', line 110

def enum(*values)
  mapping =
    if values.length == 1 && values[0].is_a?(::Hash)
      values[0]
    else
      values.zip(values).to_h
    end

  Enum.new(constrained(included_in: mapping.keys), mapping: mapping)
end

#fallback(value = Undefined, shared: false, &_fallback) ⇒ Constructor

Use the given value on type mismatch

Parameters:

  • value (Object) (defaults to: Undefined)
  • fallback (#call, nil)
  • [Boolean] (Hash) —

    a customizable set of options

Returns:



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/dry/types/builder.rb', line 155

def fallback(value = Undefined, shared: false, &_fallback) # rubocop:disable Metrics/PerceivedComplexity
  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, &|
    type.(input) do |output = input|
      if block_given?
        yield(output)
      else
        value
      end
    end
  end
end

#lax ⇒ Lax

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

Returns:



127
 
# File 'lib/dry/types/builder.rb', line 127

def lax = Lax.new(self)

#maybe ⇒ Maybe

Turn a type into a maybe type

Returns:



97
 
# File 'lib/dry/types/extensions/maybe.rb', line 97

def maybe = Maybe.new(Types["nil"] | self)

#optional ⇒ Sum

Turn a type into an optional type

Returns:



53
 
# File 'lib/dry/types/builder.rb', line 53

def optional = Types["nil"] | self

#|(other) ⇒ Sum, Sum::Constrained

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Compose two types into a Sum type

Parameters:

Returns:



28
 
# File 'lib/dry/types/builder.rb', line 28

def |(other) = compose(other, Sum)