X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperllexwarn.pod;h=0052d33ff2bc44e2d25461e6eef4cf8f9fb3347e;hb=40b568c93a31cb8feae8a14551365dff7e76b624;hp=81f44cca3afc1738d86a432a19bfe3b6a767e48a;hpb=9cbb5ea2917cb666eed5655eac07566f07548487;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod index 81f44cc..0052d33 100644 --- a/pod/perllexwarn.pod +++ b/pod/perllexwarn.pod @@ -3,13 +3,13 @@ perllexwarn - Perl Lexical Warnings =head1 DESCRIPTION - -The C pragma is a replacement for both the command line + +The C pragma is a replacement for both the command line flag B<-w> and the equivalent Perl variable, C<$^W>. The pragma works just like the existing "strict" pragma. This means that the scope of the warning pragma is limited to the -enclosing block. It also means that that the pragma setting will not +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. @@ -18,22 +18,22 @@ 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 warning ; - use warning 'all' ; - + + use warnings ; + use warnings 'all' ; + Similarly all warnings are disabled in a block by either of these: - no warning ; - no warning 'all' ; + no warnings ; + no warnings 'all' ; For example, consider the code below: - use warning ; + use warnings ; my $a ; my $b ; { - no warning ; + no warnings ; $b = 2 if $a EQ 3 ; } $b = 1 if $a NE 3 ; @@ -55,17 +55,15 @@ warning about the "2:". my $a = "2:" + 3; -though the result will be 5. - 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<"integer overflow"> warning will only +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 warning ; + no warnings ; my $b = "2:" + 3; Note that neither the B<-w> flag or the C<$^W> can be used to @@ -140,10 +138,10 @@ will enable warnings everywhere. See L for details of how this flag interacts with lexical warnings. =item B<-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 +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. @@ -160,14 +158,15 @@ 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> or lexical warnings are used, -then default warnings will be enabled and optional warnings disabled. +control warnings is used and neither C<$^W> or 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. @@ -178,129 +177,241 @@ 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 lexical warning pragma, + +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 will allow code which uses -the lexical warning pragma to control the warning behavior of $^W-type +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. -=head1 EXPERIMENTAL FEATURES - -The features described in this section are experimental, and so subject -to change. - =head2 Category Hierarchy - -A B hierarchy of "categories" have been defined to allow groups -of warnings to be enabled/disabled in isolation. The current -hierarchy is: - - all - +--- unsafe -------+--- taint - | | - | +--- substr - | | - | +--- signal - | | - | +--- closure - | | - | +--- untie - | | - | +--- utf8 - | - +--- io ---------+--- pipe - | | - | +--- unopened - | | - | +--- closed - | | - | +--- newline - | | - | +--- exec - | - +--- syntax ----+--- ambiguous - | | - | +--- semicolon - | | - | +--- precedence - | | - | +--- reserved - | | - | +--- octal - | | - | +--- parenthesis - | | - | +--- deprecated - | | - | +--- printf - | - +--- severe ----+--- inplace - | | - | +--- internal - | | - | +--- debugging - | - |--- uninitialized - | - +--- void - | - +--- recursion - | - +--- redefine - | - +--- numeric - | - +--- once - | - +--- misc - - -Just like the "strict" pragma any of these categories can be -combined - - use warning qw(void redefine) ; - no warning qw(io syntax untie) ; + +A hierarchy of "categories" have been defined to allow groups of warnings +to be enabled/disabled in isolation. + +The current hierarchy is: + + all -+ + | + +- chmod + | + +- closure + | + +- exiting + | + +- glob + | + +- io -----------+ + | | + | +- closed + | | + | +- exec + | | + | +- newline + | | + | +- pipe + | | + | +- unopened + | + +- misc + | + +- numeric + | + +- once + | + +- overflow + | + +- pack + | + +- portable + | + +- recursion + | + +- redefine + | + +- regexp + | + +- severe -------+ + | | + | +- debugging + | | + | +- inplace + | | + | +- internal + | | + | +- malloc + | + +- signal + | + +- substr + | + +- syntax -------+ + | | + | +- ambiguous + | | + | +- bareword + | | + | +- deprecated + | | + | +- digit + | | + | +- parenthesis + | | + | +- precedence + | | + | +- printf + | | + | +- prototype + | | + | +- qw + | | + | +- reserved + | | + | +- semicolon + | + +- taint + | + +- umask + | + +- uninitialized + | + +- unpack + | + +- untie + | + +- utf8 + | + +- void + | + +- y2k + +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. =head2 Fatal Warnings - -This feature is B experimental. - + The presence of the word "FATAL" in the category list will escalate any -warnings from the category specified that are detected in the lexical -scope into fatal errors. In the code below, there are 3 places where -a deprecated warning will be detected, the middle one will produce a +warnings detected from the categories specified in the lexical scope +into fatal errors. In the code below, there are 3 places where a +deprecated warning will be detected, the middle one will produce a fatal error. - - - use warning ; - + + + use warnings ; + $a = 1 if $a EQ $b ; - + { - use warning qw(FATAL deprecated) ; + use warnings FATAL => qw(deprecated) ; $a = 1 if $a EQ $b ; } - + $a = 1 if $a EQ $b ; - + +=head2 Reporting Warnings from a Module + +The C pragma provides a number of functions that are useful for +module authors. These are used when you want to report a module-specific +warning when the calling module has enabled warnings via the C +pragma. + +Consider the module C below. + + package MyMod::Abc; + + use warnings::register; + + sub open { + my $path = shift ; + if (warnings::enabled() && $path !~ m#^/#) { + warnings::warn("changing relative path to /tmp/"); + $path = "/tmp/$path" ; + } + } + + 1 ; + +The call to C will create a new warnings category +called "MyMod::abc", i.e. the new category name matches the module +name. The C function in the module will display a warning message +if it gets given a relative path as a parameter. This warnings will only +be displayed if the code that uses C has actually enabled +them with the C pragma like below. + + use MyMod::Abc; + use warnings 'MyMod::Abc'; + ... + abc::open("../fred.txt"); + +It is also possible to test whether the pre-defined warnings categories are +set in the calling module with the C function. Consider +this snippet of code: + + package MyMod::Abc; + + sub open { + if (warnings::enabled("deprecated")) { + warnings::warn("deprecated", + "open is deprecated, use new instead") ; + } + new(@_) ; + } + + sub new + ... + 1 ; + +The function C has been deprecated, so code has been included to +display a warning message whenever the calling module has (at least) the +"deprecated" warnings category enabled. Something like this, say. + + use warnings 'deprecated'; + use MyMod::Abc; + ... + MyMod::Abc::open($filename) ; + +The C function should be used to actually display the +warnings message. This is because they can make use of the feature that +allows warnings to be escalated into fatal errors. So in this case + + use MyMod::Abc; + use warnings FATAL => 'MyMod::Abc'; + ... + MyMod::Abc::open('../fred.txt'); + +the C function will detect this and die after +displaying the warning message. + =head1 TODO - -The experimental features need bottomed out. perl5db.pl The debugger saves and restores C<$^W> at runtime. I haven't checked @@ -313,14 +424,10 @@ The experimental features need bottomed out. around the limitations of C<$^W>. Now that those limitations are gone, the module should be revisited. - octal - 'octal' controls illegal octal characters warning, but 'unsafe' controls - illegal hexadecimal and binary characters warnings. - =head1 SEE ALSO -L. - +L, L. + =head1 AUTHOR - + Paul Marquess