X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperllexwarn.pod;h=0052d33ff2bc44e2d25461e6eef4cf8f9fb3347e;hb=40b568c93a31cb8feae8a14551365dff7e76b624;hp=6078aefd96a3c81da54f25b2179f8148f681f1fd;hpb=5a3e78123e3b27b54e7f651bd5fa051044f04189;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod index 6078aef..0052d33 100644 --- a/pod/perllexwarn.pod +++ b/pod/perllexwarn.pod @@ -9,7 +9,7 @@ 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,10 +18,10 @@ 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 ; @@ -55,13 +55,11 @@ 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; @@ -140,7 +138,7 @@ 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 @@ -166,8 +164,9 @@ How Lexical Warnings interact with B<-w>/C<$^W>: =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,101 +177,128 @@ 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 warnings 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 - | | - | +--- overflow - | | - | +--- portable - | | - | +--- untie - | | - | +--- utf8 - | - +--- io ---------+--- pipe - | | - | +--- unopened - | | - | +--- closed - | | - | +--- newline - | | - | +--- exec - | - +--- syntax ----+--- ambiguous - | | - | +--- semicolon - | | - | +--- precedence - | | - | +--- reserved - | | - | +--- digit - | | - | +--- parenthesis - | | - | +--- deprecated - | | - | +--- printf - | - +--- severe ----+--- inplace - | | - | +--- internal - | | - | +--- debugging - | - |--- uninitialized - | - +--- void - | - +--- recursion - | - +--- redefine - | - +--- numeric - | - +--- once - | - +--- misc +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 @@ -280,7 +306,7 @@ Just like the "strict" pragma any of these categories can be combined no warnings qw(io syntax untie) ; Also like the "strict" pragma, if there is more than one instance of the -warnings pragma in a given scope the cumulative effect is additive. +C pragma in a given scope the cumulative effect is additive. use warnings qw(void) ; # only "void" warnings enabled ... @@ -288,34 +314,104 @@ warnings pragma in a given scope the cumulative effect is additive. ... no warnings qw(void) ; # only "io" warnings enabled +To determine which category a specific warning has been assigned to see +L. =head2 Fatal Warnings - + The presence of the word "FATAL" in the category list will escalate any -warnings from the category/categories 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 fatal error. +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 warnings ; - + $a = 1 if $a EQ $b ; - + { use warnings FATAL => qw(deprecated) ; $a = 1 if $a EQ $b ; } - + $a = 1 if $a EQ $b ; - -=head1 TODO - -The experimental features need bottomed out. - perldiag.pod - Need to add warning class information and notes on - how to use the class info with the warnings pragma. +=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 perl5db.pl The debugger saves and restores C<$^W> at runtime. I haven't checked @@ -330,8 +426,8 @@ The experimental features need bottomed out. =head1 SEE ALSO -L. - +L, L. + =head1 AUTHOR - + Paul Marquess