perl/lib/autouse.pm

package autouse;

#use strict;            # debugging only
use 5.003_90;           # ->can, for my $var

$autouse::VERSION = '1.04';

$autouse::DEBUG ||= 0;

sub vet_import ($);

sub croak {
    require Carp;
    Carp::croak(@_);
}

sub import {
    my $class = @_ ? shift : 'autouse';
    croak "usage: use $class MODULE [,SUBS...]" unless @_;
    my $module = shift;

    (my $pm = $module) =~ s{::}{/}g;
    $pm .= '.pm';
    if (exists $INC{$pm}) {
        vet_import $module;
        local $Exporter::ExportLevel = $Exporter::ExportLevel + 1;
        # $Exporter::Verbose = 1;
        return $module->import(map { (my $f = $_) =~ s/\(.*?\)$//; $f } @_);
    }

    # It is not loaded: need to do real work.
    my $callpkg = caller(0);
    print "autouse called from $callpkg\n" if $autouse::DEBUG;

    my $index;
    for my $f (@_) {
        my $proto;
        $proto = $1 if (my $func = $f) =~ s/\((.*)\)$//;

        my $closure_import_func = $func;        # Full name
        my $closure_func = $func;               # Name inside package
        my $index = rindex($func, '::');
        if ($index == -1) {
            $closure_import_func = "${callpkg}::$func";
        } else {
            $closure_func = substr $func, $index + 2;
            croak "autouse into different package attempted"
                unless substr($func, 0, $index) eq $module;
        }

        my $load_sub = sub {
            unless ($INC{$pm}) {
                eval {require $pm};
                die if $@;
                vet_import $module;
            }
            no warnings 'redefine';
            *$closure_import_func = \&{"${module}::$closure_func"};
            print "autousing $module; "
                  ."imported $closure_func as $closure_import_func\n"
                if $autouse::DEBUG;
            goto &$closure_import_func;
        };

        if (defined $proto) {
            *$closure_import_func = eval "sub ($proto) { &\$load_sub }";
        } else {
            *$closure_import_func = $load_sub;
        }
    }
}

sub vet_import ($) {
    my $module = shift;
    if (my $import = $module->can('import')) {
        croak "autoused module has unique import() method"
            unless defined(&Exporter::import)
                   && $import == \&Exporter::import;
    }
}

1;

__END__

=head1 NAME

autouse - postpone load of modules until a function is used

=head1 SYNOPSIS

  use autouse 'Carp' => qw(carp croak);
  carp "this carp was predeclared and autoused ";

=head1 DESCRIPTION

If the module C<Module> is already loaded, then the declaration

  use autouse 'Module' => qw(func1 func2($;$));

is equivalent to

  use Module qw(func1 func2);

if C<Module> defines func2() with prototype C<($;$)>, and func1() has
no prototypes.  (At least if C<Module> uses C<Exporter>'s C<import>,
otherwise it is a fatal error.)

If the module C<Module> is not loaded yet, then the above declaration
declares functions func1() and func2() in the current package.  When
these functions are called, they load the package C<Module> if needed,
and substitute themselves with the correct definitions.

=begin _deprecated

   use Module qw(Module::func3);

will work and is the equivalent to:

   use Module qw(func3);

It is not a very useful feature and has been deprecated.

=end _deprecated


=head1 WARNING

Using C<autouse> will move important steps of your program's execution
from compile time to runtime.  This can

=over 4

=item *

Break the execution of your program if the module you C<autouse>d has
some initialization which it expects to be done early.

=item *

hide bugs in your code since important checks (like correctness of
prototypes) is moved from compile time to runtime.  In particular, if
the prototype you specified on C<autouse> line is wrong, you will not
find it out until the corresponding function is executed.  This will be
very unfortunate for functions which are not always called (note that
for such functions C<autouse>ing gives biggest win, for a workaround
see below).

=back

To alleviate the second problem (partially) it is advised to write
your scripts like this:

  use Module;
  use autouse Module => qw(carp($) croak(&$));
  carp "this carp was predeclared and autoused ";

The first line ensures that the errors in your argument specification
are found early.  When you ship your application you should comment
out the first line, since it makes the second one useless.

=head1 AUTHOR

Ilya Zakharevich (ilya@math.ohio-state.edu)

=head1 SEE ALSO

perl(1).

=cut
Revision:	1.1
Committed:	Thu Jun 30 14:27:08 2005 UTC (21 years, 4 months ago) by root
Branch:	MAIN
CVS Tags:	PERL-5-8-7, HEAD
Branch point for:	PERL
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	package autouse;
2
3			#use strict; # debugging only
4			use 5.003_90; # ->can, for my $var
5
6			$autouse::VERSION = '1.04';
7
8			$autouse::DEBUG \|\|= 0;
9
10			sub vet_import ($);
11
12			sub croak {
13			require Carp;
14			Carp::croak(@_);
15			}
16
17			sub import {
18			my $class = @_ ? shift : 'autouse';
19			croak "usage: use $class MODULE [,SUBS...]" unless @_;
20			my $module = shift;
21
22			(my $pm = $module) =~ s{::}{/}g;
23			$pm .= '.pm';
24			if (exists $INC{$pm}) {
25			vet_import $module;
26			local $Exporter::ExportLevel = $Exporter::ExportLevel + 1;
27			# $Exporter::Verbose = 1;
28			return $module->import(map { (my $f = $_) =~ s/\(.*?\)$//; $f } @_);
29			}
30
31			# It is not loaded: need to do real work.
32			my $callpkg = caller(0);
33			print "autouse called from $callpkg\n" if $autouse::DEBUG;
34
35			my $index;
36			for my $f (@_) {
37			my $proto;
38			$proto = $1 if (my $func = $f) =~ s/\((.*)\)$//;
39
40			my $closure_import_func = $func; # Full name
41			my $closure_func = $func; # Name inside package
42			my $index = rindex($func, '::');
43			if ($index == -1) {
44			$closure_import_func = "${callpkg}::$func";
45			} else {
46			$closure_func = substr $func, $index + 2;
47			croak "autouse into different package attempted"
48			unless substr($func, 0, $index) eq $module;
49			}
50
51			my $load_sub = sub {
52			unless ($INC{$pm}) {
53			eval {require $pm};
54			die if $@;
55			vet_import $module;
56			}
57			no warnings 'redefine';
58			*$closure_import_func = \&{"${module}::$closure_func"};
59			print "autousing $module; "
60			."imported $closure_func as $closure_import_func\n"
61			if $autouse::DEBUG;
62			goto &$closure_import_func;
63			};
64
65			if (defined $proto) {
66			*$closure_import_func = eval "sub ($proto) { &\$load_sub }";
67			} else {
68			*$closure_import_func = $load_sub;
69			}
70			}
71			}
72
73			sub vet_import ($) {
74			my $module = shift;
75			if (my $import = $module->can('import')) {
76			croak "autoused module has unique import() method"
77			unless defined(&Exporter::import)
78			&& $import == \&Exporter::import;
79			}
80			}
81
82			1;
83
84			__END__
85
86			=head1 NAME
87
88			autouse - postpone load of modules until a function is used
89
90			=head1 SYNOPSIS
91
92			use autouse 'Carp' => qw(carp croak);
93			carp "this carp was predeclared and autoused ";
94
95			=head1 DESCRIPTION
96
97			If the module C<Module> is already loaded, then the declaration
98
99			use autouse 'Module' => qw(func1 func2($;$));
100
101			is equivalent to
102
103			use Module qw(func1 func2);
104
105			if C<Module> defines func2() with prototype C<($;$)>, and func1() has
106			no prototypes. (At least if C<Module> uses C<Exporter>'s C<import>,
107			otherwise it is a fatal error.)
108
109			If the module C<Module> is not loaded yet, then the above declaration
110			declares functions func1() and func2() in the current package. When
111			these functions are called, they load the package C<Module> if needed,
112			and substitute themselves with the correct definitions.
113
114			=begin _deprecated
115
116			use Module qw(Module::func3);
117
118			will work and is the equivalent to:
119
120			use Module qw(func3);
121
122			It is not a very useful feature and has been deprecated.
123
124			=end _deprecated
125
126
127			=head1 WARNING
128
129			Using C<autouse> will move important steps of your program's execution
130			from compile time to runtime. This can
131
132			=over 4
133
134			=item *
135
136			Break the execution of your program if the module you C<autouse>d has
137			some initialization which it expects to be done early.
138
139			=item *
140
141			hide bugs in your code since important checks (like correctness of
142			prototypes) is moved from compile time to runtime. In particular, if
143			the prototype you specified on C<autouse> line is wrong, you will not
144			find it out until the corresponding function is executed. This will be
145			very unfortunate for functions which are not always called (note that
146			for such functions C<autouse>ing gives biggest win, for a workaround
147			see below).
148
149			=back
150
151			To alleviate the second problem (partially) it is advised to write
152			your scripts like this:
153
154			use Module;
155			use autouse Module => qw(carp($) croak(&$));
156			carp "this carp was predeclared and autoused ";
157
158			The first line ensures that the errors in your argument specification
159			are found early. When you ship your application you should comment
160			out the first line, since it makes the second one useless.
161
162			=head1 AUTHOR
163
164			Ilya Zakharevich (ilya@math.ohio-state.edu)
165
166			=head1 SEE ALSO
167
168			perl(1).
169
170			=cut