# Copyright (C) 2002 Free Software Foundation, Inc. # 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 # the Free Software Foundation; either version 2, or (at your option) # any later version. # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA # 02111-1307, USA. package Autom4te::Channels; =head1 NAME Autom4te::Channels - support functions for error and warning management =head1 SYNOPSIS use Autom4te::Channels; # Register a channel to output warnings about unused variables. register_channel 'unused', type => 'warning'; # Register a channel for system errors. register_channel 'system', type => 'error', exit_code => 4; # Output a message on channel 'unused'. msg 'unused', "$file:$line", "unused variable `$var'"; # Make the 'unused' channel silent. setup_channel 'unused', silent => 1; # Turn on all channels of type 'warning'. setup_channel_type 'warning', silent => 0; # Treat all warnings as errors. $warnings_are_errors = 1; # Exit with the greater exist code encountered so far. exit $exit_code; =head1 DESCRIPTION This perl module provides support functions for handling diagnostic channels in programs. Channels can be registered to convey fatal, error, warning, or debug messages. Each channel has various options (e.g. is the channel silent, should duplicate messages be removed, etc.) that can also be overridden on a per-message basis. =cut use 5.005; use strict; use Exporter; use Carp; use File::Basename; use vars qw (@ISA @EXPORT %channels $me); @ISA = qw (Exporter); @EXPORT = qw ($exit_code $warnings_are_errors &reset_local_duplicates &reset_global_duplicates ®ister_channel &msg &exists_channel &channel_type &setup_channel &setup_channel_type &dup_channel_setup &drop_channel_setup &buffer_messages &flush_messages US_GLOBAL US_LOCAL UP_NONE UP_TEXT UP_LOC_TEXT); $me = basename $0; =head2 Global Variables =over 4 =item C<$exit_code> The greatest exit code seen so far. C<$exit_code> is updated from the C options of C and C channels. =cut use vars qw ($exit_code); $exit_code = 0; =item C<$warnings_are_errors> Set this variable to 1 if warning messages should be treated as errors (i.e. if they should update C<$exit_code>). =cut use vars qw ($warnings_are_errors); $warnings_are_errors = 0; =back =head2 Constants =over 4 =item C, C, C Possible values for the C options. This select the part of the message that should be considered when filtering out duplicates. If C is used, the location and the explanation message are used for filtering. If C is used, only the explanation message is used (so the same message will be filtered out if it appears at different locations). C means that duplicate messages should be output. =cut use constant UP_NONE => 0; use constant UP_TEXT => 1; use constant UP_LOC_TEXT => 2; =item C, C Possible values for the C options. Use C for error messages that should be printed only once in the run of the program, C for message that should be printed only once per file. (Actually, C does not now when files are changed, it relies on you calling C when this happens.) =cut # possible values for uniq_scope use constant US_LOCAL => 0; use constant US_GLOBAL => 1; =back =head2 Options Channels accept the options described below. These options can be passed as a hash to the C, C, and C functions. The possible keys, with there default value are: =over =item C 'warning'> The type of the channel. One of C<'debug'>, C<'warning'>, C<'error'>, or C<'fatal'>. Fatal messages abort the program when they are output. Error messages update the exit status. Debug and warning messages are harmless, except that warnings can be treated as errors of C<$warnings_are_errors> is set. =item C 1> The value to update C<$exit_code> with when a fatal or error message is emited. C<$exit_code> is also updated for warnings output when @<$warnings_are_errors> is set. =item C \*STDERR> The file where the error should be output. =item C 0> Whether the channel should be silent. Use this do disable a category of warning, for instance. =item C UP_LOC_TEXT> The part of the message subject to duplicate filtering. See the documentation for the C, C, and C constants above. =item C US_LOCAL> The scope of duplicate filtering. See the documentation for the C, and C constants above. =item C
''> A string to prepend to each message emitted through this channel. =item C