Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | perlmod - Perl modules (packages) | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | =head2 Packages | |
8 | ||
748a9306 LW |
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 | |
a0d0e21e LW |
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>. | |
24 | ||
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.) | |
29 | ||
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. | |
36 | ||
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>. | |
748a9306 | 39 | In addition, the identifiers STDIN, STDOUT, STDERR, ARGV, |
a0d0e21e LW |
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 | |
748a9306 | 43 | the qualified form of an identifier because it will be interpreted instead |
a0d0e21e LW |
44 | as a pattern match, a substitution, or a translation. |
45 | ||
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.) | |
49 | ||
50 | Eval()ed strings are compiled in the package in which the eval() was | |
51 | compiled. (Assignments to C<$SIG{}>, however, assume the signal | |
748a9306 | 52 | handler specified is in the C<main> package. Qualify the signal handler |
a0d0e21e LW |
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>. | |
60 | ||
61 | =head2 Symbol Tables | |
62 | ||
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::>. | |
67 | ||
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: | |
72 | ||
73 | local(*main::foo) = *main::bar; local($main::{'foo'}) = | |
74 | $main::{'bar'}; | |
75 | ||
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: | |
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 | ||
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>. | |
110 | ||
111 | Assignment to a symbol table entry performs an aliasing operation, | |
112 | i.e., | |
113 | ||
114 | *dick = *richard; | |
115 | ||
748a9306 | 116 | causes variables, subroutines and file handles accessible via the |
a0d0e21e LW |
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: | |
120 | ||
121 | *dick = \$richard; | |
122 | ||
123 | makes $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 | ||
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. | |
131 | ||
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 | |
138 | file. | |
139 | ||
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 | |
748a9306 | 144 | multiple C<END> blocks within a file--they will execute in reverse |
a0d0e21e LW |
145 | order of definition; that is: last in, first out (LIFO). |
146 | ||
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. | |
149 | ||
150 | =head2 Perl Classes | |
151 | ||
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>. | |
157 | ||
158 | =head2 Perl Modules | |
159 | ||
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. | |
168 | ||
169 | Perl modules are included by saying | |
170 | ||
171 | use Module; | |
172 | ||
173 | or | |
174 | ||
175 | use Module LIST; | |
176 | ||
177 | This is exactly equivalent to | |
178 | ||
179 | BEGIN { require "Module.pm"; import Module; } | |
180 | ||
181 | or | |
182 | ||
183 | BEGIN { require "Module.pm"; import Module LIST; } | |
184 | ||
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). | |
191 | ||
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: | |
201 | ||
202 | require Cwd; # make Cwd:: accessible | |
203 | $here = Cwd::getcwd(); | |
204 | ||
205 | use Cwd; # import names from Cwd:: | |
206 | $here = getcwd(); | |
207 | ||
208 | require Cwd; # make Cwd:: accessible | |
209 | $here = getcwd(); # oops! no main::getcwd() | |
210 | ||
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>. | |
217 | ||
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. | |
225 | ||
8e07c86e | 226 | For more information on writing extension modules, see L<perlxs> |
a0d0e21e LW |
227 | and L<perlguts>. |
228 | ||
229 | =head1 NOTE | |
230 | ||
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. | |
236 | ||
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. | |
243 | ||
244 | =head1 THE PERL MODULE LIBRARY | |
245 | ||
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 | |
748a9306 | 249 | libraries supplied so that old programs that use them still run. The |
a0d0e21e LW |
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. | |
255 | ||
256 | =head2 Pragmatic Modules | |
257 | ||
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 | |
748a9306 | 260 | C<use>, or C<no>. These are locally scoped, so an inner BLOCK |
a0d0e21e LW |
261 | may countermand any of these by saying |
262 | ||
263 | no integer; | |
264 | no strict 'refs'; | |
265 | ||
266 | which lasts until the end of that BLOCK. | |
267 | ||
268 | The following programs are defined (and have their own documentation). | |
269 | ||
270 | =over 12 | |
271 | ||
272 | =item C<integer> | |
273 | ||
274 | Perl pragma to compute arithmetic in integer instead of double | |
275 | ||
276 | =item C<less> | |
277 | ||
278 | Perl pragma to request less of something from the compiler | |
279 | ||
280 | =item C<sigtrap> | |
281 | ||
282 | Perl pragma to enable stack backtrace on unexpected signals | |
283 | ||
284 | =item C<strict> | |
285 | ||
286 | Perl pragma to restrict unsafe constructs | |
287 | ||
288 | =item C<subs> | |
289 | ||
290 | Perl pragma to predeclare sub names | |
291 | ||
292 | =back | |
293 | ||
294 | =head2 Standard Modules | |
295 | ||
748a9306 | 296 | The following modules are all expected to behave in a well-defined |
a0d0e21e LW |
297 | manner with respect to namespace pollution because they use the |
298 | Exporter module. | |
299 | See their own documentation for details. | |
300 | ||
301 | =over 12 | |
302 | ||
303 | =item C<Abbrev> | |
304 | ||
305 | create an abbreviation table from a list | |
306 | ||
307 | =item C<AnyDBM_File> | |
308 | ||
309 | provide framework for multiple DBMs | |
310 | ||
311 | =item C<AutoLoader> | |
312 | ||
313 | load functions only on demand | |
314 | ||
315 | =item C<AutoSplit> | |
316 | ||
317 | split a package for autoloading | |
318 | ||
319 | =item C<Basename> | |
320 | ||
748a9306 | 321 | parse file name and path from a specification |
a0d0e21e LW |
322 | |
323 | =item C<Benchmark> | |
324 | ||
325 | benchmark running times of code | |
326 | ||
327 | =item C<Carp> | |
328 | ||
329 | warn or die of errors (from perspective of caller) | |
330 | ||
331 | =item C<CheckTree> | |
332 | ||
333 | run many filetest checks on a tree | |
334 | ||
335 | =item C<Collate> | |
336 | ||
337 | compare 8-bit scalar data according to the current locale | |
338 | ||
339 | =item C<Config> | |
340 | ||
341 | access Perl configuration option | |
342 | ||
343 | =item C<Cwd> | |
344 | ||
345 | get pathname of current working directory | |
346 | ||
347 | =item C<DynaLoader> | |
348 | ||
349 | Dynamically load C libraries into Perl code | |
350 | ||
351 | =item C<English> | |
352 | ||
353 | use nice English (or B<awk>) names for ugly punctuation variables | |
354 | ||
355 | =item C<Env> | |
356 | ||
357 | Perl module that imports environment variables | |
358 | ||
359 | =item C<Exporter> | |
360 | ||
361 | module to control namespace manipulations | |
362 | ||
363 | =item C<Fcntl> | |
364 | ||
365 | load the C Fcntl.h defines | |
366 | ||
367 | =item C<FileHandle> | |
368 | ||
369 | supply object methods for filehandles | |
370 | ||
371 | =item C<Find> | |
372 | ||
373 | traverse a file tree | |
374 | ||
375 | =item C<Finddepth> | |
376 | ||
377 | traverse a directory structure depth-first | |
378 | ||
379 | =item C<Getopt> | |
380 | ||
381 | basic and extended getopt(3) processing | |
382 | ||
383 | =item C<MakeMaker> | |
384 | ||
385 | generate a Makefile for Perl extension | |
386 | ||
387 | =item C<Open2> | |
388 | ||
389 | open a process for both reading and writing | |
390 | ||
391 | =item C<Open3> | |
392 | ||
393 | open a process for reading, writing, and error handling | |
394 | ||
395 | =item C<POSIX> | |
396 | ||
397 | Perl interface to IEEE 1003.1 namespace | |
398 | ||
399 | =item C<Ping> | |
400 | ||
401 | check a host for upness | |
402 | ||
403 | =item C<Socket> | |
404 | ||
405 | load the C socket.h defines | |
406 | ||
407 | =back | |
408 | ||
409 | =head2 Extension Modules | |
410 | ||
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. | |
414 | ||
415 | The following are popular C extension modules, which while available at | |
748a9306 | 416 | Perl 5.0 release time, do not come bundled (at least, not completely) |
a0d0e21e LW |
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 | |
748a9306 | 420 | FAQ or Meta-FAQ, the WWW page, and even with their authors before randomly |
a0d0e21e LW |
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! | |
424 | ||
425 | =over 12 | |
426 | ||
427 | =item C<Curses> | |
428 | ||
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 | |
432 | ||
433 | ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz | |
434 | ||
435 | It is currently in alpha test, so the name and ftp location may | |
436 | change. | |
437 | ||
438 | ||
439 | =item C<DBI> | |
440 | ||
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. | |
447 | ||
448 | =item C<DB_File> | |
449 | ||
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 | |
454 | where. | |
455 | ||
456 | =item C<Sx> | |
457 | ||
458 | This extension module is a front to the Athena and Xlib libraries for Perl | |
748a9306 | 459 | GUI programming, originally written by by Dominic Giampaolo |
a0d0e21e LW |
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 | |
462 | ||
463 | ftp.pasteur.fr:/pub/Perl/Sx.tar.gz | |
464 | ||
465 | =item C<Tk> | |
466 | ||
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. | |
473 | ||
474 | =back |