diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/warnings.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/warnings.3pm | 955 |
1 files changed, 955 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/warnings.3pm b/upstream/mageia-cauldron/man3pm/warnings.3pm new file mode 100644 index 00000000..f1199471 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/warnings.3pm @@ -0,0 +1,955 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "warnings 3pm" +.TH warnings 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +warnings \- Perl pragma to control optional warnings +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& use warnings; +\& no warnings; +\& +\& # Standard warnings are enabled by use v5.35 or above +\& use v5.35; +\& +\& use warnings "all"; +\& no warnings "uninitialized"; +\& +\& # or equivalent to those last two ... +\& use warnings qw(all \-uninitialized); +\& +\& use warnings::register; +\& if (warnings::enabled()) { +\& warnings::warn("some warning"); +\& } +\& +\& if (warnings::enabled("void")) { +\& warnings::warn("void", "some warning"); +\& } +\& +\& if (warnings::enabled($object)) { +\& warnings::warn($object, "some warning"); +\& } +\& +\& warnings::warnif("some warning"); +\& warnings::warnif("void", "some warning"); +\& warnings::warnif($object, "some warning"); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \f(CW\*(C`warnings\*(C'\fR pragma gives control over which warnings are enabled in +which parts of a Perl program. It's a more flexible alternative for +both the command line flag \fB\-w\fR and the equivalent Perl variable, +\&\f(CW$^W\fR. +.PP +This pragma works just like the \f(CW\*(C`strict\*(C'\fR 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 \f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR). This allows +authors to independently define the degree of warning checks that will +be applied to their module. +.PP +By default, optional warnings are disabled, so any legacy code that +doesn't attempt to control the warnings will work unchanged. +.PP +All warnings are enabled in a block by either of these: +.PP +.Vb 2 +\& use warnings; +\& use warnings \*(Aqall\*(Aq; +.Ve +.PP +Similarly all warnings are disabled in a block by either of these: +.PP +.Vb 2 +\& no warnings; +\& no warnings \*(Aqall\*(Aq; +.Ve +.PP +For example, consider the code below: +.PP +.Vb 7 +\& use warnings; +\& my @x; +\& { +\& no warnings; +\& my $y = @x[0]; +\& } +\& my $z = @x[0]; +.Ve +.PP +The code in the enclosing block has warnings enabled, but the inner +block has them disabled. In this case that means the assignment to the +scalar \f(CW$z\fR will trip the \f(CW"Scalar value @x[0] better written as $x[0]"\fR +warning, but the assignment to the scalar \f(CW$y\fR will not. +.PP +All warnings are enabled automatically within the scope of +a \f(CW\*(C`use v5.35\*(C'\fR (or higher) declaration. +.SS "Default Warnings and Optional Warnings" +.IX Subsection "Default Warnings and Optional Warnings" +Before the introduction of lexical warnings, Perl had two classes of +warnings: mandatory and optional. +.PP +As its name suggests, if your code tripped a mandatory warning, you +would get a warning whether you wanted it or not. +For example, the code below would always produce an \f(CW"isn\*(Aqt numeric"\fR +warning about the "2:". +.PP +.Vb 1 +\& my $x = "2:" + 3; +.Ve +.PP +With the introduction of lexical warnings, mandatory warnings now become +\&\fIdefault\fR warnings. The difference is that although the previously +mandatory warnings are still enabled by default, they can then be +subsequently enabled or disabled with the lexical warning pragma. For +example, in the code below, an \f(CW"isn\*(Aqt numeric"\fR warning will only +be reported for the \f(CW$x\fR variable. +.PP +.Vb 3 +\& my $x = "2:" + 3; +\& no warnings; +\& my $y = "2:" + 3; +.Ve +.PP +Note that neither the \fB\-w\fR flag or the \f(CW$^W\fR can be used to +disable/enable default warnings. They are still mandatory in this case. +.SS """Negative warnings""" +.IX Subsection """Negative warnings""" +As a convenience, you can (as of Perl 5.34) pass arguments to the +\&\f(CWimport()\fR method both positively and negatively. Negative warnings +are those with a \f(CW\*(C`\-\*(C'\fR sign prepended to their names; positive warnings +are anything else. This lets you turn on some warnings and turn off +others in one command. So, assuming that you've already turned on a +bunch of warnings but want to tweak them a bit in some block, you can +do this: +.PP +.Vb 4 +\& { +\& use warnings qw(uninitialized \-redefine); +\& ... +\& } +.Ve +.PP +which is equivalent to: +.PP +.Vb 5 +\& { +\& use warnings qw(uninitialized); +\& no warnings qw(redefine); +\& ... +\& } +.Ve +.PP +The argument list is processed in the order you specify. So, for example, if you +don't want to be warned about use of experimental features, except for \f(CW\*(C`somefeature\*(C'\fR +that you really dislike, you can say this: +.PP +.Vb 1 +\& use warnings qw(all \-experimental experimental::somefeature); +.Ve +.PP +which is equivalent to: +.PP +.Vb 3 +\& use warnings \*(Aqall\*(Aq; +\& no warnings \*(Aqexperimental\*(Aq; +\& use warnings \*(Aqexperimental::somefeature\*(Aq; +.Ve +.PP +As experimental features become regular features of Perl, +the corresponding warnings are not printed anymore. +They also stop being listed in the "Category Hierarchy" below. +.PP +It is still possible to request turning on or off these warnings, +but doing so has no effect. +.ie n .SS "What's wrong with \fB\-w\fP and $^W" +.el .SS "What's wrong with \fB\-w\fP and \f(CW$^W\fP" +.IX Subsection "What's wrong with -w and $^W" +Although very useful, the big problem with using \fB\-w\fR on the command +line to enable warnings is that it is all or nothing. Take the typical +scenario when you are writing a Perl program. Parts of the code you +will write yourself, but it's very likely that you will make use of +pre-written Perl modules. If you use the \fB\-w\fR flag in this case, you +end up enabling warnings in pieces of code that you haven't written. +.PP +Similarly, using \f(CW$^W\fR to either disable or enable blocks of code is +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: +.PP +.Vb 5 +\& { +\& local ($^W) = 0; +\& my $x =+ 2; +\& my $y; chop $y; +\& } +.Ve +.PP +When this code is run with the \fB\-w\fR flag, a warning will be produced +for the \f(CW$x\fR line: \f(CW"Reversed += operator"\fR. +.PP +The problem is that Perl has both compile-time and run-time warnings. To +disable compile-time warnings you need to rewrite the code like this: +.PP +.Vb 5 +\& { +\& BEGIN { $^W = 0 } +\& my $x =+ 2; +\& my $y; chop $y; +\& } +.Ve +.PP +And note that unlike the first example, this will permanently set \f(CW$^W\fR +since it cannot both run during compile-time and be localized to a +run-time block. +.PP +The other big problem with \f(CW$^W\fR is the way you can inadvertently +change the warning setting in unexpected places in your code. For example, +when the code below is run (without the \fB\-w\fR flag), the second call +to \f(CW\*(C`doit\*(C'\fR will trip a \f(CW"Use of uninitialized value"\fR warning, whereas +the first will not. +.PP +.Vb 4 +\& sub doit +\& { +\& my $y; chop $y; +\& } +\& +\& doit(); +\& +\& { +\& local ($^W) = 1; +\& doit() +\& } +.Ve +.PP +This is a side-effect of \f(CW$^W\fR being dynamically scoped. +.PP +Lexical warnings get around these limitations by allowing finer control +over where warnings can or can't be tripped. +.SS "Controlling Warnings from the Command Line" +.IX Subsection "Controlling Warnings from the Command Line" +There are three Command Line flags that can be used to control when +warnings are (or aren't) produced: +.IP \fB\-w\fR 5 +.IX Xref "-w" +.IX Item "-w" +This is the existing flag. If the lexical warnings pragma is \fBnot\fR +used in any of your code, or any of the modules that you use, this flag +will enable warnings everywhere. See "Backward Compatibility" for +details of how this flag interacts with lexical warnings. +.IP \fB\-W\fR 5 +.IX Xref "-W" +.IX Item "-W" +If the \fB\-W\fR flag is used on the command line, it will enable all warnings +throughout the program regardless of whether warnings were disabled +locally using \f(CW\*(C`no warnings\*(C'\fR or \f(CW\*(C`$^W =0\*(C'\fR. +This includes all files that get +included via \f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR. +Think of it as the Perl equivalent of the "lint" command. +.IP \fB\-X\fR 5 +.IX Xref "-X" +.IX Item "-X" +Does the exact opposite to the \fB\-W\fR flag, i.e. it disables all warnings. +.SS "Backward Compatibility" +.IX Subsection "Backward Compatibility" +If you are used to working with a version of Perl prior to the +introduction of lexically scoped warnings, or have code that uses both +lexical warnings and \f(CW$^W\fR, this section will describe how they interact. +.PP +How Lexical Warnings interact with \fB\-w\fR/\f(CW$^W\fR: +.IP 1. 5 +If none of the three command line flags (\fB\-w\fR, \fB\-W\fR or \fB\-X\fR) that +control warnings is used and neither \f(CW$^W\fR nor the \f(CW\*(C`warnings\*(C'\fR pragma +are used, then default warnings will be enabled and optional warnings +disabled. +This means that legacy code that doesn't attempt to control the warnings +will work unchanged. +.IP 2. 5 +The \fB\-w\fR flag just sets the global \f(CW$^W\fR variable as in 5.005. This +means that any legacy code that currently relies on manipulating \f(CW$^W\fR +to control warning behavior will still work as is. +.IP 3. 5 +Apart from now being a boolean, the \f(CW$^W\fR variable operates in exactly +the same horrible uncontrolled global way, except that it cannot +disable/enable default warnings. +.IP 4. 5 +If a piece of code is under the control of the \f(CW\*(C`warnings\*(C'\fR pragma, +both the \f(CW$^W\fR variable and the \fB\-w\fR flag will be ignored for the +scope of the lexical warning. +.IP 5. 5 +The only way to override a lexical warnings setting is with the \fB\-W\fR +or \fB\-X\fR command line flags. +.PP +The combined effect of 3 & 4 is that it will allow code which uses +the \f(CW\*(C`warnings\*(C'\fR pragma to control the warning behavior of $^W\-type +code (using a \f(CW\*(C`local $^W=0\*(C'\fR) if it really wants to, but not vice-versa. +.SS "Category Hierarchy" +.IX Xref "warning, categories" +.IX Subsection "Category Hierarchy" +A hierarchy of "categories" have been defined to allow groups of warnings +to be enabled/disabled in isolation. +.PP +The current hierarchy is: +.PP +.Vb 10 +\& all \-+ +\& | +\& +\- closure +\& | +\& +\- deprecated \-\-\-\-+ +\& | | +\& | +\- deprecated::apostrophe_as_package_separator +\& | | +\& | +\- deprecated::delimiter_will_be_paired +\& | | +\& | +\- deprecated::dot_in_inc +\& | | +\& | +\- deprecated::goto_construct +\& | | +\& | +\- deprecated::smartmatch +\& | | +\& | +\- deprecated::unicode_property_name +\& | | +\& | +\- deprecated::version_downgrade +\& | +\& +\- exiting +\& | +\& +\- experimental \-\-+ +\& | | +\& | +\- experimental::args_array_with_signatures +\& | | +\& | +\- experimental::builtin +\& | | +\& | +\- experimental::class +\& | | +\& | +\- experimental::const_attr +\& | | +\& | +\- experimental::declared_refs +\& | | +\& | +\- experimental::defer +\& | | +\& | +\- experimental::extra_paired_delimiters +\& | | +\& | +\- experimental::for_list +\& | | +\& | +\- experimental::private_use +\& | | +\& | +\- experimental::re_strict +\& | | +\& | +\- experimental::refaliasing +\& | | +\& | +\- experimental::regex_sets +\& | | +\& | +\- experimental::try +\& | | +\& | +\- experimental::uniprop_wildcards +\& | | +\& | +\- experimental::vlb +\& | +\& +\- glob +\& | +\& +\- imprecision +\& | +\& +\- io \-\-\-\-\-\-\-\-\-\-\-\-+ +\& | | +\& | +\- closed +\& | | +\& | +\- exec +\& | | +\& | +\- layer +\& | | +\& | +\- newline +\& | | +\& | +\- pipe +\& | | +\& | +\- syscalls +\& | | +\& | +\- unopened +\& | +\& +\- locale +\& | +\& +\- misc +\& | +\& +\- missing +\& | +\& +\- numeric +\& | +\& +\- once +\& | +\& +\- overflow +\& | +\& +\- pack +\& | +\& +\- portable +\& | +\& +\- recursion +\& | +\& +\- redefine +\& | +\& +\- redundant +\& | +\& +\- regexp +\& | +\& +\- scalar +\& | +\& +\- severe \-\-\-\-\-\-\-\-+ +\& | | +\& | +\- debugging +\& | | +\& | +\- inplace +\& | | +\& | +\- internal +\& | | +\& | +\- malloc +\& | +\& +\- shadow +\& | +\& +\- signal +\& | +\& +\- substr +\& | +\& +\- syntax \-\-\-\-\-\-\-\-+ +\& | | +\& | +\- ambiguous +\& | | +\& | +\- bareword +\& | | +\& | +\- digit +\& | | +\& | +\- illegalproto +\& | | +\& | +\- parenthesis +\& | | +\& | +\- precedence +\& | | +\& | +\- printf +\& | | +\& | +\- prototype +\& | | +\& | +\- qw +\& | | +\& | +\- reserved +\& | | +\& | +\- semicolon +\& | +\& +\- taint +\& | +\& +\- threads +\& | +\& +\- uninitialized +\& | +\& +\- unpack +\& | +\& +\- untie +\& | +\& +\- utf8 \-\-\-\-\-\-\-\-\-\-+ +\& | | +\& | +\- non_unicode +\& | | +\& | +\- nonchar +\& | | +\& | +\- surrogate +\& | +\& +\- void +.Ve +.PP +Just like the "strict" pragma any of these categories can be combined +.PP +.Vb 2 +\& use warnings qw(void redefine); +\& no warnings qw(io syntax untie); +.Ve +.PP +Also like the "strict" pragma, if there is more than one instance of the +\&\f(CW\*(C`warnings\*(C'\fR pragma in a given scope the cumulative effect is additive. +.PP +.Vb 5 +\& use warnings qw(void); # only "void" warnings enabled +\& ... +\& use warnings qw(io); # only "void" & "io" warnings enabled +\& ... +\& no warnings qw(void); # only "io" warnings enabled +.Ve +.PP +To determine which category a specific warning has been assigned to see +perldiag. +.PP +Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a +sub-category of the "syntax" category. It is now a top-level category +in its own right. +.PP +Note: Before 5.21.0, the "missing" lexical warnings category was +internally defined to be the same as the "uninitialized" category. It +is now a top-level category in its own right. +.SS "Fatal Warnings" +.IX Xref "warning, fatal" +.IX Subsection "Fatal Warnings" +The presence of the word "FATAL" in the category list will escalate +warnings in those categories into fatal errors in that lexical scope. +.PP +\&\fBNOTE:\fR FATAL warnings should be used with care, particularly +\&\f(CW\*(C`FATAL => \*(Aqall\*(Aq\*(C'\fR. +.PP +Libraries using warnings::warn for custom warning categories +generally don't expect warnings::warn to be fatal and can wind up +in an unexpected state as a result. For XS modules issuing categorized +warnings, such unanticipated exceptions could also expose memory leak bugs. +.PP +Moreover, the Perl interpreter itself has had serious bugs involving +fatalized warnings. For a summary of resolved and unresolved problems as +of January 2015, please see +this perl5\-porters post <http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>. +.PP +While some developers find fatalizing some warnings to be a useful +defensive programming technique, using \f(CW\*(C`FATAL => \*(Aqall\*(Aq\*(C'\fR to fatalize +all possible warning categories \-\- including custom ones \-\- is particularly +risky. Therefore, the use of \f(CW\*(C`FATAL => \*(Aqall\*(Aq\*(C'\fR is +discouraged. +.PP +The strictures module on CPAN offers one example of +a warnings subset that the module's authors believe is relatively safe to +fatalize. +.PP +\&\fBNOTE:\fR Users of FATAL warnings, especially those using +\&\f(CW\*(C`FATAL => \*(Aqall\*(Aq\*(C'\fR, should be fully aware that they are risking future +portability of their programs by doing so. Perl makes absolutely no +commitments to not introduce new warnings or warnings categories in the +future; indeed, we explicitly reserve the right to do so. Code that may +not warn now may warn in a future release of Perl if the Perl5 development +team deems it in the best interests of the community to do so. Should code +using FATAL warnings break due to the introduction of a new warning we will +NOT consider it an incompatible change. Users of FATAL warnings should +take special caution during upgrades to check to see if their code triggers +any new warnings and should pay particular attention to the fine print of +the documentation of the features they use to ensure they do not exploit +features that are documented as risky, deprecated, or unspecified, or where +the documentation says "so don't do that", or anything with the same sense +and spirit. Use of such features in combination with FATAL warnings is +ENTIRELY AT THE USER'S RISK. +.PP +The following documentation describes how to use FATAL warnings but the +perl5 porters strongly recommend that you understand the risks before doing +so, especially for library code intended for use by others, as there is no +way for downstream users to change the choice of fatal categories. +.PP +In the code below, the use of \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`length\*(C'\fR +and \f(CW\*(C`join\*(C'\fR can all produce a \f(CW"Useless use of xxx in void context"\fR +warning. +.PP +.Vb 1 +\& use warnings; +\& +\& time; +\& +\& { +\& use warnings FATAL => qw(void); +\& length "abc"; +\& } +\& +\& join "", 1,2,3; +\& +\& print "done\en"; +.Ve +.PP +When run it produces this output +.PP +.Vb 2 +\& Useless use of time in void context at fatal line 3. +\& Useless use of length in void context at fatal line 7. +.Ve +.PP +The scope where \f(CW\*(C`length\*(C'\fR is used has escalated the \f(CW\*(C`void\*(C'\fR warnings +category into a fatal error, so the program terminates immediately when it +encounters the warning. +.PP +To explicitly turn off a "FATAL" warning you just disable the warning +it is associated with. So, for example, to disable the "void" warning +in the example above, either of these will do the trick: +.PP +.Vb 2 +\& no warnings qw(void); +\& no warnings FATAL => qw(void); +.Ve +.PP +If you want to downgrade a warning that has been escalated into a fatal +error back to a normal warning, you can use the "NONFATAL" keyword. For +example, the code below will promote all warnings into fatal errors, +except for those in the "syntax" category. +.PP +.Vb 1 +\& use warnings FATAL => \*(Aqall\*(Aq, NONFATAL => \*(Aqsyntax\*(Aq; +.Ve +.PP +As of Perl 5.20, instead of \f(CW\*(C`use warnings FATAL => \*(Aqall\*(Aq;\*(C'\fR you can +use: +.PP +.Vb 2 +\& use v5.20; # Perl 5.20 or greater is required for the following +\& use warnings \*(AqFATAL\*(Aq; # short form of "use warnings FATAL => \*(Aqall\*(Aq;" +.Ve +.PP +However, you should still heed the guidance earlier in this section against +using \f(CW\*(C`use warnings FATAL => \*(Aqall\*(Aq;\*(C'\fR. +.PP +If you want your program to be compatible with versions of Perl before +5.20, you must use \f(CW\*(C`use warnings FATAL => \*(Aqall\*(Aq;\*(C'\fR instead. (In +previous versions of Perl, the behavior of the statements +\&\f(CW\*(C`use warnings \*(AqFATAL\*(Aq;\*(C'\fR, \f(CW\*(C`use warnings \*(AqNONFATAL\*(Aq;\*(C'\fR and +\&\f(CW\*(C`no warnings \*(AqFATAL\*(Aq;\*(C'\fR was unspecified; they did not behave as if +they included the \f(CW\*(C`=> \*(Aqall\*(Aq\*(C'\fR portion. As of 5.20, they do.) +.SS "Reporting Warnings from a Module" +.IX Xref "warning, reporting warning, registering" +.IX Subsection "Reporting Warnings from a Module" +The \f(CW\*(C`warnings\*(C'\fR pragma provides a number of functions that are useful for +module authors. These are used when you want to report a module-specific +warning to a calling module has enabled warnings via the \f(CW\*(C`warnings\*(C'\fR +pragma. +.PP +Consider the module \f(CW\*(C`MyMod::Abc\*(C'\fR below. +.PP +.Vb 1 +\& package MyMod::Abc; +\& +\& use warnings::register; +\& +\& sub open { +\& my $path = shift; +\& if ($path !~ m#^/#) { +\& warnings::warn("changing relative path to /var/abc") +\& if warnings::enabled(); +\& $path = "/var/abc/$path"; +\& } +\& } +\& +\& 1; +.Ve +.PP +The call to \f(CW\*(C`warnings::register\*(C'\fR will create a new warnings category +called "MyMod::Abc", i.e. the new category name matches the current +package name. The \f(CW\*(C`open\*(C'\fR 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 \f(CW\*(C`MyMod::Abc\*(C'\fR has actually +enabled them with the \f(CW\*(C`warnings\*(C'\fR pragma like below. +.PP +.Vb 4 +\& use MyMod::Abc; +\& use warnings \*(AqMyMod::Abc\*(Aq; +\& ... +\& abc::open("../fred.txt"); +.Ve +.PP +It is also possible to test whether the pre-defined warnings categories are +set in the calling module with the \f(CW\*(C`warnings::enabled\*(C'\fR function. Consider +this snippet of code: +.PP +.Vb 1 +\& package MyMod::Abc; +\& +\& sub open { +\& if (warnings::enabled("deprecated")) { +\& warnings::warn("deprecated", +\& "open is deprecated, use new instead"); +\& } +\& new(@_); +\& } +\& +\& sub new +\& ... +\& 1; +.Ve +.PP +The function \f(CW\*(C`open\*(C'\fR has been deprecated, so code has been included to +display a warning message whenever the calling module has (at least) the +"deprecated" warnings category enabled. Something like this, say. +.PP +.Vb 4 +\& use warnings \*(Aqdeprecated\*(Aq; +\& use MyMod::Abc; +\& ... +\& MyMod::Abc::open($filename); +.Ve +.PP +Either the \f(CW\*(C`warnings::warn\*(C'\fR or \f(CW\*(C`warnings::warnif\*(C'\fR 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 +.PP +.Vb 4 +\& use MyMod::Abc; +\& use warnings FATAL => \*(AqMyMod::Abc\*(Aq; +\& ... +\& MyMod::Abc::open(\*(Aq../fred.txt\*(Aq); +.Ve +.PP +the \f(CW\*(C`warnings::warnif\*(C'\fR function will detect this and die after +displaying the warning message. +.PP +The three warnings functions, \f(CW\*(C`warnings::warn\*(C'\fR, \f(CW\*(C`warnings::warnif\*(C'\fR +and \f(CW\*(C`warnings::enabled\*(C'\fR can optionally take an object reference in place +of a category name. In this case the functions will use the class name +of the object as the warnings category. +.PP +Consider this example: +.PP +.Vb 1 +\& package Original; +\& +\& no warnings; +\& use warnings::register; +\& +\& sub new +\& { +\& my $class = shift; +\& bless [], $class; +\& } +\& +\& sub check +\& { +\& my $self = shift; +\& my $value = shift; +\& +\& if ($value % 2 && warnings::enabled($self)) +\& { warnings::warn($self, "Odd numbers are unsafe") } +\& } +\& +\& sub doit +\& { +\& my $self = shift; +\& my $value = shift; +\& $self\->check($value); +\& # ... +\& } +\& +\& 1; +\& +\& package Derived; +\& +\& use warnings::register; +\& use Original; +\& our @ISA = qw( Original ); +\& sub new +\& { +\& my $class = shift; +\& bless [], $class; +\& } +\& +\& +\& 1; +.Ve +.PP +The code below makes use of both modules, but it only enables warnings from +\&\f(CW\*(C`Derived\*(C'\fR. +.PP +.Vb 7 +\& use Original; +\& use Derived; +\& use warnings \*(AqDerived\*(Aq; +\& my $x = Original\->new(); +\& $x\->doit(1); +\& my $y = Derived\->new(); +\& $x\->doit(1); +.Ve +.PP +When this code is run only the \f(CW\*(C`Derived\*(C'\fR object, \f(CW$y\fR, will generate +a warning. +.PP +.Vb 1 +\& Odd numbers are unsafe at main.pl line 7 +.Ve +.PP +Notice also that the warning is reported at the line where the object is first +used. +.PP +When registering new categories of warning, you can supply more names to +warnings::register like this: +.PP +.Vb 2 +\& package MyModule; +\& use warnings::register qw(format precision); +\& +\& ... +\& +\& warnings::warnif(\*(AqMyModule::format\*(Aq, \*(Aq...\*(Aq); +.Ve +.SH FUNCTIONS +.IX Header "FUNCTIONS" +Note: The functions with names ending in \f(CW\*(C`_at_level\*(C'\fR were added in Perl +5.28. +.IP "use warnings::register" 4 +.IX Item "use warnings::register" +Creates a new warnings category with the same name as the package where +the call to the pragma is used. +.IP \fBwarnings::enabled()\fR 4 +.IX Item "warnings::enabled()" +Use the warnings category with the same name as the current package. +.Sp +Return TRUE if that warnings category is enabled in the calling module. +Otherwise returns FALSE. +.IP warnings::enabled($category) 4 +.IX Item "warnings::enabled($category)" +Return TRUE if the warnings category, \f(CW$category\fR, is enabled in the +calling module. +Otherwise returns FALSE. +.IP warnings::enabled($object) 4 +.IX Item "warnings::enabled($object)" +Use the name of the class for the object reference, \f(CW$object\fR, as the +warnings category. +.Sp +Return TRUE if that warnings category is enabled in the first scope +where the object is used. +Otherwise returns FALSE. +.ie n .IP "warnings::enabled_at_level($category, $level)" 4 +.el .IP "warnings::enabled_at_level($category, \f(CW$level\fR)" 4 +.IX Item "warnings::enabled_at_level($category, $level)" +Like \f(CW\*(C`warnings::enabled\*(C'\fR, but \f(CW$level\fR specifies the exact call frame, 0 +being the immediate caller. +.IP \fBwarnings::fatal_enabled()\fR 4 +.IX Item "warnings::fatal_enabled()" +Return TRUE if the warnings category with the same name as the current +package has been set to FATAL in the calling module. +Otherwise returns FALSE. +.IP warnings::fatal_enabled($category) 4 +.IX Item "warnings::fatal_enabled($category)" +Return TRUE if the warnings category \f(CW$category\fR has been set to FATAL in +the calling module. +Otherwise returns FALSE. +.IP warnings::fatal_enabled($object) 4 +.IX Item "warnings::fatal_enabled($object)" +Use the name of the class for the object reference, \f(CW$object\fR, as the +warnings category. +.Sp +Return TRUE if that warnings category has been set to FATAL in the first +scope where the object is used. +Otherwise returns FALSE. +.ie n .IP "warnings::fatal_enabled_at_level($category, $level)" 4 +.el .IP "warnings::fatal_enabled_at_level($category, \f(CW$level\fR)" 4 +.IX Item "warnings::fatal_enabled_at_level($category, $level)" +Like \f(CW\*(C`warnings::fatal_enabled\*(C'\fR, but \f(CW$level\fR specifies the exact call frame, +0 being the immediate caller. +.IP warnings::warn($message) 4 +.IX Item "warnings::warn($message)" +Print \f(CW$message\fR to STDERR. +.Sp +Use the warnings category with the same name as the current package. +.Sp +If that warnings category has been set to "FATAL" in the calling module +then die. Otherwise return. +.ie n .IP "warnings::warn($category, $message)" 4 +.el .IP "warnings::warn($category, \f(CW$message\fR)" 4 +.IX Item "warnings::warn($category, $message)" +Print \f(CW$message\fR to STDERR. +.Sp +If the warnings category, \f(CW$category\fR, has been set to "FATAL" in the +calling module then die. Otherwise return. +.ie n .IP "warnings::warn($object, $message)" 4 +.el .IP "warnings::warn($object, \f(CW$message\fR)" 4 +.IX Item "warnings::warn($object, $message)" +Print \f(CW$message\fR to STDERR. +.Sp +Use the name of the class for the object reference, \f(CW$object\fR, as the +warnings category. +.Sp +If that warnings category has been set to "FATAL" in the scope where \f(CW$object\fR +is first used then die. Otherwise return. +.ie n .IP "warnings::warn_at_level($category, $level, $message)" 4 +.el .IP "warnings::warn_at_level($category, \f(CW$level\fR, \f(CW$message\fR)" 4 +.IX Item "warnings::warn_at_level($category, $level, $message)" +Like \f(CW\*(C`warnings::warn\*(C'\fR, but \f(CW$level\fR specifies the exact call frame, +0 being the immediate caller. +.IP warnings::warnif($message) 4 +.IX Item "warnings::warnif($message)" +Equivalent to: +.Sp +.Vb 2 +\& if (warnings::enabled()) +\& { warnings::warn($message) } +.Ve +.ie n .IP "warnings::warnif($category, $message)" 4 +.el .IP "warnings::warnif($category, \f(CW$message\fR)" 4 +.IX Item "warnings::warnif($category, $message)" +Equivalent to: +.Sp +.Vb 2 +\& if (warnings::enabled($category)) +\& { warnings::warn($category, $message) } +.Ve +.ie n .IP "warnings::warnif($object, $message)" 4 +.el .IP "warnings::warnif($object, \f(CW$message\fR)" 4 +.IX Item "warnings::warnif($object, $message)" +Equivalent to: +.Sp +.Vb 2 +\& if (warnings::enabled($object)) +\& { warnings::warn($object, $message) } +.Ve +.ie n .IP "warnings::warnif_at_level($category, $level, $message)" 4 +.el .IP "warnings::warnif_at_level($category, \f(CW$level\fR, \f(CW$message\fR)" 4 +.IX Item "warnings::warnif_at_level($category, $level, $message)" +Like \f(CW\*(C`warnings::warnif\*(C'\fR, but \f(CW$level\fR specifies the exact call frame, +0 being the immediate caller. +.IP warnings::register_categories(@names) 4 +.IX Item "warnings::register_categories(@names)" +This registers warning categories for the given names and is primarily for +use by the warnings::register pragma. +.PP +See also "Pragmatic Modules" in perlmodlib and perldiag. |