structured_warnings 0.1.0 → 0.1.1

data/History.txt

@@ -1,3 +1,10 @@
+== 0.1.1 2008-02-22
+
+* 1 major enhancement:
+  * Fully documented library
+* 1 minor fix
+  * Warnings can no longer be disabled twice
+
 == 0.1.0 2008-02-21
 
 * 1 major enhancement:

data/License.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2008 FIXME full name
+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
@@ -17,4 +17,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -14,8 +14,6 @@ lib/structured_warnings/test/warner.rb
 lib/structured_warnings/version.rb
 lib/structured_warnings/warner.rb
 lib/structured_warnings/warning.rb
-lib/structured_warnings/warnings.rb
-log/debug.log
 script/destroy
 script/generate
 script/txt2html

data/README.txt

@@ -1,4 +1,19 @@
 = Structured warnings 
 
-See the projects website on http://rug-b.rubyforge.org/structured_warnings or
-the inspiring article at http://www.oreillynet.com/ruby/blog/2008/02/structured_warnings_now.html.
+Have closer look at 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.
+
+Also see the projects website on http://rug-b.rubyforge.org/structured_warnings
+and the inspiring article at 
+http://www.oreillynet.com/ruby/blog/2008/02/structured_warnings_now.html.

data/lib/structured_warnings/dynamic.rb

@@ -1,8 +1,9 @@
 # This library was created by Christian Neukirchen in the context of 
 # EuRuKo 2005 and is licensed under the same terms as Ruby.
 #
-# It provides dynamically scoped variables. It is used within ContextR to 
-# store the current, thread-wide activated layers.
+# It provides dynamically scoped variables. It is used within 
+# +structured_warnings+ to store the current, thread-wide disabled warning 
+# classes.
 #
 # For more information see the corresponding slides at
 # http://chneukirchen.org/talks/euruko-2005/chneukirchen-euruko2005-contextr.pdf

data/lib/structured_warnings/kernel.rb

@@ -1,5 +1,43 @@
 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
@@ -11,7 +49,7 @@ module StructuredWarnings
         message = first.message
 
       else
-        warning = Warning
+        warning = StandardWarning
         message = first.to_s 
       end
 
@@ -21,18 +59,9 @@ module StructuredWarnings
       end
 
       if warning.active?
-        output = Kernel.warner.format(warning, message, caller[1..-1])
+        output = StructuredWarnings.warner.format(warning, message, caller(1))
         super(output) unless output.nil? or output.to_s.empty? 
       end
     end
-
-    def self.warner
-      Dynamic[:warner]
-    end
-
-  protected
-    def structured_warn(warning, message)
-      nil
-    end
   end
 end

data/lib/structured_warnings/test/assertions.rb

@@ -1,17 +1,44 @@
 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.
+      #
+      #   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
       def assert_no_warn(warning = Warning)
         w = StructuredWarnings::Test::Warner.new
-        Dynamic.let(:warner => w) do
+        StructuredWarnings::with_warner(w) do 
           yield
         end
         assert !w.warned?(warning), "#{warning} has been emitted."
       end
 
+      # Asserts that a warning was emmitted. It may be restricted to a certain
+      # subtree of warnings.
+      #
+      #   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
+      #
+      #   assert_warn(StandardWarning) { foo }         # fails
+      #
       def assert_warn(warning = Warning)
         w = StructuredWarnings::Test::Warner.new
-        Dynamic.let(:warner => w) do
+        StructuredWarnings::with_warner(w) do 
           yield
         end
         assert w.warned?(warning), "#{warning} has not been emitted."
@@ -19,4 +46,3 @@ module StructuredWarnings
     end
   end
 end
-

data/lib/structured_warnings/test/warner.rb

@@ -1,18 +1,30 @@
 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 
         nil
       end
 
+      # Returns true if any warning or a subclass of warning was emitted.
       def warned?(warning)
         given_warnings.any? {|w| (w <= warning)}
       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
   end
 end

data/lib/structured_warnings/version.rb

@@ -2,7 +2,7 @@ module StructuredWarnings #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 1
-    TINY  = 0
+    TINY  = 1
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/structured_warnings/warner.rb

@@ -1,12 +1,13 @@
 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
-
-#    formats an exception like stack frame
-#    def collect_frame(stack)
-#      stack.collect { |frame| "        from #{frame}" }.join("\n")
-#    end
   end
 end

data/lib/structured_warnings/warning.rb

@@ -1,47 +1,129 @@
+# 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
-  attr_accessor :message
+  # 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
+  # 
+  # 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
 
-  def initialize(message)
-    self.message = message
+  # Return this warning's class name and message
+  def inspect
+    "#<#{self.class}: #{self}>"
   end
 
+  # 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?
-      disabled_warnings.all? {|w| !(w >= self)}
+      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 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?
-        Dynamic.let(:disabled_warnings => disabled_warnings + [self]) do
+        StructuredWarnings::with_disabled_warnings(
+                            StructuredWarnings.disabled_warnings | [self]) do
           yield
         end
       else
-        self.disabled_warnings += [self]
+        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?
-        Dynamic.let(:disabled_warnings => disabled_warnings - [self]) do
+        StructuredWarnings::with_disabled_warnings(
+                            StructuredWarnings.disabled_warnings - [self]) do
           yield
         end
       else
-        self.disabled_warnings -= [self]
+        StructuredWarnings::disabled_warnings -= [self]
       end
     end
-
-  protected
-    def disabled_warnings
-      Dynamic[:disabled_warnings]
-    end
-    def disabled_warnings=(new)
-      Dynamic[:disabled_warnings] = new
-    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

data/lib/structured_warnings.rb

@@ -1,23 +1,92 @@
 $:.unshift File.dirname(__FILE__)
+
 require "structured_warnings/dynamic"
 require "structured_warnings/kernel"
 require "structured_warnings/warner"
 require "structured_warnings/warning"
 
+
 module StructuredWarnings
-  def self.init
-    Object.send(:include, Kernel)
-    unless Dynamic.variables.include?(:disabled_warnings)
-      Dynamic[:disabled_warnings] = []
-      Dynamic[:warner] = StructuredWarnings::Warner.new
+  # 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.
+  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.
+    #
+    # This behaviour is used in the StructuredWarnings::Assertions
+    def with_warner(warner)
+      Dynamic.let(:warner => warner) do
+        yield
+      end
+    end
+
+    # Gives access to the currently used warner. Default is an instance of
+    # StructuredWarnings::Warner
+    def warner
+      Dynamic[:warner]
+    end
+
+    #:stopdoc:
+    # Sets a new warner 
+    def warner=(new_warner)
+      Dynamic[:warner] = new_warner
+    end
+
+    # returns an Array of all currently disabled warnings.
+    #
+    # *Note*: Everyday users are supposed to use the methods in 
+    # Warning::ClassMethods
+    def disabled_warnings
+      Dynamic[:disabled_warnings]
     end
-    init_test if defined? ::Test
-  end
 
-  def self.init_test
-    require "structured_warnings/test.rb"
-    ::Test::Unit::TestCase.send(:include, StructuredWarnings::Test::Assertions)
+    # sets an array of all currently disabled warnings. It is expected that this
+    # array consists only of the Warning class and its subclasses.
+    #
+    # *Note*: Everyday users are supposed to use the methods in 
+    # Warning::ClassMethods
+    def disabled_warnings=(new_disabled_warnings)
+      Dynamic[:disabled_warnings] = new_disabled_warnings
+    end
+
+    # Executes a block with the given set of disabled instances.
+    #
+    # *Note*: Everyday users are supposed to use the methods in 
+    # Warning::ClassMethods
+    def with_disabled_warnings(disabled_warnings)
+      Dynamic.let(:disabled_warnings => disabled_warnings) do
+        yield
+      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
-end
+  extend ClassMethods
 
-StructuredWarnings.init
+  init
+end

data/test/test_structured_warnings.rb

@@ -78,4 +78,10 @@ class TestStructuredWarnings < Test::Unit::TestCase
       warn nil
     end
   end
+
+  def test_warnings_may_not_be_disabled_twice
+    assert [Warning], Warning.disable
+    assert [Warning], Warning.disable
+    assert [], Warning.enable
+  end
 end

data/website/index.html

@@ -8,9 +8,6 @@
       rug-b
   </title>
   <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
-<style>
-
-</style>
   <script type="text/javascript">
     window.onload = function() {
       settings = {
@@ -33,7 +30,7 @@
     <h1>rug-b</h1>
     <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/rug-b"; return false'>
       <p>Get Version</p>
-      <a href="http://rubyforge.org/projects/rug-b" class="numbers">0.1.0</a>
+      <a href="http://rubyforge.org/projects/rug-b" class="numbers">0.1.1</a>
     </div>
     <h1>&#x2192; &#8216;structured_warnings&#8217;</h1>
 
@@ -122,7 +119,21 @@ the inspiring article at
 	<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8z-email">8z: Email the project owner</a>, use the Email below.</p>
 
 
-	<p>The trunk repository is <code>svn://rubyforge.org/var/svn/rug-b/structured_warnings/trunk</code> for anonymous access.</p>
+	<p>The trunk repository is <code>http://rug-b.rubyforge.org/svn/structured_warnings/trunk</code> for anonymous access.</p>
+
+
+	<h2>Resources</h2>
+
+
+	<ul>
+	<li><a href="http://www.nach-vorne.de/2008/2/21/ann-structured_warnings-0-1-0-released">Initial announcement</a></li>
+		<li><a href="http://www.oreillynet.com/ruby/blog/2008/02/structured_warnings_now.html">Inspiring article</a></li>
+		<li><a href="http://rug-b.rubyforge.org/structured_warnings/">Project&#8217;s website</a></li>
+		<li><a href="http://rug-b.rubyforge.org/structured_warnings/rdoc"><span class="caps">API</span> doc</a></li>
+		<li><a href="http://www.rug-b.com">rug-b</a></li>
+		<li>Other rug-b gems <a href="http://rug-b.rubyforge.org/svn/">in <span class="caps">SVN</span></a> and 
+  <a href="http://rubyforge.org/projects/rug-b">to download</a></li>
+	</ul>
 
 
 	<h2>License</h2>
@@ -136,7 +147,7 @@ the inspiring article at
 
 	<p>Comments are welcome. Send an email to <a href="mailto:ruby@schmidtwisser.de">Gregor Schmidt</a></p>
     <p class="coda">
-      <a href="mailto:ruby@schmidtwisser.de">Gregor Schmidt</a>, 21st February 2008<br>
+      <a href="mailto:ruby@schmidtwisser.de">Gregor Schmidt</a>, 22nd February 2008<br />
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
 </div>

data/website/index.txt

@@ -74,7 +74,19 @@ h2. How to submit patches
 
 Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8z: Email the project owner":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8z-email, use the Email below.
 
-The trunk repository is <code>svn://rubyforge.org/var/svn/rug-b/structured_warnings/trunk</code> for anonymous access.
+The trunk repository is <code>http://rug-b.rubyforge.org/svn/structured_warnings/trunk</code> for anonymous access.
+
+h2. 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://rug-b.rubyforge.org/structured_warnings/
+* "API doc":http://rug-b.rubyforge.org/structured_warnings/rdoc
+* "rug-b":http://www.rug-b.com
+* Other rug-b gems "in SVN":http://rug-b.rubyforge.org/svn/ and 
+  "to download":http://rubyforge.org/projects/rug-b
+
+
 
 h2. License
 

data/website/template.rhtml

@@ -8,9 +8,6 @@
       <%= title %>
   </title>
   <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
-<style>
-
-</style>
   <script type="text/javascript">
     window.onload = function() {
       settings = {
@@ -37,7 +34,7 @@
     </div>
     <%= body %>
     <p class="coda">
-      <a href="mailto:ruby@schmidtwisser.de">Gregor Schmidt</a>, <%= modified.pretty %><br>
+      <a href="mailto:ruby@schmidtwisser.de">Gregor Schmidt</a>, <%= modified.pretty %><br />
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
 </div>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: structured_warnings
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Gregor Schmidt
@@ -30,7 +30,7 @@ cert_chain:
   y3O9DT3o4BiyPe77
   -----END CERTIFICATE-----
 
-date: 2008-02-21 00:00:00 +01:00
+date: 2008-02-22 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -64,8 +64,6 @@ files:
 - lib/structured_warnings/version.rb
 - lib/structured_warnings/warner.rb
 - lib/structured_warnings/warning.rb
-- lib/structured_warnings/warnings.rb
-- log/debug.log
 - script/destroy
 - script/generate
 - script/txt2html

data/lib/structured_warnings/warnings.rb

@@ -1,3 +0,0 @@
-class DeprecationWarning < Warning; end
-class DeprecatedMethodWarning < DeprecationWarning; end
-class DeprecatedSignatureWarning < DeprecationWarning; end