final touches for lexical warnings (from Paul Marquess)

p4raw-id: //depot/perl@5702

1 files changed, 48 insertions, 19 deletions

diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod
index af1a910334..cee1687537 100644
--- a/pod/perllexwarn.pod
+++ b/pod/perllexwarn.pod
@@ -339,20 +339,49 @@ fatal error.
 
 =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 when the 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
-    {
+    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 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.
+
+    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 {
         if (warnings::enabled("deprecated")) {
             warnings::warn("deprecated", 
-                           "abc::open is deprecated. Use abc:new") ;
+                           "open is deprecated, use new instead") ;
         }
         new(@_) ;
     }
@@ -366,21 +395,21 @@ 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) ;
 
-If the calling module has escalated the "deprecated" warnings category
-into a fatal error like this:
+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
 
-    use warnings 'FATAL deprecated';
-    use abc;
+    use MyMod::Abc;
+    use warnings FATAL => 'MyMod::Abc';
     ...
-    abc::open($filename) ;
+    MyMod::Abc::open('../fred.txt');
 
-then C<warnings::warn> will detect this and die after displaying the
-warning message.
+the C<warnings::warn> function will detect this and die after
+displaying the warning message.
 
 =head1 TODO