RE: Combining UTF-16 output with :crlf is awkward
[perl.git] / lib / autouse.pm
1 package autouse;
2
3 #use strict;            # debugging only
4 use 5.006;              # use warnings
5
6 $autouse::VERSION = '1.06';
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                 require $pm;
54                 vet_import $module;
55             }
56             no warnings qw(redefine prototype);
57             *$closure_import_func = \&{"${module}::$closure_func"};
58             print "autousing $module; "
59                   ."imported $closure_func as $closure_import_func\n"
60                 if $autouse::DEBUG;
61             goto &$closure_import_func;
62         };
63
64         if (defined $proto) {
65             *$closure_import_func = eval "sub ($proto) { goto &\$load_sub }"
66                 || die;
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 $module has unique import() method"
77             unless defined(&Exporter::import)
78                    && ($import == \&Exporter::import ||
79                        $import == \&UNIVERSAL::import)
80     }
81 }
82
83 1;
84
85 __END__
86
87 =head1 NAME
88
89 autouse - postpone load of modules until a function is used
90
91 =head1 SYNOPSIS
92
93   use autouse 'Carp' => qw(carp croak);
94   carp "this carp was predeclared and autoused ";
95
96 =head1 DESCRIPTION
97
98 If the module C<Module> is already loaded, then the declaration
99
100   use autouse 'Module' => qw(func1 func2($;$));
101
102 is equivalent to
103
104   use Module qw(func1 func2);
105
106 if C<Module> defines func2() with prototype C<($;$)>, and func1() has
107 no prototypes.  (At least if C<Module> uses C<Exporter>'s C<import>,
108 otherwise it is a fatal error.)
109
110 If the module C<Module> is not loaded yet, then the above declaration
111 declares functions func1() and func2() in the current package.  When
112 these functions are called, they load the package C<Module> if needed,
113 and substitute themselves with the correct definitions.
114
115 =begin _deprecated
116
117    use Module qw(Module::func3);
118
119 will work and is the equivalent to:
120
121    use Module qw(func3);
122
123 It is not a very useful feature and has been deprecated.
124
125 =end _deprecated
126
127
128 =head1 WARNING
129
130 Using C<autouse> will move important steps of your program's execution
131 from compile time to runtime.  This can
132
133 =over 4
134
135 =item *
136
137 Break the execution of your program if the module you C<autouse>d has
138 some initialization which it expects to be done early.
139
140 =item *
141
142 hide bugs in your code since important checks (like correctness of
143 prototypes) is moved from compile time to runtime.  In particular, if
144 the prototype you specified on C<autouse> line is wrong, you will not
145 find it out until the corresponding function is executed.  This will be
146 very unfortunate for functions which are not always called (note that
147 for such functions C<autouse>ing gives biggest win, for a workaround
148 see below).
149
150 =back
151
152 To alleviate the second problem (partially) it is advised to write
153 your scripts like this:
154
155   use Module;
156   use autouse Module => qw(carp($) croak(&$));
157   carp "this carp was predeclared and autoused ";
158
159 The first line ensures that the errors in your argument specification
160 are found early.  When you ship your application you should comment
161 out the first line, since it makes the second one useless.
162
163 =head1 AUTHOR
164
165 Ilya Zakharevich (ilya@math.ohio-state.edu)
166
167 =head1 SEE ALSO
168
169 perl(1).
170
171 =cut