structured_warnings 0.2.0 → 0.3.0

data/lib/structured_warnings/minitest.rb

@@ -0,0 +1,5 @@
+require 'structured_warnings/test'
+
+Minitest::Test.class_eval do
+  include StructuredWarnings::Test::Assertions
+end

data/lib/structured_warnings/test.rb

@@ -1,6 +1,4 @@
-require "structured_warnings/test/warner"
-require "structured_warnings/test/assertions"
+module StructuredWarnings::Test; end
 
-Test::Unit::TestCase.class_eval do
-  include StructuredWarnings::Test::Assertions
-end
+require 'structured_warnings/test/warner'
+require 'structured_warnings/test/assertions'

data/lib/structured_warnings/test/assertions.rb

@@ -1,111 +1,106 @@
-module StructuredWarnings
-  # This module ecapsulates all extensions to support <code>test/unit</code>.
-  module Test
-    module Assertions
-      # :call-seq:
-      #   assert_no_warn(message = nil) {|| ...}
-      #   assert_no_warn(warning_class, message) {|| ...}
-      #   assert_no_warn(warning_instance) {|| ...}
-      #
-      # Asserts that the given warning was not emmitted. It may be restricted
-      # to a certain subtree of warnings and/or message.
-      #
-      #   def foo
-      #     warn DeprecatedMethodWarning, "used foo, use bar instead"
-      #     bar
-      #   end
-      #
-      #   assert_no_warn(StandardWarning) { foo }    # passes
-      #
-      #   assert_no_warn(DeprecationWarning) { foo } # fails
-      #   assert_no_warn() { foo }                   # fails
-      #
-      # See assert_warn for more examples.
-      #
-      # *Note*: It is currently not possible to add a custom failure message.
-      def assert_no_warn(*args)
-        warning, message = parse_arguments(args)
+# This module ecapsulates all extensions to support <code>test/unit</code>.
+module StructuredWarnings::Test::Assertions
+  # :call-seq:
+  #   assert_no_warn(message = nil) {|| ...}
+  #   assert_no_warn(warning_class, message) {|| ...}
+  #   assert_no_warn(warning_instance) {|| ...}
+  #
+  # Asserts that the given warning was not emmitted. It may be restricted
+  # to a certain subtree of warnings and/or message.
+  #
+  #   def foo
+  #     warn StructuredWarnings::DeprecatedMethodWarning, 'used foo, use bar instead'
+  #     bar
+  #   end
+  #
+  #   assert_no_warn(StructuredWarnings::StandardWarning) { foo }    # passes
+  #
+  #   assert_no_warn(StructuredWarnings::DeprecationWarning) { foo } # fails
+  #   assert_no_warn() { foo }                                       # fails
+  #
+  # See assert_warn for more examples.
+  #
+  # *Note*: It is currently not possible to add a custom failure message.
+  def assert_no_warn(*args)
+    warning, message = parse_arguments(args)
 
-        w = StructuredWarnings::Test::Warner.new
-        StructuredWarnings::with_warner(w) do
-          yield
-        end
-        assert_block("<#{args_inspect(args)}> has been emitted.") do
-          !w.warned?(warning, message)
-        end
-      end
+    w = StructuredWarnings::Test::Warner.new
+    StructuredWarnings::with_warner(w) do
+      yield
+    end
 
-      # :call-seq:
-      #   assert_warn(message = nil) {|| ...}
-      #   assert_warn(warning_class, message) {|| ...}
-      #   assert_warn(warning_instance) {|| ...}
-      #
-      # Asserts that the given warning was emmitted. It may be restricted to a
-      # certain subtree of warnings and/or message.
-      #
-      #   def foo
-      #     warn DeprecatedMethodWarning, "used foo, use bar instead"
-      #     bar
-      #   end
-      #
-      #   # passes
-      #   assert_warn(DeprecatedMethodWarning) { foo }
-      #   assert_warn(DeprecationWarning) { foo }
-      #   assert_warn() { foo }
-      #   assert_warn(Warning, "used foo, use bar instead") { foo }
-      #   assert_warn(Warning, /use bar/) { foo }
-      #   assert_warn(Warning.new("used foo, use bar instead")) { foo }
-      #
-      #   # fails
-      #   assert_warn(StandardWarning) { foo }
-      #   assert_warn(Warning, /deprecated/) { foo }
-      #   assert_warn(Warning.new) { foo }
-      #
-      # *Note*: It is currently not possible to add a custom failure message.
-      def assert_warn(*args)
-        warning, message = parse_arguments(args)
+    assert_equal(false, w.warned?(warning, message), "<#{args_inspect(args)}> has been emitted.")
+  end
 
-        w = StructuredWarnings::Test::Warner.new
-        StructuredWarnings::with_warner(w) do
-          yield
-        end
-        assert_block("<#{args_inspect(args)}> has not been emitted.") do
-          w.warned?(warning, message)
-        end
-      end
+  # :call-seq:
+  #   assert_warn(message = nil) {|| ...}
+  #   assert_warn(warning_class, message) {|| ...}
+  #   assert_warn(warning_instance) {|| ...}
+  #
+  # Asserts that the given warning was emmitted. It may be restricted to a
+  # certain subtree of warnings and/or message.
+  #
+  #   def foo
+  #     warn StructuredWarnings::DeprecatedMethodWarning, 'used foo, use bar instead'
+  #     bar
+  #   end
+  #
+  #   # passes
+  #   assert_warn(StructuredWarnings::DeprecatedMethodWarning) { foo }
+  #   assert_warn(StructuredWarnings::DeprecationWarning) { foo }
+  #   assert_warn() { foo }
+  #   assert_warn(StructuredWarnings::Base, 'used foo, use bar instead') { foo }
+  #   assert_warn(StructuredWarnings::Base, /use bar/) { foo }
+  #   assert_warn(StructuredWarnings::Base.new('used foo, use bar instead')) { foo }
+  #
+  #   # fails
+  #   assert_warn(StructuredWarnings::StandardWarning) { foo }
+  #   assert_warn(StructuredWarnings::Base, /deprecated/) { foo }
+  #   assert_warn(StructuredWarnings::Base.new) { foo }
+  #
+  # *Note*: It is currently not possible to add a custom failure message.
+  def assert_warn(*args)
+    warning, message = parse_arguments(args)
 
-    private
-      def parse_arguments(args)
-        args = args.clone
-        first = args.shift
-        if first.is_a? Class and first <= Warning
-          warning = first
-          message = args.shift
+    w = StructuredWarnings::Test::Warner.new
+    StructuredWarnings::with_warner(w) do
+      yield
+    end
 
-        elsif first.is_a? Warning
-          warning = first.class
-          message = first.message
+    assert_equal(true, w.warned?(warning, message), "<#{args_inspect(args)}> has not been emitted.")
+  end
 
-        elsif first.is_a? String
-          warning = StandardWarning
-          message = first
+  private
 
-        else
-          warning = Warning
-          message = nil
-        end
+  def parse_arguments(args)
+    args = args.clone
+    first = args.shift
+    if first.is_a? Class and first <= StructuredWarnings::Base
+      warning = first
+      message = args.shift
 
-        unless args.empty?
-          raise ArgumentError,
-                "wrong number of arguments (#{args.size + 2} for 2)"
-        end
+    elsif first.is_a? StructuredWarnings::Base
+      warning = first.class
+      message = first.message
 
-        return warning, message
-      end
+    elsif first.is_a? String
+      warning = StructuredWarnings::StandardWarning
+      message = first
 
-      def args_inspect(args)
-        args.map { |a| a.inspect }.join(", ")
-      end
+    else
+      warning = StructuredWarnings::Base
+      message = nil
     end
+
+    unless args.empty?
+      raise ArgumentError,
+            "wrong number of arguments (#{args.size + 2} for 2)"
+    end
+
+    return warning, message
+  end
+
+  def args_inspect(args)
+    args.map { |a| a.inspect }.join(', ')
   end
 end

data/lib/structured_warnings/test/warner.rb

@@ -1,39 +1,36 @@
-module StructuredWarnings
-  module Test
-    # This warner is used in Assertions#assert_warn and
-    # Assertions#assert_no_warn blocks. It captures all warnings in format and
-    # provides access to them using the warned? method.
-    class Warner < StructuredWarnings::Warner
-      # Overrides the public interface of StructuredWarnings::Warner. This
-      # method always returns nil to avoid warnings on stdout during assert_warn
-      # and assert_no_warn blocks.
-      def format(warning, message, call_stack)
-        given_warnings << warning.new(message)
-        nil
-      end
-
-      # Returns true if any warning or a subclass of warning was emitted.
-      def warned?(warning, message = nil)
-        case message
-        when Regexp
-          given_warnings.any? {|w| w.is_a?(warning) && w.message =~ message}
-        when String
-          given_warnings.any? {|w| w.is_a?(warning) && w.message == message}
-        when nil
-          given_warnings.any? {|w| w.is_a?(warning)}
-        else
-          raise ArgumentError, "Unkown argument for 'message'"
-        end
-      end
+# This warner is used in Assertions#assert_warn and
+# Assertions#assert_no_warn blocks. It captures all warnings in format and
+# provides access to them using the warned? method.
+class StructuredWarnings::Test::Warner < StructuredWarnings::Warner
+  # Overrides the public interface of StructuredWarnings::Warner. This
+  # method always returns nil to avoid warnings on stdout during assert_warn
+  # and assert_no_warn blocks.
+  def format(warning, message, call_stack)
+    given_warnings << warning.new(message)
+    nil
+  end
 
-      # :stopdoc:
-    protected
-      # Returns an array of all warning classes, that were given to this
-      # warner's format method, including duplications.
-      def given_warnings
-        @given_warnings ||= []
-      end
-      # :startdoc:
+  # Returns true if any warning or a subclass of warning was emitted.
+  def warned?(warning, message = nil)
+    case message
+    when Regexp
+      given_warnings.any? {|w| w.is_a?(warning) && w.message =~ message}
+    when String
+      given_warnings.any? {|w| w.is_a?(warning) && w.message == message}
+    when nil
+      given_warnings.any? {|w| w.is_a?(warning)}
+    else
+      raise ArgumentError, "Unkown argument type for 'message': #{message.class.inspect}"
     end
   end
+
+  # :stopdoc:
+  protected
+
+  # Returns an array of all warning classes, that were given to this
+  # warner's format method, including duplications.
+  def given_warnings
+    @given_warnings ||= []
+  end
+  # :startdoc:
 end

data/lib/structured_warnings/test_unit.rb

@@ -0,0 +1,5 @@
+require 'structured_warnings/test'
+
+Test::Unit::TestCase.class_eval do
+  include StructuredWarnings::Test::Assertions
+end

data/lib/structured_warnings/version.rb

@@ -0,0 +1,3 @@
+module StructuredWarnings
+  VERSION = "0.3.0"
+end

data/lib/structured_warnings/warner.rb

@@ -1,13 +1,15 @@
-module StructuredWarnings
-  # The Warner class implements a very simple interface. It simply formats
-  # a warning, so it is more than just the message itself. This default
-  # warner uses a format comparable to warnings emitted by rb_warn including
-  # the place where the "thing that caused the warning" resides.
-  class Warner
-    #  Warner.new.format(DeprecationWarning, "more info..", caller)
-    #     # => "demo.rb:5 : more info.. (DeprecationWarning)"
-    def format(warning, message, stack)
-      "#{stack.shift} : #{message} (#{warning})"
-    end
+# The Warner class implements a very simple interface. It simply formats
+# a warning, so it is more than just the message itself. This default
+# warner uses a format comparable to warnings emitted by rb_warn including
+# the place where the "thing that caused the warning" resides.
+class StructuredWarnings::Warner
+  #  Warner.new.format(StructuredWarning::DeprecationWarning, "more info..", caller)
+  #     # => "demo.rb:5 : more info.. (StructuredWarning::DeprecationWarning)"
+  def format(warning, message, stack)
+    frame = stack.shift
+    # This file contains the backwards compatibility code for Ruby 2.3 and
+    # lower, let's skip it
+    frame = stack.shift if frame.include? 'lib/structured_warnings/kernel.rb'
+    "#{frame} : #{message} (#{warning})"
   end
 end

data/lib/structured_warnings/warning.rb

@@ -1,129 +1,71 @@
-# Descendents of class Warning are used to  raise structured warnings. They
-# programmers to explicitly supress certain kinds of warnings and provide
-# additional information in contrast to the plain warn method. They
-# implement an Exception-like interface and carry information about the
-# warning -- its type (the warning's class name), an optional descriptive
-# string, and optional traceback information. Programs may subclass Warning
-# to add additional information.
-#
-# Large portions of this class's documentation are taken from the Exception
-# RDoc.
-class Warning
-  # Construct a new Warning object, optionally passing in a message.
-  def initialize(message = nil)
-    @message = message
-    @backtrace = caller(1)
-  end
-
-
-  # call-seq:
-  #    warning.backtrace    => array
+# This module encapsulates the extensions to Warning, that are introduced
+# by this library.
+module StructuredWarnings::Warning
+  # :call-seq:
+  #   warn(message = nil)
+  #   warn(warning_class, message)
+  #   warn(warning_instance)
   #
-  # Returns any backtrace associated with the warning. The backtrace
-  # is an array of strings, each containing either ``filename:lineNo: in
-  # `method''' or ``filename:lineNo.''
-  def backtrace
-    @backtrace
-  end
-
-  # Sets the backtrace information associated with warning. The argument must
-  # be an array of String objects in the format described in
-  # Exception#backtrace.
-  def set_backtrace(backtrace)
-    @backtrace = backtrace
-  end
-
-  # Returns warning's message (or the name of the warning if no message is set).
-  def to_s
-    @message || self.class.name
-  end
-  alias_method :to_str, :to_s
-  alias_method :message, :to_s
-
-  # Return this warning's class name and message
-  def inspect
-    "#<#{self.class}: #{self}>"
-  end
+  # 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 <code>StructuredWarnings::Base.disable</code>.
+  #
+  #   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")
+  #
+  def warn(*args)
+    first = args.shift
+    if first.is_a? Class and first <= StructuredWarnings::Base
+      warning = first
+      message = args.shift
 
-  # This module extends Warning and each subclass. It may be used to activate
-  # or deactivate a set of warnings.
-  module ClassMethods
-    # returns a Boolean, stating whether a warning of this type would be
-    # emmitted or not.
-    def active?
-      StructuredWarnings::disabled_warnings.all? {|w| !(w >= self)}
-    end
+    elsif first.is_a? StructuredWarnings::Base
+      warning = first.class
+      message = first.message
 
-    # call-seq:
-    #   disable()
-    #   disable() {...}
-    #
-    # If called without a block, Warnings of this type will be disabled in the
-    # current thread and all new child threads.
-    #
-    #   warn("this will be printed") # creates a StandardWarning which is
-    #                                # enabled by default
-    #
-    #   Warning.disable
-    #
-    #   warn("this will not be printed") # creates a StandardWarning which is
-    #                                    # currently disabled
-    #
-    # If called with a block, warnings of this type will be disabled in the
-    # dynamic scope of the given block.
-    #
-    #   Warning.disable do
-    #     warn("this will not be printed") # creates a StandardWarning which is
-    #                                      # currently disabled
-    #   end
-    #
-    #   warn("this will be printed") # creates a StandardWarning which is
-    #                                # currently enabled
-    def disable
-      if block_given?
-        StructuredWarnings::with_disabled_warnings(
-                            StructuredWarnings.disabled_warnings | [self]) do
-          yield
+    else
+      warning =
+        if caller.shift.include? 'lib/structured_warnings/kernel.rb'
+          StructuredWarnings::StandardWarning
+        else
+          StructuredWarnings::BuiltInWarning
         end
-      else
-        StructuredWarnings::disabled_warnings |= [self]
-      end
+      message = first.to_s
     end
 
-    # call-seq:
-    #   enable()
-    #   enable() {...}
-    #
-    # This method has the same semantics as disable, only with the opposite
-    # outcome. In general the last assignment wins, so that disabled warnings
-    # may be enabled again and so on.
-    def enable
-      if block_given?
-        StructuredWarnings::with_disabled_warnings(
-                            StructuredWarnings.disabled_warnings - [self]) do
-          yield
-        end
-      else
-        StructuredWarnings::disabled_warnings -= [self]
-      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, caller(1))
+      super(output) unless output.nil? or output.to_s.empty?
     end
   end
-
-  extend ClassMethods
 end
 
-# This warning is used when calling #Kernel.warn without arguments.
-class StandardWarning < Warning; end
-
-# This is a general warning used to mark certain actions as deprecated. We
-# recommend to add a useful warning message, which alternative to use instead.
-class DeprecationWarning < Warning; end
-
-# This warning marks single methods as deprecated. We
-# recommend to add a useful warning message, which alternative to use instead.
-class DeprecatedMethodWarning < DeprecationWarning; end
-
-# This warning marks the given parameters for a certain methods as
-# deprecated. We recommend to add a useful warning message, which
-# alternative to use instead.
-class DeprecatedSignatureWarning < DeprecationWarning; end
+Warning.extend StructuredWarnings::Warning