diff options
Diffstat (limited to 'pod/perllexwarn.pod')
| -rw-r--r-- | pod/perllexwarn.pod | 249 |
1 files changed, 158 insertions, 91 deletions
diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod index 6078aefd96..d370f04412 100644 --- a/pod/perllexwarn.pod +++ b/pod/perllexwarn.pod @@ -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<default> 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; @@ -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<warnings> 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. @@ -185,7 +184,7 @@ 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<warnings> pragma, both the C<$^W> variable and the B<-w> flag will be ignored for the scope of the lexical warning. @@ -197,82 +196,109 @@ 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 C<warnings> pragma to control the warning behavior of $^W-type code (using a C<local $^W=0>) 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<tentative> 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<warnings> pragma in a given scope the cumulative effect is additive. use warnings qw(void) ; # only "void" warnings enabled ... @@ -288,14 +314,16 @@ 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<perldiag>. =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 ; @@ -308,15 +336,54 @@ produce a fatal error. } $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<warnings> pragma provides two functions, namely C<warnings::enabled> +and C<warnings::warn>, that are useful for module authors. They are +used when you want to report a module-specific warning, but only when +the calling module has enabled warnings via the C<warnings> pragma. + +Consider the module C<abc> below. + + package abc; + + sub open + { + if (warnings::enabled("deprecated")) { + warnings::warn("deprecated", + "abc::open is deprecated. Use abc:new") ; + } + new(@_) ; + } + sub new + ... + 1 ; + +The function C<open> 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 abc; + ... + abc::open($filename) ; + + +If the calling module has escalated the "deprecated" warnings category +into a fatal error like this: + + use warnings 'FATAL deprecated'; + use abc; + ... + abc::open($filename) ; + +then C<warnings::warn> 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 whether the debugger will still work with the lexical warnings @@ -330,7 +397,7 @@ The experimental features need bottomed out. =head1 SEE ALSO -L<warnings>. +L<warnings>, L<perldiag>. =head1 AUTHOR |