3 perlmod - Perl modules (packages)
9 Perl provides a mechanism for alternative namespaces to protect packages
10 from stomping on each others variables. In fact, apart from certain magical
11 variables, there's really no such thing as a global variable in Perl.
12 By default, a Perl script starts
13 compiling into the package known as C<main>. You can switch namespaces
14 using the C<package> declaration. The scope of the package declaration is
15 from the declaration itself to the end of the enclosing block (the same
16 scope as the local() operator). Typically it would be the first
17 declaration in a file to be included by the C<require> operator. You can
18 switch into a package in more than one place; it merely influences which
19 symbol table is used by the compiler for the rest of that block. You can
20 refer to variables and filehandles in other packages by prefixing the
21 identifier with the package name and a double colon:
22 C<$Package::Variable>. If the package name is null, the C<main> package
23 as assumed. That is, C<$::sail> is equivalent to C<$main::sail>.
25 (The old package delimiter was a single quote, but double colon
26 is now the preferred delimiter, in part because it's more readable
27 to humans, and in part because it's more readable to B<emacs> macros.
28 It also makes C++ programmers feel like they know what's going on.)
30 Packages may be nested inside other packages: C<$OUTER::INNER::var>. This
31 implies nothing about the order of name lookups, however. All symbols
32 are either local to the current package, or must be fully qualified
33 from the outer package name down. For instance, there is nowhere
34 within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>.
35 It would treat package C<INNER> as a totally separate global package.
37 Only identifiers starting with letters (or underscore) are stored in a
38 package's symbol table. All other symbols are kept in package C<main>.
39 In addition, the identifiers STDIN, STDOUT, STDERR, ARGV,
40 ARGVOUT, ENV, INC and SIG are forced to be in package C<main>,
41 even when used for other purposes than their built-in one. Note also
42 that, if you have a package called C<m>, C<s> or C<y>, then you can't use
43 the qualified form of an identifier because it will be interpreted instead
44 as a pattern match, a substitution, or a translation.
46 (Variables beginning with underscore used to be forced into package
47 main, but we decided it was more useful for package writers to be able
48 to use leading underscore to indicate private variables and method names.)
50 Eval()ed strings are compiled in the package in which the eval() was
51 compiled. (Assignments to C<$SIG{}>, however, assume the signal
52 handler specified is in the C<main> package. Qualify the signal handler
53 name if you wish to have a signal handler in a package.) For an
54 example, examine F<perldb.pl> in the Perl library. It initially switches
55 to the C<DB> package so that the debugger doesn't interfere with variables
56 in the script you are trying to debug. At various points, however, it
57 temporarily switches back to the C<main> package to evaluate various
58 expressions in the context of the C<main> package (or wherever you came
59 from). See L<perldebug>.
63 The symbol table for a package happens to be stored in the associative
64 array of that name appended with two colons. The main symbol table's
65 name is thus C<%main::>, or C<%::> for short. Likewise the nested package
66 mentioned earlier is named C<%OUTER::INNER::>.
68 The value in each entry of the associative array is what you are
69 referring to when you use the C<*name> notation. In fact, the following
70 have the same effect, though the first is more efficient because it
71 does the symbol table lookups at compile time:
73 local(*main::foo) = *main::bar; local($main::{'foo'}) =
76 You can use this to print out all the variables in a package, for
77 instance. Here is F<dumpvar.pl> from the Perl library:
82 local(*stab) = eval("*${package}::");
83 while (($key,$val) = each(%stab)) {
86 print "\$$key = '$entry'\n";
91 foreach $num ($[ .. $#entry) {
92 print " $num\t'",$entry[$num],"'\n";
97 if ($key ne "${package}::" && defined %entry) {
99 foreach $key (sort keys(%entry)) {
100 print " $key\t'",$entry{$key},"'\n";
107 Note that even though the subroutine is compiled in package C<dumpvar>,
108 the name of the subroutine is qualified so that its name is inserted
109 into package C<main>.
111 Assignment to a symbol table entry performs an aliasing operation,
116 causes variables, subroutines and file handles accessible via the
117 identifier C<richard> to also be accessible via the symbol C<dick>. If
118 you only want to alias a particular variable or subroutine, you can
119 assign a reference instead:
123 makes $richard and $dick the same variable, but leaves
124 @richard and @dick as separate arrays. Tricky, eh?
126 =head2 Package Constructors and Destructors
128 There are two special subroutine definitions that function as package
129 constructors and destructors. These are the C<BEGIN> and C<END>
130 routines. The C<sub> is optional for these routines.
132 A C<BEGIN> subroutine is executed as soon as possible, that is, the
133 moment it is completely defined, even before the rest of the containing
134 file is parsed. You may have multiple C<BEGIN> blocks within a
135 file--they will execute in order of definition. Because a C<BEGIN>
136 block executes immediately, it can pull in definitions of subroutines
137 and such from other files in time to be visible to the rest of the
140 An C<END> subroutine is executed as late as possible, that is, when the
141 interpreter is being exited, even if it is exiting as a result of a
142 die() function. (But not if it's is being blown out of the water by a
143 signal--you have to trap that yourself (if you can).) You may have
144 multiple C<END> blocks within a file--they will execute in reverse
145 order of definition; that is: last in, first out (LIFO).
147 Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN>
148 and C<END> work just as they do in B<awk>, as a degenerate case.
152 There is no special class syntax in Perl 5, but a package may function
153 as a class if it provides subroutines that function as methods. Such a
154 package may also derive some of its methods from another class package
155 by listing the other package name in its @ISA array. For more on
156 this, see L<perlobj>.
160 In Perl 5, the notion of packages has been extended into the notion of
161 modules. A module is a package that is defined in a library file of
162 the same name, and is designed to be reusable. It may do this by
163 providing a mechanism for exporting some of its symbols into the symbol
164 table of any package using it. Or it may function as a class
165 definition and make its semantics available implicitly through method
166 calls on the class and its objects, without explicit exportation of any
167 symbols. Or it can do a little of both.
169 Perl modules are included by saying
177 This is exactly equivalent to
179 BEGIN { require "Module.pm"; import Module; }
183 BEGIN { require "Module.pm"; import Module LIST; }
185 All Perl module files have the extension F<.pm>. C<use> assumes this so
186 that you don't have to spell out "F<Module.pm>" in quotes. This also
187 helps to differentiate new modules from old F<.pl> and F<.ph> files.
188 Module names are also capitalized unless they're functioning as pragmas,
189 "Pragmas" are in effect compiler directives, and are sometimes called
190 "pragmatic modules" (or even "pragmata" if you're a classicist).
192 Because the C<use> statement implies a C<BEGIN> block, the importation
193 of semantics happens at the moment the C<use> statement is compiled,
194 before the rest of the file is compiled. This is how it is able
195 to function as a pragma mechanism, and also how modules are able to
196 declare subroutines that are then visible as list operators for
197 the rest of the current file. This will not work if you use C<require>
198 instead of C<use>. Therefore, if you're planning on the module altering
199 your namespace, use C<use>; otherwise, use C<require>. Otherwise you
200 can get into this problem:
202 require Cwd; # make Cwd:: accessible
203 $here = Cwd::getcwd();
205 use Cwd; # import names from Cwd::
208 require Cwd; # make Cwd:: accessible
209 $here = getcwd(); # oops! no main::getcwd()
211 Perl packages may be nested inside other package names, so we can have
212 package names containing C<::>. But if we used that package name
213 directly as a filename it would makes for unwieldy or impossible
214 filenames on some systems. Therefore, if a module's name is, say,
215 C<Text::Soundex>, then its definition is actually found in the library
216 file F<Text/Soundex.pm>.
218 Perl modules always have a F<.pm> file, but there may also be dynamically
219 linked executables or autoloaded subroutine definitions associated with
220 the module. If so, these will be entirely transparent to the user of
221 the module. It is the responsibility of the F<.pm> file to load (or
222 arrange to autoload) any additional functionality. The POSIX module
223 happens to do both dynamic loading and autoloading, but the user can
224 just say C<use POSIX> to get it all.
226 For more information on writing extension modules, see L<perlxs>
231 Perl does not enforce private and public parts of its modules as you may
232 have been used to in other languages like C++, Ada, or Modula-17. Perl
233 doesn't have an infatuation with enforced privacy. It would prefer
234 that you stayed out of its living room because you weren't invited, not
235 because it has a shotgun.
237 The module and its user have a contract, part of which is common law,
238 and part of which is "written". Part of the common law contract is
239 that a module doesn't pollute any namespace it wasn't asked to. The
240 written contract for the module (AKA documentation) may make other
241 provisions. But then you know when you C<use RedefineTheWorld> that
242 you're redefining the world and willing to take the consequences.
244 =head1 THE PERL MODULE LIBRARY
246 A number of modules are included the the Perl distribution. These are
247 described below, and all end in F<.pm>. You may also discover files in
248 the library directory that end in either F<.pl> or F<.ph>. These are old
249 libraries supplied so that old programs that use them still run. The
250 F<.pl> files will all eventually be converted into standard modules, and
251 the F<.ph> files made by B<h2ph> will probably end up as extension modules
252 made by B<h2xs>. (Some F<.ph> values may already be available through the
253 POSIX module.) The B<pl2pm> file in the distribution may help in your
254 conversion, but it's just a mechanical process, so is far from bullet proof.
256 =head2 Pragmatic Modules
258 They work somewhat like pragmas in that they tend to affect the compilation of
259 your program, and thus will usually only work well when used within a
260 C<use>, or C<no>. These are locally scoped, so an inner BLOCK
261 may countermand any of these by saying
266 which lasts until the end of that BLOCK.
268 The following programs are defined (and have their own documentation).
274 Perl pragma to compute arithmetic in integer instead of double
278 Perl pragma to request less of something from the compiler
282 Perl pragma to enable stack backtrace on unexpected signals
286 Perl pragma to restrict unsafe constructs
290 Perl pragma to predeclare sub names
294 =head2 Standard Modules
296 The following modules are all expected to behave in a well-defined
297 manner with respect to namespace pollution because they use the
299 See their own documentation for details.
305 create an abbreviation table from a list
309 provide framework for multiple DBMs
313 load functions only on demand
317 split a package for autoloading
321 parse file name and path from a specification
325 benchmark running times of code
329 warn or die of errors (from perspective of caller)
333 run many filetest checks on a tree
337 compare 8-bit scalar data according to the current locale
341 access Perl configuration option
345 get pathname of current working directory
349 Dynamically load C libraries into Perl code
353 use nice English (or B<awk>) names for ugly punctuation variables
357 Perl module that imports environment variables
361 module to control namespace manipulations
365 load the C Fcntl.h defines
369 supply object methods for filehandles
377 traverse a directory structure depth-first
381 basic and extended getopt(3) processing
385 generate a Makefile for Perl extension
389 open a process for both reading and writing
393 open a process for reading, writing, and error handling
397 Perl interface to IEEE 1003.1 namespace
401 check a host for upness
405 load the C socket.h defines
409 =head2 Extension Modules
411 Extension modules are written in C (or a mix of Perl and C) and get
412 dynamically loaded into Perl if and when you need them. Supported
413 extension modules include the Socket, Fcntl, and POSIX modules.
415 The following are popular C extension modules, which while available at
416 Perl 5.0 release time, do not come bundled (at least, not completely)
417 due to their size, volatility, or simply lack of time for adequate testing
418 and configuration across the multitude of platforms on which Perl was
419 beta-tested. You are encouraged to look for them in archie(1L), the Perl
420 FAQ or Meta-FAQ, the WWW page, and even with their authors before randomly
421 posting asking for their present condition and disposition. There's no
422 guarantee that the names or addresses below have not changed since printing,
423 and in fact, they probably have!
429 Written by William Setzer <F<William_Setzer@ncsu.edu>>, while not
430 included with the standard distribution, this extension module ports to
431 most systems. FTP from your nearest Perl archive site, or try
433 ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz
435 It is currently in alpha test, so the name and ftp location may
441 This is the portable database interface written by
442 <F<Tim.Bunce@ig.co.uk>>. This supersedes the many perl4 ports for
443 database extensions. The official archive for DBperl extensions is
444 F<ftp.demon.co.uk:/pub/perl/db>. This archive contains copies of perl4
445 ports for Ingres, Oracle, Sybase, Informix, Unify, Postgres, and
446 Interbase, as well as rdb and shql and other non-SQL systems.
450 Fastest and most restriction-free of the DBM bindings, this extension module
451 uses the popular Berkeley DB to tie() into your hashes. This has a
452 standardly-distributed man page and dynamic loading extension module, but
453 you'll have to fetch the Berkeley code yourself. See L<DB_File> for
458 This extension module is a front to the Athena and Xlib libraries for Perl
459 GUI programming, originally written by by Dominic Giampaolo
460 <F<dbg@sgi.com>>, then and rewritten for Sx by FrE<eacute>dE<eacute>ric
461 Chauveau <F<fmc@pasteur.fr>>. It's available for FTP from
463 ftp.pasteur.fr:/pub/Perl/Sx.tar.gz
467 This extension module is an object-oriented Perl5 binding to the popular
468 tcl/tk X11 package. However, you need know no TCL to use it!
469 It was written by Malcolm Beattie <F<mbeattie@sable.ox.ac.uk>>.
470 If you are unable to locate it using archie(1L) or a similar
471 tool, you may try retrieving it from F</private/Tk-october.tar.gz>
472 from Malcolm's machine listed above.