Module: Toys::Warnings

Defined in:
lib/toys/warnings.rb

Overview

A warning reporter that supports throttling of repeated messages and environment variable based silencing. Used in particular to display deprecation warnings.

Constant Summary collapse

DEFAULT_MAX_COUNT =

Returns The default value for max_count.

Returns:

  • (Integer) —

    The default value for max_count.

5
SUPPRESS_WARNINGS_ENV =

Returns The name of an environment variable that, when set to a non-empty value, suppresses warnings emitted by this module.

Returns:

  • (String) —

    The name of an environment variable that, when set to a non-empty value, suppresses warnings emitted by this module.

"TOYS_SUPPRESS_WARNINGS"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.max_count ⇒ Integer?

The maximum number of times a warning with the same identity will be displayed before further instances are suppressed, or nil to keep displaying each warning regardless of how many times it has repeated. Defaults to DEFAULT_MAX_COUNT. Can be set using max_count=.

Returns:

  • (Integer, nil) 


40
41
42
 
# File 'lib/toys/warnings.rb', line 40

def max_count
  @max_count
end

Class Method Details

.warn(identifier, message, uplevel: nil, max_count: :default) ⇒ Integer

Displays a warning message.

You must pass an identifier object and a message string. The identifier should identify "which" warning is being displayed, and is used to count repeated warnings so they can be throttled after a certain number of instances.

Uses the Ruby Kernel#warn method, so it is affected by $VERBOSE and the -W0 flag. Does not currently support the category: argument to Kernel#warn because it is not supported in Ruby 2.7, and in newer Rubies, common values such as category: :deprecated default to silent, whereas this method should not be silent unless explicitly requested.

Parameters:

  • identifier (Object) —

    An object that identifies the warning for counting purposes. Generally this should be a fixed small set of objects, preferably symbols, as each identifier seen is used as a hash key and never deleted.

  • message (String) —

    The warning message

  • uplevel (Integer, nil) (defaults to: nil) —

    If given and set to a nonnegative Integer, the warning will be prepended with the caller frame, that many stack levels above the call site. If not given or set to nil, the caller is not included in the report.

  • max_count (Integer, nil, :default) (defaults to: :default) —

    The maximum number of times a warning with the same identity will be displayed before further instances are suppressed. Must be a nonnegative integer, or nil to keep displaying each warning regardless of how many times it has repeated. The value 0 suppresses warnings of this identifier unconditionally. The special value :default (which is used if the argument is not provided) falls back to max_count.

Returns:

  • (Integer) —

    The number of times this warning's identifier has happened, regardless of whether it was actually displayed.



89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/toys/warnings.rb', line 89

def warn(identifier, message, uplevel: nil, max_count: :default)
  if max_count == :default
    max_count = @max_count
  else
    validate_max_count(max_count)
  end
  uplevel = validate_and_bump_uplevel(uplevel)
  count = next_count(identifier)
  message = annotate_message(message, count, max_count)
  if message && ::ENV[SUPPRESS_WARNINGS_ENV].to_s.empty?
    ::Kernel.warn(message, uplevel: uplevel)
  end
  count
end