X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperllexwarn.pod;h=b98e3332e4cccb537290573ec1317118e65737e1;hb=7817ba4dfeb754838a0da8f159127895c2dcf4fc;hp=af1a910334d5395f29fc43eff18db053e99e51a7;hpb=c47ff5f1a1ef5d0daccf1724400a446cd8e93573;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod
index af1a910..b98e333 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<use>, C<require> or C<do>). This allows
 authors to independently define the degree of warning checks that will
 be applied to their module.
@@ -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
@@ -195,7 +194,7 @@ or B<-X> command line flags.
 
 =back
 
-The combined effect of 3 & 4 is that it will will allow code which uses
+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.
 
@@ -321,39 +320,77 @@ L<perldiag>.
 
 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" ;
     }
+ 
+    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.
 
-    $a = 1 if $a EQ $b ;
 
 =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.
+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<abc> below.
+Consider the module C<MyMod::Abc> below.
 
-    package abc;
+    package MyMod::Abc;
 
-    sub open
-    {
-        if (warnings::enabled("deprecated")) {
-            warnings::warn("deprecated", 
-                           "abc::open is deprecated. Use abc:new") ;
+    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<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(@_) ;
     }
 
@@ -366,21 +403,92 @@ 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;
+    use MyMod::Abc;
     ...
-    abc::open($filename) ;
+    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
 
-If the calling module has escalated the "deprecated" warnings category
-into a fatal error like this:
-
-    use warnings 'FATAL deprecated';
-    use abc;
+    use MyMod::Abc;
+    use warnings FATAL => 'MyMod::Abc';
     ...
-    abc::open($filename) ;
+    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.
 
-then C<warnings::warn> will detect this and die after displaying the
-warning message.
+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
 
@@ -395,6 +503,8 @@ 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>.