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