ModPerl::MethodLookup(3pm)

1docs::api::ModPerl::MetUhsoedrLoCooknutpr(i3b)uted PerldDooccsu:m:eanptia:t:iMoondPerl::MethodLookup(3)
2
3
4

NAME

6       ModPerl::MethodLookup -- Lookup mod_perl modules, objects and methods
7

Synopsis

9         use ModPerl::MethodLookup;
10
11         # return all module names containing XS method 'print'
12         my ($hint, @modules) =
13             ModPerl::MethodLookup::lookup_method('print');
14
15         # return only module names containing method 'print' which
16         # expects the first argument to be of type 'Apache2::Filter'
17         # (here $filter is an Apache2::Filter object)
18         my ($hint, @modules) =
19             ModPerl::MethodLookup::lookup_method('print', $filter);
20         # or
21         my ($hint, @modules) =
22             ModPerl::MethodLookup::lookup_method('print', 'Apache2::Filter');
23
24         # what XS methods defined by module 'Apache2::Filter'
25         my ($hint, @methods) =
26             ModPerl::MethodLookup::lookup_module('Apache2::Filter');
27
28         # what XS methods can be invoked on the object $r (or a ref)
29         my ($hint, @methods) =
30             ModPerl::MethodLookup::lookup_object($r);
31         # or
32         my ($hint, @methods) =
33             ModPerl::MethodLookup::lookup_object('Apache2::RequestRec');
34
35         # preload all mp2 modules in startup.pl
36         ModPerl::MethodLookup::preload_all_modules();
37
38         # command line shortcuts
39         % perl -MModPerl::MethodLookup -e print_module \
40           Apache2::RequestRec Apache2::Filter
41         % perl -MModPerl::MethodLookup -e print_object Apache2
42         % perl -MModPerl::MethodLookup -e print_method \
43           get_server_built request
44         % perl -MModPerl::MethodLookup -e print_method read
45         % perl -MModPerl::MethodLookup -e print_method read APR::Bucket
46

Description

48       mod_perl 2.0 provides many methods, which reside in various modules.
49       One has to load each of the modules before using the desired methods.
50       "ModPerl::MethodLookup" provides the Perl API for finding module names
51       which contain methods in question and other helper functions, to find
52       out out what methods defined by some module, what methods can be called
53       on a given object, etc.
54

API

56   "lookup_method()"
57       Find modules (packages) containing a certain method
58
59         ($hint, @modules) = lookup_method($method_name);
60         ($hint, @modules) = lookup_method($method_name, $object);
61         ($hint, @modules) = lookup_method($method_name, $class));
62
63       arg1: $method_name ( string )
64           the method name to look up
65
66       opt arg2: $object or $class
67           a blessed object or the name of the class it's blessed into. If
68           there is more than one match, this extra information is used to
69           return only modules containing methods operating on the objects of
70           the same kind.
71
72           If a sub-classed object is passed it'll be handled correctly, by
73           checking its super-class(es).  This usage is useful when the
74           "AUTOLOAD" is used to find a not yet loaded module which include
75           the called method.
76
77       ret1: $hint
78           a string containing a human readable lookup result, suggesting
79           which modules should be loaded, ready for copy-n-paste or
80           explaining the failure if the lookup didn't succeed.
81
82       ret2: @modules
83           an array of modules which have matched the query, i.e. the names of
84           the modules which contain the requested method.
85
86       since: 2.0.00
87
88       Examples:
89
90       Return all module names containing XS method print:
91
92         my ($hint, @modules) =
93             ModPerl::MethodLookup::lookup_method('print');
94
95       Return only module names containing method print which expects the
96       first argument to be of type "Apache2::Filter":
97
98         my $filter = bless {}, 'Apache2::Filter';
99         my ($hint, @modules) =
100             ModPerl::MethodLookup::lookup_method('print', $filter);
101
102       or:
103
104         my ($hint, @modules) =
105             ModPerl::MethodLookup::lookup_method('print', 'Apache2::Filter');
106
107   "lookup_module()"
108       Find methods contained in a certain module (package)
109
110         ($hint, @methods) = lookup_module($module_name);
111
112       arg1: $module_name ( string )
113           the module name
114
115       ret1: $hint
116           a string containing a human readable lookup result, suggesting,
117           which methods the module $module_name implements, or explaining the
118           failure if the lookup failed.
119
120       ret2: @methods
121           an array of methods which have matched the query, i.e. the names of
122           the methods defined in the requested module.
123
124       since: 2.0.00
125
126       Example:
127
128       What XS methods defined by module "Apache2::Filter":
129
130         my ($hint, @methods) =
131             ModPerl::MethodLookup::lookup_module('Apache2::Filter');
132
133   "lookup_object()"
134         ($hint, @methods) = lookup_object($object);
135         ($hint, @methods) = lookup_object($class);
136
137       arg1: $object or $class
138           an object or a name of a class an object is blessed into
139
140           If a sub-classed object is passed it'll be handled correctly, by
141           including methods provided by its super-class(es).
142
143       ret1: $hint
144           a string containing a human readable lookup result, suggesting,
145           which methods the given object can invoke (including module names
146           that need to be loaded to use those methods), or explaining the
147           failure if the lookup failed.
148
149       ret2: @methods
150           an array of methods which have matched the query, i.e. the names of
151           the methods that can be invoked on the given object (or its class
152           name).
153
154       since: 2.0.00
155
156       META: As of this writing this function may miss some of the
157       functions/methods that can be invoked on the given object. Currently we
158       can't programmatically deduct the objects they are invoked on, because
159       these methods are written in pure XS and manipulate the arguments stack
160       themselves. Currently these are mainly XS functions, not methods, which
161       of course aren't invoked on objects. There are also logging function
162       wrappers ("Apache2::Log").
163
164       Examples:
165
166       What XS methods can be invoked on the object $r:
167
168         my ($hint, @methods) =
169             ModPerl::MethodLookup::lookup_object($r);
170
171       or $r's class -- "Apache2::RequestRec":
172
173         my ($hint, @methods) =
174             ModPerl::MethodLookup::lookup_object('Apache2::RequestRec');
175
176   "preload_all_modules()"
177       The function "preload_all_modules()" preloads all mod_perl 2.0 modules,
178       which implement their API in XS. This is similar to the mod_perl 1.0
179       behavior which has most of its methods loaded at the startup.
180
181       CPAN modules developers should make sure their distribution loads each
182       of the used mod_perl 2.0 modules explicitly, and not use this function,
183       as it takes the fine control away from the users. One should avoid
184       doing this the production server (unless all modules are used indeed)
185       in order to save memory.
186
187       since: 2.0.00
188
189   "print_method()"
190       "print_method()" is a convenience wrapper for "lookup_method()", mainly
191       designed to be used from the command line. For example to print all the
192       modules which define method read execute:
193
194         % perl -MModPerl::MethodLookup -e print_method read
195
196       Since this will return more than one module, we can narrow the query to
197       only those methods which expect the first argument to be blessed into
198       class "APR::Bucket":
199
200         % perl -MModPerl::MethodLookup -e print_method read APR::Bucket
201
202       You can pass more than one method and it'll perform a lookup on each of
203       the methods. For example to lookup methods "get_server_built" and
204       "request" you can do:
205
206         % perl -MModPerl::MethodLookup -e print_method \
207           get_server_built request
208
209       The function "print_method()" is exported by default.
210
211       since: 2.0.00
212
213   "print_module()"
214       "print_module()" is a convenience wrapper for "lookup_module()", mainly
215       designed to be used from the command line. For example to print all the
216       methods defined in the module "Apache2::RequestRec", followed by
217       methods defined in the module "Apache2::Filter" you can run:
218
219         % perl -MModPerl::MethodLookup -e print_module \
220           Apache2::RequestRec Apache2::Filter
221
222       The function "print_module()" is exported by default.
223
224       since: 2.0.00
225
226   "print_object()"
227       "print_object()" is a convenience wrapper for "lookup_object()", mainly
228       designed to be used from the command line. For example to print all the
229       methods that can be invoked on object blessed into a class
230       "Apache2::RequestRec" run:
231
232         % perl -MModPerl::MethodLookup -e print_object \
233           Apache2::RequestRec
234
235       Similar to "print_object()", more than one class can be passed to this
236       function.
237
238       The function "print_object()" is exported by default.
239
240       since: 2.0.00
241

Applications

243   "AUTOLOAD"
244       When Perl fails to locate a method it checks whether the package the
245       object belongs to has an "AUTOLOAD" function defined and if so, calls
246       it with the same arguments as the missing method while setting a global
247       variable $AUTOLOAD (in that package) to the name of the originally
248       called method. We can use this facility to lookup the modules to be
249       loaded when such a failure occurs. Though since we have many packages
250       to take care of we will use a special "UNIVERSAL::AUTOLOAD" function
251       which Perl calls if can't find the "AUTOLOAD" function in the given
252       package.
253
254       In that function you can query "ModPerl::MethodLookup", require() the
255       module that includes the called method and call that method again using
256       the goto() trick:
257
258         use ModPerl::MethodLookup;
259         sub UNIVERSAL::AUTOLOAD {
260             my ($hint, @modules) =
261                 ModPerl::MethodLookup::lookup_method($UNIVERSAL::AUTOLOAD, @_);
262             if (@modules) {
263                 eval "require $_" for @modules;
264                 goto &$UNIVERSAL::AUTOLOAD;
265             }
266             else {
267                 die $hint;
268             }
269         }
270
271       However we don't endorse this approach. It's a better approach to
272       always abort the execution which printing the $hintand use fix the code
273       to load the missing module. Moreover installing "UNIVERSAL::AUTOLOAD"
274       may cause a lot of problems, since once it's installed Perl will call
275       it every time some method is missing (e.g. undefined "DESTROY"
276       methods). The following approach seems to somewhat work for me. It
277       installs "UNIVERSAL::AUTOLOAD" only when the the child process starts.
278
279         httpd.conf:
280         -----------
281         PerlChildInitHandler ModPerl::MethodLookupAuto
282
283         startup.pl:
284         -----------
285         {
286             package ModPerl::MethodLookupAuto;
287             use ModPerl::MethodLookup;
288
289             use Carp;
290             sub handler {
291
292                 *UNIVERSAL::AUTOLOAD = sub {
293                     my $method = $AUTOLOAD;
294                     return if $method =~ /DESTROY/; # exclude DESTROY resolving
295
296                     my ($hint, @modules) =
297                         ModPerl::MethodLookup::lookup_method($method, @_);
298                     $hint ||= "Can't find method $AUTOLOAD";
299                     croak $hint;
300                 };
301                 return 0;
302             }
303         }
304
305       This example doesn't load the modules for you. It'll print to STDERR
306       what module should be loaded, when a method from the not-yet-loaded
307       module is called.
308
309       A similar technique is used by "Apache2::porting".
310
311       META: there is a better version of AUTOLOAD discussed on the dev list.
312       Replace the current one with it. (search the archive for EazyLife)
313
314   Command Line Lookups
315       When a method is used and mod_perl has reported a failure to find it,
316       it's often useful to use the command line query to figure out which
317       module needs to be loaded. For example if when executing:
318
319         $r->construct_url();
320
321       mod_perl complains:
322
323         Can't locate object method "construct_url" via package
324         "Apache2::RequestRec" at ...
325
326       you can ask "ModPerl::MethodLookup" for help:
327
328         % perl -MModPerl::MethodLookup -e print_method construct_url
329         To use method 'construct_url' add:
330                 use Apache2::URI ();
331
332       and after copy-n-pasting the use statement in our code, the problem
333       goes away.
334
335       One can create a handy alias for this technique. For example, C-style
336       shell users can do:
337
338          % alias lookup "perl -MModPerl::MethodLookup -e print_method"
339
340       For Bash-style shell users:
341
342          % alias lookup="perl -MModPerl::MethodLookup -e print_method"
343
344       Now the lookup is even easier:
345
346         % lookup construct_url
347         to use method 'construct_url' add:
348                 use Apache2::URI;
349
350       Similar aliases can be provided for "print_object()" and
351       "print_module()".
352

Todo

354       These methods aren't yet picked by this module (the extract from the
355       map file):
356
357        modperl_filter_attributes     | MODIFY_CODE_ATTRIBUTES
358        modperl_spawn_proc_prog       | spawn_proc_prog
359        apr_ipsubnet_create           | new
360
361       Please report to the mod_perl development mailing list if you find any
362       other missing methods. But remember that as of this moment the module
363       reports only XS functions. In the future we may add support for pure
364       perl functions/methods as well.
365

Copyright

376       mod_perl 2.0 and its core modules are copyrighted under The Apache
377       Software License, Version 2.0.
378

Authors

380       The mod_perl development team and numerous contributors.
381
382
383
384perl v5.36.0                      2022-07-21docs::api::ModPerl::MethodLookup(3)