This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
if.pm: Better failure message for 'no if'
[perl5.git] / dist / if / if.pm
CommitLineData
cd16c24c
IZ
1package if;
2
14735530 3$VERSION = '0.0605';
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
53=head2 EXAMPLES
54
55The following line is taken from the testsuite for L<File::Map>:
56
57 use if $^O ne 'MSWin32', POSIX => qw/setlocale LC_ALL/;
58
59If run on any operating system other than Windows,
60this will import the functions C<setlocale> and C<LC_ALL> from L<POSIX>.
61On Windows it does nothing.
62
63The following is used to L<deprecate> core modules beyond a certain version of Perl:
64
65 use if $] > 5.016, 'deprecate';
66
67This line is taken from L<Text::Soundex> 3.04,
68and marks it as deprecated beyond Perl 5.16.
69If you C<use Text::Soundex> in Perl 5.18, for example,
70and you have used L<warnings>,
71then you'll get a warning message
72(the deprecate module looks to see whether the
73calling module was C<use>'d from a core library directory,
74and if so, generates a warning),
75unless you've installed a more recent version of L<Text::Soundex> from CPAN.
fae40608 76
d1d50e3e
KW
77You can also specify to NOT use something:
78
79 no if $] ge 5.021_006, warnings => "locale";
80
81This warning category was added in the specified Perl version (a development
82release). Without the C<'if'>, trying to use it in an earlier release would
83generate an unknown warning category error.
84
cd16c24c
IZ
85=head1 BUGS
86
87The current implementation does not allow specification of the
88required version of the module.
89
88da3e79
NB
90=head1 SEE ALSO
91
92L<Module::Requires> can be used to conditionally load one or modules,
93with constraints based on the version of the module.
94Unlike C<if> though, L<Module::Requires> is not a core module.
95
96L<Module::Load::Conditional> provides a number of functions you can use to
97query what modules are available, and then load one or more of them at runtime.
98
99L<provide> can be used to select one of several possible modules to load,
100based on what version of Perl is running.
101
cd16c24c
IZ
102=head1 AUTHOR
103
81495e8f 104Ilya Zakharevich L<mailto:ilyaz@cpan.org>.
cd16c24c
IZ
105
106=cut