X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/5bc28da93666e223bb56098f72517273bc8bcbf9..9dc383df09a9cff0c61b1ef24cca31649466258f:/pod/perllexwarn.pod

diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod
index 32fc210..12ce1f6 100644
--- a/pod/perllexwarn.pod
+++ b/pod/perllexwarn.pod
@@ -3,13 +3,13 @@
 perllexwarn - Perl Lexical Warnings
 
 =head1 DESCRIPTION
- 
+
 The C<use warnings> 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<use>, C<require> or C<do>). 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 ;
@@ -30,18 +30,17 @@ Similarly all warnings are disabled in a block by either of these:
 For example, consider the code below:
 
     use warnings ;
-    my $a ;
-    my $b ;
+    my @a ;
     {
         no warnings ;
-	$b = 2 if $a EQ 3 ;
+	my $b = @a[0] ;
     }
-    $b = 1 if $a NE 3 ;
+    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 that the use of the C<EQ>
-operator won't trip a C<"Use of EQ is deprecated"> warning, but the use of
-C<NE> will produce a C<"Use of NE is deprecated"> warning.
+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
 
@@ -55,13 +54,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;
@@ -102,7 +99,7 @@ disable compile-time warnings you need to rewrite the code like this:
 	 my $b ; chop $b ;
      }
 
-The other big problem with C<$^W> is that way you can inadvertently
+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<doit> will trip a C<"Use of uninitialized value"> warning, whereas
@@ -140,7 +137,7 @@ will enable warnings everywhere. See L<Backward Compatibility> 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<no warnings> or C<$^W =0>. This includes all files that get
@@ -160,14 +157,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<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.
 
@@ -178,101 +176,130 @@ 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<warnings> 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<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 -+
+       |
+       +- assertions
+       |
+       +- closure
+       |
+       +- deprecated
+       |
+       +- exiting
+       |
+       +- glob
+       |
+       +- io -----------+
+       |                |
+       |                +- closed
+       |                |
+       |                +- exec
+       |                |
+       |                +- layer
+       |                |
+       |                +- newline
+       |                |
+       |                +- pipe
+       |                |
+       |                +- unopened
+       |
+       +- misc
+       |
+       +- numeric
+       |
+       +- once
+       |
+       +- overflow
+       |
+       +- pack
+       |
+       +- portable
+       |
+       +- recursion
+       |
+       +- redefine
+       |
+       +- regexp
+       |
+       +- severe -------+
+       |                |
+       |                +- debugging
+       |                |
+       |                +- inplace
+       |                |
+       |                +- internal
+       |                |
+       |                +- malloc
+       |
+       +- signal
+       |
+       +- substr
+       |
+       +- syntax -------+
+       |                |
+       |                +- ambiguous
+       |                |
+       |                +- bareword
+       |                |
+       |                +- digit
+       |                |
+       |                +- parenthesis
+       |                |
+       |                +- precedence
+       |                |
+       |                +- printf
+       |                |
+       |                +- prototype
+       |                |
+       |                +- qw
+       |                |
+       |                +- reserved
+       |                |
+       |                +- semicolon
+       |
+       +- taint
+       |
+       +- threads
+       |
+       +- uninitialized
+       |
+       +- unpack
+       |
+       +- untie
+       |
+       +- utf8
+       |
+       +- void
+       |
+       +- y2k
 
 Just like the "strict" pragma any of these categories can be combined
 
@@ -280,7 +307,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,34 +315,203 @@ 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>.
+
+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
- 
-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.
 
+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<time>, C<length>
+and C<join> can all produce a C<"Useless use of xxx in void context">
+warning.
 
     use warnings ;
- 
-    $a = 1 if $a EQ $b ;
- 
+
+    time ;
+
     {
-        use warnings FATAL => qw(deprecated) ;
-        $a = 1 if $a EQ $b ;
+        use warnings FATAL => qw(void) ;
+        length "abc" ;
     }
- 
-    $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.
+    join "", 1,2,3 ;
+
+    print "done\n" ;     
+
+When run it produces this output
+
+    Useless use of time in void context at fatal line 3.
+    Useless use of length in void context at fatal line 7.  
+
+The scope where C<length> is used has escalated the C<void> warnings
+category into a fatal error, so the program terminates immediately it
+encounters the warning.
+
+To explicitly turn off a "FATAL" warning you just disable the warning
+it is associated with.  So, for example, to disable the "void" warning
+in the example above, either of these will do the trick:
+
+    no warnings qw(void);
+    no warnings FATAL => qw(void);
+
+If you want to downgrade a warning that has been escalated into a fatal
+error back to a normal warning, you can use the "NONFATAL" keyword. For
+example, the code below will promote all warnings into fatal errors,
+except for those in the "syntax" category.
+
+    use warnings FATAL => 'all', NONFATAL => 'syntax';
+
+=head2 Reporting Warnings from a Module
+
+The C<warnings> pragma provides a number of functions that are useful for
+module authors. These are used when you want to report a module-specific
+warning to a calling module has enabled warnings via the C<warnings>
+pragma.
+
+Consider the module C<MyMod::Abc> below.
+
+    package MyMod::Abc;
+
+    use warnings::register;
+
+    sub open {
+        my $path = shift ;
+        if ($path !~ m#^/#) {
+            warnings::warn("changing relative path to /var/abc")
+                if warnings::enabled();
+            $path = "/var/abc/$path";
+        }
+    }
+
+    1 ;
+
+The call to C<warnings::register> will create a new warnings category
+called "MyMod::abc", i.e. the new category name matches the current
+package name. The C<open> 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<MyMod::Abc> has actually
+enabled them with the C<warnings> 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<warnings::enabled> function. Consider
+this snippet of code:
+
+    package MyMod::Abc;
+
+    sub open {
+        warnings::warnif("deprecated", 
+                         "open is deprecated, use new instead") ;
+        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 MyMod::Abc;
+    ...
+    MyMod::Abc::open($filename) ;
+
+Either the C<warnings::warn> or C<warnings::warnif> 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<warnings::warnif> function will detect this and die after
+displaying the warning message.
+
+The three warnings functions, C<warnings::warn>, C<warnings::warnif>
+and C<warnings::enabled> can optionally take an object reference in place
+of a category name. In this case the functions will use the class name
+of the object as the warnings category.
+
+Consider this example:
+
+    package Original ;
+
+    no warnings ;
+    use warnings::register ;
+
+    sub new
+    {
+        my $class = shift ;
+        bless [], $class ;
+    }
+
+    sub check
+    {
+        my $self = shift ;
+        my $value = shift ;
+
+        if ($value % 2 && warnings::enabled($self))
+          { warnings::warn($self, "Odd numbers are unsafe") }
+    }
+
+    sub doit
+    {
+        my $self = shift ;
+        my $value = shift ;
+        $self->check($value) ;
+        # ...
+    }
+
+    1 ;
+
+    package Derived ;
+
+    use warnings::register ;
+    use Original ;
+    our @ISA = qw( Original ) ;
+    sub new
+    {
+        my $class = shift ;
+        bless [], $class ;
+    }
+
+
+    1 ;
+
+The code below makes use of both modules, but it only enables warnings from 
+C<Derived>.
+
+    use Original ;
+    use Derived ;
+    use warnings 'Derived';
+    my $a = new Original ;
+    $a->doit(1) ;
+    my $b = new Derived ;
+    $a->doit(1) ;
+
+When this code is run only the C<Derived> object, C<$b>, will generate
+a warning. 
+
+    Odd numbers are unsafe at main.pl line 7
+
+Notice also that the warning is reported at the line where the object is first
+used.
+
+=head1 TODO
 
   perl5db.pl
     The debugger saves and restores C<$^W> at runtime. I haven't checked
@@ -328,10 +524,12 @@ The experimental features need bottomed out.
     around the limitations of C<$^W>. Now that those limitations are gone,
     the module should be revisited.
 
+  document calling the warnings::* functions from XS
+
 =head1 SEE ALSO
 
-L<warnings>.
- 
+L<warnings>, L<perldiag>.
+
 =head1 AUTHOR
- 
+
 Paul Marquess