Debian Codegraph @

upstream/debian-unstable/man3/if.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (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 .\"
57 .IX Title "if 3perl"
58 .TH if 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 if \- "use" a Perl module if a condition holds
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& use if CONDITION, "MODULE", ARGUMENTS;
69 \& no if CONDITION, "MODULE", ARGUMENTS;
70 .Ve
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 .ie n .SS """use if"""
74 .el .SS "\f(CWuse if\fP"
75 .IX Subsection "use if"
76 The \f(CW\*(C`if\*(C'\fR module is used to conditionally load another module. The construct:
77 .PP
78 .Vb 1
79 \& use if CONDITION, "MODULE", ARGUMENTS;
80 .Ve
81 .PP
82 \&... will load \f(CW\*(C`MODULE\*(C'\fR only if \f(CW\*(C`CONDITION\*(C'\fR evaluates to true; it has no
83 effect if \f(CW\*(C`CONDITION\*(C'\fR evaluates to false. (The module name, assuming it
84 contains at least one \f(CW\*(C`::\*(C'\fR, must be quoted when \f(CW\*(Aquse strict "subs";\*(Aq\fR is in
85 effect.) If the CONDITION does evaluate to true, then the above line has the
86 same effect as:
87 .PP
88 .Vb 1
89 \& use MODULE ARGUMENTS;
90 .Ve
91 .PP
92 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:
93 .PP
94 .Vb 2
95 \& use if defined &DynaLoader::boot_DynaLoader,
96 \& "Unicode::Normalize" => qw(getCombinClass NFD);
97 .Ve
98 .PP
99 Suppose you wanted \f(CW\*(C`ARGUMENTS\*(C'\fR to be an empty list, \fIi.e.\fR, to have the
100 effect of:
101 .PP
102 .Vb 1
103 \& use MODULE ();
104 .Ve
105 .PP
106 You can't do this with the \f(CW\*(C`if\*(C'\fR pragma; however, you can achieve
107 exactly this effect, at compile time, with:
108 .PP
109 .Vb 1
110 \& BEGIN { require MODULE if CONDITION }
111 .Ve
112 .ie n .SS """no if"""
113 .el .SS "\f(CWno if\fP"
114 .IX Subsection "no if"
115 The \f(CW\*(C`no if\*(C'\fR construct is mainly used to deactivate categories of warnings
116 when those categories would produce superfluous output under specified
117 versions of \fIperl\fR.
118 .PP
119 For example, the \f(CW\*(C`redundant\*(C'\fR category of warnings was introduced in
120 Perl\-5.22. This warning flags certain instances of superfluous arguments to
121 \&\f(CW\*(C`printf\*(C'\fR and \f(CW\*(C`sprintf\*(C'\fR. But if your code was running warnings-free on
122 earlier versions of \fIperl\fR and you don't care about \f(CW\*(C`redundant\*(C'\fR warnings in
123 more recent versions, you can call:
124 .PP
125 .Vb 2
126 \& use warnings;
127 \& no if $] >= 5.022, q|warnings|, qw(redundant);
128 \&
129 \& my $test = { fmt => "%s", args => [ qw( x y ) ] };
130 \& my $result = sprintf $test\->{fmt}, @{$test\->{args}};
131 .Ve
132 .PP
133 The \f(CW\*(C`no if\*(C'\fR construct assumes that a module or pragma has correctly
134 implemented an \f(CWunimport()\fR method \-\- but most modules and pragmata have not.
135 That explains why the \f(CW\*(C`no if\*(C'\fR construct is of limited applicability.
136 .SH BUGS
137 .IX Header "BUGS"
138 The current implementation does not allow specification of the required
139 version of the module.
140 .SH "SEE ALSO"
141 .IX Header "SEE ALSO"
142 Module::Requires can be used to conditionally load one or more modules,
143 with constraints based on the version of the module.
144 Unlike \f(CW\*(C`if\*(C'\fR though, Module::Requires is not a core module.
145 .PP
146 Module::Load::Conditional provides a number of functions you can use to
147 query what modules are available, and then load one or more of them at runtime.
148 .PP
149 The provide module from CPAN can be used to select one of several possible
150 modules to load based on the version of Perl that is running.
151 .SH AUTHOR
152 .IX Header "AUTHOR"
153 Ilya Zakharevich <mailto:[email protected]>.
154 .SH "COPYRIGHT AND LICENCE"
155 .IX Header "COPYRIGHT AND LICENCE"
156 This software is copyright (c) 2002 by Ilya Zakharevich.
157 .PP
158 This is free software; you can redistribute it and/or modify it under
159 the same terms as the Perl 5 programming language system itself.