This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 5.000
[perl5.git] / pod / perlmod.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlmod - Perl modules (packages)
4
5=head1 DESCRIPTION
6
7=head2 Packages
8
9Perl provides a mechanism for alternate namespaces to protect packages
10from stomping on each others variables. By default, a Perl script starts
11compiling into the package known as C<main>. You can switch namespaces
12using the C<package> declaration. The scope of the package declaration is
13from the declaration itself to the end of the enclosing block (the same
14scope as the local() operator). Typically it would be the first
15declaration in a file to be included by the C<require> operator. You can
16switch into a package in more than one place; it merely influences which
17symbol table is used by the compiler for the rest of that block. You can
18refer to variables and filehandles in other packages by prefixing the
19identifier with the package name and a double colon:
20C<$Package::Variable>. If the package name is null, the C<main> package
21as assumed. That is, C<$::sail> is equivalent to C<$main::sail>.
22
23(The old package delimiter was a single quote, but double colon
24is now the preferred delimiter, in part because it's more readable
25to humans, and in part because it's more readable to B<emacs> macros.
26It also makes C++ programmers feel like they know what's going on.)
27
28Packages may be nested inside other packages: C<$OUTER::INNER::var>. This
29implies nothing about the order of name lookups, however. All symbols
30are either local to the current package, or must be fully qualified
31from the outer package name down. For instance, there is nowhere
32within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>.
33It would treat package C<INNER> as a totally separate global package.
34
35Only identifiers starting with letters (or underscore) are stored in a
36package's symbol table. All other symbols are kept in package C<main>.
37In addition, the identifiers STDIN, STDOUT, STDERR, C<ARGV>,
38ARGVOUT, ENV, INC and SIG are forced to be in package C<main>,
39even when used for other purposes than their built-in one. Note also
40that, if you have a package called C<m>, C<s> or C<y>, then you can't use
41the qualified form of an identifier since it will be interpreted instead
42as a pattern match, a substitution, or a translation.
43
44(Variables beginning with underscore used to be forced into package
45main, but we decided it was more useful for package writers to be able
46to use leading underscore to indicate private variables and method names.)
47
48Eval()ed strings are compiled in the package in which the eval() was
49compiled. (Assignments to C<$SIG{}>, however, assume the signal
50handler specified is in the C<main. package. Qualify the signal handler
51name if you wish to have a signal handler in a package.) For an
52example, examine F<perldb.pl> in the Perl library. It initially switches
53to the C<DB> package so that the debugger doesn't interfere with variables
54in the script you are trying to debug. At various points, however, it
55temporarily switches back to the C<main> package to evaluate various
56expressions in the context of the C<main> package (or wherever you came
57from). See L<perldebug>.
58
59=head2 Symbol Tables
60
61The symbol table for a package happens to be stored in the associative
62array of that name appended with two colons. The main symbol table's
63name is thus C<%main::>, or C<%::> for short. Likewise the nested package
64mentioned earlier is named C<%OUTER::INNER::>.
65
66The value in each entry of the associative array is what you are
67referring to when you use the C<*name> notation. In fact, the following
68have the same effect, though the first is more efficient because it
69does the symbol table lookups at compile time:
70
71 local(*main::foo) = *main::bar; local($main::{'foo'}) =
72 $main::{'bar'};
73
74You can use this to print out all the variables in a package, for
75instance. Here is F<dumpvar.pl> from the Perl library:
76
77 package dumpvar;
78 sub main::dumpvar {
79 ($package) = @_;
80 local(*stab) = eval("*${package}::");
81 while (($key,$val) = each(%stab)) {
82 local(*entry) = $val;
83 if (defined $entry) {
84 print "\$$key = '$entry'\n";
85 }
86
87 if (defined @entry) {
88 print "\@$key = (\n";
89 foreach $num ($[ .. $#entry) {
90 print " $num\t'",$entry[$num],"'\n";
91 }
92 print ")\n";
93 }
94
95 if ($key ne "${package}::" && defined %entry) {
96 print "\%$key = (\n";
97 foreach $key (sort keys(%entry)) {
98 print " $key\t'",$entry{$key},"'\n";
99 }
100 print ")\n";
101 }
102 }
103 }
104
105Note that even though the subroutine is compiled in package C<dumpvar>,
106the name of the subroutine is qualified so that its name is inserted
107into package C<main>.
108
109Assignment to a symbol table entry performs an aliasing operation,
110i.e.,
111
112 *dick = *richard;
113
114causes variables, subroutines and filehandles accessible via the
115identifier C<richard> to also be accessible via the symbol C<dick>. If
116you only want to alias a particular variable or subroutine, you can
117assign a reference instead:
118
119 *dick = \$richard;
120
121makes $richard and $dick the same variable, but leaves
122@richard and @dick as separate arrays. Tricky, eh?
123
124=head2 Package Constructors and Destructors
125
126There are two special subroutine definitions that function as package
127constructors and destructors. These are the C<BEGIN> and C<END>
128routines. The C<sub> is optional for these routines.
129
130A C<BEGIN> subroutine is executed as soon as possible, that is, the
131moment it is completely defined, even before the rest of the containing
132file is parsed. You may have multiple C<BEGIN> blocks within a
133file--they will execute in order of definition. Because a C<BEGIN>
134block executes immediately, it can pull in definitions of subroutines
135and such from other files in time to be visible to the rest of the
136file.
137
138An C<END> subroutine is executed as late as possible, that is, when the
139interpreter is being exited, even if it is exiting as a result of a
140die() function. (But not if it's is being blown out of the water by a
141signal--you have to trap that yourself (if you can).) You may have
142multiple C<END> blocks within a file--they wil execute in reverse
143order of definition; that is: last in, first out (LIFO).
144
145Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN>
146and C<END> work just as they do in B<awk>, as a degenerate case.
147
148=head2 Perl Classes
149
150There is no special class syntax in Perl 5, but a package may function
151as a class if it provides subroutines that function as methods. Such a
152package may also derive some of its methods from another class package
153by listing the other package name in its @ISA array. For more on
154this, see L<perlobj>.
155
156=head2 Perl Modules
157
158In Perl 5, the notion of packages has been extended into the notion of
159modules. A module is a package that is defined in a library file of
160the same name, and is designed to be reusable. It may do this by
161providing a mechanism for exporting some of its symbols into the symbol
162table of any package using it. Or it may function as a class
163definition and make its semantics available implicitly through method
164calls on the class and its objects, without explicit exportation of any
165symbols. Or it can do a little of both.
166
167Perl modules are included by saying
168
169 use Module;
170
171or
172
173 use Module LIST;
174
175This is exactly equivalent to
176
177 BEGIN { require "Module.pm"; import Module; }
178
179or
180
181 BEGIN { require "Module.pm"; import Module LIST; }
182
183All Perl module files have the extension F<.pm>. C<use> assumes this so
184that you don't have to spell out "F<Module.pm>" in quotes. This also
185helps to differentiate new modules from old F<.pl> and F<.ph> files.
186Module names are also capitalized unless they're functioning as pragmas,
187"Pragmas" are in effect compiler directives, and are sometimes called
188"pragmatic modules" (or even "pragmata" if you're a classicist).
189
190Because the C<use> statement implies a C<BEGIN> block, the importation
191of semantics happens at the moment the C<use> statement is compiled,
192before the rest of the file is compiled. This is how it is able
193to function as a pragma mechanism, and also how modules are able to
194declare subroutines that are then visible as list operators for
195the rest of the current file. This will not work if you use C<require>
196instead of C<use>. Therefore, if you're planning on the module altering
197your namespace, use C<use>; otherwise, use C<require>. Otherwise you
198can get into this problem:
199
200 require Cwd; # make Cwd:: accessible
201 $here = Cwd::getcwd();
202
203 use Cwd; # import names from Cwd::
204 $here = getcwd();
205
206 require Cwd; # make Cwd:: accessible
207 $here = getcwd(); # oops! no main::getcwd()
208
209Perl packages may be nested inside other package names, so we can have
210package names containing C<::>. But if we used that package name
211directly as a filename it would makes for unwieldy or impossible
212filenames on some systems. Therefore, if a module's name is, say,
213C<Text::Soundex>, then its definition is actually found in the library
214file F<Text/Soundex.pm>.
215
216Perl modules always have a F<.pm> file, but there may also be dynamically
217linked executables or autoloaded subroutine definitions associated with
218the module. If so, these will be entirely transparent to the user of
219the module. It is the responsibility of the F<.pm> file to load (or
220arrange to autoload) any additional functionality. The POSIX module
221happens to do both dynamic loading and autoloading, but the user can
222just say C<use POSIX> to get it all.
223
224For more information on writing extension modules, see L<perlapi>
225and L<perlguts>.
226
227=head1 NOTE
228
229Perl does not enforce private and public parts of its modules as you may
230have been used to in other languages like C++, Ada, or Modula-17. Perl
231doesn't have an infatuation with enforced privacy. It would prefer
232that you stayed out of its living room because you weren't invited, not
233because it has a shotgun.
234
235The module and its user have a contract, part of which is common law,
236and part of which is "written". Part of the common law contract is
237that a module doesn't pollute any namespace it wasn't asked to. The
238written contract for the module (AKA documentation) may make other
239provisions. But then you know when you C<use RedefineTheWorld> that
240you're redefining the world and willing to take the consequences.
241
242=head1 THE PERL MODULE LIBRARY
243
244A number of modules are included the the Perl distribution. These are
245described below, and all end in F<.pm>. You may also discover files in
246the library directory that end in either F<.pl> or F<.ph>. These are old
247libaries supplied so that old programs that use them still run. The
248F<.pl> files will all eventually be converted into standard modules, and
249the F<.ph> files made by B<h2ph> will probably end up as extension modules
250made by B<h2xs>. (Some F<.ph> values may already be available through the
251POSIX module.) The B<pl2pm> file in the distribution may help in your
252conversion, but it's just a mechanical process, so is far from bullet proof.
253
254=head2 Pragmatic Modules
255
256They work somewhat like pragmas in that they tend to affect the compilation of
257your program, and thus will usually only work well when used within a
258C<use>, or C<no>. These are locally scoped, so if an inner BLOCK
259may countermand any of these by saying
260
261 no integer;
262 no strict 'refs';
263
264which lasts until the end of that BLOCK.
265
266The following programs are defined (and have their own documentation).
267
268=over 12
269
270=item C<integer>
271
272Perl pragma to compute arithmetic in integer instead of double
273
274=item C<less>
275
276Perl pragma to request less of something from the compiler
277
278=item C<sigtrap>
279
280Perl pragma to enable stack backtrace on unexpected signals
281
282=item C<strict>
283
284Perl pragma to restrict unsafe constructs
285
286=item C<subs>
287
288Perl pragma to predeclare sub names
289
290=back
291
292=head2 Standard Modules
293
294The following modules are all expacted to behave in a well-defined
295manner with respect to namespace pollution because they use the
296Exporter module.
297See their own documentation for details.
298
299=over 12
300
301=item C<Abbrev>
302
303create an abbreviation table from a list
304
305=item C<AnyDBM_File>
306
307provide framework for multiple DBMs
308
309=item C<AutoLoader>
310
311load functions only on demand
312
313=item C<AutoSplit>
314
315split a package for autoloading
316
317=item C<Basename>
318
319parse file anme and path from a specification
320
321=item C<Benchmark>
322
323benchmark running times of code
324
325=item C<Carp>
326
327warn or die of errors (from perspective of caller)
328
329=item C<CheckTree>
330
331run many filetest checks on a tree
332
333=item C<Collate>
334
335compare 8-bit scalar data according to the current locale
336
337=item C<Config>
338
339access Perl configuration option
340
341=item C<Cwd>
342
343get pathname of current working directory
344
345=item C<DynaLoader>
346
347Dynamically load C libraries into Perl code
348
349=item C<English>
350
351use nice English (or B<awk>) names for ugly punctuation variables
352
353=item C<Env>
354
355Perl module that imports environment variables
356
357=item C<Exporter>
358
359module to control namespace manipulations
360
361=item C<Fcntl>
362
363load the C Fcntl.h defines
364
365=item C<FileHandle>
366
367supply object methods for filehandles
368
369=item C<Find>
370
371traverse a file tree
372
373=item C<Finddepth>
374
375traverse a directory structure depth-first
376
377=item C<Getopt>
378
379basic and extended getopt(3) processing
380
381=item C<MakeMaker>
382
383generate a Makefile for Perl extension
384
385=item C<Open2>
386
387open a process for both reading and writing
388
389=item C<Open3>
390
391open a process for reading, writing, and error handling
392
393=item C<POSIX>
394
395Perl interface to IEEE 1003.1 namespace
396
397=item C<Ping>
398
399check a host for upness
400
401=item C<Socket>
402
403load the C socket.h defines
404
405=back
406
407=head2 Extension Modules
408
409Extension modules are written in C (or a mix of Perl and C) and get
410dynamically loaded into Perl if and when you need them. Supported
411extension modules include the Socket, Fcntl, and POSIX modules.
412
413The following are popular C extension modules, which while available at
414Perl 5.0 release time, do not come not bundled (at least, not completely)
415due to their size, volatility, or simply lack of time for adequate testing
416and configuration across the multitude of platforms on which Perl was
417beta-tested. You are encouraged to look for them in archie(1L), the Perl
418FAQ or Meta-FAQ, the WWW page, and even their authors before randomly
419posting asking for their present condition and disposition. There's no
420guarantee that the names or addresses below have not changed since printing,
421and in fact, they probably have!
422
423=over 12
424
425=item C<Curses>
426
427Written by William Setzer <F<William_Setzer@ncsu.edu>>, while not
428included with the standard distribution, this extension module ports to
429most systems. FTP from your nearest Perl archive site, or try
430
431 ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz
432
433It is currently in alpha test, so the name and ftp location may
434change.
435
436
437=item C<DBI>
438
439This is the portable database interface written by
440<F<Tim.Bunce@ig.co.uk>>. This supersedes the many perl4 ports for
441database extensions. The official archive for DBperl extensions is
442F<ftp.demon.co.uk:/pub/perl/db>. This archive contains copies of perl4
443ports for Ingres, Oracle, Sybase, Informix, Unify, Postgres, and
444Interbase, as well as rdb and shql and other non-SQL systems.
445
446=item C<DB_File>
447
448Fastest and most restriction-free of the DBM bindings, this extension module
449uses the popular Berkeley DB to tie() into your hashes. This has a
450standardly-distributed man page and dynamic loading extension module, but
451you'll have to fetch the Berkeley code yourself. See L<DB_File> for
452where.
453
454=item C<Sx>
455
456This extension module is a front to the Athena and Xlib libraries for Perl
457GUI progamming, originally written by by Dominic Giampaolo
458<F<dbg@sgi.com>>, then and rewritten for Sx by FrE<eacute>dE<eacute>ric
459Chauveau <F<fmc@pasteur.fr>>. It's available for FTP from
460
461 ftp.pasteur.fr:/pub/Perl/Sx.tar.gz
462
463=item C<Tk>
464
465This extension module is an object-oriented Perl5 binding to the popular
466tcl/tk X11 package. However, you need know no TCL to use it!
467It was written by Malcolm Beattie <F<mbeattie@sable.ox.ac.uk>>.
468If you are unable to locate it using archie(1L) or a similar
469tool, you may try retrieving it from F</private/Tk-october.tar.gz>
470from Malcolm's machine listed above.
471
472=back