Skip to content
This repository was archived by the owner on Jun 1, 2023. It is now read-only.

Commit 29e241a

Browse files
rurbanrurban
committed
if-0.0608
Doc how to import when you want to use MODULE ()
1 parent d70b6ee commit 29e241a

File tree

5 files changed

+128
-64
lines changed

5 files changed

+128
-64
lines changed

‎Porting/Maintainers.pl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -840,7 +840,7 @@ package Maintainers;
840840
},
841841

842842
'if' => {
843-
'DISTRIBUTION' => 'RJBS/if-0.0606.tar.gz',
843+
'DISTRIBUTION' => 'XSAWYERX/if-0.0608.tar.gz',
844844
'FILES' => q[dist/if],
845845
},
846846

‎dist/Module-CoreList/lib/Module/CoreList.pm‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17724,6 +17724,7 @@ our %delta :const = (
1772417724
'File::Temp' => '0.2308',
1772517725
'Filter::Util::Call' => '1.59',
1772617726
'HTTP::Tiny' => '0.076_01',
17727+
'if' => '0.0608',
1772717728
'IO' => '1.39_01',
1772817729
'IO::Dir' => '1.39',
1772917730
'IO::File' => '1.39',

‎dist/if/if.pm‎

Lines changed: 44 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
package if;
22

3-
$VERSION = '0.0606';
3+
$VERSION = '0.0608';
44

55
sub work {
66
my $method = shift() ? 'import' : 'unimport';
@@ -25,67 +25,70 @@ __END__
2525
2626
=head1 NAME
2727
28-
if - C<use> a Perl module if a condition holds (also can C<no> a module)
28+
if - C<use> a Perl module if a condition holds
2929
3030
=head1 SYNOPSIS
3131
32-
use if CONDITION, MODULE => ARGUMENTS;
33-
no if CONDITION, MODULE => ARGUMENTS;
32+
use if CONDITION, "MODULE", ARGUMENTS;
33+
no if CONDITION, "MODULE", ARGUMENTS;
3434
3535
=head1 DESCRIPTION
3636
37-
The C<if> module is used to conditionally load or unload another module.
38-
The construct
37+
=head2 C<use if>
3938
40-
use if CONDITION, MODULE => ARGUMENTS;
39+
The C<if> module is used to conditionally load another module. The construct:
4140
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:
41+
use if CONDITION, "MODULE", ARGUMENTS;
4642
47-
use MODULE ARGUMENTS;
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:
4848
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.
49+
use MODULE ARGUMENTS;
5250
53-
=head2 EXAMPLES
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:
5452
55-
The following line is taken from the testsuite for L<File::Map>:
53+
use if defined &DynaLoader::boot_DynaLoader,
54+
"Unicode::Normalize" => qw(getCombinClass NFD);
5655
57-
use if $^O ne 'MSWin32', POSIX => qw/setlocale LC_ALL/;
56+
Suppose you wanted C<ARGUMENTS> to be an empty list, I<i.e.>, to have the
57+
effect of:
5858
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.
59+
use MODULE ();
6260
63-
The following is used to L<deprecate> core modules beyond a certain version of Perl:
61+
You can't do this with the C<if> pragma; however, you can achieve
62+
exactly this effect, at compile time, with:
6463
65-
use if $] > 5.016, 'deprecate';
64+
BEGIN { require MODULE if CONDITION }
6665
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.
66+
=head2 C<no if>
7667
77-
You can also specify to NOT use something:
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>.
7871
79-
no if $] ge 5.021_006, warnings => "locale";
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:
8077
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.
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.
8487
8588
=head1 BUGS
8689
87-
The current implementation does not allow specification of the
88-
required version of the module.
90+
The current implementation does not allow specification of the required
91+
version of the module.
8992
9093
=head1 SEE ALSO
9194
@@ -96,8 +99,8 @@ Unlike C<if> though, L<Module::Requires> is not a core module.
9699
L<Module::Load::Conditional> provides a number of functions you can use to
97100
query what modules are available, and then load one or more of them at runtime.
98101
99-
L<provide> can be used to select one of several possible modules to load,
100-
based on what version of Perl is running.
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.
101104
102105
=head1 AUTHOR
103106

‎dist/if/t/if.t‎

Lines changed: 78 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
#!./perl
22

33
use strict;
4-
use Test::More tests => 10;
4+
use Test::More tests => 18;
55

6-
my $v_plus = $] + 1;
6+
my $v_plus = $] + 1;
77
my $v_minus = $] - 1;
88

99
unless (eval 'use open ":std"; 1') {
@@ -12,29 +12,85 @@ unless (eval 'use open ":std"; 1') {
1212
eval 'sub open::foo{}'; # Just in case...
1313
}
1414

15-
no strict;
15+
{
16+
no strict;
1617

17-
is( eval "use if ($v_minus > \$]), strict => 'subs'; \${'f'} = 12", 12,
18-
'"use if" with a false condition, fake pragma');
19-
is( eval "use if ($v_minus > \$]), strict => 'refs'; \${'f'} = 12", 12,
20-
'"use if" with a false condition and a pragma');
18+
is( eval "use if ($v_minus > \$]), strict => 'subs'; \${'f'} = 12", 12,
19+
'"use if" with a false condition, fake pragma');
20+
is( eval "use if ($v_minus > \$]), strict => 'refs'; \${'f'} = 12", 12,
21+
'"use if" with a false condition and a pragma');
2122

22-
is( eval "use if ($v_plus > \$]), strict => 'subs'; \${'f'} = 12", 12,
23-
'"use if" with a true condition, fake pragma');
23+
is( eval "use if ($v_plus > \$]), strict => 'subs'; \${'f'} = 12", 12,
24+
'"use if" with a true condition, fake pragma');
2425

25-
is( eval "use if ($v_plus > \$]), strict => 'refs'; \${'f'} = 12", undef,
26-
'"use if" with a true condition and a pragma');
27-
like( $@, qr/while "strict refs" in use/, 'expected error message'),
26+
is( eval "use if ($v_plus > \$]), strict => 'refs'; \${'f'} = 12", undef,
27+
'"use if" with a true condition and a pragma');
28+
like( $@, qr/while "strict refs" in use/, 'expected error message'),
2829

29-
# Old version had problems with the module name 'open', which is a keyword too
30-
# Use 'open' =>, since pre-5.6.0 could interpret differently
31-
is( (eval "use if ($v_plus > \$]), 'open' => IN => ':crlf'; 12" || 0), 12,
32-
'"use if" with open');
30+
# Old version had problems with the module name 'open', which is a keyword too
31+
# Use 'open' =>, since pre-5.6.0 could interpret differently
32+
is( (eval "use if ($v_plus > \$]), 'open' => IN => ':crlf'; 12" || 0), 12,
33+
'"use if" with open');
3334

34-
is(eval "use if ($v_plus > \$])", undef,
35-
"Too few args to 'use if' returns <undef>");
36-
like($@, qr/Too few arguments to 'use if'/, " ... and returns correct error");
35+
is(eval "use if ($v_plus > \$])", undef,
36+
"Too few args to 'use if' returns <undef>");
37+
like($@, qr/Too few arguments to 'use if'/, " ... and returns correct error");
3738

38-
is(eval "no if ($v_plus > \$])", undef,
39-
"Too few args to 'no if' returns <undef>");
40-
like($@, qr/Too few arguments to 'no if'/, " ... and returns correct error");
39+
is(eval "no if ($v_plus > \$])", undef,
40+
"Too few args to 'no if' returns <undef>");
41+
like($@, qr/Too few arguments to 'no if'/, " ... and returns correct error");
42+
}
43+
44+
{
45+
note(q|RT 132732: strict 'subs'|);
46+
use strict "subs";
47+
48+
{
49+
SKIP: {
50+
unless ($] >= 5.018) {
51+
skip "bigrat apparently not testable prior to perl-5.18", 4;
52+
}
53+
note(q|strict "subs" : 'use if' : condition false|);
54+
eval "use if (0 > 1), q|bigrat|, qw(hex oct);";
55+
ok (! main->can('hex'), "Cannot call bigrat::hex() in importing package");
56+
ok (! main->can('oct'), "Cannot call bigrat::oct() in importing package");
57+
58+
note(q|strict "subs" : 'use if' : condition true|);
59+
eval "use if (1 > 0), q|bigrat|, qw(hex oct);";
60+
ok ( main->can('hex'), "Can call bigrat::hex() in importing package");
61+
ok ( main->can('oct'), "Can call bigrat::oct() in importing package");
62+
}
63+
}
64+
65+
{
66+
note(q|strict "subs" : 'no if' : condition variable|);
67+
note(($] >= 5.022) ? "Recent enough Perl: $]" : "Older Perl: $]");
68+
use warnings;
69+
SKIP: {
70+
unless ($] >= 5.022) {
71+
skip "Redundant argument warning not available in pre-5.22 perls", 4;
72+
}
73+
74+
{
75+
no if $] >= 5.022, q|warnings|, qw(redundant);
76+
my ($test, $result, $warn);
77+
local $SIG{__WARN__} = sub { $warn = shift };
78+
$test = { fmt => "%s", args => [ qw( x y ) ] };
79+
$result = sprintf $test->{fmt}, @{$test->{args}};
80+
is($result, $test->{args}->[0], "Got expected string");
81+
ok(! $warn, "Redundant argument warning suppressed");
82+
}
83+
84+
{
85+
use if $] >= 5.022, q|warnings|, qw(redundant);
86+
my ($test, $result, $warn);
87+
local $SIG{__WARN__} = sub { $warn = shift };
88+
$test = { fmt => "%s", args => [ qw( x y ) ] };
89+
$result = sprintf $test->{fmt}, @{$test->{args}};
90+
is($result, $test->{args}->[0], "Got expected string");
91+
like($warn, qr/Redundant argument in sprintf/,
92+
"Redundant argument warning generated and captured");
93+
}
94+
}
95+
}
96+
}

‎pod/perlcdelta.pod‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,10 @@ Add int casts, assert on 2GB limitation.
277277
Allow 'peer' to be a coderef.
278278
Document protocol field, case-sensitive method names.
279279

280+
=item L<if> 0.0608
281+
282+
Doc how to import when you want to C<use MODULE ()>
283+
280284
=item L<IO> 1.39_01
281285

282286
replace use vars with our,

0 commit comments

Comments
 (0)