revised warnings + more tests + docs

[p5sagit/p5-mst-13.2.git] / pod / perllexwarn.pod

diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod
index efc0196..7b3ce3c 100644 (file)
--- a/pod/perllexwarn.pod
+++ b/pod/perllexwarn.pod
@@ -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
 
@@ -100,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
@@ -208,10 +207,10 @@ The current hierarchy is:
 
   all -+
        |
-       +- chmod
-       |
        +- closure
        |
+       +- deprecated
+       |
        +- exiting
        |
        +- glob
@@ -222,6 +221,8 @@ The current hierarchy is:
        |                |
        |                +- exec
        |                |
+       |                +- layer
+       |                |
        |                +- newline
        |                |
        |                +- pipe
@@ -266,8 +267,6 @@ The current hierarchy is:
        |                |
        |                +- bareword
        |                |
-       |                +- deprecated
-       |                |
        |                +- digit
        |                |
        |                +- parenthesis
@@ -286,7 +285,7 @@ The current hierarchy is:
        |
        +- taint
        |
-       +- umask
+       +- threads
        |
        +- uninitialized
        |
@@ -317,25 +316,47 @@ C<warnings> pragma in a given scope the cumulative effect is additive.
 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 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.
-
+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 ;
+    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 disable 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);
 
 =head2 Reporting Warnings from a Module
 
@@ -352,8 +373,9 @@ Consider the module C<MyMod::Abc> below.
 
     sub open {
         my $path = shift ;
-        if (warnings::enabled() && $path !~ m#^/#) {
-            warnings::warn("changing relative path to /tmp/");
+        if ($path !~ m#^/#) {
+            warnings::warn("changing relative path to /tmp/")
+                if warnings::enabled();
             $path = "/tmp/$path" ; 
         }
     }
@@ -458,7 +480,7 @@ Consider this example:
         bless [], $class ;
     }
 
-   
+
     1 ;
 
 The code below makes use of both modules, but it only enables warnings from