X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperllexwarn.pod;h=1eb8b30087ddefaa92ec2e706aba48a61b59a2d6;hb=7360c6b444ea6e19b6583f9530f845bee19c7921;hp=8274c4d70ee05311ee0dc95ddbe1f6c7fd59ee74;hpb=d74e8afc9309529cf5c6c4390fc311850865d506;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod
index 8274c4d..1eb8b30 100644
--- a/pod/perllexwarn.pod
+++ b/pod/perllexwarn.pod
@@ -5,10 +5,12 @@ 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 C<use warnings> pragma enables to control precisely what warnings are
+to be enabled in which parts of a Perl program. It's a more flexible
+alternative 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 pragma works just like the C<strict> pragma.
 This means that the scope of the warning pragma is limited to the
 enclosing block. It also means that the pragma setting will not
 leak across files (via C<use>, C<require> or C<do>). This allows
@@ -20,21 +22,21 @@ 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 ;
+    use warnings;
+    my @a;
     {
-        no warnings ;
-	my $b = @a[0] ;
+        no warnings;
+	my $b = @a[0];
     }
     my $c = @a[0];
 
@@ -63,7 +65,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 +85,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,8 +98,8 @@ 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 the way you can inadvertently
@@ -108,13 +110,13 @@ the first will not.
 
     sub doit
     {
-        my $b ; chop $b ;
+        my $b; chop $b;
     }
 
-    doit() ;
+    doit();
 
     {
-        local ($^W) = 1 ;
+        local ($^W) = 1;
         doit()
     }
 
@@ -212,8 +214,6 @@ The current hierarchy is:
 
   all -+
        |
-       +- assertions
-       |
        +- closure
        |
        +- deprecated
@@ -236,6 +236,8 @@ The current hierarchy is:
        |                |
        |                +- unopened
        |
+       +- imprecision
+       |
        +- misc
        |
        +- numeric
@@ -306,17 +308,17 @@ The current hierarchy is:
 
 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>.
@@ -335,18 +337,18 @@ 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;
 
-    time ;
+    time;
 
     {
-        use warnings FATAL => qw(void) ;
-        length "abc" ;
+        use warnings FATAL => qw(void);
+        length "abc";
     }
 
-    join "", 1,2,3 ;
+    join "", 1,2,3;
 
-    print "done\n" ;     
+    print "done\n";
 
 When run it produces this output
 
@@ -386,7 +388,7 @@ Consider the module C<MyMod::Abc> below.
     use warnings::register;
 
     sub open {
-        my $path = shift ;
+        my $path = shift;
         if ($path !~ m#^/#) {
             warnings::warn("changing relative path to /var/abc")
                 if warnings::enabled();
@@ -394,10 +396,10 @@ Consider the module C<MyMod::Abc> below.
         }
     }
 
-    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 current
+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
@@ -416,13 +418,13 @@ this snippet of code:
 
     sub open {
         warnings::warnif("deprecated", 
-                         "open is deprecated, use new instead") ;
-        new(@_) ;
+                         "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
@@ -431,7 +433,7 @@ 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);
 
 Either the C<warnings::warn> or C<warnings::warnif> function should be
 used to actually display the warnings message. This is because they can
@@ -453,21 +455,21 @@ of the object as the warnings category.
 
 Consider this example:
 
-    package Original ;
+    package Original;
 
-    no warnings ;
-    use warnings::register ;
+    no warnings;
+    use warnings::register;
 
     sub new
     {
-        my $class = shift ;
-        bless [], $class ;
+        my $class = shift;
+        bless [], $class;
     }
 
     sub check
     {
-        my $self = shift ;
-        my $value = shift ;
+        my $self = shift;
+        my $value = shift;
 
         if ($value % 2 && warnings::enabled($self))
           { warnings::warn($self, "Odd numbers are unsafe") }
@@ -475,38 +477,38 @@ Consider this example:
 
     sub doit
     {
-        my $self = shift ;
-        my $value = shift ;
-        $self->check($value) ;
+        my $self = shift;
+        my $value = shift;
+        $self->check($value);
         # ...
     }
 
-    1 ;
+    1;
 
-    package Derived ;
+    package Derived;
 
-    use warnings::register ;
-    use Original ;
-    our @ISA = qw( Original ) ;
+    use warnings::register;
+    use Original;
+    our @ISA = qw( Original );
     sub new
     {
-        my $class = shift ;
-        bless [], $class ;
+        my $class = shift;
+        bless [], $class;
     }
 
 
-    1 ;
+    1;
 
 The code below makes use of both modules, but it only enables warnings from 
 C<Derived>.
 
-    use Original ;
-    use Derived ;
+    use Original;
+    use Derived;
     use warnings 'Derived';
-    my $a = new Original ;
-    $a->doit(1) ;
-    my $b = new Derived ;
-    $a->doit(1) ;
+    my $a = Original->new();
+    $a->doit(1);
+    my $b = Derived->new();
+    $a->doit(1);
 
 When this code is run only the C<Derived> object, C<$b>, will generate
 a warning. 
@@ -516,21 +518,6 @@ a warning.
 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
-    whether the debugger will still work with the lexical warnings
-    patch applied.
-
-  diagnostics.pm
-    I *think* I've got diagnostics to work with the lexical warnings
-    patch, but there were design decisions made in diagnostics to work
-    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>.