This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
This is patch.2b1f to perl5.002beta1.
[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
748a9306
LW
9Perl provides a mechanism for alternative namespaces to protect packages
10from stomping on each others variables. In fact, apart from certain magical
11variables, there's really no such thing as a global variable in Perl.
12By default, a Perl script starts
a0d0e21e
LW
13compiling into the package known as C<main>. You can switch namespaces
14using the C<package> declaration. The scope of the package declaration is
15from the declaration itself to the end of the enclosing block (the same
16scope as the local() operator). Typically it would be the first
17declaration in a file to be included by the C<require> operator. You can
18switch into a package in more than one place; it merely influences which
19symbol table is used by the compiler for the rest of that block. You can
20refer to variables and filehandles in other packages by prefixing the
21identifier with the package name and a double colon:
22C<$Package::Variable>. If the package name is null, the C<main> package
23as assumed. That is, C<$::sail> is equivalent to C<$main::sail>.
24
25(The old package delimiter was a single quote, but double colon
26is now the preferred delimiter, in part because it's more readable
27to humans, and in part because it's more readable to B<emacs> macros.
28It also makes C++ programmers feel like they know what's going on.)
29
30Packages may be nested inside other packages: C<$OUTER::INNER::var>. This
31implies nothing about the order of name lookups, however. All symbols
32are either local to the current package, or must be fully qualified
33from the outer package name down. For instance, there is nowhere
34within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>.
35It would treat package C<INNER> as a totally separate global package.
36
37Only identifiers starting with letters (or underscore) are stored in a
38package's symbol table. All other symbols are kept in package C<main>.
748a9306 39In addition, the identifiers STDIN, STDOUT, STDERR, ARGV,
a0d0e21e
LW
40ARGVOUT, ENV, INC and SIG are forced to be in package C<main>,
41even when used for other purposes than their built-in one. Note also
42that, if you have a package called C<m>, C<s> or C<y>, then you can't use
748a9306 43the qualified form of an identifier because it will be interpreted instead
a0d0e21e
LW
44as a pattern match, a substitution, or a translation.
45
46(Variables beginning with underscore used to be forced into package
47main, but we decided it was more useful for package writers to be able
48to use leading underscore to indicate private variables and method names.)
49
50Eval()ed strings are compiled in the package in which the eval() was
51compiled. (Assignments to C<$SIG{}>, however, assume the signal
748a9306 52handler specified is in the C<main> package. Qualify the signal handler
a0d0e21e
LW
53name if you wish to have a signal handler in a package.) For an
54example, examine F<perldb.pl> in the Perl library. It initially switches
55to the C<DB> package so that the debugger doesn't interfere with variables
56in the script you are trying to debug. At various points, however, it
57temporarily switches back to the C<main> package to evaluate various
58expressions in the context of the C<main> package (or wherever you came
59from). See L<perldebug>.
60
61=head2 Symbol Tables
62
63The symbol table for a package happens to be stored in the associative
64array of that name appended with two colons. The main symbol table's
65name is thus C<%main::>, or C<%::> for short. Likewise the nested package
66mentioned earlier is named C<%OUTER::INNER::>.
67
68The value in each entry of the associative array is what you are
4633a7c4 69referring to when you use the C<*name> typeglob notation. In fact, the following
a0d0e21e
LW
70have the same effect, though the first is more efficient because it
71does the symbol table lookups at compile time:
72
73 local(*main::foo) = *main::bar; local($main::{'foo'}) =
74 $main::{'bar'};
75
76You can use this to print out all the variables in a package, for
77instance. Here is F<dumpvar.pl> from the Perl library:
78
79 package dumpvar;
80 sub main::dumpvar {
81 ($package) = @_;
82 local(*stab) = eval("*${package}::");
83 while (($key,$val) = each(%stab)) {
84 local(*entry) = $val;
85 if (defined $entry) {
86 print "\$$key = '$entry'\n";
87 }
88
89 if (defined @entry) {
90 print "\@$key = (\n";
91 foreach $num ($[ .. $#entry) {
92 print " $num\t'",$entry[$num],"'\n";
93 }
94 print ")\n";
95 }
96
97 if ($key ne "${package}::" && defined %entry) {
98 print "\%$key = (\n";
99 foreach $key (sort keys(%entry)) {
100 print " $key\t'",$entry{$key},"'\n";
101 }
102 print ")\n";
103 }
104 }
105 }
106
107Note that even though the subroutine is compiled in package C<dumpvar>,
108the name of the subroutine is qualified so that its name is inserted
109into package C<main>.
110
4633a7c4 111Assignment to a typeglob performs an aliasing operation,
a0d0e21e
LW
112i.e.,
113
114 *dick = *richard;
115
748a9306 116causes variables, subroutines and file handles accessible via the
a0d0e21e
LW
117identifier C<richard> to also be accessible via the symbol C<dick>. If
118you only want to alias a particular variable or subroutine, you can
119assign a reference instead:
120
121 *dick = \$richard;
122
123makes $richard and $dick the same variable, but leaves
124@richard and @dick as separate arrays. Tricky, eh?
125
126=head2 Package Constructors and Destructors
127
128There are two special subroutine definitions that function as package
129constructors and destructors. These are the C<BEGIN> and C<END>
130routines. The C<sub> is optional for these routines.
131
132A C<BEGIN> subroutine is executed as soon as possible, that is, the
133moment it is completely defined, even before the rest of the containing
134file is parsed. You may have multiple C<BEGIN> blocks within a
135file--they will execute in order of definition. Because a C<BEGIN>
136block executes immediately, it can pull in definitions of subroutines
137and such from other files in time to be visible to the rest of the
138file.
139
140An C<END> subroutine is executed as late as possible, that is, when the
141interpreter is being exited, even if it is exiting as a result of a
142die() function. (But not if it's is being blown out of the water by a
143signal--you have to trap that yourself (if you can).) You may have
748a9306 144multiple C<END> blocks within a file--they will execute in reverse
a0d0e21e
LW
145order of definition; that is: last in, first out (LIFO).
146
147Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN>
148and C<END> work just as they do in B<awk>, as a degenerate case.
149
150=head2 Perl Classes
151
4633a7c4 152There is no special class syntax in Perl, but a package may function
a0d0e21e
LW
153as a class if it provides subroutines that function as methods. Such a
154package may also derive some of its methods from another class package
4633a7c4
LW
155by listing the other package name in its @ISA array.
156
157For more on this, see L<perlobj>.
a0d0e21e
LW
158
159=head2 Perl Modules
160
4633a7c4 161A module is a just package that is defined in a library file of
a0d0e21e
LW
162the same name, and is designed to be reusable. It may do this by
163providing a mechanism for exporting some of its symbols into the symbol
164table of any package using it. Or it may function as a class
165definition and make its semantics available implicitly through method
166calls on the class and its objects, without explicit exportation of any
167symbols. Or it can do a little of both.
168
4633a7c4
LW
169For example, to start a normal module called Fred, create
170a file called Fred.pm and put this at the start of it:
171
172 package Fred;
173 require Exporter;
174 @ISA = qw(Exporter);
175 @EXPORT = qw(func1 func2);
176 @EXPORT_OK = qw($sally @listabob %harry func3);
177
178Then go on to declare and use your variables in functions
179without any qualifications.
180See L<Exporter> and the I<Perl Modules File> for details on
181mechanics and style issues in module creation.
182
183Perl modules are included into your program by saying
a0d0e21e
LW
184
185 use Module;
186
187or
188
189 use Module LIST;
190
191This is exactly equivalent to
192
193 BEGIN { require "Module.pm"; import Module; }
194
195or
196
197 BEGIN { require "Module.pm"; import Module LIST; }
198
199All Perl module files have the extension F<.pm>. C<use> assumes this so
200that you don't have to spell out "F<Module.pm>" in quotes. This also
201helps to differentiate new modules from old F<.pl> and F<.ph> files.
202Module names are also capitalized unless they're functioning as pragmas,
203"Pragmas" are in effect compiler directives, and are sometimes called
204"pragmatic modules" (or even "pragmata" if you're a classicist).
205
206Because the C<use> statement implies a C<BEGIN> block, the importation
207of semantics happens at the moment the C<use> statement is compiled,
208before the rest of the file is compiled. This is how it is able
209to function as a pragma mechanism, and also how modules are able to
210declare subroutines that are then visible as list operators for
211the rest of the current file. This will not work if you use C<require>
212instead of C<use>. Therefore, if you're planning on the module altering
213your namespace, use C<use>; otherwise, use C<require>. Otherwise you
214can get into this problem:
215
216 require Cwd; # make Cwd:: accessible
217 $here = Cwd::getcwd();
218
219 use Cwd; # import names from Cwd::
220 $here = getcwd();
221
222 require Cwd; # make Cwd:: accessible
223 $here = getcwd(); # oops! no main::getcwd()
224
225Perl packages may be nested inside other package names, so we can have
226package names containing C<::>. But if we used that package name
227directly as a filename it would makes for unwieldy or impossible
228filenames on some systems. Therefore, if a module's name is, say,
229C<Text::Soundex>, then its definition is actually found in the library
230file F<Text/Soundex.pm>.
231
232Perl modules always have a F<.pm> file, but there may also be dynamically
233linked executables or autoloaded subroutine definitions associated with
234the module. If so, these will be entirely transparent to the user of
235the module. It is the responsibility of the F<.pm> file to load (or
236arrange to autoload) any additional functionality. The POSIX module
237happens to do both dynamic loading and autoloading, but the user can
238just say C<use POSIX> to get it all.
239
8e07c86e 240For more information on writing extension modules, see L<perlxs>
a0d0e21e
LW
241and L<perlguts>.
242
243=head1 NOTE
244
245Perl does not enforce private and public parts of its modules as you may
246have been used to in other languages like C++, Ada, or Modula-17. Perl
247doesn't have an infatuation with enforced privacy. It would prefer
248that you stayed out of its living room because you weren't invited, not
249because it has a shotgun.
250
251The module and its user have a contract, part of which is common law,
252and part of which is "written". Part of the common law contract is
253that a module doesn't pollute any namespace it wasn't asked to. The
254written contract for the module (AKA documentation) may make other
255provisions. But then you know when you C<use RedefineTheWorld> that
256you're redefining the world and willing to take the consequences.
257
258=head1 THE PERL MODULE LIBRARY
259
260A number of modules are included the the Perl distribution. These are
261described below, and all end in F<.pm>. You may also discover files in
262the library directory that end in either F<.pl> or F<.ph>. These are old
748a9306 263libraries supplied so that old programs that use them still run. The
a0d0e21e
LW
264F<.pl> files will all eventually be converted into standard modules, and
265the F<.ph> files made by B<h2ph> will probably end up as extension modules
266made by B<h2xs>. (Some F<.ph> values may already be available through the
267POSIX module.) The B<pl2pm> file in the distribution may help in your
268conversion, but it's just a mechanical process, so is far from bullet proof.
269
270=head2 Pragmatic Modules
271
272They work somewhat like pragmas in that they tend to affect the compilation of
273your program, and thus will usually only work well when used within a
748a9306 274C<use>, or C<no>. These are locally scoped, so an inner BLOCK
a0d0e21e
LW
275may countermand any of these by saying
276
277 no integer;
278 no strict 'refs';
279
280which lasts until the end of that BLOCK.
281
282The following programs are defined (and have their own documentation).
283
284=over 12
285
4633a7c4
LW
286=item C<diagnostics>
287
288Pragma to produce enhanced diagnostics
289
a0d0e21e
LW
290=item C<integer>
291
4633a7c4 292Pragma to compute arithmetic in integer instead of double
a0d0e21e
LW
293
294=item C<less>
295
4633a7c4 296Pragma to request less of something from the compiler
a0d0e21e
LW
297
298=item C<sigtrap>
299
4633a7c4 300Pragma to enable stack backtrace on unexpected signals
a0d0e21e
LW
301
302=item C<strict>
303
4633a7c4 304Pragma to restrict unsafe constructs
a0d0e21e
LW
305
306=item C<subs>
307
4633a7c4 308Pragma to predeclare sub names
a0d0e21e
LW
309
310=back
311
312=head2 Standard Modules
313
4633a7c4 314Standard, bundled modules are all expected to behave in a well-defined
a0d0e21e 315manner with respect to namespace pollution because they use the
4633a7c4 316Exporter module. See their own documentation for details.
a0d0e21e 317
4633a7c4 318To find out all the modules installed on your system, do this:
a0d0e21e 319
4633a7c4 320 find `perl -e 'print "@INC"'` -name '*.pm' -print
a0d0e21e 321
4633a7c4
LW
322They should all have their own documentation installed and accessible via
323your system man(1) command. If that fails, try the I<perldoc> program.
a0d0e21e 324
4633a7c4 325=head2 Extension Modules
a0d0e21e 326
4633a7c4
LW
327Extension modules are written in C (or a mix of Perl and C) and get
328dynamically loaded into Perl if and when you need them. Supported
329extension modules include the Socket, Fcntl, and POSIX modules.
a0d0e21e 330
4633a7c4
LW
331Many popular C extension modules
332do not come bundled (at least, not completely)
333due to their size, volatility, or simply lack of time for adequate testing
334and configuration across the multitude of platforms on which Perl was
335beta-tested. You are encouraged to look for them in archie(1L), the Perl
336FAQ or Meta-FAQ, the WWW page, and even with their authors before randomly
337posting asking for their present condition and disposition.
a0d0e21e 338
4633a7c4 339=head2 CPAN
a0d0e21e 340
4633a7c4
LW
341CPAN stands for the Comprehensive Perl Archive Network. This is a globally
342replicated collection of all known Perl materials, including hundreds
343of unbunded modules. Here are the major categories of modules:
a0d0e21e 344
4633a7c4 345=over
a0d0e21e 346
4633a7c4
LW
347=item *
348Language Extensions and Documentation Tools
a0d0e21e 349
4633a7c4
LW
350=item *
351Development Support
a0d0e21e 352
4633a7c4
LW
353=item *
354Operating System Interfaces
a0d0e21e 355
4633a7c4
LW
356=item *
357Networking, Device Control (modems) and InterProcess Communication
a0d0e21e 358
4633a7c4
LW
359=item *
360Data Types and Data Type Utilities
a0d0e21e 361
4633a7c4
LW
362=item *
363Database Interfaces
a0d0e21e 364
4633a7c4
LW
365=item *
366User Interfaces
a0d0e21e 367
4633a7c4
LW
368=item *
369Interfaces to / Emulations of Other Programming Languages
a0d0e21e 370
4633a7c4
LW
371=item *
372File Names, File Systems and File Locking (see also File Handles)
a0d0e21e 373
4633a7c4
LW
374=item *
375String Processing, Language Text Processing, Parsing and Searching
a0d0e21e 376
4633a7c4
LW
377=item *
378Option, Argument, Parameter and Configuration File Processing
a0d0e21e 379
4633a7c4
LW
380=item *
381Internationalization and Locale
a0d0e21e 382
4633a7c4
LW
383=item *
384Authentication, Security and Encryption
a0d0e21e 385
4633a7c4
LW
386=item *
387World Wide Web, HTML, HTTP, CGI, MIME
a0d0e21e 388
4633a7c4
LW
389=item *
390Server and Daemon Utilities
a0d0e21e 391
4633a7c4
LW
392=item *
393Archiving and Compression
a0d0e21e 394
4633a7c4
LW
395=item *
396Images, Pixmap and Bitmap Manipulation, Drawing and Graphing
a0d0e21e 397
4633a7c4
LW
398=item *
399Mail and Usenet News
a0d0e21e 400
4633a7c4
LW
401=item *
402Control Flow Utilities (callbacks and exceptions etc)
a0d0e21e 403
4633a7c4
LW
404=item *
405File Handle and Input/Output Stream Utilities
a0d0e21e 406
4633a7c4
LW
407=item *
408Miscellaneous Modules
a0d0e21e 409
4633a7c4 410=back
a0d0e21e 411
4633a7c4
LW
412Some of the reguster CPAN sites as of this writing include the following.
413You should try to choose one close to you:
a0d0e21e 414
4633a7c4 415=over
a0d0e21e 416
4633a7c4
LW
417=item *
418ftp://ftp.sterling.com/programming/languages/perl/
a0d0e21e 419
4633a7c4
LW
420=item *
421ftp://ftp.sedl.org/pub/mirrors/CPAN/
a0d0e21e 422
4633a7c4
LW
423=item *
424ftp://ftp.uoknor.edu/mirrors/CPAN/
a0d0e21e 425
4633a7c4
LW
426=item *
427ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/
a0d0e21e 428
4633a7c4
LW
429=item *
430ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/
a0d0e21e 431
4633a7c4
LW
432=item *
433ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
a0d0e21e 434
4633a7c4
LW
435=item *
436ftp://ftp.switch.ch/mirror/CPAN/
a0d0e21e 437
4633a7c4
LW
438=item *
439ftp://ftp.sunet.se/pub/lang/perl/CPAN/
a0d0e21e 440
4633a7c4
LW
441=item *
442ftp://ftp.ci.uminho.pt/pub/lang/perl/
a0d0e21e 443
4633a7c4
LW
444=item *
445ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
a0d0e21e 446
4633a7c4
LW
447=item *
448ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
a0d0e21e 449
4633a7c4
LW
450=item *
451ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/
a0d0e21e 452
4633a7c4
LW
453=item *
454ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/
a0d0e21e 455
4633a7c4
LW
456=item *
457ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
a0d0e21e 458
4633a7c4
LW
459=item *
460ftp://ftp.ibp.fr/pub/perl/CPAN/
a0d0e21e 461
4633a7c4
LW
462=item *
463ftp://ftp.funet.fi/pub/languages/perl/CPAN/
a0d0e21e 464
4633a7c4
LW
465=item *
466ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/
a0d0e21e 467
4633a7c4
LW
468=item *
469ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/
a0d0e21e 470
4633a7c4
LW
471=item *
472ftp://coombs.anu.edu.au/pub/perl/
a0d0e21e 473
4633a7c4
LW
474=item *
475ftp://dongpo.math.ncu.edu.tw/perl/CPAN/
a0d0e21e 476
4633a7c4
LW
477=item *
478ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
a0d0e21e 479
4633a7c4
LW
480=item *
481ftp://ftp.is.co.za/programming/perl/CPAN/
a0d0e21e
LW
482
483=back
4633a7c4
LW
484
485For an up-to-date listing of CPAN sites,
486see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/.