From a7f2b7af293abc1754863e50deb95f196276d197 Mon Sep 17 00:00:00 2001 From: Ricardo Signes Date: Tue, 18 Mar 2014 13:29:42 -0400 Subject: [PATCH] regenerate warnings.pm --- lib/warnings.pm | 600 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 586 insertions(+), 14 deletions(-) diff --git a/lib/warnings.pm b/lib/warnings.pm index 38f9ce2..059c7c5 100644 --- a/lib/warnings.pm +++ b/lib/warnings.pm @@ -5,7 +5,7 @@ package warnings; -our $VERSION = '1.22'; +our $VERSION = '1.23'; # Verify that we're called correctly so that warnings will work. # see also strict.pm. @@ -45,15 +45,587 @@ warnings - Perl pragma to control optional warnings =head1 DESCRIPTION -The C pragma is a replacement for the command line flag C<-w>, -but the pragma is limited to the enclosing block, while the flag is global. -See L for more information and the list of built-in warning -categories. +The C pragma gives control over which warnings are enabled in +which parts of a Perl program. It's a more flexible alternative for +both the command line flag B<-w> and the equivalent Perl variable, +C<$^W>. -If no import list is supplied, all possible warnings are either enabled -or disabled. +This pragma works just like the C pragma. +This means that the scope of the warning pragma is limited to the +enclosing block. It also means that the pragma setting will not +leak across files (via C, C or C). This allows +authors to independently define the degree of warning checks that will +be applied to their module. -A number of functions are provided to assist module authors. +By default, optional warnings are disabled, so any legacy code that +doesn't attempt to control the warnings will work unchanged. + +All warnings are enabled in a block by either of these: + + use warnings; + use warnings 'all'; + +Similarly all warnings are disabled in a block by either of these: + + no warnings; + no warnings 'all'; + +For example, consider the code below: + + use warnings; + my @a; + { + no warnings; + my $b = @a[0]; + } + my $c = @a[0]; + +The code in the enclosing block has warnings enabled, but the inner +block has them disabled. In this case that means the assignment to the +scalar C<$c> will trip the C<"Scalar value @a[0] better written as $a[0]"> +warning, but the assignment to the scalar C<$b> will not. + +=head2 Default Warnings and Optional Warnings + +Before the introduction of lexical warnings, Perl had two classes of +warnings: mandatory and optional. + +As its name suggests, if your code tripped a mandatory warning, you +would get a warning whether you wanted it or not. +For example, the code below would always produce an C<"isn't numeric"> +warning about the "2:". + + my $a = "2:" + 3; + +With the introduction of lexical warnings, mandatory warnings now become +I warnings. The difference is that although the previously +mandatory warnings are still enabled by default, they can then be +subsequently enabled or disabled with the lexical warning pragma. For +example, in the code below, an C<"isn't numeric"> warning will only +be reported for the C<$a> variable. + + my $a = "2:" + 3; + no warnings; + my $b = "2:" + 3; + +Note that neither the B<-w> flag or the C<$^W> can be used to +disable/enable default warnings. They are still mandatory in this case. + +=head2 What's wrong with B<-w> and C<$^W> + +Although very useful, the big problem with using B<-w> on the command +line to enable warnings is that it is all or nothing. Take the typical +scenario when you are writing a Perl program. Parts of the code you +will write yourself, but it's very likely that you will make use of +pre-written Perl modules. If you use the B<-w> flag in this case, you +end up enabling warnings in pieces of code that you haven't written. + +Similarly, using C<$^W> to either disable or enable blocks of code is +fundamentally flawed. For a start, say you want to disable warnings in +a block of code. You might expect this to be enough to do the trick: + + { + local ($^W) = 0; + my $a =+ 2; + my $b; chop $b; + } + +When this code is run with the B<-w> flag, a warning will be produced +for the C<$a> line: C<"Reversed += operator">. + +The problem is that Perl has both compile-time and run-time warnings. To +disable compile-time warnings you need to rewrite the code like this: + + { + BEGIN { $^W = 0 } + my $a =+ 2; + my $b; chop $b; + } + +The other big problem with C<$^W> is the way you can inadvertently +change the warning setting in unexpected places in your code. For example, +when the code below is run (without the B<-w> flag), the second call +to C will trip a C<"Use of uninitialized value"> warning, whereas +the first will not. + + sub doit + { + my $b; chop $b; + } + + doit(); + + { + local ($^W) = 1; + doit() + } + +This is a side-effect of C<$^W> being dynamically scoped. + +Lexical warnings get around these limitations by allowing finer control +over where warnings can or can't be tripped. + +=head2 Controlling Warnings from the Command Line + +There are three Command Line flags that can be used to control when +warnings are (or aren't) produced: + +=over 5 + +=item B<-w> +X<-w> + +This is the existing flag. If the lexical warnings pragma is B +used in any of you code, or any of the modules that you use, this flag +will enable warnings everywhere. See L for +details of how this flag interacts with lexical warnings. + +=item B<-W> +X<-W> + +If the B<-W> flag is used on the command line, it will enable all warnings +throughout the program regardless of whether warnings were disabled +locally using C or C<$^W =0>. +This includes all files that get +included via C, C or C. +Think of it as the Perl equivalent of the "lint" command. + +=item B<-X> +X<-X> + +Does the exact opposite to the B<-W> flag, i.e. it disables all warnings. + +=back + +=head2 Backward Compatibility + +If you are used to working with a version of Perl prior to the +introduction of lexically scoped warnings, or have code that uses both +lexical warnings and C<$^W>, this section will describe how they interact. + +How Lexical Warnings interact with B<-w>/C<$^W>: + +=over 5 + +=item 1. + +If none of the three command line flags (B<-w>, B<-W> or B<-X>) that +control warnings is used and neither C<$^W> nor the C pragma +are used, then default warnings will be enabled and optional warnings +disabled. +This means that legacy code that doesn't attempt to control the warnings +will work unchanged. + +=item 2. + +The B<-w> flag just sets the global C<$^W> variable as in 5.005. This +means that any legacy code that currently relies on manipulating C<$^W> +to control warning behavior will still work as is. + +=item 3. + +Apart from now being a boolean, the C<$^W> variable operates in exactly +the same horrible uncontrolled global way, except that it cannot +disable/enable default warnings. + +=item 4. + +If a piece of code is under the control of the C pragma, +both the C<$^W> variable and the B<-w> flag will be ignored for the +scope of the lexical warning. + +=item 5. + +The only way to override a lexical warnings setting is with the B<-W> +or B<-X> command line flags. + +=back + +The combined effect of 3 & 4 is that it will allow code which uses +the C pragma to control the warning behavior of $^W-type +code (using a C) if it really wants to, but not vice-versa. + +=head2 Category Hierarchy +X + +A hierarchy of "categories" have been defined to allow groups of warnings +to be enabled/disabled in isolation. + +The current hierarchy is: + + all -+ + | + +- closure + | + +- deprecated + | + +- exiting + | + +- experimental --+ + | | + | +- experimental::autoderef + | | + | +- experimental::lexical_subs + | | + | +- experimental::lexical_topic + | | + | +- experimental::postderef + | | + | +- experimental::regex_sets + | | + | +- experimental::signatures + | | + | +- experimental::smartmatch + | + +- glob + | + +- imprecision + | + +- io ------------+ + | | + | +- closed + | | + | +- exec + | | + | +- layer + | | + | +- newline + | | + | +- pipe + | | + | +- syscalls + | | + | +- unopened + | + +- misc + | + +- numeric + | + +- once + | + +- overflow + | + +- pack + | + +- portable + | + +- recursion + | + +- redefine + | + +- regexp + | + +- severe --------+ + | | + | +- debugging + | | + | +- inplace + | | + | +- internal + | | + | +- malloc + | + +- signal + | + +- substr + | + +- syntax --------+ + | | + | +- ambiguous + | | + | +- bareword + | | + | +- digit + | | + | +- illegalproto + | | + | +- parenthesis + | | + | +- precedence + | | + | +- printf + | | + | +- prototype + | | + | +- qw + | | + | +- reserved + | | + | +- semicolon + | + +- taint + | + +- threads + | + +- uninitialized + | + +- unpack + | + +- untie + | + +- utf8 ----------+ + | | + | +- non_unicode + | | + | +- nonchar + | | + | +- surrogate + | + +- void + +Just like the "strict" pragma any of these categories can be combined + + use warnings qw(void redefine); + no warnings qw(io syntax untie); + +Also like the "strict" pragma, if there is more than one instance of the +C pragma in a given scope the cumulative effect is additive. + + use warnings qw(void); # only "void" warnings enabled + ... + use warnings qw(io); # only "void" & "io" warnings enabled + ... + no warnings qw(void); # only "io" warnings enabled + +To determine which category a specific warning has been assigned to see +L. + +Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a +sub-category of the "syntax" category. It is now a top-level category +in its own right. + +=head2 Fatal Warnings +X + +The presence of the word "FATAL" in the category list will escalate any +warnings detected from the categories specified in the lexical scope +into fatal errors. In the code below, the use of C