Structured Warnings ↑

This is an implementation of Daniel Berger's proposal of structured warnings for Ruby. 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

Installation & Compatibility ↑

gem install structured_warnings

structured_warnings works with all interpreters, it was tested with.

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:

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

Resources ↑

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 Kernel#warn, 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.

Copyright (c) 2008 Gregor Schmidt

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.