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