perl/regen/warnings.pl

11 # When changing the number of warnings, t/op/caller.t should change to
12 # correspond with the value of $BYTES in lib/warnings.pm
14 # With an argument of 'tree', just dump the contents of $WARNING_TREE and exits.
31 # Define the hierarchy of warnings.
33 # Each level in the tree is a hash which lists the names of all the
34 # children below that level. Each child is an array consisting of the
37 # another hash of children.
43 # of 'io', a warnings category called 'io::pipe' is NOT automatically
173 my @DEFAULTS;      # List of category numbers which are DEFAULT_ON
199 # being a list of node names with that version, e.g.
232 # Returns count of categories.
316 # return a string containing a visual representation of the warnings tree
388 # Convert a list of bit offsets (0...) into a string containing $max bytes
389 # of the form "\xMM\xNN...."
463     print $warn_h "/* end of file warnings.h */\n";
610 perl program becomes C<WARN_VOID> when used in XS code and passed to one of
617 These return a boolean as to whether or not warnings are enabled for any of
620 Should any of the categories by default be enabled even if not within the
621 scope of S<C<use warnings>>, instead use the C<L</ckWARN_d>> macros.
632 default enabled even if not within the scope of S<C<use warnings>>.
640 macros and functions that take a warning category parameter.  The number of
641 categories to pack is given by the name, with a corresponding number of
651  * a subcategory of any other */
667  * a subcategory of any other */
702 die sprintf "Incorrect use of pragma '%s' at %s line %d.\n", __PACKAGE__, +(caller)[1,2]
1001 # These are not part of any public interface, so we can delete them to save
1046 which parts of a Perl program.  It's a more flexible alternative for
1051 This means that the scope of the warning pragma is limited to the
1054 authors to independently define the degree of warning checks that will
1060 All warnings are enabled in a block by either of these:
1065 Similarly all warnings are disabled in a block by either of these:
1085 All warnings are enabled automatically within the scope of
1090 Before the introduction of lexical warnings, Perl had two classes of
1100 With the introduction of lexical warnings, mandatory warnings now become
1116 As a convenience, you can (as of Perl 5.34) pass arguments to the
1121 bunch of warnings but want to tweak them a bit in some block, you can
1138 don't want to be warned about use of experimental features, except for C<somefeature>
1149 As experimental features become regular features of Perl,
1160 scenario when you are writing a Perl program.  Parts of the code you
1161 will write yourself, but it's very likely that you will make use of
1163 end up enabling warnings in pieces of code that you haven't written.
1165 Similarly, using C<$^W> to either disable or enable blocks of code is
1167 a block of code.  You might expect this to be enough to do the trick:
1194 to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
1209 This is a side-effect of C<$^W> being dynamically scoped.
1225 used in any of your code, or any of the modules that you use, this flag
1227 details of how this flag interacts with lexical warnings.
1233 throughout the program regardless of whether warnings were disabled
1237 Think of it as the Perl equivalent of the "lint" command.
1248 If you are used to working with a version of Perl prior to the
1249 introduction of lexically scoped warnings, or have code that uses both
1258 If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
1279 If a piece of code is under the control of the C<warnings> pragma,
1281 scope of the lexical warning.
1290 The combined effect of 3 & 4 is that it will allow code which uses
1291 the C<warnings> pragma to control the warning behavior of $^W-type
1297 A hierarchy of "categories" have been defined to allow groups of warnings
1304 Just like the "strict" pragma any of these categories can be combined
1309 Also like the "strict" pragma, if there is more than one instance of the
1322 sub-category of the "syntax" category.  It is now a top-level category
1332 The presence of the word "FATAL" in the category list will escalate
1344 fatalized warnings.  For a summary of resolved and unresolved problems as
1345 of January 2015, please see
1351 risky.  Therefore, the use of C<< FATAL => 'all' >> is
1354 The L<strictures|strictures/VERSION-2> module on CPAN offers one example of
1358 B<NOTE:> Users of FATAL warnings, especially those using
1360 portability of their programs by doing so.  Perl makes absolutely no
1363 not warn now may warn in a future release of Perl if the Perl5 development
1364 team deems it in the best interests of the community to do so.  Should code
1365 using FATAL warnings break due to the introduction of a new warning we will
1366 NOT consider it an incompatible change.  Users of FATAL warnings should
1368 any new warnings and should pay particular attention to the fine print of
1369 the documentation of the features they use to ensure they do not exploit
1372 and spirit.  Use of such features in combination with FATAL warnings is
1378 way for downstream users to change the choice of fatal categories.
1380 In the code below, the use of C<time>, C<length>
1381 and C<join> can all produce a C<"Useless use of xxx in void context">
1399     Useless use of time in void context at fatal line 3.
1400     Useless use of length in void context at fatal line 7.
1408 in the example above, either of these will do the trick:
1420 As of Perl 5.20, instead of C<< use warnings FATAL => 'all'; >> you can
1424    use warnings 'FATAL';  # short form of "use warnings FATAL => 'all';"
1429 If you want your program to be compatible with versions of Perl before
1431 previous versions of Perl, the behavior of the statements
1434 they included the C<< => 'all' >> portion.  As of 5.20, they do.)
1439 The C<warnings> pragma provides a number of functions that are useful for
1475 this snippet of code:
1502 make use of the feature that allows warnings to be escalated into fatal
1515 of a category name.  In this case the functions will use the class name
1516 of the object as the warnings category.
1564 The code below makes use of both modules, but it only enables warnings from
1583 When registering new categories of warning, you can supply more names to
1620 Use the name of the class for the object reference, C<$object>, as the
1646 Use the name of the class for the object reference, C<$object>, as the
1678 Use the name of the class for the object reference, C<$object>, as the