dist/if/if.pm

   1 package if;
   2
   3 $VERSION = '0.0608';
   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
  29
  30 =head1 SYNOPSIS
  31
  32     use if CONDITION, "MODULE", ARGUMENTS;
  33     no  if CONDITION, "MODULE", ARGUMENTS;
  34
  35 =head1 DESCRIPTION
  36
  37 =head2 C<use if>
  38
  39 The C<if> module is used to conditionally load another module.  The construct:
  40
  41     use if CONDITION, "MODULE", ARGUMENTS;
  42
  43 ... will load C<MODULE> only if C<CONDITION> evaluates to true; it has no
  44 effect if C<CONDITION> evaluates to false.  (The module name, assuming it
  45 contains at least one C<::>, must be quoted when C<'use strict "subs";'> is in
  46 effect.)  If the CONDITION does evaluate to true, then the above line has the
  47 same effect as:
  48
  49     use MODULE ARGUMENTS;
  50
  51 For example, the F<Unicode::UCD> module's F<charinfo> function will use two functions from F<Unicode::Normalize> only if a certain condition is met:
  52
  53     use if defined &DynaLoader::boot_DynaLoader,
  54         "Unicode::Normalize" => qw(getCombinClass NFD);
  55
  56 Suppose you wanted C<ARGUMENTS> to be an empty list, I<i.e.>, to have the
  57 effect of:
  58
  59     use MODULE ();
  60
  61 You can't do this with the C<if> pragma; however, you can achieve
  62 exactly this effect, at compile time, with:
  63
  64     BEGIN { require MODULE if CONDITION }
  65
  66 =head2 C<no if>
  67
  68 The C<no if> construct is mainly used to deactivate categories of warnings
  69 when those categories would produce superfluous output under specified
  70 versions of F<perl>.
  71
  72 For example, the C<redundant> category of warnings was introduced in
  73 Perl-5.22.  This warning flags certain instances of superfluous arguments to
  74 C<printf> and C<sprintf>.  But if your code was running warnings-free on
  75 earlier versions of F<perl> and you don't care about C<redundant> warnings in
  76 more recent versions, you can call:
  77
  78     use warnings;
  79     no if $] >= 5.022, q|warnings|, qw(redundant);
  80
  81     my $test    = { fmt  => "%s", args => [ qw( x y ) ] };
  82     my $result  = sprintf $test->{fmt}, @{$test->{args}};
  83
  84 The C<no if> construct assumes that a module or pragma has correctly
  85 implemented an C<unimport()> method -- but most modules and pragmata have not.
  86 That explains why the C<no if> construct is of limited applicability.
  87
  88 =head1 BUGS
  89
  90 The current implementation does not allow specification of the required
  91 version of the module.
  92
  93 =head1 SEE ALSO
  94
  95 L<Module::Requires> can be used to conditionally load one or modules,
  96 with constraints based on the version of the module.
  97 Unlike C<if> though, L<Module::Requires> is not a core module.
  98
  99 L<Module::Load::Conditional> provides a number of functions you can use to
 100 query what modules are available, and then load one or more of them at runtime.
 101
 102 The L<provide> module from CPAN can be used to select one of several possible
 103 modules to load based on the version of Perl that is running.
 104
 105 =head1 AUTHOR
 106
 107 Ilya Zakharevich L<mailto:ilyaz@cpan.org>.
 108
 109 =head1 COPYRIGHT AND LICENCE
 110
 111 This software is copyright (c) 2002 by Ilya Zakharevich.
 112
 113 This is free software; you can redistribute it and/or modify it under
 114 the same terms as the Perl 5 programming language system itself.
 115
 116 =cut