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> typeglob 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 typeglob 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, 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.
157 For more on this, see L<perlobj>.
161 A module is a just 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 For example, to start a normal module called Fred, create
170 a file called Fred.pm and put this at the start of it:
175 @EXPORT = qw(func1 func2);
176 @EXPORT_OK = qw($sally @listabob %harry func3);
178 Then go on to declare and use your variables in functions
179 without any qualifications.
180 See L<Exporter> and the I<Perl Modules File> for details on
181 mechanics and style issues in module creation.
183 Perl modules are included into your program by saying
191 This is exactly equivalent to
193 BEGIN { require "Module.pm"; import Module; }
197 BEGIN { require "Module.pm"; import Module LIST; }
199 All Perl module files have the extension F<.pm>. C<use> assumes this so
200 that you don't have to spell out "F<Module.pm>" in quotes. This also
201 helps to differentiate new modules from old F<.pl> and F<.ph> files.
202 Module 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).
206 Because the C<use> statement implies a C<BEGIN> block, the importation
207 of semantics happens at the moment the C<use> statement is compiled,
208 before the rest of the file is compiled. This is how it is able
209 to function as a pragma mechanism, and also how modules are able to
210 declare subroutines that are then visible as list operators for
211 the rest of the current file. This will not work if you use C<require>
212 instead of C<use>. Therefore, if you're planning on the module altering
213 your namespace, use C<use>; otherwise, use C<require>. Otherwise you
214 can get into this problem:
216 require Cwd; # make Cwd:: accessible
217 $here = Cwd::getcwd();
219 use Cwd; # import names from Cwd::
222 require Cwd; # make Cwd:: accessible
223 $here = getcwd(); # oops! no main::getcwd()
225 Perl packages may be nested inside other package names, so we can have
226 package names containing C<::>. But if we used that package name
227 directly as a filename it would makes for unwieldy or impossible
228 filenames on some systems. Therefore, if a module's name is, say,
229 C<Text::Soundex>, then its definition is actually found in the library
230 file F<Text/Soundex.pm>.
232 Perl modules always have a F<.pm> file, but there may also be dynamically
233 linked executables or autoloaded subroutine definitions associated with
234 the module. If so, these will be entirely transparent to the user of
235 the module. It is the responsibility of the F<.pm> file to load (or
236 arrange to autoload) any additional functionality. The POSIX module
237 happens to do both dynamic loading and autoloading, but the user can
238 just say C<use POSIX> to get it all.
240 For more information on writing extension modules, see L<perlxs>
245 Perl does not enforce private and public parts of its modules as you may
246 have been used to in other languages like C++, Ada, or Modula-17. Perl
247 doesn't have an infatuation with enforced privacy. It would prefer
248 that you stayed out of its living room because you weren't invited, not
249 because it has a shotgun.
251 The module and its user have a contract, part of which is common law,
252 and part of which is "written". Part of the common law contract is
253 that a module doesn't pollute any namespace it wasn't asked to. The
254 written contract for the module (AKA documentation) may make other
255 provisions. But then you know when you C<use RedefineTheWorld> that
256 you're redefining the world and willing to take the consequences.
258 =head1 THE PERL MODULE LIBRARY
260 A number of modules are included the the Perl distribution. These are
261 described below, and all end in F<.pm>. You may also discover files in
262 the library directory that end in either F<.pl> or F<.ph>. These are old
263 libraries supplied so that old programs that use them still run. The
264 F<.pl> files will all eventually be converted into standard modules, and
265 the F<.ph> files made by B<h2ph> will probably end up as extension modules
266 made by B<h2xs>. (Some F<.ph> values may already be available through the
267 POSIX module.) The B<pl2pm> file in the distribution may help in your
268 conversion, but it's just a mechanical process, so is far from bullet proof.
270 =head2 Pragmatic Modules
272 They work somewhat like pragmas in that they tend to affect the compilation of
273 your program, and thus will usually only work well when used within a
274 C<use>, or C<no>. These are locally scoped, so an inner BLOCK
275 may countermand any of these by saying
280 which lasts until the end of that BLOCK.
282 The following programs are defined (and have their own documentation).
288 Pragma to produce enhanced diagnostics
292 Pragma to compute arithmetic in integer instead of double
296 Pragma to request less of something from the compiler
300 Pragma to enable stack backtrace on unexpected signals
304 Pragma to restrict unsafe constructs
308 Pragma to predeclare sub names
312 =head2 Standard Modules
314 Standard, bundled modules are all expected to behave in a well-defined
315 manner with respect to namespace pollution because they use the
316 Exporter module. See their own documentation for details.
318 To find out all the modules installed on your system, do this:
320 find `perl -e 'print "@INC"'` -name '*.pm' -print
322 They should all have their own documentation installed and accessible via
323 your system man(1) command. If that fails, try the I<perldoc> program.
325 =head2 Extension Modules
327 Extension modules are written in C (or a mix of Perl and C) and get
328 dynamically loaded into Perl if and when you need them. Supported
329 extension modules include the Socket, Fcntl, and POSIX modules.
331 Many popular C extension modules
332 do not come bundled (at least, not completely)
333 due to their size, volatility, or simply lack of time for adequate testing
334 and configuration across the multitude of platforms on which Perl was
335 beta-tested. You are encouraged to look for them in archie(1L), the Perl
336 FAQ or Meta-FAQ, the WWW page, and even with their authors before randomly
337 posting asking for their present condition and disposition.
341 CPAN stands for the Comprehensive Perl Archive Network. This is a globally
342 replicated collection of all known Perl materials, including hundreds
343 of unbunded modules. Here are the major categories of modules:
348 Language Extensions and Documentation Tools
354 Operating System Interfaces
357 Networking, Device Control (modems) and InterProcess Communication
360 Data Types and Data Type Utilities
369 Interfaces to / Emulations of Other Programming Languages
372 File Names, File Systems and File Locking (see also File Handles)
375 String Processing, Language Text Processing, Parsing and Searching
378 Option, Argument, Parameter and Configuration File Processing
381 Internationalization and Locale
384 Authentication, Security and Encryption
387 World Wide Web, HTML, HTTP, CGI, MIME
390 Server and Daemon Utilities
393 Archiving and Compression
396 Images, Pixmap and Bitmap Manipulation, Drawing and Graphing
402 Control Flow Utilities (callbacks and exceptions etc)
405 File Handle and Input/Output Stream Utilities
408 Miscellaneous Modules
412 Some of the reguster CPAN sites as of this writing include the following.
413 You should try to choose one close to you:
418 ftp://ftp.sterling.com/programming/languages/perl/
421 ftp://ftp.sedl.org/pub/mirrors/CPAN/
424 ftp://ftp.uoknor.edu/mirrors/CPAN/
427 ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/
430 ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/
433 ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
436 ftp://ftp.switch.ch/mirror/CPAN/
439 ftp://ftp.sunet.se/pub/lang/perl/CPAN/
442 ftp://ftp.ci.uminho.pt/pub/lang/perl/
445 ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
448 ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
451 ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/
454 ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/
457 ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
460 ftp://ftp.ibp.fr/pub/perl/CPAN/
463 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
466 ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/
469 ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/
472 ftp://coombs.anu.edu.au/pub/perl/
475 ftp://dongpo.math.ncu.edu.tw/perl/CPAN/
478 ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
481 ftp://ftp.is.co.za/programming/perl/CPAN/
485 For an up-to-date listing of CPAN sites,
486 see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/.