X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperllexwarn.pod;h=20f1875c0cbd18857e603ac62369e2539e034fb9;hb=8269e00da02a2e0f107fbb8b4a78f0c4058f3587;hp=0052d33ff2bc44e2d25461e6eef4cf8f9fb3347e;hpb=ee8c7f5465f003860e2347a2946abacac39bd9b9;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod
index 0052d33..20f1875 100644
--- a/pod/perllexwarn.pod
+++ b/pod/perllexwarn.pod
@@ -1,4 +1,5 @@
 =head1 NAME
+X<warning, lexical> X<warnings> X<warning>
 
 perllexwarn - Perl Lexical Warnings
 
@@ -19,29 +20,28 @@ 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' ;
+    use warnings;
+    use warnings 'all';
 
 Similarly all warnings are disabled in a block by either of these:
 
-    no warnings ;
-    no warnings 'all' ;
+    no warnings;
+    no warnings 'all';
 
 For example, consider the code below:
 
-    use warnings ;
-    my $a ;
-    my $b ;
+    use warnings;
+    my @a;
     {
-        no warnings ;
-	$b = 2 if $a EQ 3 ;
+        no warnings;
+	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
 
@@ -63,7 +63,7 @@ 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 warnings ;
+    no warnings;
     my $b = "2:" + 3;
 
 Note that neither the B<-w> flag or the C<$^W> can be used to
@@ -83,9 +83,9 @@ fundamentally flawed. For a start, say you want to disable warnings in
 a block of code. You might expect this to be enough to do the trick:
 
      {
-         local ($^W) = 0 ;
-	 my $a =+ 2 ;
-	 my $b ; chop $b ;
+         local ($^W) = 0;
+	 my $a =+ 2;
+	 my $b; chop $b;
      }
 
 When this code is run with the B<-w> flag, a warning will be produced
@@ -96,11 +96,11 @@ disable compile-time warnings you need to rewrite the code like this:
 
      {
          BEGIN { $^W = 0 }
-	 my $a =+ 2 ;
-	 my $b ; chop $b ;
+	 my $a =+ 2;
+	 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
@@ -108,13 +108,13 @@ the first will not.
 
     sub doit
     {
-        my $b ; chop $b ;
+        my $b; chop $b;
     }
 
-    doit() ;
+    doit();
 
     {
-        local ($^W) = 1 ;
+        local ($^W) = 1;
         doit()
     }
 
@@ -131,6 +131,7 @@ warnings are (or aren't) produced:
 =over 5
 
 =item B<-w>
+X<-w>
 
 This is  the existing flag. If the lexical warnings pragma is B<not>
 used in any of you code, or any of the modules that you use, this flag
@@ -138,6 +139,7 @@ will enable warnings everywhere. See L<Backward Compatibility> for
 details of how this flag interacts with lexical warnings.
 
 =item B<-W>
+X<-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
@@ -146,6 +148,7 @@ included via C<use>, C<require> or C<do>.
 Think of it as the Perl equivalent of the "lint" command.
 
 =item B<-X>
+X<-X>
 
 Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
 
@@ -200,6 +203,7 @@ 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.
 
 =head2 Category Hierarchy
+X<warning, categories>
 
 A hierarchy of "categories" have been defined to allow groups of warnings
 to be enabled/disabled in isolation.
@@ -208,10 +212,12 @@ The current hierarchy is:
 
   all -+
        |
-       +- chmod
+       +- assertions
        |
        +- closure
        |
+       +- deprecated
+       |
        +- exiting
        |
        +- glob
@@ -222,6 +228,8 @@ The current hierarchy is:
        |                |
        |                +- exec
        |                |
+       |                +- layer
+       |                |
        |                +- newline
        |                |
        |                +- pipe
@@ -266,8 +274,6 @@ The current hierarchy is:
        |                |
        |                +- bareword
        |                |
-       |                +- deprecated
-       |                |
        |                +- digit
        |                |
        |                +- parenthesis
@@ -286,7 +292,7 @@ The current hierarchy is:
        |
        +- taint
        |
-       +- umask
+       +- threads
        |
        +- uninitialized
        |
@@ -297,51 +303,80 @@ The current hierarchy is:
        +- 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) ;
+    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<warnings> pragma in a given scope the cumulative effect is additive. 
 
-    use warnings qw(void) ; # only "void" warnings enabled
+    use warnings qw(void); # only "void" warnings enabled
     ...
-    use warnings qw(io) ;   # only "void" & "io" warnings enabled
+    use warnings qw(io);   # only "void" & "io" warnings enabled
     ...
-    no warnings qw(void) ;  # only "io" warnings enabled
+    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
+X<warning, fatal>
 
 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;
 
-    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 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
+X<warning, reporting> X<warning, registering>
 
 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 when the calling module has enabled warnings via the C<warnings>
+warning to a calling module has enabled warnings via the C<warnings>
 pragma.
 
 Consider the module C<MyMod::Abc> below.
@@ -351,21 +386,22 @@ Consider the module C<MyMod::Abc> below.
     use warnings::register;
 
     sub open {
-        my $path = shift ;
-        if (warnings::enabled() && $path !~ m#^/#) {
-            warnings::warn("changing relative path to /tmp/");
-            $path = "/tmp/$path" ; 
+        my $path = shift;
+        if ($path !~ m#^/#) {
+            warnings::warn("changing relative path to /var/abc")
+                if warnings::enabled();
+            $path = "/var/abc/$path";
         }
     }
 
-    1 ;
+    1;
 
 The call to C<warnings::register> will create a new warnings category
-called "MyMod::abc", i.e. the new category name matches the module
-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.
+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';
@@ -379,16 +415,14 @@ this snippet of code:
     package MyMod::Abc;
 
     sub open {
-        if (warnings::enabled("deprecated")) {
-            warnings::warn("deprecated", 
-                           "open is deprecated, use new instead") ;
-        }
-        new(@_) ;
+        warnings::warnif("deprecated", 
+                         "open is deprecated, use new instead");
+        new(@_);
     }
 
     sub new
     ...
-    1 ;
+    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
@@ -397,20 +431,91 @@ display a warning message whenever the calling module has (at least) the
     use warnings 'deprecated';
     use MyMod::Abc;
     ...
-    MyMod::Abc::open($filename) ;
+    MyMod::Abc::open($filename);
 
-The C<warnings::warn> 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
+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::warn> function will detect this and die after
+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
@@ -424,6 +529,8 @@ displaying the warning message.
     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<perldiag>.