This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pp_warn: use MEXTEND rather than EXTEND
[perl5.git] / dist / if / if.pm
CommitLineData
cd16c24c
IZ
1package if;
2
16279618 3$VERSION = '0.0607';
cd16c24c
IZ
4
5sub work {
6 my $method = shift() ? 'import' : 'unimport';
14735530
KW
7 unless (@_ >= 2) {
8 my $type = ($method eq 'import') ? 'use' : 'no';
9 die "Too few arguments to '$type if' (some code returning an empty list in list context?)"
10 }
cd16c24c 11 return unless shift; # CONDITION
a3e5cfd4
S
12
13 my $p = $_[0]; # PACKAGE
b9761643 14 (my $file = "$p.pm") =~ s!::!/!g;
2f761939 15 require $file; # Works even if $_[0] is a keyword (like open)
a3e5cfd4
S
16 my $m = $p->can($method);
17 goto &$m if $m;
cd16c24c
IZ
18}
19
20sub import { shift; unshift @_, 1; goto &work }
21sub unimport { shift; unshift @_, 0; goto &work }
22
231;
24__END__
25
26=head1 NAME
27
d1d50e3e 28if - C<use> a Perl module if a condition holds (also can C<no> a module)
cd16c24c
IZ
29
30=head1 SYNOPSIS
31
32 use if CONDITION, MODULE => ARGUMENTS;
d1d50e3e 33 no if CONDITION, MODULE => ARGUMENTS;
cd16c24c
IZ
34
35=head1 DESCRIPTION
36
d1d50e3e 37The C<if> module is used to conditionally load or unload another module.
cd16c24c
IZ
38The construct
39
40 use if CONDITION, MODULE => ARGUMENTS;
41
88da3e79
NB
42will load MODULE only if CONDITION evaluates to true.
43The above statement has no effect unless C<CONDITION> is true.
44If the CONDITION does evaluate to true, then the above line has
45the same effect as:
cd16c24c
IZ
46
47 use MODULE ARGUMENTS;
48
88da3e79
NB
49The use of C<< => >> above provides necessary quoting of C<MODULE>.
50If you don't use the fat comma (eg you don't have any ARGUMENTS),
51then you'll need to quote the MODULE.
52
16279618
KC
53If you wanted ARGUMENTS to be an empty list, i.e. have the effect of:
54
55 use MODULE ();
56
57you can't do this with the C<if> pragma; however, you can achieve
58exactly this effect, at compile time, with:
59
60 BEGIN { require MODULE if CONDITION }
61
88da3e79
NB
62=head2 EXAMPLES
63
64The following line is taken from the testsuite for L<File::Map>:
65
66 use if $^O ne 'MSWin32', POSIX => qw/setlocale LC_ALL/;
67
68If run on any operating system other than Windows,
69this will import the functions C<setlocale> and C<LC_ALL> from L<POSIX>.
70On Windows it does nothing.
71
72The following is used to L<deprecate> core modules beyond a certain version of Perl:
73
74 use if $] > 5.016, 'deprecate';
75
76This line is taken from L<Text::Soundex> 3.04,
77and marks it as deprecated beyond Perl 5.16.
78If you C<use Text::Soundex> in Perl 5.18, for example,
79and you have used L<warnings>,
80then you'll get a warning message
81(the deprecate module looks to see whether the
82calling module was C<use>'d from a core library directory,
83and if so, generates a warning),
84unless you've installed a more recent version of L<Text::Soundex> from CPAN.
fae40608 85
d1d50e3e
KW
86You can also specify to NOT use something:
87
88 no if $] ge 5.021_006, warnings => "locale";
89
90This warning category was added in the specified Perl version (a development
91release). Without the C<'if'>, trying to use it in an earlier release would
92generate an unknown warning category error.
93
cd16c24c
IZ
94=head1 BUGS
95
96The current implementation does not allow specification of the
97required version of the module.
98
88da3e79
NB
99=head1 SEE ALSO
100
101L<Module::Requires> can be used to conditionally load one or modules,
102with constraints based on the version of the module.
103Unlike C<if> though, L<Module::Requires> is not a core module.
104
105L<Module::Load::Conditional> provides a number of functions you can use to
106query what modules are available, and then load one or more of them at runtime.
107
108L<provide> can be used to select one of several possible modules to load,
109based on what version of Perl is running.
110
cd16c24c
IZ
111=head1 AUTHOR
112
81495e8f 113Ilya Zakharevich L<mailto:ilyaz@cpan.org>.
cd16c24c 114
4b89cb47
KE
115=head1 COPYRIGHT AND LICENCE
116
117This software is copyright (c) 2002 by Ilya Zakharevich.
118
119This is free software; you can redistribute it and/or modify it under
120the same terms as the Perl 5 programming language system itself.
121
cd16c24c 122=cut