Module: T::Configuration

Defined in:
lib/types/configuration.rb

Overview

typed: true frozen_string_literal: true

Class Method Summary collapse

Class Method Details

.call_validation_error_handler(signature, opts = {}) ⇒ Object 



222
223
224
225
226
227
228
229
 
# File 'lib/types/configuration.rb', line 222

def self.call_validation_error_handler(signature, opts={})
  if @call_validation_error_handler
    @call_validation_error_handler.call(signature, opts)
  else
    call_validation_error_handler_default(signature, opts)
  end
  nil
end

.call_validation_error_handler=(value) ⇒ Object

Set a handler for type errors that result from calling a method.

By default, errors from calling a method cause an exception to be raised. Setting call_validation_error_handler to an object that implements :call (e.g. proc or lambda) allows users to customize the behavior when a method is called with invalid parameters, or returns an invalid value.

Parameters passed to value.call:

Examples:

T::Configuration.call_validation_error_handler = lambda do |signature, opts|
  puts opts[:message]
end

Parameters:

  • value (Lambda, Proc, Object, nil) —

    Proc that handles the error report (pass nil to reset to default behavior)

  • signature (T::Private::Methods::Signature) —

    Signature that failed

  • opts (Hash) —

    A hash containing contextual information on the error:



213
214
215
216
 
# File 'lib/types/configuration.rb', line 213

def self.call_validation_error_handler=(value)
  validate_lambda_given!(value)
  @call_validation_error_handler = value
end

.default_checked_level=(default_checked_level) ⇒ Object

Configure the default checked level for a sig with no explicit ‘.checked` builder. When unset, the default checked level is `:always`.

Note: setting this option is potentially dangerous! Sorbet can’t check all code statically. The runtime checks complement the checks that Sorbet does statically, so that methods don’t have to guard themselves from being called incorrectly by untyped code.

Parameters:

  • default_checked_level (:never, :tests, :always) 


54
55
56
 
# File 'lib/types/configuration.rb', line 54

def self.default_checked_level=(default_checked_level)
  T::Private::RuntimeLevels.default_checked_level = default_checked_level
end

.enable_checking_for_sigs_marked_checked_tests ⇒ Object

Announces to Sorbet that we are currently in a test environment, so it should treat any sigs which are marked ‘.checked(:tests)` as if they were just a normal sig.

If this method is not called, sigs marked ‘.checked(:tests)` will not be checked. In fact, such methods won’t even be wrapped–the runtime will put back the original method.

Note: Due to the way sigs are evaluated and methods are wrapped, this method MUST be called before any code calls ‘sig`. This method raises if it has been called too late.



16
17
18
 
# File 'lib/types/configuration.rb', line 16

def self.enable_checking_for_sigs_marked_checked_tests
  T::Private::RuntimeLevels.enable_checking_in_tests
end

.enable_final_checks_on_hooks ⇒ Object

Announce to Sorbet that we would like the final checks to be enabled when including and extending modules. Iff this is not called, then the following example will not raise an error.

“‘ruby module M

extend T::Sig
sig(:final) {void}
def foo; end

end class C

include M
def foo; end

end “‘



35
36
37
 
# File 'lib/types/configuration.rb', line 35

def self.enable_final_checks_on_hooks
  T::Private::Methods.set_final_checks_on_hooks(true)
end

.hard_assert_handler(str, extra = {}) ⇒ Object 



322
323
324
325
326
327
328
 
# File 'lib/types/configuration.rb', line 322

def self.hard_assert_handler(str, extra={})
  if @hard_assert_handler
    @hard_assert_handler.call(str, extra)
  else
    hard_assert_handler_default(str, extra)
  end
end

.hard_assert_handler=(value) ⇒ Object

Set a handler for hard assertions

These generally should stop execution of the program, and optionally inform some party of the assertion.

Parameters passed to value.call:

Examples:

T::Configuration.hard_assert_handler = lambda do |str, extra|
  raise "#{str}, context: #{extra}"
end

Parameters:

  • value (Lambda, Proc, Object, nil) —

    Proc that handles the error report (pass nil to reset to default behavior)

  • str (String) —

    Assertion message

  • extra (Hash) —

    A hash containing additional parameters to be passed along to the handler.



313
314
315
316
 
# File 'lib/types/configuration.rb', line 313

def self.hard_assert_handler=(value)
  validate_lambda_given!(value)
  @hard_assert_handler = value
end

.inline_type_error_handler(error) ⇒ Object 



86
87
88
89
90
91
92
93
 
# File 'lib/types/configuration.rb', line 86

def self.inline_type_error_handler(error)
  if @inline_type_error_handler
    @inline_type_error_handler.call(error)
  else
    inline_type_error_handler_default(error)
  end
  nil
end

.inline_type_error_handler=(value) ⇒ Object

Set a handler to handle ‘TypeError`s raised by any in-line type assertions, including `T.must`, `T.let`, `T.cast`, and `T.assert_type!`.

By default, any ‘TypeError`s detected by this gem will be raised. Setting inline_type_error_handler to an object that implements :call (e.g. proc or lambda) allows users to customize the behavior when a `TypeError` is raised on any inline type assertion.

Parameters passed to value.call:

Examples:

T::Configuration.inline_type_error_handler = lambda do |error|
  puts error.message
end

Parameters:

  • value (Lambda, Proc, Object, nil) —

    Proc that handles the error (pass nil to reset to default behavior)

  • error (TypeError) —

    TypeError that was raised



77
78
79
80
 
# File 'lib/types/configuration.rb', line 77

def self.inline_type_error_handler=(value)
  validate_lambda_given!(value)
  @inline_type_error_handler = value
end

.log_info_handler(str, extra) ⇒ Object 



254
255
256
257
258
259
260
 
# File 'lib/types/configuration.rb', line 254

def self.log_info_handler(str, extra)
  if @log_info_handler
    @log_info_handler.call(str, extra)
  else
    log_info_handler_default(str, extra)
  end
end

.log_info_handler=(value) ⇒ Object

Set a handler for logging

Parameters passed to value.call:

Examples:

T::Configuration.log_info_handler = lambda do |str, extra|
  puts "#{str}, context: #{extra}"
end

Parameters:

  • value (Lambda, Proc, Object, nil) —

    Proc that handles the error report (pass nil to reset to default behavior)

  • str (String) —

    Message to be logged

  • extra (Hash) —

    A hash containing additional parameters to be passed along to the logger.



245
246
247
248
 
# File 'lib/types/configuration.rb', line 245

def self.log_info_handler=(value)
  validate_lambda_given!(value)
  @log_info_handler = value
end

.reset_final_checks_on_hooks ⇒ Object

Undo the effects of a previous call to ‘enable_final_checks_on_hooks`.



41
42
43
 
# File 'lib/types/configuration.rb', line 41

def self.reset_final_checks_on_hooks
  T::Private::Methods.set_final_checks_on_hooks(false)
end

.scalar_types ⇒ Object 



361
362
363
 
# File 'lib/types/configuration.rb', line 361

def self.scalar_types
  @scalar_types || @default_scalar_types
end

.scalar_types=(values) ⇒ Object

Set a list of class strings that are to be considered scalar.

(pass nil to reset to default behavior)

Examples:

T::Configuration.scalar_types = ["NilClass", "TrueClass", "FalseClass", ...]

Parameters:

  • value (String) —

    Class name.



337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/types/configuration.rb', line 337

def self.scalar_types=(values)
  if values.nil?
    @scalar_tyeps = values
  else
    bad_values = values.select {|v| v.class != String}
    unless bad_values.empty?
      raise ArgumentError.new("Provided values must all be class name strings.")
    end

    @scalar_types = Set.new(values).freeze
  end
end

.sig_builder_error_handler(error, location) ⇒ Object 



126
127
128
129
130
131
132
133
 
# File 'lib/types/configuration.rb', line 126

def self.sig_builder_error_handler(error, location)
  if @sig_builder_error_handler
    @sig_builder_error_handler.call(error, location)
  else
    sig_builder_error_handler_default(error, location)
  end
  nil
end

.sig_builder_error_handler=(value) ⇒ Object

Set a handler to handle errors that occur when the builder methods in the body of a sig are executed. The sig builder methods are inside a proc so that they can be lazily evaluated the first time the method being sig’d is called.

By default, improper use of the builder methods within the body of a sig cause an ArgumentError to be raised. Setting sig_builder_error_handler to an object that implements :call (e.g. proc or lambda) allows users to customize the behavior when a sig can’t be built for some reason.

Parameters passed to value.call:

Examples:

T::Configuration.sig_builder_error_handler = lambda do |error, location|
  puts error.message
end

Parameters:

  • value (Lambda, Proc, Object, nil) —

    Proc that handles the error (pass nil to reset to default behavior)

  • error (StandardError) —

    The error that was raised

  • location (Thread::Backtrace::Location) —

    Location of the error



117
118
119
120
 
# File 'lib/types/configuration.rb', line 117

def self.sig_builder_error_handler=(value)
  validate_lambda_given!(value)
  @sig_builder_error_handler = value
end

.sig_validation_error_handler(error, opts = {}) ⇒ Object 



176
177
178
179
180
181
182
183
 
# File 'lib/types/configuration.rb', line 176

def self.sig_validation_error_handler(error, opts={})
  if @sig_validation_error_handler
    @sig_validation_error_handler.call(error, opts)
  else
    sig_validation_error_handler_default(error, opts)
  end
  nil
end

.sig_validation_error_handler=(value) ⇒ Object

Set a handler to handle sig validation errors.

Sig validation errors include things like abstract checks, override checks, and type compatibility of arguments. They happen after a sig has been successfully built, but the built sig is incompatible with other sigs in some way.

By default, sig validation errors cause an exception to be raised. Setting sig_validation_error_handler to an object that implements :call (e.g. proc or lambda) allows users to customize the behavior when a method signature’s build fails.

Parameters passed to value.call:

Examples:

T::Configuration.sig_validation_error_handler = lambda do |error, opts|
  puts error.message
end

Parameters:

  • value (Lambda, Proc, Object, nil) —

    Proc that handles the error (pass nil to reset to default behavior)

  • error (StandardError) —

    The error that was raised

  • opts (Hash) —

    A hash containing contextual information on the error:



167
168
169
170
 
# File 'lib/types/configuration.rb', line 167

def self.sig_validation_error_handler=(value)
  validate_lambda_given!(value)
  @sig_validation_error_handler = value
end

.soft_assert_handler(str, extra) ⇒ Object 



288
289
290
291
292
293
294
 
# File 'lib/types/configuration.rb', line 288

def self.soft_assert_handler(str, extra)
  if @soft_assert_handler
    @soft_assert_handler.call(str, extra)
  else
    soft_assert_handler_default(str, extra)
  end
end

.soft_assert_handler=(value) ⇒ Object

Set a handler for soft assertions

These generally shouldn’t stop execution of the program, but rather inform some party of the assertion to action on later.

Parameters passed to value.call:

Examples:

T::Configuration.soft_assert_handler = lambda do |str, extra|
  puts "#{str}, context: #{extra}"
end

Parameters:

  • value (Lambda, Proc, Object, nil) —

    Proc that handles the error report (pass nil to reset to default behavior)

  • str (String) —

    Assertion message

  • extra (Hash) —

    A hash containing additional parameters to be passed along to the handler.



279
280
281
282
 
# File 'lib/types/configuration.rb', line 279

def self.soft_assert_handler=(value)
  validate_lambda_given!(value)
  @soft_assert_handler = value
end

.without_ruby_warnings { ... } ⇒ Object

Temporarily disable ruby warnings while executing the given block. This is useful when doing something that would normally cause a warning to be emitted in Ruby verbose mode ($VERBOSE = true).

Yields:



371
372
373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/types/configuration.rb', line 371

def self.without_ruby_warnings
  if $VERBOSE
    begin
      original_verbose = $VERBOSE
      $VERBOSE = false
      yield
    ensure
      $VERBOSE = original_verbose
    end
  else
    yield
  end
end