summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/if.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/if.pm')
-rw-r--r--Master/tlpkg/tlperl/lib/if.pm50
1 files changed, 45 insertions, 5 deletions
diff --git a/Master/tlpkg/tlperl/lib/if.pm b/Master/tlpkg/tlperl/lib/if.pm
index 1fb5f3deb49..511b8a5b7c6 100644
--- a/Master/tlpkg/tlperl/lib/if.pm
+++ b/Master/tlpkg/tlperl/lib/if.pm
@@ -1,6 +1,6 @@
package if;
-$VERSION = '0.0602';
+$VERSION = '0.0603';
sub work {
my $method = shift() ? 'import' : 'unimport';
@@ -31,23 +31,63 @@ if - C<use> a Perl module if a condition holds
=head1 DESCRIPTION
+The C<if> module is used to conditionally load another module.
The construct
use if CONDITION, MODULE => ARGUMENTS;
-has no effect unless C<CONDITION> is true. In this case the effect is
-the same as of
+will load MODULE only if CONDITION evaluates to true.
+The above statement has no effect unless C<CONDITION> is true.
+If the CONDITION does evaluate to true, then the above line has
+the same effect as:
use MODULE ARGUMENTS;
-Above C<< => >> provides necessary quoting of C<MODULE>. If not used (e.g.,
-no ARGUMENTS to give), you'd better quote C<MODULE> yourselves.
+The use of C<< => >> above provides necessary quoting of C<MODULE>.
+If you don't use the fat comma (eg you don't have any ARGUMENTS),
+then you'll need to quote the MODULE.
+
+=head2 EXAMPLES
+
+The following line is taken from the testsuite for L<File::Map>:
+
+ use if $^O ne 'MSWin32', POSIX => qw/setlocale LC_ALL/;
+
+If run on any operating system other than Windows,
+this will import the functions C<setlocale> and C<LC_ALL> from L<POSIX>.
+On Windows it does nothing.
+
+The following is used to L<deprecate> core modules beyond a certain version of Perl:
+
+ use if $] > 5.016, 'deprecate';
+
+This line is taken from L<Text::Soundex> 3.04,
+and marks it as deprecated beyond Perl 5.16.
+If you C<use Text::Soundex> in Perl 5.18, for example,
+and you have used L<warnings>,
+then you'll get a warning message
+(the deprecate module looks to see whether the
+calling module was C<use>'d from a core library directory,
+and if so, generates a warning),
+unless you've installed a more recent version of L<Text::Soundex> from CPAN.
=head1 BUGS
The current implementation does not allow specification of the
required version of the module.
+=head1 SEE ALSO
+
+L<Module::Requires> can be used to conditionally load one or modules,
+with constraints based on the version of the module.
+Unlike C<if> though, L<Module::Requires> is not a core module.
+
+L<Module::Load::Conditional> provides a number of functions you can use to
+query what modules are available, and then load one or more of them at runtime.
+
+L<provide> can be used to select one of several possible modules to load,
+based on what version of Perl is running.
+
=head1 AUTHOR
Ilya Zakharevich L<mailto:ilyaz@cpan.org>.