structured_warnings 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2b48e72d14f6d01966512679d69e6fbc7f012b15
-  data.tar.gz: 71d1ba1bf37e469cee648f774dc8a8e805e557d8
+  metadata.gz: 82e448e3265ea35dd71196fb6f3adbc6b629cbb5
+  data.tar.gz: 5ed838c91e79e3d459f10d2cb9c7b596f03b5d98
 SHA512:
-  metadata.gz: b66bd37bd801f9de3541d9a2793ffa8da342a8f2cf253a6295a6da55ae3230dab6f2cfba46994c27351c8050d8e3ed7998cb4dd2936b830a823023c2e1a77ed1
-  data.tar.gz: e6db07f6d4e5393cc009d62300c62a8ff32d500d00ebf44b4dec97e8a5c6cc92226db98048f6db8a241673b398b186daf36f5b893e9b0fd8740ba4b4cee24534
+  metadata.gz: c784e0acb8c6aa8840ba44a36f5fdd090d7a46d178b4701fc97f1c6203d0f0de41f8d90a8579a53a7064a4df9146a314a936b6c6d290c892d3022840bce58282
+  data.tar.gz: f816ed5e9f249359c9c8108ba65c978140f9c2cef49f7d70202b26537ba4ced18ad1699c76ee9954ea8771bde64da59e98a08f34deee41766b06f76328a836df

data/README.md

@@ -0,0 +1,200 @@
+# StructuredWarnings
+
+> **Disclaimer:** This is an experimental reimplementation of structured
+> warnings, based on Ruby 2.4's new warning module. This is not yet ready for
+> prime time.
+
+This is an implementation of Daniel Berger's [proposal of structured warnings
+for Ruby](https://web.archive.org/web/20140328021259/http://www.oreillynet.com/ruby/blog/2008/02/structured_warnings_now.html).
+They provide dynamic suppression and activation, as well as, an inheritance
+hierarchy to model their relations. This library preserves the old `warn`
+signature, but additionally allows a `raise`-like use.
+
+For more information on the usage and benefits of this library have a look at
+the inspiring article at O'Reilly.
+
+[www.oreillynet.com/ruby/blog/2008/02/structured\_warnings\_now.html](https://web.archive.org/web/20140328021259/http://www.oreillynet.com/ruby/blog/2008/02/structured_warnings_now.html)
+(link to web archive - O'Reilly took it down)
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'structured_warnings'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install structured_warnings
+
+
+## Compatibility
+
+`structured_warnings` aims to work with all Ruby interpreters. Please file a bug
+for any incompatibilities.
+
+
+Versions of `structured_warnings` before `v0.3.0` are incompatible with Ruby
+2.4+. Please upgrade accordingly, if you need Ruby 2.4 compatibility. Please
+note on the otherhand, that many class names changed in an incompatible way
+with `structured_warnings` `v0.3.0`. This was done to avoid future name clashes.
+
+Here's a table which should ease upgrading.
+
+| v0.2.0 and before            | v0.3.0 and after                                 |
+|------------------------------|--------------------------------------------------|
+| `Warning`                    | `StructuredWarnings::Base`                       |
+| `StandardWarning`            | `StructuredWarnings::StandardWarning`            |
+| `DeprecationWarning`         | `StructuredWarnings::DeprecationWarning`         |
+| `DeprecatedMethodWarning`    | `StructuredWarnings::DeprecatedMethodWarning`    |
+| `DeprecatedSignatureWarning` | `StructuredWarnings::DeprecatedSignatureWarning` |
+
+
+### Test framework support
+
+`structured_warnings` supports both
+[test-unit](https://github.com/test-unit/test-unit/) and
+[minitest/test](https://github.com/seattlerb/minitest/) by adding the
+`assert_warn` and `assert_no_warn` assertions.
+
+Pull requests which add support for `RSpec` or `minitest/spec` are very welcome.
+
+
+### Known Issues
+
+In Ruby versions before 2.4, the library may not extend Ruby's built-in
+warnings handled by the C-level function `rb_warn`. Therefore warnings like
+"method redefined", "void context", and "parenthesis" may not be manipulated by
+`structured_warnings`.
+
+
+## Usage
+
+To get you started - here is a short example
+
+In order to use `structured_warnings` in library code, use the following code.
+
+```ruby
+# in lib/...
+require 'structured_warnings'
+
+class Foo
+  def old_method
+    warn StructuredWarnings::DeprecatedMethodWarning, 'This method is deprecated. Use new_method instead'
+    # Do stuff
+  end
+end
+
+# in test/...
+require 'test/unit'
+require 'structured_warnings'
+
+class FooTests < Test::Unit::TestCase
+  def setup
+    @foo = Foo.new
+  end
+
+  def test_old_method_emits_deprecation_warning
+    assert_warn(StructuredWarnings::DeprecatedMethodWarning){ @foo.old_method }
+  end
+end
+```
+
+`StructuredWarnings::DeprecatedMethodWarning` is only one of multiple predefined
+warning types. You may add your own types by subclassing
+`StructuredWarnings::Base` if you like.
+
+Client code of your library will look as follows:
+
+```ruby
+require "foo"
+
+foo = Foo.new
+foo.old_method # => will print
+               # ... `old_method' : This method is deprecated. Use new_method instead (StructuredWarnings::DeprecatedMethodWarning)
+```
+
+But the main difference to the standard warning concept shipped with ruby, is
+that the client is able to selectively disable certain warnings s/he is aware of
+and not willing to fix.
+
+```ruby
+StructuredWarnings::DeprecatedMethodWarning.disable # Globally disable warnings about deprecated methods!
+
+foo.old_method # => will print nothing
+
+StructuredWarnings::DeprecatedMethodWarning.enable # Reenable warnings again.
+```
+
+And there is an even more powerful option for your clients, the can selectively
+disable warnings in a dynamic block scope.
+
+```ruby
+# Don't bug me about deprecated method warnings within this block, I know
+# what I'm doing.
+#
+StructuredWarnings::DeprecatedMethodWarning.disable do
+  foo.old_method
+end
+```
+
+These settings are scoped to the local thread (and all threads spawned in the
+block scope) and automatically reset after the block.
+
+
+## Detailed Documentation
+
+Have closer look at the RDoc of `StructuredWarnings::Warning`,
+`StructuredWarnings::Base` and `StructuredWarnings::Base::ClassMethods`.
+
+Part of this library is a set of different warnings:
+
+* `StructuredWarnings::Base`
+  * `StructuredWarnings::BuiltInWarning`
+  * `StructuredWarnings::StandardWarning`
+  * `StructuredWarnings::DeprecationWarning`
+    * `StructuredWarnings::DeprecatedMethodWarning`
+    * `StructuredWarnings::DeprecatedSignatureWarning`
+
+You are encouraged to use your own subclasses of `StructuredWarnings::Base` to
+give as much feedback to your users as possible.
+
+
+## Resources
+
+* [Inspiring article](https://web.archive.org/web/20140328021259/http://www.oreillynet.com/ruby/blog/2008/02/structured_warnings_now.html)
+* [Implementation Highlights](http://www.nach-vorne.de/2008/2/22/structured_warnings-highlights)
+* [Project's website](https://github.com/schmidt/structured_warnings/)
+* [API doc](http://rdoc.info/projects/schmidt/structured_warnings)
+* [Build status](https://travis-ci.org/schmidt/structured_warnings)
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake test` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+[github.com/schmidt/structured\_warnings](https://github.com/schmidt/structured_warnings).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](http://opensource.org/licenses/MIT).

data/lib/structured_warnings.rb

@@ -1,11 +1,13 @@
-require "structured_warnings/dynamic"
-require "structured_warnings/kernel"
-require "structured_warnings/warner"
-require "structured_warnings/warning"
+require 'structured_warnings/version'
+
+# Compatibility layer
+require 'warning' unless defined? ::Warning
+
+require 'dynamic'
 
 module StructuredWarnings
-  # If you <code>require "test/unit"</code> after +structured_warnings+ you
-  # have to <code>require "structured_warnings/test"</code> manually,
+  # If you <code>require 'test/unit'</code> after +structured_warnings+ you
+  # have to <code>require 'structured_warnings/test'</code> manually,
   # otherwise the test extensions will be added automatically.
   module ClassMethods
     # Executes a block using the given warner. This may be used to suppress
@@ -58,12 +60,20 @@ module StructuredWarnings
     end
     #:startdoc:
   end
+
   extend ClassMethods
 end
 
-unless Object < StructuredWarnings::Kernel
-  Object.class_eval { include StructuredWarnings::Kernel }
+require 'structured_warnings/kernel'
+require 'structured_warnings/warning'
+require 'structured_warnings/warner'
+require 'structured_warnings/base'
+
+
+unless Dynamic.variables.key? :disabled_warnings
   StructuredWarnings::disabled_warnings = []
   StructuredWarnings::warner = StructuredWarnings::Warner.new
 end
-require "structured_warnings/test" if defined? Test::Unit::TestCase
+
+require 'structured_warnings/minitest' if defined? Minitest::Test
+require 'structured_warnings/test_unit' if defined? Test::Unit::TestCase

data/lib/structured_warnings/base.rb

@@ -0,0 +1,132 @@
+# Descendents of class StructuredWarnings::Base are used to  raise structured
+# warnings. They enable 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
+# StructuredWarnings::Base to add additional information.
+#
+# Large portions of this class's documentation are taken from the Exception
+# RDoc.
+class StructuredWarnings::Base
+  # Construct a new StructuredWarning::Base object, optionally passing in a
+  # message.
+  def initialize(message = nil)
+    @message = message
+    @backtrace = caller(1)
+  end
+
+
+  # call-seq:
+  #    warning.backtrace    => array
+  #
+  # 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 module extends StructuredWarnings::Base 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
+
+    # 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 StructuredWarnings::StandardWarning
+    #                                # which is enabled by default
+    #
+    #   StructuredWarnings::Base.disable
+    #
+    #   warn("this will not be printed") # creates a StructuredWarnings::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.
+    #
+    #   StructuredWarnings::Base.disable do
+    #     warn("this will not be printed") # creates a StructuredWarnings::StandardWarning
+    #                                      # which is currently disabled
+    #   end
+    #
+    #   warn("this will be printed") # creates a StructuredWarnings::StandardWarning
+    #                                # which is currently enabled
+    def disable
+      if block_given?
+        StructuredWarnings::with_disabled_warnings(StructuredWarnings.disabled_warnings | [self]) do
+          yield
+        end
+      else
+        StructuredWarnings::disabled_warnings |= [self]
+      end
+    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
+    end
+  end
+
+  extend ClassMethods
+end
+
+# This warning is used when calling #Kernel.warn without arguments.
+class StructuredWarnings::StandardWarning < StructuredWarnings::Base; 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 StructuredWarnings::DeprecationWarning < StructuredWarnings::Base; end
+
+# This warning marks single methods as deprecated. We
+# recommend to add a useful warning message, which alternative to use instead.
+class StructuredWarnings::DeprecatedMethodWarning < StructuredWarnings::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 StructuredWarnings::DeprecatedSignatureWarning < StructuredWarnings::DeprecationWarning; end
+
+# This warning is used for Ruby's built in warnings about accessing unused
+# instance vars, redefining constants, etc.
+class StructuredWarnings::BuiltInWarning < StructuredWarnings::Base; end

data/lib/structured_warnings/kernel.rb

@@ -1,67 +1,7 @@
-module StructuredWarnings
-  # This module encapsulates the extensions to Object, that are introduced
-  # by this library.
-  module Kernel
-
-    # :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 ::Kernel 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 ::Kernel. That way, it is less likely, that structured_warnings
-    # interferes with other extensions.
-    #
-    # It the warner return 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 ::Kernel#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>Warning.disable</code>.
-    #
-    #   warn "This is an old-style warning" # This will emit a StandardWarning
-    #
-    #   class Foo
-    #     def bar
-    #       warn DeprecationWarning, "Never use bar again, use beer"
-    #     end
-    #     def beer
-    #       "Ahhh"
-    #     end
-    #   end
-    #
-    #   warn Warning.new("The least specific warning you can get")
-    #
-    def warn(*args)
-      first = args.shift
-      if first.is_a? Class and first <= Warning
-        warning = first
-        message = args.shift
-
-      elsif first.is_a? Warning
-        warning = first.class
-        message = first.message
-
-      else
-        warning = StandardWarning
-        message = first.to_s
-      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
+module StructuredWarnings::Kernel
+  def warn(*args)
+    Warning.warn(*args)
   end
 end
+
+Object.class_eval { include StructuredWarnings::Kernel }