Module: StructuredWarnings::Warning

Defined in:
lib/structured_warnings/warning.rb

Overview

This module encapsulates the extensions to Warning, that are introduced by this library.

Instance Method Summary collapse

Instance Method Details

#warn(*args, **options) ⇒ Object

:call-seq:

warn(message = nil)
warn(warning_class, message)
warn(warning_instance)

This method provides a raise-like interface. It extends the default warn in ::Warning to allow the use of structured warnings.

Internally it uses the StructuredWarnings::warner to format a message based on the given warning class, the message and a stack frame. The return value is passed to super, which is likely the implementation in ::Warning. That way, it is less likely, that structured_warnings interferes with other extensions.

If the warner returns nil or an empty string the underlying warn will not be called. That way, warnings may be transferred to other devices without the need to redefine ::Warning#warn.

Just like the original version, this method does not take command line switches or verbosity levels into account. In order to deactivate all warnings use StructuredWarnings::Base.disable.

warn "This is an old-style warning" # This will emit a StructuredWarnings::StandardWarning

class Foo
  def bar
    warn StructuredWarnings::DeprecationWarning, "Never use bar again, use beer"
  end
  def beer
    "Ahhh"
  end
end

warn StructuredWarnings::Base.new("The least specific warning you can get")



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/structured_warnings/warning.rb', line 39

def warn(*args, **options)
  first = args.shift
  if first.is_a? Class and first <= StructuredWarnings::Base
    warning = first
    message = args.shift

  elsif first.is_a? StructuredWarnings::Base
    warning = first.class
    message = first.message

  elsif caller.shift.include? 'lib/structured_warnings/kernel.rb'
    warning = StructuredWarnings::StandardWarning
    message = first.to_s

  else
    warning = StructuredWarnings::BuiltInWarning
    message = first.to_s.split(':', 4).last.strip
  end

  # If args is not empty, user passed an incompatible set of arguments.
  # Maybe somebody else is overriding warn as well and knows, what to do.
  # Better do nothing in this case. See #5
  return super unless args.empty?

  if warning.active?
    output = StructuredWarnings.warner.format(warning, message, options, caller(1))
    super(output) unless output.nil? or output.to_s.empty?
  end
end