structured_warnings 0.1.1 → 0.1.2

data/.gitignore

@@ -0,0 +1,2 @@
+doc
+pkg

data/History.txt

@@ -1,3 +1,15 @@
+== 0.1.3 2009-11-28
+
+* major enhancements
+  * improved API of assert_warn and assert_no_warn
+
+== 0.1.2 2009-11-27
+
+* major enhancements
+  * moved to gemcutter
+* minor enhancements
+  * removed all old cruft
+
 == 0.1.1 2008-02-22
 
 * 1 major enhancement:

data/README.rdoc

@@ -0,0 +1,128 @@
+= 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
+
+  gem install structured_warnings
+
+== 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
+
+* {Initial announcement}[http://www.nach-vorne.de/2008/2/21/ann-structured_warnings-0-1-0-released]
+* {Inspiring article}[http://www.oreillynet.com/ruby/blog/2008/02/structured_warnings_now.html]
+* {Project's website}[http://github.com/schmidt/structured_warnings/]
+* {API doc}[http://rdoc.info/projects/schmidt/structured_warnings]
+* {Build Status on RunCodeRun}[http://runcoderun.com/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

data/Rakefile

@@ -1,4 +1,38 @@
-require 'config/requirements'
-require 'config/hoe' # setup Hoe + all gem configuration
-
-Dir['tasks/**/*.rake'].each { |rake| load rake }
+require 'rake'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "structured_warnings"
+    gemspec.summary = "Provides structured warnings for Ruby, using an exception-like interface and hierarchy."
+    gemspec.description = "This is an implementation of Daniel Berger's proposal of structured warnings for Ruby."
+    gemspec.email = "ruby@schmidtwisser.de"
+    gemspec.homepage = "http://github.com/schmidt/structured_warnings"
+    gemspec.authors = ["Gregor Schmidt"]
+
+    gemspec.add_development_dependency('rake')
+    gemspec.add_development_dependency('jeweler', '>= 1.4.0')
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end
+
+desc "Run all tests"
+task :test do 
+  require 'rake/runtest'
+  Rake.run_tests 'test/**/*_test.rb'
+end
+
+desc 'Generate documentation for the structured_warnings gem.'
+Rake::RDocTask.new(:doc) do |doc|
+  doc.rdoc_dir = 'doc'
+  doc.title = 'structured_warnings'
+  doc.options << '--line-numbers' << '--inline-source'
+  doc.rdoc_files.include('README.rdoc')
+  doc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :test

data/lib/structured_warnings.rb

@@ -7,11 +7,9 @@ require "structured_warnings/warning"
 
 
 module StructuredWarnings
-  # On initialization self.init is called. When a test module is defined, it
-  # is a assumed, that <code>test/unit</code> is used and the warn assertions 
-  # are added to Test::Unit::TestCase. If you <code>require "test/unit"</code> 
-  # after +structured_warnings+ you have to call #StructuredWarnings::init_test 
-  # 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
     # warnings to stdout, but fetch them and redirect them to somewhere else.
@@ -62,31 +60,13 @@ module StructuredWarnings
       end
     end
     #:startdoc:
-
-  protected
-    # Initializes the StructuredWarnings library. Includes the Kernel extensions
-    # into Object, sets the initial set of disabled_warnings (none) and 
-    # initializes the warner to an instance of StructuredWarnings::Warner
-    def init
-      unless Object < StructuredWarnings::Kernel
-        Object.class_eval { include StructuredWarnings::Kernel }
-        StructuredWarnings::disabled_warnings = []
-        StructuredWarnings::warner = StructuredWarnings::Warner.new
-      end
-      init_test if defined? ::Test
-    end
-
-    # Initializes the StructuredWarnings test extensions - namely adds 
-    # StructuredWarnings::Test::Assertions to Test::Unit::TestCase
-    def init_test
-      require "structured_warnings/test.rb"
-      ::Test::Unit::TestCase.class_eval do
-        include StructuredWarnings::Test::Assertions
-      end
-    rescue NameError
-    end
   end
   extend ClassMethods
+end
 
-  init
+unless Object < StructuredWarnings::Kernel
+  Object.class_eval { include StructuredWarnings::Kernel }
+  StructuredWarnings::disabled_warnings = []
+  StructuredWarnings::warner = StructuredWarnings::Warner.new
 end
+require "structured_warnings/test" if defined? Test::Unit::TestCase

data/lib/structured_warnings/kernel.rb

@@ -40,7 +40,7 @@ module StructuredWarnings
     #
     def warn(*args)
       first = args.shift
-      if first.is_a? Class and first < Warning
+      if first.is_a? Class and first <= Warning
         warning = first 
         message = args.shift
 

data/lib/structured_warnings/test.rb

@@ -1,2 +1,7 @@
+require "structured_warnings"
 require "structured_warnings/test/warner.rb"
 require "structured_warnings/test/assertions.rb"
+
+Test::Unit::TestCase.class_eval do
+  include StructuredWarnings::Test::Assertions
+end

data/lib/structured_warnings/test/assertions.rb

@@ -2,8 +2,13 @@ module StructuredWarnings
   # This module ecapsulates all extensions to support <code>test/unit</code>.
   module Test
     module Assertions
-      # Asserts that no warning was emmitted. It may be restricted to a certain
-      # subtree of warnings.
+      # :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"
@@ -14,34 +19,80 @@ module StructuredWarnings
       #
       #   assert_no_warn(DeprecationWarning) { foo } # fails
       #   assert_no_warn() { foo }                   # fails
-      def assert_no_warn(warning = Warning)
+      #
+      # See assert_warn for more examples.
+      def assert_no_warn(*args)
+        warning, message = parse_arguments(args)
+
         w = StructuredWarnings::Test::Warner.new
         StructuredWarnings::with_warner(w) do 
           yield
         end
-        assert !w.warned?(warning), "#{warning} has been emitted."
+        assert !w.warned?(warning, message), "#{warning} has been emitted."
       end
 
-      # Asserts that a warning was emmitted. It may be restricted to a certain
-      # subtree of warnings.
+      # :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
       #
-      #   assert_warn(DeprecatedMethodWarning) { foo } # passes
-      #   assert_warn(DeprecationWarning) { foo }      # passes
-      #   assert_warn() { foo }                        # passes
+      #   # 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 }
       #
-      #   assert_warn(StandardWarning) { foo }         # fails
+      #   # fails
+      #   assert_warn(StandardWarning) { foo }
+      #   assert_warn(Warning, /deprecated/) { foo }
+      #   assert_warn(Warning.new) { foo }
       #
-      def assert_warn(warning = Warning)
+      def assert_warn(*args)
+        warning, message = parse_arguments(args)
+
         w = StructuredWarnings::Test::Warner.new
         StructuredWarnings::with_warner(w) do 
           yield
         end
-        assert w.warned?(warning), "#{warning} has not been emitted."
+        assert w.warned?(warning, message), "#{warning} has not been emitted."
+      end
+
+    private
+      def parse_arguments(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
+
+        elsif first.is_a? String
+          warning = StandardWarning
+          message = first
+
+        else
+          warning = Warning
+          message = nil
+        end
+
+        unless args.empty?
+          raise ArgumentError, 
+                "wrong number of arguments (#{args.size + 2} for 2)" 
+        end
+
+        return warning, message
       end
     end
   end

data/lib/structured_warnings/test/warner.rb

@@ -8,13 +8,22 @@ module StructuredWarnings
       # 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 
+        given_warnings << warning.new(message)
         nil
       end
 
       # Returns true if any warning or a subclass of warning was emitted.
-      def warned?(warning)
-        given_warnings.any? {|w| (w <= warning)}
+      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
 
       # :stopdoc:

data/structured_warnings.gemspec

@@ -0,0 +1,63 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{structured_warnings}
+  s.version = "0.1.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Gregor Schmidt"]
+  s.date = %q{2009-11-28}
+  s.description = %q{This is an implementation of Daniel Berger's proposal of structured warnings for Ruby.}
+  s.email = %q{ruby@schmidtwisser.de}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "History.txt",
+     "License.txt",
+     "README.rdoc",
+     "Rakefile",
+     "lib/structured_warnings.rb",
+     "lib/structured_warnings/dynamic.rb",
+     "lib/structured_warnings/kernel.rb",
+     "lib/structured_warnings/test.rb",
+     "lib/structured_warnings/test/assertions.rb",
+     "lib/structured_warnings/test/warner.rb",
+     "lib/structured_warnings/warner.rb",
+     "lib/structured_warnings/warning.rb",
+     "structured_warnings.gemspec",
+     "test/structured_warnings_test.rb",
+     "test/test_helper.rb",
+     "version.yml"
+  ]
+  s.homepage = %q{http://github.com/schmidt/structured_warnings}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Provides structured warnings for Ruby, using an exception-like interface and hierarchy.}
+  s.test_files = [
+    "test/structured_warnings_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 1.4.0"])
+    else
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 1.4.0"])
+    end
+  else
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 1.4.0"])
+  end
+end
+