[beast] DOXER: implement an alternative to assertions: non-fatal warnings. Bug #477275

[Stefan Westerfeld <stw src gnome org>]

commit 67820ab1f34e64b0abed7ecce990da6923d24c61
Author: Stefan Westerfeld <stefan space twc de>
Date:   Thu May 6 15:08:21 2010 +0200

    DOXER: implement an alternative to assertions: non-fatal warnings. Bug #477275
    
    Sat Sep 15 20:29:37 2007  Stefan Westerfeld  <stefan space twc de>
    
    	* Config.py: Implemented doxer_warn_if_fail() and
            doxer_warn_if_reached(), as alternative to assertions. For details on
    	why using these is better than assert(), see #477211.
    
    	* warntest.py: Added a small program which tests doxer_warn_if_fail()
    	and doxer_warn_if_reached().
    
    	* doxer.py: Handle --fatal-warnings which makes the program abort on
    	doxer_warn() warnings, so that a full stacktrace is shown.

 doxer/Config.py       |   21 +++++++++++++++++++++
 doxer/ManGenerator.py |    4 ++--
 doxer/doxer.py        |    3 +++
 3 files changed, 26 insertions(+), 2 deletions(-)
---
diff --git a/doxer/Config.py b/doxer/Config.py
index c901478..03bde25 100644
--- a/doxer/Config.py
+++ b/doxer/Config.py
@@ -2,6 +2,7 @@
 #
 # Doxer - Software documentation system
 # Copyright (C) 2005-2006 Tim Janik
+# Copyright (C) 2007 Stefan Westerfeld
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -72,6 +73,26 @@ class ConstDict:
           line += " "
         line += str (s)
       sys.stderr.write ("|> " + line + "\n")
+  # doxer warnings
+  def doxer_warn (self, msg, stacklevel=1):
+    class DoxerWarning (UserWarning):
+      """
+        Doxer's own warnings (we subclass to not conflict with installed warning filters)
+      """
+    import warnings
+    if self.__dict__.has_key ("fatal_warnings"):
+      raise msg
+    else:
+      warnings.warn (msg + ": ", DoxerWarning, stacklevel=stacklevel+1)
+  def doxer_warn_if_reached (self):
+    import inspect
+    frame_info = inspect.getframeinfo (inspect.currentframe (1))
+    self.doxer_warn ("doxer_warn_if_reached() encountered in function %s" % (frame_info[2]), 2)
+  def doxer_warn_if_fail (self, condition):
+    import inspect
+    if not condition:
+      frame_info = inspect.getframeinfo (inspect.currentframe (1))
+      self.doxer_warn ("doxer_warn_if_fail() failed in function %s" % (frame_info[2]), 2)
 
 # --- module interface ---
 sys.modules[__name__] = ConstDict (init_dict)
diff --git a/doxer/ManGenerator.py b/doxer/ManGenerator.py
index 7886aba..476f8bd 100644
--- a/doxer/ManGenerator.py
+++ b/doxer/ManGenerator.py
@@ -18,9 +18,9 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
 import os, sys, re, Config, Data, DoxiParser, warnings
+from Config import doxer_warn_if_reached
+
 def debug (*args): Config.debug_print (*args)
-def doxer_warn_if_reached():
-  warnings.warn ("doxer_warn_if_reached() triggered", stacklevel=2) # better implementation: see #477275
 
 # --- ManOStream ---
 class ManOStream:
diff --git a/doxer/doxer.py b/doxer/doxer.py
index 9be2fc3..8a06624 100755
--- a/doxer/doxer.py
+++ b/doxer/doxer.py
@@ -413,6 +413,8 @@ def parse_command_and_args():
     if arg == '--debug':
       Config.debug = True
       Config.print_traceback = True
+    elif arg == '--fatal-warnings':
+      Config.fatal_warnings = True
     elif arg == '--help' or arg == '-h':
       print_help ()
       sys.exit (0)
@@ -485,6 +487,7 @@ def print_help (with_help = True):
   print "  --help, -h                print this help message"
   print "  --version, -v             print version info"
   print "  --debug                   print debug information"
+  print "  --fatal-warnings          abort program on doxer_warn()"
   print "  -d OUTPUTDIR              write output to OUTPUTDIR/ (defaults to ./)"
   print "  -D name value             define 'name' to 'value'"
   print "  -I DIRECTORY              add DIRECTORY to include path"