Module: T::Configuration

Defined in:
lib/types/configuration.rb

Overview

typed: true frozen_string_literal: true

Constant Summary collapse

AT_LEAST_RUBY_2_7 =

Cache this comparisonn to avoid two allocations all over the place.

Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.7')

Class Method Summary collapse

Class Method Details

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



299
300
301
302
303
304
305
306
 
# File 'lib/types/configuration.rb', line 299

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:

@param [T::Private::Methods::Signature] signature Signature that failed
@param [Hash] opts A hash containing contextual information on the error:
@option opts [String] :message Error message
@option opts [String] :kind One of:
  ['Parameter', 'Block parameter', 'Return value']
@option opts [Symbol] :name Param or block param name (nil for return
  value)
@option opts [Object] :type Expected param/return value type
@option opts [Object] :value Actual param/return value
@option opts [Thread::Backtrace::Location] :location Location of the
  caller

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)



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

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

.can_enable_vm_prop_serde? ⇒ T::Boolean

Whether VM-defined prop serialization/deserialization routines can be enabled.

Returns:



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

def self.can_enable_vm_prop_serde?
  T::Props::Private::DeserializerGenerator.respond_to?(:generate2)
end

.class_owner_finder ⇒ Object 



513
514
515
 
# File 'lib/types/configuration.rb', line 513

def self.class_owner_finder
  @class_owner_finder
end

.class_owner_finder=(handler) ⇒ Object

Set to a function which can get the ‘owner’ of a class. This is used in reporting deserialization errors

produces its owner, or ‘nil` if it does not have one.

Parameters:

  • handler (Lambda, Proc, nil) —

    Proc that takes a class and



509
510
511
 
# File 'lib/types/configuration.rb', line 509

def self.class_owner_finder=(handler)
  @class_owner_finder = handler
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, :compiled, :tests, :always) 


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

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

.disable_legacy_t_enum_migration_mode ⇒ Object 



541
542
543
 
# File 'lib/types/configuration.rb', line 541

def self.disable_legacy_t_enum_migration_mode
  @legacy_t_enum_migration_mode = false
end

.disable_vm_prop_serde ⇒ Object

Disable using VM-defined prop serialization/deserialization routines.



104
105
106
 
# File 'lib/types/configuration.rb', line 104

def self.disable_vm_prop_serde
  @use_vm_prop_serde = false
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.



19
20
21
 
# File 'lib/types/configuration.rb', line 19

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 “‘



38
39
40
 
# File 'lib/types/configuration.rb', line 38

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

.enable_legacy_t_enum_migration_mode ⇒ Object 



538
539
540
 
# File 'lib/types/configuration.rb', line 538

def self.enable_legacy_t_enum_migration_mode
  @legacy_t_enum_migration_mode = true
end

.enable_vm_prop_serde ⇒ Object

Enable using VM-defined prop serialization/deserialization routines.

This method is likely to break things outside of Stripe’s systems.



96
97
98
99
100
101
 
# File 'lib/types/configuration.rb', line 96

def self.enable_vm_prop_serde
  if !can_enable_vm_prop_serde?
    hard_assert_handler('Ruby VM is not setup to use VM-defined prop serde')
  end
  @use_vm_prop_serde = true
end

.exclude_value_in_type_errors ⇒ Object

Configure if type errors excludes the value of the problematic type.

The default is to include values in type errors:

TypeError: Expected type Integer, got String with value "foo"

When values are excluded from type errors:

TypeError: Expected type Integer, got String



66
67
68
 
# File 'lib/types/configuration.rb', line 66

def self.exclude_value_in_type_errors
  @include_value_in_type_errors = false
end

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



402
403
404
405
406
407
408
 
# File 'lib/types/configuration.rb', line 402

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:

@param [String] str Assertion message
@param [Hash] extra A hash containing additional parameters to be passed along to the handler.

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)



393
394
395
396
 
# File 'lib/types/configuration.rb', line 393

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

.include_value_in_type_errors ⇒ Object

Opposite of exclude_value_in_type_errors. (Including values in type errors is the default)



72
73
74
 
# File 'lib/types/configuration.rb', line 72

def self.include_value_in_type_errors
  @include_value_in_type_errors = true
end

.include_value_in_type_errors? ⇒ T::Boolean

Whether to include values in TypeError messages.

Including values is useful for debugging, but can potentially leak sensitive information to logs.

Returns:



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

def self.include_value_in_type_errors?
  @include_value_in_type_errors
end

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



155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/types/configuration.rb', line 155

def self.inline_type_error_handler(error, opts={})
  if @inline_type_error_handler
    # Backwards compatibility before `inline_type_error_handler` took a second arg
    if @inline_type_error_handler.arity == 1
      @inline_type_error_handler.call(error)
    else
      @inline_type_error_handler.call(error, opts)
    end
  else
    inline_type_error_handler_default(error, opts)
  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:

@param [TypeError] error TypeError that was raised
@param [Hash] opts A hash containing contextual information on the error:
@option opts [String] :kind One of:
  ['T.cast', 'T.let', 'T.bind', 'T.assert_type!', 'T.must', 'T.absurd']
@option opts [Object, nil] :type Expected param/return value type
@option opts [Object] :value Actual param/return value

Examples:

T::Configuration.inline_type_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)



146
147
148
149
 
# File 'lib/types/configuration.rb', line 146

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

.legacy_t_enum_migration_mode? ⇒ Boolean

Returns:



544
545
546
 
# File 'lib/types/configuration.rb', line 544

def self.legacy_t_enum_migration_mode?
  @legacy_t_enum_migration_mode || false
end

.log_info_handler(str, extra) ⇒ Object 



332
333
334
335
336
337
338
 
# File 'lib/types/configuration.rb', line 332

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:

@param [String] str Message to be logged
@param [Hash] extra A hash containing additional parameters to be passed along to the logger.

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)



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

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

.module_name_mangler ⇒ Object 



459
460
461
 
# File 'lib/types/configuration.rb', line 459

def self.module_name_mangler
  @module_name_mangler || @default_module_name_mangler
end

.module_name_mangler=(handler) ⇒ Object

Set to override the default behavior for converting types

to names in generated code. Used by the runtime implementation
associated with `--stripe-packages` mode.

Parameters:

  • handler (Lambda, Proc, nil) —

    Proc that converts a type (Class/Module) to a String (pass nil to reset to default behavior)



469
470
471
 
# File 'lib/types/configuration.rb', line 469

def self.module_name_mangler=(handler)
  @module_name_mangler = handler
end

.normalize_sensitivity_and_pii_handler ⇒ Object 



483
484
485
 
# File 'lib/types/configuration.rb', line 483

def self.normalize_sensitivity_and_pii_handler
  @sensitivity_and_pii_handler
end

.normalize_sensitivity_and_pii_handler=(handler) ⇒ Object

Set to a PII handler function. This will be called with the ‘sensitivity:` annotations on things that use `T::Props` and can modify them ahead-of-time.

prop values. Pass nil to avoid changing ‘sensitivity:` annotations.

Parameters:

  • handler (Lambda, Proc, nil) —

    Proc that takes a hash mapping symbols to the



479
480
481
 
# File 'lib/types/configuration.rb', line 479

def self.normalize_sensitivity_and_pii_handler=(handler)
  @sensitivity_and_pii_handler = handler
end

.prop_freeze_handler ⇒ Object 



554
555
556
 
# File 'lib/types/configuration.rb', line 554

def self.prop_freeze_handler
  @prop_freeze_handler
end

.prop_freeze_handler=(handler) ⇒ Object 



550
551
552
 
# File 'lib/types/configuration.rb', line 550

def self.prop_freeze_handler=(handler)
  @prop_freeze_handler = handler
end

.redaction_handler ⇒ Object 



499
500
501
 
# File 'lib/types/configuration.rb', line 499

def self.redaction_handler
  @redaction_handler
end

.redaction_handler=(handler) ⇒ Object

Set to a redaction handling function. This will be called when the ‘_redacted` version of a prop reader is used. By default this is set to `nil` and will raise an exception when the redacted version of a prop is accessed.

redacted version according to the spec passed as the second argument.

Parameters:

  • handler (Lambda, Proc, nil) —

    Proc that converts a value into its



495
496
497
 
# File 'lib/types/configuration.rb', line 495

def self.redaction_handler=(handler)
  @redaction_handler = handler
end

.reset_final_checks_on_hooks ⇒ Object

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



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

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

.scalar_types ⇒ Object 



443
444
445
 
# File 'lib/types/configuration.rb', line 443

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:

  • values (String) —

    Class name.



418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/types/configuration.rb', line 418

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

    @scalar_types = values.each_with_object({}) {|x, acc| acc[x] = true}.freeze
  end
end

.sealed_violation_whitelist ⇒ Object 



582
583
584
 
# File 'lib/types/configuration.rb', line 582

def self.sealed_violation_whitelist
  @sealed_violation_whitelist
end

.sealed_violation_whitelist=(sealed_violation_whitelist) ⇒ Object

Parameters:

  • sealed_violation_whitelist (Array) —

    An array of Regexp to validate whether inheriting /including a sealed module outside the defining module should be allowed. Useful to whitelist benign violations, like shim files generated for an autoloader.



563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
 
# File 'lib/types/configuration.rb', line 563

def self.sealed_violation_whitelist=(sealed_violation_whitelist)
  if !@sealed_violation_whitelist.nil?
    raise ArgumentError.new("Cannot overwrite sealed_violation_whitelist after setting it")
  end

  case sealed_violation_whitelist
  when Array
    sealed_violation_whitelist.each do |x|
      case x
      when Regexp then nil
      else raise TypeError.new("sealed_violation_whitelist accepts an Array of Regexp")
      end
    end
  else
    raise TypeError.new("sealed_violation_whitelist= accepts an Array of Regexp")
  end

  @sealed_violation_whitelist = sealed_violation_whitelist
end

.sig_builder_error_handler(error, location) ⇒ Object 



201
202
203
204
205
206
207
208
 
# File 'lib/types/configuration.rb', line 201

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:

@param [StandardError] error The error that was raised
@param [Thread::Backtrace::Location] location Location of the error

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)



192
193
194
195
 
# File 'lib/types/configuration.rb', line 192

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

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



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

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:

@param [StandardError] error The error that was raised
@param [Hash] opts A hash containing contextual information on the error:
@option opts [Method, UnboundMethod] :method Method on which the signature build failed
@option opts [T::Private::Methods::Declaration] :declaration Method
  signature declaration struct
@option opts [T::Private::Methods::Signature, nil] :signature Signature
  that failed (nil if sig build failed before Signature initialization)
@option opts [T::Private::Methods::Signature, nil] :super_signature Super
  method's signature (nil if method is not an override or super method
  does not have a method signature)

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)



243
244
245
246
 
# File 'lib/types/configuration.rb', line 243

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

.soft_assert_handler(str, extra) ⇒ Object 



367
368
369
370
371
372
373
 
# File 'lib/types/configuration.rb', line 367

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:

@param [String] str Assertion message
@param [Hash] extra A hash containing additional parameters to be passed along to the handler.

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)



358
359
360
361
 
# File 'lib/types/configuration.rb', line 358

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

.use_vm_prop_serde? ⇒ T::Boolean

Whether to use VM-defined prop serialization/deserialization routines.

The default is to use runtime codegen inside sorbet-runtime itself.

Returns:



89
90
91
 
# File 'lib/types/configuration.rb', line 89

def self.use_vm_prop_serde?
  @use_vm_prop_serde || false
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:



523
524
525
526
527
528
529
530
531
532
533
534
535
 
# File 'lib/types/configuration.rb', line 523

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