Debian Codegraph @

upstream/opensuse-tumbleweed/man3/if.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "if 3pm"
61 .TH if 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 if \- "use" a Perl module if a condition holds
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use if CONDITION, "MODULE", ARGUMENTS;
72 \& no if CONDITION, "MODULE", ARGUMENTS;
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 .ie n .SS """use if"""
77 .el .SS "\f(CWuse if\fP"
78 .IX Subsection "use if"
79 The \f(CW\*(C`if\*(C'\fR module is used to conditionally load another module. The construct:
80 .PP
81 .Vb 1
82 \& use if CONDITION, "MODULE", ARGUMENTS;
83 .Ve
84 .PP
85 \&... will load \f(CW\*(C`MODULE\*(C'\fR only if \f(CW\*(C`CONDITION\*(C'\fR evaluates to true; it has no
86 effect if \f(CW\*(C`CONDITION\*(C'\fR evaluates to false. (The module name, assuming it
87 contains at least one \f(CW\*(C`::\*(C'\fR, must be quoted when \f(CW\*(Aquse strict "subs";\*(Aq\fR is in
88 effect.) If the CONDITION does evaluate to true, then the above line has the
89 same effect as:
90 .PP
91 .Vb 1
92 \& use MODULE ARGUMENTS;
93 .Ve
94 .PP
95 For example, the \fIUnicode::UCD\fR module\*(Aqs \fIcharinfo\fR function will use two functions from \fIUnicode::Normalize\fR only if a certain condition is met:
96 .PP
97 .Vb 2
98 \& use if defined &DynaLoader::boot_DynaLoader,
99 \& "Unicode::Normalize" => qw(getCombinClass NFD);
100 .Ve
101 .PP
102 Suppose you wanted \f(CW\*(C`ARGUMENTS\*(C'\fR to be an empty list, \fIi.e.\fR, to have the
103 effect of:
104 .PP
105 .Vb 1
106 \& use MODULE ();
107 .Ve
108 .PP
109 You can\*(Aqt do this with the \f(CW\*(C`if\*(C'\fR pragma; however, you can achieve
110 exactly this effect, at compile time, with:
111 .PP
112 .Vb 1
113 \& BEGIN { require MODULE if CONDITION }
114 .Ve
115 .ie n .SS """no if"""
116 .el .SS "\f(CWno if\fP"
117 .IX Subsection "no if"
118 The \f(CW\*(C`no if\*(C'\fR construct is mainly used to deactivate categories of warnings
119 when those categories would produce superfluous output under specified
120 versions of \fIperl\fR.
121 .PP
122 For example, the \f(CW\*(C`redundant\*(C'\fR category of warnings was introduced in
123 Perl\-5.22. This warning flags certain instances of superfluous arguments to
124 \&\f(CW\*(C`printf\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR. But if your code was running warnings\-free on
125 earlier versions of \fIperl\fR and you don\*(Aqt care about \f(CW\*(C`redundant\*(C'\fR warnings in
126 more recent versions, you can call:
127 .PP
128 .Vb 2
129 \& use warnings;
130 \& no if $] >= 5.022, q|warnings|, qw(redundant);
131 \&
132 \& my $test = { fmt => "%s", args => [ qw( x y ) ] };
133 \& my $result = sprintf $test\->{fmt}, @{$test\->{args}};
134 .Ve
135 .PP
136 The \f(CW\*(C`no if\*(C'\fR construct assumes that a module or pragma has correctly
137 implemented an \f(CWunimport()\fR method \-\- but most modules and pragmata have not.
138 That explains why the \f(CW\*(C`no if\*(C'\fR construct is of limited applicability.
139 .SH BUGS
140 .IX Header "BUGS"
141 The current implementation does not allow specification of the required
142 version of the module.
143 .SH "SEE ALSO"
144 .IX Header "SEE ALSO"
145 Module::Requires can be used to conditionally load one or more modules,
146 with constraints based on the version of the module.
147 Unlike \f(CW\*(C`if\*(C'\fR though, Module::Requires is not a core module.
148 .PP
149 Module::Load::Conditional provides a number of functions you can use to
150 query what modules are available, and then load one or more of them at runtime.
151 .PP
152 The provide module from CPAN can be used to select one of several possible
153 modules to load based on the version of Perl that is running.
154 .SH AUTHOR
155 .IX Header "AUTHOR"
156 Ilya Zakharevich <mailto:[email protected]>.
157 .SH "COPYRIGHT AND LICENCE"
158 .IX Header "COPYRIGHT AND LICENCE"
159 This software is copyright (c) 2002 by Ilya Zakharevich.
160 .PP
161 This is free software; you can redistribute it and/or modify it under
162 the same terms as the Perl 5 programming language system itself.