View of /trunk/webwork2/lib/WeBWorK/Debug.pm

    1 ################################################################################
    2 # WeBWorK Online Homework Delivery System
    3 # Copyright © 2000-2003 The WeBWorK Project, http://openwebwork.sf.net/
    4 # $CVSHeader: webwork2/lib/WeBWorK/Debug.pm,v 1.5 2005/08/12 02:47:28 sh002i Exp $
    5 #
    6 # This program is free software; you can redistribute it and/or modify it under
    7 # the terms of either: (a) the GNU General Public License as published by the
    8 # Free Software Foundation; either version 2, or (at your option) any later
    9 # version, or (b) the "Artistic License" which comes with this package.
   10 #
   11 # This program is distributed in the hope that it will be useful, but WITHOUT
   12 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
   13 # FOR A PARTICULAR PURPOSE.  See either the GNU General Public License or the
   14 # Artistic License for more details.
   15 ################################################################################
   16 
   17 package WeBWorK::Debug;
   18 use base qw(Exporter);
   19 use Date::Format;
   20 our @EXPORT = qw(debug);
   21 
   22 =head1 NAME
   23 
   24 WeBWorK::Debug - Print (or don't print) debugging output.
   25 
   26 head1 SYNOPSIS
   27 
   28  use WeBWorK::Debug;
   29 
   30  # Enable debugging
   31  $WeBWorK::Debug::Enabled = 1;
   32 
   33  # Log to a file instead of STDERR
   34  $WeBWorK::Debug::Logfile = "/path/to/debug.log";
   35 
   36  # log some debugging output
   37  debug("Generated 5 widgets.");
   38 
   39 =cut
   40 
   41 use strict;
   42 use warnings;
   43 use Time::HiRes qw/gettimeofday/;
   44 
   45 ################################################################################
   46 
   47 =head1 CONFIGURATION VARIABLES
   48 
   49 =over
   50 
   51 =item $Enabled
   52 
   53 If true, debugging messages will be output. If false, they will be ignored.
   54 
   55 =cut
   56 
   57 our $Enabled = 0 unless defined $Enabled;
   58 
   59 =item $Logfile
   60 
   61 If non-empty, debugging output will be sent to the file named rather than STDERR.
   62 
   63 =cut
   64 
   65 our $Logfile = "" unless defined $Logfile;
   66 
   67 =item $DenySubroutineOutput
   68 
   69 If defined, prevent subroutines matching the following regular expression from
   70 logging.
   71 
   72 =cut
   73 
   74 our $DenySubroutineOutput;
   75 
   76 =item $AllowSubroutineOutput
   77 
   78 If defined, allow only subroutines matching the following regular expression to
   79 log.
   80 
   81 =cut
   82 
   83 our $AllowSubroutineOutput;
   84 
   85 =back
   86 
   87 =cut
   88 
   89 ################################################################################
   90 
   91 =head1 FUNCTIONS
   92 
   93 =over
   94 
   95 =item debug(@messages)
   96 
   97 Write @messages to the debugging log.
   98 
   99 =cut
  100 
  101 sub debug {
  102   my (@message) = @_;
  103 
  104   if ($Enabled) {
  105     my ($package, $filename, $line, $subroutine) = caller(1);
  106     return if defined $AllowSubroutineOutput and not $subroutine =~ m/$AllowSubroutineOutput/;
  107     return if defined $DenySubroutineOutput and $subroutine =~ m/$DenySubroutineOutput/;
  108 
  109     my ($sec, $msec) = gettimeofday;
  110     my $date = time2str("%a %b %d %H:%M:%S.$msec %Y", $sec);
  111     my $finalMessage = "[$date] $subroutine: " . join("", @message);
  112     $finalMessage .= "\n" unless $finalMessage =~ m/\n$/;
  113 
  114     if ($WeBWorK::Debug::Logfile ne "") {
  115       if (open my $fh, ">>", $Logfile) {
  116         print $fh $finalMessage;
  117         close $fh;
  118       } else {
  119         warn "Failed to open debug log '$Logfile' in append mode: $!";
  120         print STDERR $finalMessage;
  121       }
  122     } else {
  123       print STDERR $finalMessage;
  124     }
  125   }
  126 }
  127 
  128 =back
  129 
  130 =cut
  131 
  132 ################################################################################
  133 
  134 =head1 AUTHOR
  135 
  136 Written by Sam Hathaway, sh002i (at) math.rochester.edu.
  137 
  138 =cut
  139 
  140 1;