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

Instance Method Summary collapse

Methods inherited from Base

instance

Constructor Details

#initialize(deprecation_caller_depth: nil, deprecation_strategy: 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’.



22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 22

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

  @deprecation_caller_depth =
    deprecation_caller_depth ||
    ENV.fetch('DEPRECATION_CALLER_DEPTH', '3').to_i
  @deprecation_strategy =
    deprecation_strategy || ENV.fetch('DEPRECATION_STRATEGY', 'warn')
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.



37
38
39
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 37

def deprecation_caller_depth
  @deprecation_caller_depth
end

#deprecation_strategy ⇒ String (readonly)

Returns the current deprecation strategy.

Returns:

  • (String) —

    the current deprecation strategy.



40
41
42
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 40

def deprecation_strategy
  @deprecation_strategy
end

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.

    • 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) (defaults to: ) —

      the format string.

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

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



92
93
94
95
96
97
98
99
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 92

def deprecate(*args, format: nil, message: nil)
  send(
    :"deprecate_as_#{deprecation_strategy}",
    *args,
    format:,
    message:
  )
end

#empty_binding ⇒ Binding

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

Returns:

  • (Binding) —

    The empty binding object.



104
105
106
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 104

def empty_binding
  Object.new.instance_exec { binding }
end

#require_each(*file_patterns) ⇒ Object

Expands each file pattern and requires each file.

Parameters:

  • file_patterns (Array) —

    The files to require.



111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/sleeping_king_studios/tools/core_tools.rb', line 111

def require_each(*file_patterns)
  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