1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
.\" -*- 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 "if 3perl"
.TH if 3perl 2024-02-11 "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
if \- "use" a Perl module if a condition holds
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use if CONDITION, "MODULE", ARGUMENTS;
\& no if CONDITION, "MODULE", ARGUMENTS;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
.ie n .SS """use if"""
.el .SS "\f(CWuse if\fP"
.IX Subsection "use if"
The \f(CW\*(C`if\*(C'\fR module is used to conditionally load another module. The construct:
.PP
.Vb 1
\& use if CONDITION, "MODULE", ARGUMENTS;
.Ve
.PP
\&... will load \f(CW\*(C`MODULE\*(C'\fR only if \f(CW\*(C`CONDITION\*(C'\fR evaluates to true; it has no
effect if \f(CW\*(C`CONDITION\*(C'\fR evaluates to false. (The module name, assuming it
contains at least one \f(CW\*(C`::\*(C'\fR, must be quoted when \f(CW\*(Aquse strict "subs";\*(Aq\fR is in
effect.) If the CONDITION does evaluate to true, then the above line has the
same effect as:
.PP
.Vb 1
\& use MODULE ARGUMENTS;
.Ve
.PP
For example, the \fIUnicode::UCD\fR module's \fIcharinfo\fR function will use two functions from \fIUnicode::Normalize\fR only if a certain condition is met:
.PP
.Vb 2
\& use if defined &DynaLoader::boot_DynaLoader,
\& "Unicode::Normalize" => qw(getCombinClass NFD);
.Ve
.PP
Suppose you wanted \f(CW\*(C`ARGUMENTS\*(C'\fR to be an empty list, \fIi.e.\fR, to have the
effect of:
.PP
.Vb 1
\& use MODULE ();
.Ve
.PP
You can't do this with the \f(CW\*(C`if\*(C'\fR pragma; however, you can achieve
exactly this effect, at compile time, with:
.PP
.Vb 1
\& BEGIN { require MODULE if CONDITION }
.Ve
.ie n .SS """no if"""
.el .SS "\f(CWno if\fP"
.IX Subsection "no if"
The \f(CW\*(C`no if\*(C'\fR construct is mainly used to deactivate categories of warnings
when those categories would produce superfluous output under specified
versions of \fIperl\fR.
.PP
For example, the \f(CW\*(C`redundant\*(C'\fR category of warnings was introduced in
Perl\-5.22. This warning flags certain instances of superfluous arguments to
\&\f(CW\*(C`printf\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR. But if your code was running warnings-free on
earlier versions of \fIperl\fR and you don't care about \f(CW\*(C`redundant\*(C'\fR warnings in
more recent versions, you can call:
.PP
.Vb 2
\& use warnings;
\& no if $] >= 5.022, q|warnings|, qw(redundant);
\&
\& my $test = { fmt => "%s", args => [ qw( x y ) ] };
\& my $result = sprintf $test\->{fmt}, @{$test\->{args}};
.Ve
.PP
The \f(CW\*(C`no if\*(C'\fR construct assumes that a module or pragma has correctly
implemented an \f(CWunimport()\fR method \-\- but most modules and pragmata have not.
That explains why the \f(CW\*(C`no if\*(C'\fR construct is of limited applicability.
.SH BUGS
.IX Header "BUGS"
The current implementation does not allow specification of the required
version of the module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Module::Requires can be used to conditionally load one or more modules,
with constraints based on the version of the module.
Unlike \f(CW\*(C`if\*(C'\fR though, Module::Requires is not a core module.
.PP
Module::Load::Conditional provides a number of functions you can use to
query what modules are available, and then load one or more of them at runtime.
.PP
The provide module from CPAN can be used to select one of several possible
modules to load based on the version of Perl that is running.
.SH AUTHOR
.IX Header "AUTHOR"
Ilya Zakharevich <mailto:ilyaz@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2002 by Ilya Zakharevich.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
|
