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