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