X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/e9158b84fe735f37141c35ffabc02ac81dd2ea4b..a04e6aad3b10787abd99c78eeac04ca9f4b33d0b:/pod/perllexwarn.pod diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod index d632920..d604624 100644 --- a/pod/perllexwarn.pod +++ b/pod/perllexwarn.pod @@ -1,584 +1,11 @@ =head1 NAME -X X X perllexwarn - Perl Lexical Warnings =head1 DESCRIPTION -The C pragma enables to control precisely what warnings are -to be 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>. +Perl v5.6.0 introduced lexical control over the handling of warnings by +category. The C pragma generally replaces the command line flag +B<-w>. Documentation on the use of lexical warnings, once partly found in +this document, is now found in the L documentation. -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. - -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: - -=for comment -This tree is generated by regen/warnings.pl. Any changes made here -will be lost. - -=for warnings.pl begin - - all -+ - | - +- closure - | - +- deprecated - | - +- exiting - | - +- experimental --+ - | | - | +- experimental::lexical_subs - | | - | +- experimental::lexical_topic - | | - | +- experimental::postderef - | | - | +- experimental::regex_sets - | | - | +- 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 - -=for warnings.pl end - -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: In Perl 5.6.1, 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