Class: SleepingKingStudios::Tools::CoreTools

Inherits:
Base
  • Object
show all
Defined in:
lib/sleeping_king_studios/tools/core_tools.rb

Overview

Tools for working with an application or working environment.

Defined Under Namespace

Classes: DeprecationError

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

instance, #toolbelt

Constructor Details

#initialize(deprecation_caller_depth: nil, deprecation_strategy: nil, toolbelt: nil) ⇒ CoreTools

Returns a new instance of CoreTools.

Parameters:

  • deprecation_caller_depth (Integer) (defaults to: nil) —

    the number of backtrace lines to display when outputting a deprecation warning.

  • deprecation_strategy (String) (defaults to: nil) —

    the name of the strategy used when deprecated code is called. Must be ‘ignore’, ‘raise’, or ‘warn’.

  • toolbelt (SleepingKingStudios::Tools::Toolbelt) (defaults to: nil) —

    the toolbelt this tools instance belongs to.



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 30

def initialize(
  deprecation_caller_depth: nil,
  deprecation_strategy:     nil,
  toolbelt:                 nil
)
  super(toolbelt:)

  @deprecation_caller_depth =
    deprecation_caller_depth ||
    ENV.fetch('DEPRECATION_CALLER_DEPTH', '3').to_i
  @deprecation_strategy =
    deprecation_strategy&.to_s || ENV.fetch('DEPRECATION_STRATEGY', 'warn')

  validate_deprecation_strategy(@deprecation_strategy)
end

Instance Attribute Details

#deprecation_caller_depth ⇒ Integer (readonly)

Returns the number of backtrace lines to display when outputting a deprecation warning.

Returns:

  • (Integer) —

    the number of backtrace lines to display when outputting a deprecation warning.



48
49
50
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 48

def deprecation_caller_depth
  @deprecation_caller_depth
end

#deprecation_strategy ⇒ String (readonly)

Returns the current deprecation strategy.

Returns:

  • (String) —

    the current deprecation strategy.



51
52
53
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 51

def deprecation_strategy
  @deprecation_strategy
end

Class Method Details

.deprecation_strategies ⇒ Set

Returns the permitted deprecation strategies for the tool.

Returns:

  • (Set) —

    the permitted deprecation strategies for the tool.



21
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 21

def deprecation_strategies = DEPRECATION_STRATEGIES

Instance Method Details

#deprecate(name, message: nil) ⇒ Object #deprecate(*args, format:, message: nil) ⇒ Object

Prints a deprecation warning or raises an exception.

The behavior of this method depends on the configured deprecation strategy, which can be passed to the constructor or configured using the DEPRECATION_STRATEGY environment variable.

  • If the strategy is ‘warn’ (the default), the formatted message is passed to Kernel.warn, which prints the message to $stderr.

  • If the strategy is ‘raise’, raises a DeprecationError with the message.

  • If the strategy is ‘ignore’, this method does nothing.

Examples:

CoreTools.deprecate 'ObjectTools#old_method'
#=> prints to stderr:
#
#   [WARNING] ObjectTools#old_method is deprecated.
#       called from /path/to/file.rb:4: in something_or_other

With An Additional Message

CoreTools.deprecate 'ObjectTools#old_method',
  'Use #new_method instead.'
#=> prints to stderr:
#
#   [WARNING] ObjectTools#old_method is deprecated. Use #new_method instead.
#     called from /path/to/file.rb:4: in something_or_other

With A Format String

CoreTools.deprecate 'ObjectTools#old_method',
  '0.1.0',
  format: '%s was deprecated in version %s.'
#=> prints to stderr:
#
#   ObjectTools#old_method was deprecated in version 0.1.0.
#     called from /path/to/file.rb:4: in something_or_other

Overloads:

  • #deprecate(name, message: nil) ⇒ Object

    Prints a deprecation warning or raises an exception.

    Parameters:

    • name (String) —

      the name of the object, method, or feature that has been deprecated.

    • caller (Array<String>) —

      overrides the displayed call stack, if the configured deprecation strategy displays the call stack.

    • message (String) (defaults to: nil) —

      an optional message to print after the formatted string. Defaults to nil.

  • #deprecate(*args, format:, message: nil) ⇒ Object

    Prints a deprecation warning with the specified format or raises.

    Parameters:

    • args (Array) —

      the arguments to pass into the format string.

    • format (String) —

      the format string.

    • message (String) (defaults to: nil) —

      an optional message to print after the formatted string. Defaults to nil.



105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 105

def deprecate(*, caller: nil, format: nil, message: nil)
  deprecate("#{self.class.name}#deprecate with :format option") if format

  case deprecation_strategy
  when 'ignore'
    # Do nothing.
  when 'raise'
    deprecate_with_exception(*, caller:, format:, message:)
  when 'warn'
    deprecate_with_warning(*, caller:, format:, message:)
  end
end

#empty_binding ⇒ Binding

Generates an empty Binding object with an Object as the receiver.

Returns:

  • (Binding) —

    The empty binding object.

See Also:



123
124
125
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 123

def empty_binding
  Object.new.instance_exec { binding }
end

#require_each(*file_patterns) ⇒ Object

Deprecated.

v1.3.0

Expands each file pattern and requires each file.

Parameters:

  • file_patterns (Array) —

    The files to require.



132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 132

def require_each(*file_patterns)
  deprecate("#{self.class.name}#require_each")

  file_patterns.each do |file_pattern|
    if file_pattern.include?('*')
      Dir[file_pattern].each do |file_name|
        Kernel.require file_name
      end
    else
      Kernel.require file_pattern
    end
  end
end