= Structured Warnings

This is an implementation of Daniel Berger's {proposal of structured warnings
for Ruby}[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
<code>warn</code> signature, but additionally allows a <code>raise</code>-like
use.

For more information on the usage and benefits of this library have a look at
the inspiring article at O'Reilly.

http://www.oreillynet.com/ruby/blog/2008/02/structured_warnings_now.html

== Installation & Compatibility

  gem install structured_warnings

structured_warnings works with all interpreters, it was tested with.

* Ruby 1.8-2.2
* Rubinius 2.4
* JRuby 1.7

Please let me know, of any other compatibilities or file a bug for any
incompatibilities.

== Example Usage

To get you started - here is a short example

In order to use structured_warnings in library code, use the following code.

  # in lib/...
  require 'structured_warnings'

  class Foo
    def old_method
      warn 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(DeprecatedMethodWarning){ @foo.old_method }
    end
  end

DeprecatedMethodWarning is only one of multiple predefined warning types. You
may add your own types by subclassing Warning if you like.

Client code of your library will look as follows:

  require "foo"

  foo = Foo.new
  foo.old_method # => will print
                 # ... `old_method' : This method is deprecated. Use new_method instead (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.

  DeprecatedMethodWarning.disable # Globally disable warnings about deprecated methods!

  foo.old_method # => will print nothing

  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.

  # Don't bug me about deprecated method warnings within this block, I know
  # what I'm doing.
  #
  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::Kernel, Warning and
Warning::ClassMethods.

Part of this library is a set of different warnings:

* Warning
  * StandardWarning
  * DeprecationWarning
    * DeprecatedMethodWarning
    * DeprecatedSignatureWarning

You are encourage to use your own subclasses of Warning to give as much
feedback to your users as possible.


== Resources

* {Inspiring article}[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]


== How to submit patches

In order to submit patches, please fork the repository on GitHub, add your
patches to your own copy and send a "Pull Request" afterwards. I will then try
to add your submissions as soon as possible. Patches containing corresponding
tests are always welcome.

Bug reports or general feature requests should be added using GitHub Issues.

== Known Issues

Although the library transparently coorperates with Ruby's built-in
<code>Kernel#warn</code>, it may not override +rb_warn+ which is used internally to emit
"method redefined", "void context", and "parenthesis" warnings. They may not be
manipulated by structured_warnings.

== License

This code is free to use under the terms of the MIT license.

  :include: License.txt