1# Copyright (C) 2002, 2003, 2006 Free Software Foundation, Inc.
2
3# This program is free software; you can redistribute it and/or modify
4# it under the terms of the GNU General Public License as published by
5# the Free Software Foundation; either version 2, or (at your option)
6# any later version.
7
8# This program is distributed in the hope that it will be useful,
9# but WITHOUT ANY WARRANTY; without even the implied warranty of
10# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11# GNU General Public License for more details.
12
13# You should have received a copy of the GNU General Public License
14# along with this program; if not, write to the Free Software
15# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
16# 02110-1301, USA.
17
18package Autom4te::ChannelDefs;
19
20use Autom4te::Channels;
21
22=head1 NAME
23
24Autom4te::ChannelDefs - channel definitions for Automake and helper functions
25
26=head1 SYNOPSIS
27
28  use Autom4te::ChannelDefs;
29
30  print Autom4te::ChannelDefs::usage (), "\n";
31  prog_error ($MESSAGE, [%OPTIONS]);
32  error ($WHERE, $MESSAGE, [%OPTIONS]);
33  error ($MESSAGE);
34  fatal ($WHERE, $MESSAGE, [%OPTIONS]);
35  fatal ($MESSAGE);
36  verb ($MESSAGE, [%OPTIONS]);
37  switch_warning ($CATEGORY);
38  parse_WARNINGS ();
39  parse_warnings ($OPTION, $ARGUMENT);
40  Autom4te::ChannelDefs::set_strictness ($STRICTNESS_NAME);
41
42=head1 DESCRIPTION
43
44This packages defines channels that can be used in Automake to
45output diagnostics and other messages (via C<msg()>).  It also defines
46some helper function to enable or disable these channels, and some
47shorthand function to output on specific channels.
48
49=cut
50
51use 5.005;
52use strict;
53use Exporter;
54
55use vars qw (@ISA @EXPORT);
56
57@ISA = qw (Exporter);
58@EXPORT = qw (&prog_error &error &fatal &verb
59	      &switch_warning &parse_WARNINGS &parse_warnings);
60
61=head2 CHANNELS
62
63The following channels can be used as the first argument of
64C<Autom4te::Channel::msg>.  For some of them we list a shorthand
65function that makes the code more readable.
66
67=over 4
68
69=item C<fatal>
70
71Fatal errors.  Use C<&fatal> to send messages over this channel.
72
73=item C<error>
74
75Common errors.   Use C<&error> to send messages over this channel.
76
77=item C<error-gnu>
78
79Errors related to GNU Standards.
80
81=item C<error-gnu/warn>
82
83Errors related to GNU Standards that should be warnings in "foreign" mode.
84
85=item C<error-gnits>
86
87Errors related to GNITS Standards (silent by default).
88
89=item C<automake>
90
91Internal errors.  Use C<&prog_error> to send messages over this channel.
92
93=item C<cross>
94
95Constructs compromising the cross-compilation of the package.
96
97=item C<gnu>
98
99Warnings related to GNU Coding Standards.
100
101=item C<obsolete>
102
103Warnings about obsolete features (silent by default).
104
105=item C<override>
106
107Warnings about user redefinitions of Automake rules or
108variables (silent by default).
109
110=item C<portability>
111
112Warnings about non-portable constructs.
113
114=item C<syntax>
115
116Warnings about weird syntax, unused variables, typos...
117
118=item C<unsupported>
119
120Warnings about unsupported (or mis-supported) features.
121
122=item C<verb>
123
124Messages output in C<--verbose> mode.  Use C<&verb> to send such messages.
125
126=item C<note>
127
128Informative messages.
129
130=back
131
132=cut
133
134# Initialize our list of error/warning channels.
135# Do not forget to update &usage and the manual
136# if you add or change a warning channel.
137
138register_channel 'fatal', type => 'fatal';
139register_channel 'error', type => 'error';
140register_channel 'error-gnu', type => 'error';
141register_channel 'error-gnu/warn', type => 'error';
142register_channel 'error-gnits', type => 'error', silent => 1;
143register_channel 'automake', type => 'fatal', backtrace => 1,
144  header => ("####################\n" .
145	     "## Internal Error ##\n" .
146	     "####################\n"),
147  footer => "\nPlease contact <bug-automake\@gnu.org>.";
148
149register_channel 'cross', type => 'warning', silent => 1;
150register_channel 'gnu', type => 'warning';
151register_channel 'obsolete', type => 'warning', silent => 1;
152register_channel 'override', type => 'warning', silent => 1;
153register_channel 'portability', type => 'warning', silent => 1;
154register_channel 'syntax', type => 'warning';
155register_channel 'unsupported', type => 'warning';
156
157register_channel 'verb', type => 'debug', silent => 1;
158register_channel 'note', type => 'debug', silent => 0;
159
160=head2 FUNCTIONS
161
162=over 4
163
164=item C<usage ()>
165
166Return the warning category descriptions.
167
168=cut
169
170sub usage ()
171{
172  return "Warning categories include:
173  `cross'         cross compilation issues
174  `gnu'           GNU coding standards (default in gnu and gnits modes)
175  `obsolete'      obsolete features or constructions
176  `override'      user redefinitions of Automake rules or variables
177  `portability'   portability issues (default in gnu and gnits modes)
178  `syntax'        dubious syntactic constructs (default)
179  `unsupported'   unsupported or incomplete features (default)
180  `all'           all the warnings
181  `no-CATEGORY'   turn off warnings in CATEGORY
182  `none'          turn off all the warnings
183  `error'         treat warnings as errors";
184}
185
186=item C<prog_error ($MESSAGE, [%OPTIONS])>
187
188Signal a programming error (on channel C<automake>),
189display C<$MESSAGE>, and exit 1.
190
191=cut
192
193sub prog_error ($;%)
194{
195  my ($msg, %opts) = @_;
196  msg 'automake', '', $msg, %opts;
197}
198
199=item C<error ($WHERE, $MESSAGE, [%OPTIONS])>
200
201=item C<error ($MESSAGE)>
202
203Uncategorized errors.
204
205=cut
206
207sub error ($;$%)
208{
209  my ($where, $msg, %opts) = @_;
210  msg ('error', $where, $msg, %opts);
211}
212
213=item C<fatal ($WHERE, $MESSAGE, [%OPTIONS])>
214
215=item C<fatal ($MESSAGE)>
216
217Fatal errors.
218
219=cut
220
221sub fatal ($;$%)
222{
223  my ($where, $msg, %opts) = @_;
224  msg ('fatal', $where, $msg, %opts);
225}
226
227=item C<verb ($MESSAGE, [%OPTIONS])>
228
229C<--verbose> messages.
230
231=cut
232
233sub verb ($;%)
234{
235  my ($msg, %opts) = @_;
236  msg 'verb', '', $msg, %opts;
237}
238
239=item C<switch_warning ($CATEGORY)>
240
241If C<$CATEGORY> is C<mumble>, turn on channel C<mumble>.
242If it is C<no-mumble>, turn C<mumble> off.
243Else handle C<all> and C<none> for completeness.
244
245=cut
246
247sub switch_warning ($)
248{
249  my ($cat) = @_;
250  my $has_no = 0;
251
252  if ($cat =~ /^no-(.*)$/)
253    {
254      $cat = $1;
255      $has_no = 1;
256    }
257
258  if ($cat eq 'all')
259    {
260      setup_channel_type 'warning', silent => $has_no;
261    }
262  elsif ($cat eq 'none')
263    {
264      setup_channel_type 'warning', silent => ! $has_no;
265    }
266  elsif ($cat eq 'error')
267    {
268      $warnings_are_errors = ! $has_no;
269      # Set exit code if Perl warns about something
270      # (like uninitialized variables).
271      $SIG{"__WARN__"} =
272	$has_no ? 'DEFAULT' : sub { print STDERR @_; $exit_code = 1; };
273    }
274  elsif (channel_type ($cat) eq 'warning')
275    {
276      setup_channel $cat, silent => $has_no;
277    }
278  else
279    {
280      return 1;
281    }
282  return 0;
283}
284
285=item C<parse_WARNINGS ()>
286
287Parse the WARNINGS environment variable.
288
289=cut
290
291sub parse_WARNINGS ()
292{
293  if (exists $ENV{'WARNINGS'})
294    {
295      # Ignore unknown categories.  This is required because WARNINGS
296      # should be honored by many tools.
297      switch_warning $_ foreach (split (',', $ENV{'WARNINGS'}));
298    }
299}
300
301=item C<parse_warnings ($OPTION, @ARGUMENT)>
302
303Parse the argument of C<--warning=CATEGORY> or C<-WCATEGORY>.
304
305C<$OPTIONS> is C<"--warning"> or C<"-W">, C<@ARGUMENT> is a list of
306C<CATEGORY>.
307
308This can be used as a argument to C<Getopt>.
309
310=cut
311
312sub parse_warnings ($@)
313{
314  my ($opt, @categories) = @_;
315
316  foreach my $cat (map { split ',' } @categories)
317    {
318      msg 'unsupported', "unknown warning category `$cat'"
319	if switch_warning $cat;
320    }
321}
322
323=item C<set_strictness ($STRICTNESS_NAME)>
324
325Configure channels for strictness C<$STRICTNESS_NAME>.
326
327=cut
328
329sub set_strictness ($)
330{
331  my ($name) = @_;
332
333  if ($name eq 'gnu')
334    {
335      setup_channel 'error-gnu', silent => 0;
336      setup_channel 'error-gnu/warn', silent => 0, type => 'error';
337      setup_channel 'error-gnits', silent => 1;
338      setup_channel 'portability', silent => 0;
339      setup_channel 'gnu', silent => 0;
340    }
341  elsif ($name eq 'gnits')
342    {
343      setup_channel 'error-gnu', silent => 0;
344      setup_channel 'error-gnu/warn', silent => 0, type => 'error';
345      setup_channel 'error-gnits', silent => 0;
346      setup_channel 'portability', silent => 0;
347      setup_channel 'gnu', silent => 0;
348    }
349  elsif ($name eq 'foreign')
350    {
351      setup_channel 'error-gnu', silent => 1;
352      setup_channel 'error-gnu/warn', silent => 0, type => 'warning';
353      setup_channel 'error-gnits', silent => 1;
354      setup_channel 'portability', silent => 1;
355      setup_channel 'gnu', silent => 1;
356    }
357  else
358    {
359      prog_error "level `$name' not recognized\n";
360    }
361}
362
363=back
364
365=head1 SEE ALSO
366
367L<Autom4te::Channels>
368
369=head1 HISTORY
370
371Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt>.
372
373=cut
374
375### Setup "GNU" style for perl-mode and cperl-mode.
376## Local Variables:
377## perl-indent-level: 2
378## perl-continued-statement-offset: 2
379## perl-continued-brace-offset: 0
380## perl-brace-offset: 0
381## perl-brace-imaginary-offset: 0
382## perl-label-offset: -2
383## cperl-indent-level: 2
384## cperl-brace-offset: 0
385## cperl-continued-brace-offset: 0
386## cperl-label-offset: -2
387## cperl-extra-newline-before-brace: t
388## cperl-merge-trailing-else: nil
389## cperl-continued-statement-offset: 2
390## End:
391