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

rubocop:disable Metrics/ModuleLength

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:



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

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

#>(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:



55
56
57
 
# File 'lib/dry/types/builder.rb', line 55

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

#constrained ⇒ Constrained

Turn a type into a constrained type

Parameters:

Returns:



75
76
77
 
# File 'lib/dry/types/builder.rb', line 75

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) 


15
16
17
 
# File 'lib/dry/types/builder.rb', line 15

def constrained_type
  Constrained
end

#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:



153
154
155
 
# File 'lib/dry/types/builder.rb', line 153

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) 


22
23
24
 
# File 'lib/dry/types/builder.rb', line 22

def constructor_type
  Constructor
end

#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:



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/dry/types/builder.rb', line 90

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:



123
124
125
126
127
128
129
130
131
132
 
# File 'lib/dry/types/builder.rb', line 123

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:



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/dry/types/builder.rb', line 170

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, &_block|
    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:



140
141
142
 
# File 'lib/dry/types/builder.rb', line 140

def lax
  Lax.new(self)
end

#maybe ⇒ Maybe

Turn a type into a maybe type

Returns:



99
100
101
 
# File 'lib/dry/types/extensions/maybe.rb', line 99

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

#optional ⇒ Sum

Turn a type into an optional type

Returns:



64
65
66
 
# File 'lib/dry/types/builder.rb', line 64

def optional
  Types["nil"] | self
end

#|(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:



33
34
35
 
# File 'lib/dry/types/builder.rb', line 33

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