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