1 | =head1 NAME
|
---|
2 |
|
---|
3 | perlmod - Perl modules (packages and symbol tables)
|
---|
4 |
|
---|
5 | =head1 DESCRIPTION
|
---|
6 |
|
---|
7 | =head2 Packages
|
---|
8 | X<package> X<namespace> X<variable, global> X<global variable> X<global>
|
---|
9 |
|
---|
10 | Perl provides a mechanism for alternative namespaces to protect
|
---|
11 | packages from stomping on each other's variables. In fact, there's
|
---|
12 | really no such thing as a global variable in Perl. The package
|
---|
13 | statement declares the compilation unit as being in the given
|
---|
14 | namespace. The scope of the package declaration is from the
|
---|
15 | declaration itself through the end of the enclosing block, C<eval>,
|
---|
16 | or file, whichever comes first (the same scope as the my() and
|
---|
17 | local() operators). Unqualified dynamic identifiers will be in
|
---|
18 | this namespace, except for those few identifiers that if unqualified,
|
---|
19 | default to the main package instead of the current one as described
|
---|
20 | below. A package statement affects only dynamic variables--including
|
---|
21 | those you've used local() on--but I<not> lexical variables created
|
---|
22 | with my(). Typically it would be the first declaration in a file
|
---|
23 | included by the C<do>, C<require>, or C<use> operators. You can
|
---|
24 | switch into a package in more than one place; it merely influences
|
---|
25 | which symbol table is used by the compiler for the rest of that
|
---|
26 | block. You can refer to variables and filehandles in other packages
|
---|
27 | by prefixing the identifier with the package name and a double
|
---|
28 | colon: C<$Package::Variable>. If the package name is null, the
|
---|
29 | C<main> package is assumed. That is, C<$::sail> is equivalent to
|
---|
30 | C<$main::sail>.
|
---|
31 |
|
---|
32 | The old package delimiter was a single quote, but double colon is now the
|
---|
33 | preferred delimiter, in part because it's more readable to humans, and
|
---|
34 | in part because it's more readable to B<emacs> macros. It also makes C++
|
---|
35 | programmers feel like they know what's going on--as opposed to using the
|
---|
36 | single quote as separator, which was there to make Ada programmers feel
|
---|
37 | like they knew what was going on. Because the old-fashioned syntax is still
|
---|
38 | supported for backwards compatibility, if you try to use a string like
|
---|
39 | C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
|
---|
40 | the $s variable in package C<owner>, which is probably not what you meant.
|
---|
41 | Use braces to disambiguate, as in C<"This is ${owner}'s house">.
|
---|
42 | X<::> X<'>
|
---|
43 |
|
---|
44 | Packages may themselves contain package separators, as in
|
---|
45 | C<$OUTER::INNER::var>. This implies nothing about the order of
|
---|
46 | name lookups, however. There are no relative packages: all symbols
|
---|
47 | are either local to the current package, or must be fully qualified
|
---|
48 | from the outer package name down. For instance, there is nowhere
|
---|
49 | within package C<OUTER> that C<$INNER::var> refers to
|
---|
50 | C<$OUTER::INNER::var>. C<INNER> refers to a totally
|
---|
51 | separate global package.
|
---|
52 |
|
---|
53 | Only identifiers starting with letters (or underscore) are stored
|
---|
54 | in a package's symbol table. All other symbols are kept in package
|
---|
55 | C<main>, including all punctuation variables, like $_. In addition,
|
---|
56 | when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
|
---|
57 | ARGVOUT, ENV, INC, and SIG are forced to be in package C<main>,
|
---|
58 | even when used for other purposes than their built-in ones. If you
|
---|
59 | have a package called C<m>, C<s>, or C<y>, then you can't use the
|
---|
60 | qualified form of an identifier because it would be instead interpreted
|
---|
61 | as a pattern match, a substitution, or a transliteration.
|
---|
62 | X<variable, punctuation>
|
---|
63 |
|
---|
64 | Variables beginning with underscore used to be forced into package
|
---|
65 | main, but we decided it was more useful for package writers to be able
|
---|
66 | to use leading underscore to indicate private variables and method names.
|
---|
67 | However, variables and functions named with a single C<_>, such as
|
---|
68 | $_ and C<sub _>, are still forced into the package C<main>. See also
|
---|
69 | L<perlvar/"Technical Note on the Syntax of Variable Names">.
|
---|
70 |
|
---|
71 | C<eval>ed strings are compiled in the package in which the eval() was
|
---|
72 | compiled. (Assignments to C<$SIG{}>, however, assume the signal
|
---|
73 | handler specified is in the C<main> package. Qualify the signal handler
|
---|
74 | name if you wish to have a signal handler in a package.) For an
|
---|
75 | example, examine F<perldb.pl> in the Perl library. It initially switches
|
---|
76 | to the C<DB> package so that the debugger doesn't interfere with variables
|
---|
77 | in the program you are trying to debug. At various points, however, it
|
---|
78 | temporarily switches back to the C<main> package to evaluate various
|
---|
79 | expressions in the context of the C<main> package (or wherever you came
|
---|
80 | from). See L<perldebug>.
|
---|
81 |
|
---|
82 | The special symbol C<__PACKAGE__> contains the current package, but cannot
|
---|
83 | (easily) be used to construct variable names.
|
---|
84 |
|
---|
85 | See L<perlsub> for other scoping issues related to my() and local(),
|
---|
86 | and L<perlref> regarding closures.
|
---|
87 |
|
---|
88 | =head2 Symbol Tables
|
---|
89 | X<symbol table> X<stash> X<%::> X<%main::> X<typeglob> X<glob> X<alias>
|
---|
90 |
|
---|
91 | The symbol table for a package happens to be stored in the hash of that
|
---|
92 | name with two colons appended. The main symbol table's name is thus
|
---|
93 | C<%main::>, or C<%::> for short. Likewise the symbol table for the nested
|
---|
94 | package mentioned earlier is named C<%OUTER::INNER::>.
|
---|
95 |
|
---|
96 | The value in each entry of the hash is what you are referring to when you
|
---|
97 | use the C<*name> typeglob notation. In fact, the following have the same
|
---|
98 | effect, though the first is more efficient because it does the symbol
|
---|
99 | table lookups at compile time:
|
---|
100 |
|
---|
101 | local *main::foo = *main::bar;
|
---|
102 | local $main::{foo} = $main::{bar};
|
---|
103 |
|
---|
104 | (Be sure to note the B<vast> difference between the second line above
|
---|
105 | and C<local $main::foo = $main::bar>. The former is accessing the hash
|
---|
106 | C<%main::>, which is the symbol table of package C<main>. The latter is
|
---|
107 | simply assigning scalar C<$bar> in package C<main> to scalar C<$foo> of
|
---|
108 | the same package.)
|
---|
109 |
|
---|
110 | You can use this to print out all the variables in a package, for
|
---|
111 | instance. The standard but antiquated F<dumpvar.pl> library and
|
---|
112 | the CPAN module Devel::Symdump make use of this.
|
---|
113 |
|
---|
114 | Assignment to a typeglob performs an aliasing operation, i.e.,
|
---|
115 |
|
---|
116 | *dick = *richard;
|
---|
117 |
|
---|
118 | causes variables, subroutines, formats, and file and directory handles
|
---|
119 | accessible via the identifier C<richard> also to be accessible via the
|
---|
120 | identifier C<dick>. If you want to alias only a particular variable or
|
---|
121 | subroutine, assign a reference instead:
|
---|
122 |
|
---|
123 | *dick = \$richard;
|
---|
124 |
|
---|
125 | Which makes $richard and $dick the same variable, but leaves
|
---|
126 | @richard and @dick as separate arrays. Tricky, eh?
|
---|
127 |
|
---|
128 | There is one subtle difference between the following statements:
|
---|
129 |
|
---|
130 | *foo = *bar;
|
---|
131 | *foo = \$bar;
|
---|
132 |
|
---|
133 | C<*foo = *bar> makes the typeglobs themselves synonymous while
|
---|
134 | C<*foo = \$bar> makes the SCALAR portions of two distinct typeglobs
|
---|
135 | refer to the same scalar value. This means that the following code:
|
---|
136 |
|
---|
137 | $bar = 1;
|
---|
138 | *foo = \$bar; # Make $foo an alias for $bar
|
---|
139 |
|
---|
140 | {
|
---|
141 | local $bar = 2; # Restrict changes to block
|
---|
142 | print $foo; # Prints '1'!
|
---|
143 | }
|
---|
144 |
|
---|
145 | Would print '1', because C<$foo> holds a reference to the I<original>
|
---|
146 | C<$bar> -- the one that was stuffed away by C<local()> and which will be
|
---|
147 | restored when the block ends. Because variables are accessed through the
|
---|
148 | typeglob, you can use C<*foo = *bar> to create an alias which can be
|
---|
149 | localized. (But be aware that this means you can't have a separate
|
---|
150 | C<@foo> and C<@bar>, etc.)
|
---|
151 |
|
---|
152 | What makes all of this important is that the Exporter module uses glob
|
---|
153 | aliasing as the import/export mechanism. Whether or not you can properly
|
---|
154 | localize a variable that has been exported from a module depends on how
|
---|
155 | it was exported:
|
---|
156 |
|
---|
157 | @EXPORT = qw($FOO); # Usual form, can't be localized
|
---|
158 | @EXPORT = qw(*FOO); # Can be localized
|
---|
159 |
|
---|
160 | You can work around the first case by using the fully qualified name
|
---|
161 | (C<$Package::FOO>) where you need a local value, or by overriding it
|
---|
162 | by saying C<*FOO = *Package::FOO> in your script.
|
---|
163 |
|
---|
164 | The C<*x = \$y> mechanism may be used to pass and return cheap references
|
---|
165 | into or from subroutines if you don't want to copy the whole
|
---|
166 | thing. It only works when assigning to dynamic variables, not
|
---|
167 | lexicals.
|
---|
168 |
|
---|
169 | %some_hash = (); # can't be my()
|
---|
170 | *some_hash = fn( \%another_hash );
|
---|
171 | sub fn {
|
---|
172 | local *hashsym = shift;
|
---|
173 | # now use %hashsym normally, and you
|
---|
174 | # will affect the caller's %another_hash
|
---|
175 | my %nhash = (); # do what you want
|
---|
176 | return \%nhash;
|
---|
177 | }
|
---|
178 |
|
---|
179 | On return, the reference will overwrite the hash slot in the
|
---|
180 | symbol table specified by the *some_hash typeglob. This
|
---|
181 | is a somewhat tricky way of passing around references cheaply
|
---|
182 | when you don't want to have to remember to dereference variables
|
---|
183 | explicitly.
|
---|
184 |
|
---|
185 | Another use of symbol tables is for making "constant" scalars.
|
---|
186 | X<constant> X<scalar, constant>
|
---|
187 |
|
---|
188 | *PI = \3.14159265358979;
|
---|
189 |
|
---|
190 | Now you cannot alter C<$PI>, which is probably a good thing all in all.
|
---|
191 | This isn't the same as a constant subroutine, which is subject to
|
---|
192 | optimization at compile-time. A constant subroutine is one prototyped
|
---|
193 | to take no arguments and to return a constant expression. See
|
---|
194 | L<perlsub> for details on these. The C<use constant> pragma is a
|
---|
195 | convenient shorthand for these.
|
---|
196 |
|
---|
197 | You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and
|
---|
198 | package the *foo symbol table entry comes from. This may be useful
|
---|
199 | in a subroutine that gets passed typeglobs as arguments:
|
---|
200 |
|
---|
201 | sub identify_typeglob {
|
---|
202 | my $glob = shift;
|
---|
203 | print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
|
---|
204 | }
|
---|
205 | identify_typeglob *foo;
|
---|
206 | identify_typeglob *bar::baz;
|
---|
207 |
|
---|
208 | This prints
|
---|
209 |
|
---|
210 | You gave me main::foo
|
---|
211 | You gave me bar::baz
|
---|
212 |
|
---|
213 | The C<*foo{THING}> notation can also be used to obtain references to the
|
---|
214 | individual elements of *foo. See L<perlref>.
|
---|
215 |
|
---|
216 | Subroutine definitions (and declarations, for that matter) need
|
---|
217 | not necessarily be situated in the package whose symbol table they
|
---|
218 | occupy. You can define a subroutine outside its package by
|
---|
219 | explicitly qualifying the name of the subroutine:
|
---|
220 |
|
---|
221 | package main;
|
---|
222 | sub Some_package::foo { ... } # &foo defined in Some_package
|
---|
223 |
|
---|
224 | This is just a shorthand for a typeglob assignment at compile time:
|
---|
225 |
|
---|
226 | BEGIN { *Some_package::foo = sub { ... } }
|
---|
227 |
|
---|
228 | and is I<not> the same as writing:
|
---|
229 |
|
---|
230 | {
|
---|
231 | package Some_package;
|
---|
232 | sub foo { ... }
|
---|
233 | }
|
---|
234 |
|
---|
235 | In the first two versions, the body of the subroutine is
|
---|
236 | lexically in the main package, I<not> in Some_package. So
|
---|
237 | something like this:
|
---|
238 |
|
---|
239 | package main;
|
---|
240 |
|
---|
241 | $Some_package::name = "fred";
|
---|
242 | $main::name = "barney";
|
---|
243 |
|
---|
244 | sub Some_package::foo {
|
---|
245 | print "in ", __PACKAGE__, ": \$name is '$name'\n";
|
---|
246 | }
|
---|
247 |
|
---|
248 | Some_package::foo();
|
---|
249 |
|
---|
250 | prints:
|
---|
251 |
|
---|
252 | in main: $name is 'barney'
|
---|
253 |
|
---|
254 | rather than:
|
---|
255 |
|
---|
256 | in Some_package: $name is 'fred'
|
---|
257 |
|
---|
258 | This also has implications for the use of the SUPER:: qualifier
|
---|
259 | (see L<perlobj>).
|
---|
260 |
|
---|
261 | =head2 BEGIN, CHECK, INIT and END
|
---|
262 | X<BEGIN> X<CHECK> X<INIT> X<END>
|
---|
263 |
|
---|
264 | Four specially named code blocks are executed at the beginning and at the end
|
---|
265 | of a running Perl program. These are the C<BEGIN>, C<CHECK>, C<INIT>, and
|
---|
266 | C<END> blocks.
|
---|
267 |
|
---|
268 | These code blocks can be prefixed with C<sub> to give the appearance of a
|
---|
269 | subroutine (although this is not considered good style). One should note
|
---|
270 | that these code blocks don't really exist as named subroutines (despite
|
---|
271 | their appearance). The thing that gives this away is the fact that you can
|
---|
272 | have B<more than one> of these code blocks in a program, and they will get
|
---|
273 | B<all> executed at the appropriate moment. So you can't execute any of
|
---|
274 | these code blocks by name.
|
---|
275 |
|
---|
276 | A C<BEGIN> code block is executed as soon as possible, that is, the moment
|
---|
277 | it is completely defined, even before the rest of the containing file (or
|
---|
278 | string) is parsed. You may have multiple C<BEGIN> blocks within a file (or
|
---|
279 | eval'ed string) -- they will execute in order of definition. Because a C<BEGIN>
|
---|
280 | code block executes immediately, it can pull in definitions of subroutines
|
---|
281 | and such from other files in time to be visible to the rest of the compile
|
---|
282 | and run time. Once a C<BEGIN> has run, it is immediately undefined and any
|
---|
283 | code it used is returned to Perl's memory pool.
|
---|
284 |
|
---|
285 | It should be noted that C<BEGIN> code blocks B<are> executed inside string
|
---|
286 | C<eval()>'s. The C<CHECK> and C<INIT> code blocks are B<not> executed inside
|
---|
287 | a string eval, which e.g. can be a problem in a mod_perl environment.
|
---|
288 |
|
---|
289 | An C<END> code block is executed as late as possible, that is, after
|
---|
290 | perl has finished running the program and just before the interpreter
|
---|
291 | is being exited, even if it is exiting as a result of a die() function.
|
---|
292 | (But not if it's morphing into another program via C<exec>, or
|
---|
293 | being blown out of the water by a signal--you have to trap that yourself
|
---|
294 | (if you can).) You may have multiple C<END> blocks within a file--they
|
---|
295 | will execute in reverse order of definition; that is: last in, first
|
---|
296 | out (LIFO). C<END> blocks are not executed when you run perl with the
|
---|
297 | C<-c> switch, or if compilation fails.
|
---|
298 |
|
---|
299 | Note that C<END> code blocks are B<not> executed at the end of a string
|
---|
300 | C<eval()>: if any C<END> code blocks are created in a string C<eval()>,
|
---|
301 | they will be executed just as any other C<END> code block of that package
|
---|
302 | in LIFO order just before the interpreter is being exited.
|
---|
303 |
|
---|
304 | Inside an C<END> code block, C<$?> contains the value that the program is
|
---|
305 | going to pass to C<exit()>. You can modify C<$?> to change the exit
|
---|
306 | value of the program. Beware of changing C<$?> by accident (e.g. by
|
---|
307 | running something via C<system>).
|
---|
308 | X<$?>
|
---|
309 |
|
---|
310 | C<CHECK> and C<INIT> code blocks are useful to catch the transition between
|
---|
311 | the compilation phase and the execution phase of the main program.
|
---|
312 |
|
---|
313 | C<CHECK> code blocks are run just after the B<initial> Perl compile phase ends
|
---|
314 | and before the run time begins, in LIFO order. C<CHECK> code blocks are used
|
---|
315 | in the Perl compiler suite to save the compiled state of the program.
|
---|
316 |
|
---|
317 | C<INIT> blocks are run just before the Perl runtime begins execution, in
|
---|
318 | "first in, first out" (FIFO) order. For example, the code generators
|
---|
319 | documented in L<perlcc> make use of C<INIT> blocks to initialize and
|
---|
320 | resolve pointers to XSUBs.
|
---|
321 |
|
---|
322 | When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
|
---|
323 | C<END> work just as they do in B<awk>, as a degenerate case.
|
---|
324 | Both C<BEGIN> and C<CHECK> blocks are run when you use the B<-c>
|
---|
325 | switch for a compile-only syntax check, although your main code
|
---|
326 | is not.
|
---|
327 |
|
---|
328 | The B<begincheck> program makes it all clear, eventually:
|
---|
329 |
|
---|
330 | #!/usr/bin/perl
|
---|
331 |
|
---|
332 | # begincheck
|
---|
333 |
|
---|
334 | print " 8. Ordinary code runs at runtime.\n";
|
---|
335 |
|
---|
336 | END { print "14. So this is the end of the tale.\n" }
|
---|
337 | INIT { print " 5. INIT blocks run FIFO just before runtime.\n" }
|
---|
338 | CHECK { print " 4. So this is the fourth line.\n" }
|
---|
339 |
|
---|
340 | print " 9. It runs in order, of course.\n";
|
---|
341 |
|
---|
342 | BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
|
---|
343 | END { print "13. Read perlmod for the rest of the story.\n" }
|
---|
344 | CHECK { print " 3. CHECK blocks run LIFO at compilation's end.\n" }
|
---|
345 | INIT { print " 6. Run this again, using Perl's -c switch.\n" }
|
---|
346 |
|
---|
347 | print "10. This is anti-obfuscated code.\n";
|
---|
348 |
|
---|
349 | END { print "12. END blocks run LIFO at quitting time.\n" }
|
---|
350 | BEGIN { print " 2. So this line comes out second.\n" }
|
---|
351 | INIT { print " 7. You'll see the difference right away.\n" }
|
---|
352 |
|
---|
353 | print "11. It merely _looks_ like it should be confusing.\n";
|
---|
354 |
|
---|
355 | __END__
|
---|
356 |
|
---|
357 | =head2 Perl Classes
|
---|
358 | X<class> X<@ISA>
|
---|
359 |
|
---|
360 | There is no special class syntax in Perl, but a package may act
|
---|
361 | as a class if it provides subroutines to act as methods. Such a
|
---|
362 | package may also derive some of its methods from another class (package)
|
---|
363 | by listing the other package name(s) in its global @ISA array (which
|
---|
364 | must be a package global, not a lexical).
|
---|
365 |
|
---|
366 | For more on this, see L<perltoot> and L<perlobj>.
|
---|
367 |
|
---|
368 | =head2 Perl Modules
|
---|
369 | X<module>
|
---|
370 |
|
---|
371 | A module is just a set of related functions in a library file, i.e.,
|
---|
372 | a Perl package with the same name as the file. It is specifically
|
---|
373 | designed to be reusable by other modules or programs. It may do this
|
---|
374 | by providing a mechanism for exporting some of its symbols into the
|
---|
375 | symbol table of any package using it, or it may function as a class
|
---|
376 | definition and make its semantics available implicitly through
|
---|
377 | method calls on the class and its objects, without explicitly
|
---|
378 | exporting anything. Or it can do a little of both.
|
---|
379 |
|
---|
380 | For example, to start a traditional, non-OO module called Some::Module,
|
---|
381 | create a file called F<Some/Module.pm> and start with this template:
|
---|
382 |
|
---|
383 | package Some::Module; # assumes Some/Module.pm
|
---|
384 |
|
---|
385 | use strict;
|
---|
386 | use warnings;
|
---|
387 |
|
---|
388 | BEGIN {
|
---|
389 | use Exporter ();
|
---|
390 | our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
|
---|
391 |
|
---|
392 | # set the version for version checking
|
---|
393 | $VERSION = 1.00;
|
---|
394 | # if using RCS/CVS, this may be preferred
|
---|
395 | $VERSION = sprintf "%d.%03d", q$Revision: 1.1 $ =~ /(\d+)/g;
|
---|
396 |
|
---|
397 | @ISA = qw(Exporter);
|
---|
398 | @EXPORT = qw(&func1 &func2 &func4);
|
---|
399 | %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
|
---|
400 |
|
---|
401 | # your exported package globals go here,
|
---|
402 | # as well as any optionally exported functions
|
---|
403 | @EXPORT_OK = qw($Var1 %Hashit &func3);
|
---|
404 | }
|
---|
405 | our @EXPORT_OK;
|
---|
406 |
|
---|
407 | # exported package globals go here
|
---|
408 | our $Var1;
|
---|
409 | our %Hashit;
|
---|
410 |
|
---|
411 | # non-exported package globals go here
|
---|
412 | our @more;
|
---|
413 | our $stuff;
|
---|
414 |
|
---|
415 | # initialize package globals, first exported ones
|
---|
416 | $Var1 = '';
|
---|
417 | %Hashit = ();
|
---|
418 |
|
---|
419 | # then the others (which are still accessible as $Some::Module::stuff)
|
---|
420 | $stuff = '';
|
---|
421 | @more = ();
|
---|
422 |
|
---|
423 | # all file-scoped lexicals must be created before
|
---|
424 | # the functions below that use them.
|
---|
425 |
|
---|
426 | # file-private lexicals go here
|
---|
427 | my $priv_var = '';
|
---|
428 | my %secret_hash = ();
|
---|
429 |
|
---|
430 | # here's a file-private function as a closure,
|
---|
431 | # callable as &$priv_func; it cannot be prototyped.
|
---|
432 | my $priv_func = sub {
|
---|
433 | # stuff goes here.
|
---|
434 | };
|
---|
435 |
|
---|
436 | # make all your functions, whether exported or not;
|
---|
437 | # remember to put something interesting in the {} stubs
|
---|
438 | sub func1 {} # no prototype
|
---|
439 | sub func2() {} # proto'd void
|
---|
440 | sub func3($$) {} # proto'd to 2 scalars
|
---|
441 |
|
---|
442 | # this one isn't exported, but could be called!
|
---|
443 | sub func4(\%) {} # proto'd to 1 hash ref
|
---|
444 |
|
---|
445 | END { } # module clean-up code here (global destructor)
|
---|
446 |
|
---|
447 | ## YOUR CODE GOES HERE
|
---|
448 |
|
---|
449 | 1; # don't forget to return a true value from the file
|
---|
450 |
|
---|
451 | Then go on to declare and use your variables in functions without
|
---|
452 | any qualifications. See L<Exporter> and the L<perlmodlib> for
|
---|
453 | details on mechanics and style issues in module creation.
|
---|
454 |
|
---|
455 | Perl modules are included into your program by saying
|
---|
456 |
|
---|
457 | use Module;
|
---|
458 |
|
---|
459 | or
|
---|
460 |
|
---|
461 | use Module LIST;
|
---|
462 |
|
---|
463 | This is exactly equivalent to
|
---|
464 |
|
---|
465 | BEGIN { require Module; import Module; }
|
---|
466 |
|
---|
467 | or
|
---|
468 |
|
---|
469 | BEGIN { require Module; import Module LIST; }
|
---|
470 |
|
---|
471 | As a special case
|
---|
472 |
|
---|
473 | use Module ();
|
---|
474 |
|
---|
475 | is exactly equivalent to
|
---|
476 |
|
---|
477 | BEGIN { require Module; }
|
---|
478 |
|
---|
479 | All Perl module files have the extension F<.pm>. The C<use> operator
|
---|
480 | assumes this so you don't have to spell out "F<Module.pm>" in quotes.
|
---|
481 | This also helps to differentiate new modules from old F<.pl> and
|
---|
482 | F<.ph> files. Module names are also capitalized unless they're
|
---|
483 | functioning as pragmas; pragmas are in effect compiler directives,
|
---|
484 | and are sometimes called "pragmatic modules" (or even "pragmata"
|
---|
485 | if you're a classicist).
|
---|
486 |
|
---|
487 | The two statements:
|
---|
488 |
|
---|
489 | require SomeModule;
|
---|
490 | require "SomeModule.pm";
|
---|
491 |
|
---|
492 | differ from each other in two ways. In the first case, any double
|
---|
493 | colons in the module name, such as C<Some::Module>, are translated
|
---|
494 | into your system's directory separator, usually "/". The second
|
---|
495 | case does not, and would have to be specified literally. The other
|
---|
496 | difference is that seeing the first C<require> clues in the compiler
|
---|
497 | that uses of indirect object notation involving "SomeModule", as
|
---|
498 | in C<$ob = purge SomeModule>, are method calls, not function calls.
|
---|
499 | (Yes, this really can make a difference.)
|
---|
500 |
|
---|
501 | Because the C<use> statement implies a C<BEGIN> block, the importing
|
---|
502 | of semantics happens as soon as the C<use> statement is compiled,
|
---|
503 | before the rest of the file is compiled. This is how it is able
|
---|
504 | to function as a pragma mechanism, and also how modules are able to
|
---|
505 | declare subroutines that are then visible as list or unary operators for
|
---|
506 | the rest of the current file. This will not work if you use C<require>
|
---|
507 | instead of C<use>. With C<require> you can get into this problem:
|
---|
508 |
|
---|
509 | require Cwd; # make Cwd:: accessible
|
---|
510 | $here = Cwd::getcwd();
|
---|
511 |
|
---|
512 | use Cwd; # import names from Cwd::
|
---|
513 | $here = getcwd();
|
---|
514 |
|
---|
515 | require Cwd; # make Cwd:: accessible
|
---|
516 | $here = getcwd(); # oops! no main::getcwd()
|
---|
517 |
|
---|
518 | In general, C<use Module ()> is recommended over C<require Module>,
|
---|
519 | because it determines module availability at compile time, not in the
|
---|
520 | middle of your program's execution. An exception would be if two modules
|
---|
521 | each tried to C<use> each other, and each also called a function from
|
---|
522 | that other module. In that case, it's easy to use C<require> instead.
|
---|
523 |
|
---|
524 | Perl packages may be nested inside other package names, so we can have
|
---|
525 | package names containing C<::>. But if we used that package name
|
---|
526 | directly as a filename it would make for unwieldy or impossible
|
---|
527 | filenames on some systems. Therefore, if a module's name is, say,
|
---|
528 | C<Text::Soundex>, then its definition is actually found in the library
|
---|
529 | file F<Text/Soundex.pm>.
|
---|
530 |
|
---|
531 | Perl modules always have a F<.pm> file, but there may also be
|
---|
532 | dynamically linked executables (often ending in F<.so>) or autoloaded
|
---|
533 | subroutine definitions (often ending in F<.al>) associated with the
|
---|
534 | module. If so, these will be entirely transparent to the user of
|
---|
535 | the module. It is the responsibility of the F<.pm> file to load
|
---|
536 | (or arrange to autoload) any additional functionality. For example,
|
---|
537 | although the POSIX module happens to do both dynamic loading and
|
---|
538 | autoloading, the user can say just C<use POSIX> to get it all.
|
---|
539 |
|
---|
540 | =head2 Making your module threadsafe
|
---|
541 | X<threadsafe> X<thread safe>
|
---|
542 | X<module, threadsafe> X<module, thread safe>
|
---|
543 | X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread>
|
---|
544 |
|
---|
545 | Since 5.6.0, Perl has had support for a new type of threads called
|
---|
546 | interpreter threads (ithreads). These threads can be used explicitly
|
---|
547 | and implicitly.
|
---|
548 |
|
---|
549 | Ithreads work by cloning the data tree so that no data is shared
|
---|
550 | between different threads. These threads can be used by using the C<threads>
|
---|
551 | module or by doing fork() on win32 (fake fork() support). When a
|
---|
552 | thread is cloned all Perl data is cloned, however non-Perl data cannot
|
---|
553 | be cloned automatically. Perl after 5.7.2 has support for the C<CLONE>
|
---|
554 | special subroutine. In C<CLONE> you can do whatever
|
---|
555 | you need to do,
|
---|
556 | like for example handle the cloning of non-Perl data, if necessary.
|
---|
557 | C<CLONE> will be called once as a class method for every package that has it
|
---|
558 | defined (or inherits it). It will be called in the context of the new thread,
|
---|
559 | so all modifications are made in the new area. Currently CLONE is called with
|
---|
560 | no parameters other than the invocant package name, but code should not assume
|
---|
561 | that this will remain unchanged, as it is likely that in future extra parameters
|
---|
562 | will be passed in to give more information about the state of cloning.
|
---|
563 |
|
---|
564 | If you want to CLONE all objects you will need to keep track of them per
|
---|
565 | package. This is simply done using a hash and Scalar::Util::weaken().
|
---|
566 |
|
---|
567 | Perl after 5.8.7 has support for the C<CLONE_SKIP> special subroutine.
|
---|
568 | Like C<CLONE>, C<CLONE_SKIP> is called once per package; however, it is
|
---|
569 | called just before cloning starts, and in the context of the parent
|
---|
570 | thread. If it returns a true value, then no objects of that class will
|
---|
571 | be cloned; or rather, they will be copied as unblessed, undef values.
|
---|
572 | This provides a simple mechanism for making a module threadsafe; just add
|
---|
573 | C<sub CLONE_SKIP { 1 }> at the top of the class, and C<DESTROY()> will be
|
---|
574 | now only be called once per object. Of course, if the child thread needs
|
---|
575 | to make use of the objects, then a more sophisticated approach is
|
---|
576 | needed.
|
---|
577 |
|
---|
578 | Like C<CLONE>, C<CLONE_SKIP> is currently called with no parameters other
|
---|
579 | than the invocant package name, although that may change. Similarly, to
|
---|
580 | allow for future expansion, the return value should be a single C<0> or
|
---|
581 | C<1> value.
|
---|
582 |
|
---|
583 | =head1 SEE ALSO
|
---|
584 |
|
---|
585 | See L<perlmodlib> for general style issues related to building Perl
|
---|
586 | modules and classes, as well as descriptions of the standard library
|
---|
587 | and CPAN, L<Exporter> for how Perl's standard import/export mechanism
|
---|
588 | works, L<perltoot> and L<perltooc> for an in-depth tutorial on
|
---|
589 | creating classes, L<perlobj> for a hard-core reference document on
|
---|
590 | objects, L<perlsub> for an explanation of functions and scoping,
|
---|
591 | and L<perlxstut> and L<perlguts> for more information on writing
|
---|
592 | extension modules.
|
---|