Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | perlmod - Perl modules (packages) |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | =head2 Packages |
8 | |
748a9306 |
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 |
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 |
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 |
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 |
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 |
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 |
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 | |
226 | For more information on writing extension modules, see L<perlapi> |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |