home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl560.zip / pod / perllexwarn.pod < prev    next >
Text File  |  2000-03-12  |  12KB  |  434 lines

  1. =head1 NAME
  2.  
  3. perllexwarn - Perl Lexical Warnings
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. The C<use warnings> pragma is a replacement for both the command line
  8. flag B<-w> and the equivalent Perl variable, C<$^W>.
  9.  
  10. The pragma works just like the existing "strict" pragma.
  11. This means that the scope of the warning pragma is limited to the
  12. enclosing block. It also means that that the pragma setting will not
  13. leak across files (via C<use>, C<require> or C<do>). This allows
  14. authors to independently define the degree of warning checks that will
  15. be applied to their module.
  16.  
  17. By default, optional warnings are disabled, so any legacy code that
  18. doesn't attempt to control the warnings will work unchanged.
  19.  
  20. All warnings are enabled in a block by either of these:
  21.  
  22.     use warnings ;
  23.     use warnings 'all' ;
  24.  
  25. Similarly all warnings are disabled in a block by either of these:
  26.  
  27.     no warnings ;
  28.     no warnings 'all' ;
  29.  
  30. For example, consider the code below:
  31.  
  32.     use warnings ;
  33.     my $a ;
  34.     my $b ;
  35.     {
  36.         no warnings ;
  37.     $b = 2 if $a EQ 3 ;
  38.     }
  39.     $b = 1 if $a NE 3 ;
  40.  
  41. The code in the enclosing block has warnings enabled, but the inner
  42. block has them disabled. In this case that means that the use of the C<EQ>
  43. operator won't trip a C<"Use of EQ is deprecated"> warning, but the use of
  44. C<NE> will produce a C<"Use of NE is deprecated"> warning.
  45.  
  46. =head2 Default Warnings and Optional Warnings
  47.  
  48. Before the introduction of lexical warnings, Perl had two classes of
  49. warnings: mandatory and optional. 
  50.  
  51. As its name suggests, if your code tripped a mandatory warning, you
  52. would get a warning whether you wanted it or not.
  53. For example, the code below would always produce an C<"isn't numeric">
  54. warning about the "2:".
  55.  
  56.     my $a = "2:" + 3;
  57.  
  58. With the introduction of lexical warnings, mandatory warnings now become
  59. I<default> warnings. The difference is that although the previously
  60. mandatory warnings are still enabled by default, they can then be
  61. subsequently enabled or disabled with the lexical warning pragma. For
  62. example, in the code below, an C<"isn't numeric"> warning will only
  63. be reported for the C<$a> variable.
  64.  
  65.     my $a = "2:" + 3;
  66.     no warnings ;
  67.     my $b = "2:" + 3;
  68.  
  69. Note that neither the B<-w> flag or the C<$^W> can be used to
  70. disable/enable default warnings. They are still mandatory in this case.
  71.  
  72. =head2 What's wrong with B<-w> and C<$^W>
  73.  
  74. Although very useful, the big problem with using B<-w> on the command
  75. line to enable warnings is that it is all or nothing. Take the typical
  76. scenario when you are writing a Perl program. Parts of the code you
  77. will write yourself, but it's very likely that you will make use of
  78. pre-written Perl modules. If you use the B<-w> flag in this case, you
  79. end up enabling warnings in pieces of code that you haven't written.
  80.  
  81. Similarly, using C<$^W> to either disable or enable blocks of code is
  82. fundamentally flawed. For a start, say you want to disable warnings in
  83. a block of code. You might expect this to be enough to do the trick:
  84.  
  85.      {
  86.          local ($^W) = 0 ;
  87.      my $a =+ 2 ;
  88.      my $b ; chop $b ;
  89.      }
  90.  
  91. When this code is run with the B<-w> flag, a warning will be produced
  92. for the C<$a> line -- C<"Reversed += operator">.
  93.  
  94. The problem is that Perl has both compile-time and run-time warnings. To
  95. disable compile-time warnings you need to rewrite the code like this:
  96.  
  97.      {
  98.          BEGIN { $^W = 0 }
  99.      my $a =+ 2 ;
  100.      my $b ; chop $b ;
  101.      }
  102.  
  103. The other big problem with C<$^W> is that way you can inadvertently
  104. change the warning setting in unexpected places in your code. For example,
  105. when the code below is run (without the B<-w> flag), the second call
  106. to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
  107. the first will not.
  108.  
  109.     sub doit
  110.     {
  111.         my $b ; chop $b ;
  112.     }
  113.  
  114.     doit() ;
  115.  
  116.     {
  117.         local ($^W) = 1 ;
  118.         doit()
  119.     }
  120.  
  121. This is a side-effect of C<$^W> being dynamically scoped.
  122.  
  123. Lexical warnings get around these limitations by allowing finer control
  124. over where warnings can or can't be tripped.
  125.  
  126. =head2 Controlling Warnings from the Command Line
  127.  
  128. There are three Command Line flags that can be used to control when
  129. warnings are (or aren't) produced:
  130.  
  131. =over 5
  132.  
  133. =item B<-w>
  134.  
  135. This is  the existing flag. If the lexical warnings pragma is B<not>
  136. used in any of you code, or any of the modules that you use, this flag
  137. will enable warnings everywhere. See L<Backward Compatibility> for
  138. details of how this flag interacts with lexical warnings.
  139.  
  140. =item B<-W>
  141.  
  142. If the B<-W> flag is used on the command line, it will enable all warnings
  143. throughout the program regardless of whether warnings were disabled
  144. locally using C<no warnings> or C<$^W =0>. This includes all files that get
  145. included via C<use>, C<require> or C<do>.
  146. Think of it as the Perl equivalent of the "lint" command.
  147.  
  148. =item B<-X>
  149.  
  150. Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
  151.  
  152. =back
  153.  
  154. =head2 Backward Compatibility
  155.  
  156. If you are used with working with a version of Perl prior to the
  157. introduction of lexically scoped warnings, or have code that uses both
  158. lexical warnings and C<$^W>, this section will describe how they interact.
  159.  
  160. How Lexical Warnings interact with B<-w>/C<$^W>:
  161.  
  162. =over 5
  163.  
  164. =item 1.
  165.  
  166. If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
  167. control warnings is used and neither C<$^W> or the C<warnings> pragma
  168. are used, then default warnings will be enabled and optional warnings
  169. disabled.
  170. This means that legacy code that doesn't attempt to control the warnings
  171. will work unchanged.
  172.  
  173. =item 2.
  174.  
  175. The B<-w> flag just sets the global C<$^W> variable as in 5.005 -- this
  176. means that any legacy code that currently relies on manipulating C<$^W>
  177. to control warning behavior will still work as is. 
  178.  
  179. =item 3.
  180.  
  181. Apart from now being a boolean, the C<$^W> variable operates in exactly
  182. the same horrible uncontrolled global way, except that it cannot
  183. disable/enable default warnings.
  184.  
  185. =item 4.
  186.  
  187. If a piece of code is under the control of the C<warnings> pragma,
  188. both the C<$^W> variable and the B<-w> flag will be ignored for the
  189. scope of the lexical warning.
  190.  
  191. =item 5.
  192.  
  193. The only way to override a lexical warnings setting is with the B<-W>
  194. or B<-X> command line flags.
  195.  
  196. =back
  197.  
  198. The combined effect of 3 & 4 is that it will will allow code which uses
  199. the C<warnings> pragma to control the warning behavior of $^W-type
  200. code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
  201.  
  202. =head2 Category Hierarchy
  203.  
  204. A hierarchy of "categories" have been defined to allow groups of warnings
  205. to be enabled/disabled in isolation.
  206.  
  207. The current hierarchy is:
  208.  
  209.   all -+
  210.        |
  211.        +- chmod
  212.        |
  213.        +- closure
  214.        |
  215.        +- exiting
  216.        |
  217.        +- glob
  218.        |
  219.        +- io -----------+
  220.        |                |
  221.        |                +- closed
  222.        |                |
  223.        |                +- exec
  224.        |                |
  225.        |                +- newline
  226.        |                |
  227.        |                +- pipe
  228.        |                |
  229.        |                +- unopened
  230.        |
  231.        +- misc
  232.        |
  233.        +- numeric
  234.        |
  235.        +- once
  236.        |
  237.        +- overflow
  238.        |
  239.        +- pack
  240.        |
  241.        +- portable
  242.        |
  243.        +- recursion
  244.        |
  245.        +- redefine
  246.        |
  247.        +- regexp
  248.        |
  249.        +- severe -------+
  250.        |                |
  251.        |                +- debugging
  252.        |                |
  253.        |                +- inplace
  254.        |                |
  255.        |                +- internal
  256.        |                |
  257.        |                +- malloc
  258.        |
  259.        +- signal
  260.        |
  261.        +- substr
  262.        |
  263.        +- syntax -------+
  264.        |                |
  265.        |                +- ambiguous
  266.        |                |
  267.        |                +- bareword
  268.        |                |
  269.        |                +- deprecated
  270.        |                |
  271.        |                +- digit
  272.        |                |
  273.        |                +- parenthesis
  274.        |                |
  275.        |                +- precedence
  276.        |                |
  277.        |                +- printf
  278.        |                |
  279.        |                +- prototype
  280.        |                |
  281.        |                +- qw
  282.        |                |
  283.        |                +- reserved
  284.        |                |
  285.        |                +- semicolon
  286.        |
  287.        +- taint
  288.        |
  289.        +- umask
  290.        |
  291.        +- uninitialized
  292.        |
  293.        +- unpack
  294.        |
  295.        +- untie
  296.        |
  297.        +- utf8
  298.        |
  299.        +- void
  300.        |
  301.        +- y2k
  302.  
  303. Just like the "strict" pragma any of these categories can be combined
  304.  
  305.     use warnings qw(void redefine) ;
  306.     no warnings qw(io syntax untie) ;
  307.  
  308. Also like the "strict" pragma, if there is more than one instance of the
  309. C<warnings> pragma in a given scope the cumulative effect is additive. 
  310.  
  311.     use warnings qw(void) ; # only "void" warnings enabled
  312.     ...
  313.     use warnings qw(io) ;   # only "void" & "io" warnings enabled
  314.     ...
  315.     no warnings qw(void) ;  # only "io" warnings enabled
  316.  
  317. To determine which category a specific warning has been assigned to see
  318. L<perldiag>.
  319.  
  320. =head2 Fatal Warnings
  321.  
  322. The presence of the word "FATAL" in the category list will escalate any
  323. warnings detected from the categories specified in the lexical scope
  324. into fatal errors. In the code below, there are 3 places where a
  325. deprecated warning will be detected, the middle one will produce a
  326. fatal error.
  327.  
  328.  
  329.     use warnings ;
  330.  
  331.     $a = 1 if $a EQ $b ;
  332.  
  333.     {
  334.         use warnings FATAL => qw(deprecated) ;
  335.         $a = 1 if $a EQ $b ;
  336.     }
  337.  
  338.     $a = 1 if $a EQ $b ;
  339.  
  340. =head2 Reporting Warnings from a Module
  341.  
  342. The C<warnings> pragma provides a number of functions that are useful for
  343. module authors. These are used when you want to report a module-specific
  344. warning when the calling module has enabled warnings via the C<warnings>
  345. pragma.
  346.  
  347. Consider the module C<MyMod::Abc> below.
  348.  
  349.     package MyMod::Abc;
  350.  
  351.     use warnings::register;
  352.  
  353.     sub open {
  354.         my $path = shift ;
  355.         if (warnings::enabled() && $path !~ m#^/#) {
  356.             warnings::warn("changing relative path to /tmp/");
  357.             $path = "/tmp/$path" ; 
  358.         }
  359.     }
  360.  
  361.     1 ;
  362.  
  363. The call to C<warnings::register> will create a new warnings category
  364. called "MyMod::abc", i.e. the new category name matches the module
  365. name. The C<open> function in the module will display a warning message
  366. if it gets given a relative path as a parameter. This warnings will only
  367. be displayed if the code that uses C<MyMod::Abc> has actually enabled
  368. them with the C<warnings> pragma like below.
  369.  
  370.     use MyMod::Abc;
  371.     use warnings 'MyMod::Abc';
  372.     ...
  373.     abc::open("../fred.txt");
  374.  
  375. It is also possible to test whether the pre-defined warnings categories are
  376. set in the calling module with the C<warnings::enabled> function. Consider
  377. this snippet of code:
  378.  
  379.     package MyMod::Abc;
  380.  
  381.     sub open {
  382.         if (warnings::enabled("deprecated")) {
  383.             warnings::warn("deprecated", 
  384.                            "open is deprecated, use new instead") ;
  385.         }
  386.         new(@_) ;
  387.     }
  388.  
  389.     sub new
  390.     ...
  391.     1 ;
  392.  
  393. The function C<open> has been deprecated, so code has been included to
  394. display a warning message whenever the calling module has (at least) the
  395. "deprecated" warnings category enabled. Something like this, say.
  396.  
  397.     use warnings 'deprecated';
  398.     use MyMod::Abc;
  399.     ...
  400.     MyMod::Abc::open($filename) ;
  401.  
  402. The C<warnings::warn> function should be used to actually display the
  403. warnings message. This is because they can make use of the feature that
  404. allows warnings to be escalated into fatal errors. So in this case
  405.  
  406.     use MyMod::Abc;
  407.     use warnings FATAL => 'MyMod::Abc';
  408.     ...
  409.     MyMod::Abc::open('../fred.txt');
  410.  
  411. the C<warnings::warn> function will detect this and die after
  412. displaying the warning message.
  413.  
  414. =head1 TODO
  415.  
  416.   perl5db.pl
  417.     The debugger saves and restores C<$^W> at runtime. I haven't checked
  418.     whether the debugger will still work with the lexical warnings
  419.     patch applied.
  420.  
  421.   diagnostics.pm
  422.     I *think* I've got diagnostics to work with the lexical warnings
  423.     patch, but there were design decisions made in diagnostics to work
  424.     around the limitations of C<$^W>. Now that those limitations are gone,
  425.     the module should be revisited.
  426.  
  427. =head1 SEE ALSO
  428.  
  429. L<warnings>, L<perldiag>.
  430.  
  431. =head1 AUTHOR
  432.  
  433. Paul Marquess
  434.