| 1 | =head1 NAME |
| 2 | |
| 3 | perlmod - Perl modules (packages) |
| 4 | |
| 5 | =head1 DESCRIPTION |
| 6 | |
| 7 | =head2 Packages |
| 8 | |
| 9 | Perl provides a mechanism for alternate namespaces to protect packages |
| 10 | from stomping on each others variables. By default, a Perl script starts |
| 11 | compiling into the package known as C<main>. You can switch namespaces |
| 12 | using the C<package> declaration. The scope of the package declaration is |
| 13 | from the declaration itself to the end of the enclosing block (the same |
| 14 | scope as the local() operator). Typically it would be the first |
| 15 | declaration in a file to be included by the C<require> operator. You can |
| 16 | switch into a package in more than one place; it merely influences which |
| 17 | symbol table is used by the compiler for the rest of that block. You can |
| 18 | refer to variables and filehandles in other packages by prefixing the |
| 19 | identifier with the package name and a double colon: |
| 20 | C<$Package::Variable>. If the package name is null, the C<main> package |
| 21 | as assumed. That is, C<$::sail> is equivalent to C<$main::sail>. |
| 22 | |
| 23 | (The old package delimiter was a single quote, but double colon |
| 24 | is now the preferred delimiter, in part because it's more readable |
| 25 | to humans, and in part because it's more readable to B<emacs> macros. |
| 26 | It also makes C++ programmers feel like they know what's going on.) |
| 27 | |
| 28 | Packages may be nested inside other packages: C<$OUTER::INNER::var>. This |
| 29 | implies nothing about the order of name lookups, however. All symbols |
| 30 | are either local to the current package, or must be fully qualified |
| 31 | from the outer package name down. For instance, there is nowhere |
| 32 | within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>. |
| 33 | It would treat package C<INNER> as a totally separate global package. |
| 34 | |
| 35 | Only identifiers starting with letters (or underscore) are stored in a |
| 36 | package's symbol table. All other symbols are kept in package C<main>. |
| 37 | In addition, the identifiers STDIN, STDOUT, STDERR, C<ARGV>, |
| 38 | ARGVOUT, ENV, INC and SIG are forced to be in package C<main>, |
| 39 | even when used for other purposes than their built-in one. Note also |
| 40 | that, if you have a package called C<m>, C<s> or C<y>, then you can't use |
| 41 | the qualified form of an identifier since it will be interpreted instead |
| 42 | as a pattern match, a substitution, or a translation. |
| 43 | |
| 44 | (Variables beginning with underscore used to be forced into package |
| 45 | main, but we decided it was more useful for package writers to be able |
| 46 | to use leading underscore to indicate private variables and method names.) |
| 47 | |
| 48 | Eval()ed strings are compiled in the package in which the eval() was |
| 49 | compiled. (Assignments to C<$SIG{}>, however, assume the signal |
| 50 | handler specified is in the C<main. package. Qualify the signal handler |
| 51 | name if you wish to have a signal handler in a package.) For an |
| 52 | example, examine F<perldb.pl> in the Perl library. It initially switches |
| 53 | to the C<DB> package so that the debugger doesn't interfere with variables |
| 54 | in the script you are trying to debug. At various points, however, it |
| 55 | temporarily switches back to the C<main> package to evaluate various |
| 56 | expressions in the context of the C<main> package (or wherever you came |
| 57 | from). See L<perldebug>. |
| 58 | |
| 59 | =head2 Symbol Tables |
| 60 | |
| 61 | The symbol table for a package happens to be stored in the associative |
| 62 | array of that name appended with two colons. The main symbol table's |
| 63 | name is thus C<%main::>, or C<%::> for short. Likewise the nested package |
| 64 | mentioned earlier is named C<%OUTER::INNER::>. |
| 65 | |
| 66 | The value in each entry of the associative array is what you are |
| 67 | referring to when you use the C<*name> notation. In fact, the following |
| 68 | have the same effect, though the first is more efficient because it |
| 69 | does the symbol table lookups at compile time: |
| 70 | |
| 71 | local(*main::foo) = *main::bar; local($main::{'foo'}) = |
| 72 | $main::{'bar'}; |
| 73 | |
| 74 | You can use this to print out all the variables in a package, for |
| 75 | instance. Here is F<dumpvar.pl> from the Perl library: |
| 76 | |
| 77 | package dumpvar; |
| 78 | sub main::dumpvar { |
| 79 | ($package) = @_; |
| 80 | local(*stab) = eval("*${package}::"); |
| 81 | while (($key,$val) = each(%stab)) { |
| 82 | local(*entry) = $val; |
| 83 | if (defined $entry) { |
| 84 | print "\$$key = '$entry'\n"; |
| 85 | } |
| 86 | |
| 87 | if (defined @entry) { |
| 88 | print "\@$key = (\n"; |
| 89 | foreach $num ($[ .. $#entry) { |
| 90 | print " $num\t'",$entry[$num],"'\n"; |
| 91 | } |
| 92 | print ")\n"; |
| 93 | } |
| 94 | |
| 95 | if ($key ne "${package}::" && defined %entry) { |
| 96 | print "\%$key = (\n"; |
| 97 | foreach $key (sort keys(%entry)) { |
| 98 | print " $key\t'",$entry{$key},"'\n"; |
| 99 | } |
| 100 | print ")\n"; |
| 101 | } |
| 102 | } |
| 103 | } |
| 104 | |
| 105 | Note that even though the subroutine is compiled in package C<dumpvar>, |
| 106 | the name of the subroutine is qualified so that its name is inserted |
| 107 | into package C<main>. |
| 108 | |
| 109 | Assignment to a symbol table entry performs an aliasing operation, |
| 110 | i.e., |
| 111 | |
| 112 | *dick = *richard; |
| 113 | |
| 114 | causes variables, subroutines and filehandles accessible via the |
| 115 | identifier C<richard> to also be accessible via the symbol C<dick>. If |
| 116 | you only want to alias a particular variable or subroutine, you can |
| 117 | assign a reference instead: |
| 118 | |
| 119 | *dick = \$richard; |
| 120 | |
| 121 | makes $richard and $dick the same variable, but leaves |
| 122 | @richard and @dick as separate arrays. Tricky, eh? |
| 123 | |
| 124 | =head2 Package Constructors and Destructors |
| 125 | |
| 126 | There are two special subroutine definitions that function as package |
| 127 | constructors and destructors. These are the C<BEGIN> and C<END> |
| 128 | routines. The C<sub> is optional for these routines. |
| 129 | |
| 130 | A C<BEGIN> subroutine is executed as soon as possible, that is, the |
| 131 | moment it is completely defined, even before the rest of the containing |
| 132 | file is parsed. You may have multiple C<BEGIN> blocks within a |
| 133 | file--they will execute in order of definition. Because a C<BEGIN> |
| 134 | block executes immediately, it can pull in definitions of subroutines |
| 135 | and such from other files in time to be visible to the rest of the |
| 136 | file. |
| 137 | |
| 138 | An C<END> subroutine is executed as late as possible, that is, when the |
| 139 | interpreter is being exited, even if it is exiting as a result of a |
| 140 | die() function. (But not if it's is being blown out of the water by a |
| 141 | signal--you have to trap that yourself (if you can).) You may have |
| 142 | multiple C<END> blocks within a file--they wil execute in reverse |
| 143 | order of definition; that is: last in, first out (LIFO). |
| 144 | |
| 145 | Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN> |
| 146 | and C<END> work just as they do in B<awk>, as a degenerate case. |
| 147 | |
| 148 | =head2 Perl Classes |
| 149 | |
| 150 | There is no special class syntax in Perl 5, but a package may function |
| 151 | as a class if it provides subroutines that function as methods. Such a |
| 152 | package may also derive some of its methods from another class package |
| 153 | by listing the other package name in its @ISA array. For more on |
| 154 | this, see L<perlobj>. |
| 155 | |
| 156 | =head2 Perl Modules |
| 157 | |
| 158 | In Perl 5, the notion of packages has been extended into the notion of |
| 159 | modules. A module is a package that is defined in a library file of |
| 160 | the same name, and is designed to be reusable. It may do this by |
| 161 | providing a mechanism for exporting some of its symbols into the symbol |
| 162 | table of any package using it. Or it may function as a class |
| 163 | definition and make its semantics available implicitly through method |
| 164 | calls on the class and its objects, without explicit exportation of any |
| 165 | symbols. Or it can do a little of both. |
| 166 | |
| 167 | Perl modules are included by saying |
| 168 | |
| 169 | use Module; |
| 170 | |
| 171 | or |
| 172 | |
| 173 | use Module LIST; |
| 174 | |
| 175 | This is exactly equivalent to |
| 176 | |
| 177 | BEGIN { require "Module.pm"; import Module; } |
| 178 | |
| 179 | or |
| 180 | |
| 181 | BEGIN { require "Module.pm"; import Module LIST; } |
| 182 | |
| 183 | All Perl module files have the extension F<.pm>. C<use> assumes this so |
| 184 | that you don't have to spell out "F<Module.pm>" in quotes. This also |
| 185 | helps to differentiate new modules from old F<.pl> and F<.ph> files. |
| 186 | Module names are also capitalized unless they're functioning as pragmas, |
| 187 | "Pragmas" are in effect compiler directives, and are sometimes called |
| 188 | "pragmatic modules" (or even "pragmata" if you're a classicist). |
| 189 | |
| 190 | Because the C<use> statement implies a C<BEGIN> block, the importation |
| 191 | of semantics happens at the moment the C<use> statement is compiled, |
| 192 | before the rest of the file is compiled. This is how it is able |
| 193 | to function as a pragma mechanism, and also how modules are able to |
| 194 | declare subroutines that are then visible as list operators for |
| 195 | the rest of the current file. This will not work if you use C<require> |
| 196 | instead of C<use>. Therefore, if you're planning on the module altering |
| 197 | your namespace, use C<use>; otherwise, use C<require>. Otherwise you |
| 198 | can get into this problem: |
| 199 | |
| 200 | require Cwd; # make Cwd:: accessible |
| 201 | $here = Cwd::getcwd(); |
| 202 | |
| 203 | use Cwd; # import names from Cwd:: |
| 204 | $here = getcwd(); |
| 205 | |
| 206 | require Cwd; # make Cwd:: accessible |
| 207 | $here = getcwd(); # oops! no main::getcwd() |
| 208 | |
| 209 | Perl packages may be nested inside other package names, so we can have |
| 210 | package names containing C<::>. But if we used that package name |
| 211 | directly as a filename it would makes for unwieldy or impossible |
| 212 | filenames on some systems. Therefore, if a module's name is, say, |
| 213 | C<Text::Soundex>, then its definition is actually found in the library |
| 214 | file F<Text/Soundex.pm>. |
| 215 | |
| 216 | Perl modules always have a F<.pm> file, but there may also be dynamically |
| 217 | linked executables or autoloaded subroutine definitions associated with |
| 218 | the module. If so, these will be entirely transparent to the user of |
| 219 | the module. It is the responsibility of the F<.pm> file to load (or |
| 220 | arrange to autoload) any additional functionality. The POSIX module |
| 221 | happens to do both dynamic loading and autoloading, but the user can |
| 222 | just say C<use POSIX> to get it all. |
| 223 | |
| 224 | For more information on writing extension modules, see L<perlapi> |
| 225 | and L<perlguts>. |
| 226 | |
| 227 | =head1 NOTE |
| 228 | |
| 229 | Perl does not enforce private and public parts of its modules as you may |
| 230 | have been used to in other languages like C++, Ada, or Modula-17. Perl |
| 231 | doesn't have an infatuation with enforced privacy. It would prefer |
| 232 | that you stayed out of its living room because you weren't invited, not |
| 233 | because it has a shotgun. |
| 234 | |
| 235 | The module and its user have a contract, part of which is common law, |
| 236 | and part of which is "written". Part of the common law contract is |
| 237 | that a module doesn't pollute any namespace it wasn't asked to. The |
| 238 | written contract for the module (AKA documentation) may make other |
| 239 | provisions. But then you know when you C<use RedefineTheWorld> that |
| 240 | you're redefining the world and willing to take the consequences. |
| 241 | |
| 242 | =head1 THE PERL MODULE LIBRARY |
| 243 | |
| 244 | A number of modules are included the the Perl distribution. These are |
| 245 | described below, and all end in F<.pm>. You may also discover files in |
| 246 | the library directory that end in either F<.pl> or F<.ph>. These are old |
| 247 | libaries supplied so that old programs that use them still run. The |
| 248 | F<.pl> files will all eventually be converted into standard modules, and |
| 249 | the F<.ph> files made by B<h2ph> will probably end up as extension modules |
| 250 | made by B<h2xs>. (Some F<.ph> values may already be available through the |
| 251 | POSIX module.) The B<pl2pm> file in the distribution may help in your |
| 252 | conversion, but it's just a mechanical process, so is far from bullet proof. |
| 253 | |
| 254 | =head2 Pragmatic Modules |
| 255 | |
| 256 | They work somewhat like pragmas in that they tend to affect the compilation of |
| 257 | your program, and thus will usually only work well when used within a |
| 258 | C<use>, or C<no>. These are locally scoped, so if an inner BLOCK |
| 259 | may countermand any of these by saying |
| 260 | |
| 261 | no integer; |
| 262 | no strict 'refs'; |
| 263 | |
| 264 | which lasts until the end of that BLOCK. |
| 265 | |
| 266 | The following programs are defined (and have their own documentation). |
| 267 | |
| 268 | =over 12 |
| 269 | |
| 270 | =item C<integer> |
| 271 | |
| 272 | Perl pragma to compute arithmetic in integer instead of double |
| 273 | |
| 274 | =item C<less> |
| 275 | |
| 276 | Perl pragma to request less of something from the compiler |
| 277 | |
| 278 | =item C<sigtrap> |
| 279 | |
| 280 | Perl pragma to enable stack backtrace on unexpected signals |
| 281 | |
| 282 | =item C<strict> |
| 283 | |
| 284 | Perl pragma to restrict unsafe constructs |
| 285 | |
| 286 | =item C<subs> |
| 287 | |
| 288 | Perl pragma to predeclare sub names |
| 289 | |
| 290 | =back |
| 291 | |
| 292 | =head2 Standard Modules |
| 293 | |
| 294 | The following modules are all expacted to behave in a well-defined |
| 295 | manner with respect to namespace pollution because they use the |
| 296 | Exporter module. |
| 297 | See their own documentation for details. |
| 298 | |
| 299 | =over 12 |
| 300 | |
| 301 | =item C<Abbrev> |
| 302 | |
| 303 | create an abbreviation table from a list |
| 304 | |
| 305 | =item C<AnyDBM_File> |
| 306 | |
| 307 | provide framework for multiple DBMs |
| 308 | |
| 309 | =item C<AutoLoader> |
| 310 | |
| 311 | load functions only on demand |
| 312 | |
| 313 | =item C<AutoSplit> |
| 314 | |
| 315 | split a package for autoloading |
| 316 | |
| 317 | =item C<Basename> |
| 318 | |
| 319 | parse file anme and path from a specification |
| 320 | |
| 321 | =item C<Benchmark> |
| 322 | |
| 323 | benchmark running times of code |
| 324 | |
| 325 | =item C<Carp> |
| 326 | |
| 327 | warn or die of errors (from perspective of caller) |
| 328 | |
| 329 | =item C<CheckTree> |
| 330 | |
| 331 | run many filetest checks on a tree |
| 332 | |
| 333 | =item C<Collate> |
| 334 | |
| 335 | compare 8-bit scalar data according to the current locale |
| 336 | |
| 337 | =item C<Config> |
| 338 | |
| 339 | access Perl configuration option |
| 340 | |
| 341 | =item C<Cwd> |
| 342 | |
| 343 | get pathname of current working directory |
| 344 | |
| 345 | =item C<DynaLoader> |
| 346 | |
| 347 | Dynamically load C libraries into Perl code |
| 348 | |
| 349 | =item C<English> |
| 350 | |
| 351 | use nice English (or B<awk>) names for ugly punctuation variables |
| 352 | |
| 353 | =item C<Env> |
| 354 | |
| 355 | Perl module that imports environment variables |
| 356 | |
| 357 | =item C<Exporter> |
| 358 | |
| 359 | module to control namespace manipulations |
| 360 | |
| 361 | =item C<Fcntl> |
| 362 | |
| 363 | load the C Fcntl.h defines |
| 364 | |
| 365 | =item C<FileHandle> |
| 366 | |
| 367 | supply object methods for filehandles |
| 368 | |
| 369 | =item C<Find> |
| 370 | |
| 371 | traverse a file tree |
| 372 | |
| 373 | =item C<Finddepth> |
| 374 | |
| 375 | traverse a directory structure depth-first |
| 376 | |
| 377 | =item C<Getopt> |
| 378 | |
| 379 | basic and extended getopt(3) processing |
| 380 | |
| 381 | =item C<MakeMaker> |
| 382 | |
| 383 | generate a Makefile for Perl extension |
| 384 | |
| 385 | =item C<Open2> |
| 386 | |
| 387 | open a process for both reading and writing |
| 388 | |
| 389 | =item C<Open3> |
| 390 | |
| 391 | open a process for reading, writing, and error handling |
| 392 | |
| 393 | =item C<POSIX> |
| 394 | |
| 395 | Perl interface to IEEE 1003.1 namespace |
| 396 | |
| 397 | =item C<Ping> |
| 398 | |
| 399 | check a host for upness |
| 400 | |
| 401 | =item C<Socket> |
| 402 | |
| 403 | load the C socket.h defines |
| 404 | |
| 405 | =back |
| 406 | |
| 407 | =head2 Extension Modules |
| 408 | |
| 409 | Extension modules are written in C (or a mix of Perl and C) and get |
| 410 | dynamically loaded into Perl if and when you need them. Supported |
| 411 | extension modules include the Socket, Fcntl, and POSIX modules. |
| 412 | |
| 413 | The following are popular C extension modules, which while available at |
| 414 | Perl 5.0 release time, do not come not bundled (at least, not completely) |
| 415 | due to their size, volatility, or simply lack of time for adequate testing |
| 416 | and configuration across the multitude of platforms on which Perl was |
| 417 | beta-tested. You are encouraged to look for them in archie(1L), the Perl |
| 418 | FAQ or Meta-FAQ, the WWW page, and even their authors before randomly |
| 419 | posting asking for their present condition and disposition. There's no |
| 420 | guarantee that the names or addresses below have not changed since printing, |
| 421 | and in fact, they probably have! |
| 422 | |
| 423 | =over 12 |
| 424 | |
| 425 | =item C<Curses> |
| 426 | |
| 427 | Written by William Setzer <F<William_Setzer@ncsu.edu>>, while not |
| 428 | included with the standard distribution, this extension module ports to |
| 429 | most systems. FTP from your nearest Perl archive site, or try |
| 430 | |
| 431 | ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz |
| 432 | |
| 433 | It is currently in alpha test, so the name and ftp location may |
| 434 | change. |
| 435 | |
| 436 | |
| 437 | =item C<DBI> |
| 438 | |
| 439 | This is the portable database interface written by |
| 440 | <F<Tim.Bunce@ig.co.uk>>. This supersedes the many perl4 ports for |
| 441 | database extensions. The official archive for DBperl extensions is |
| 442 | F<ftp.demon.co.uk:/pub/perl/db>. This archive contains copies of perl4 |
| 443 | ports for Ingres, Oracle, Sybase, Informix, Unify, Postgres, and |
| 444 | Interbase, as well as rdb and shql and other non-SQL systems. |
| 445 | |
| 446 | =item C<DB_File> |
| 447 | |
| 448 | Fastest and most restriction-free of the DBM bindings, this extension module |
| 449 | uses the popular Berkeley DB to tie() into your hashes. This has a |
| 450 | standardly-distributed man page and dynamic loading extension module, but |
| 451 | you'll have to fetch the Berkeley code yourself. See L<DB_File> for |
| 452 | where. |
| 453 | |
| 454 | =item C<Sx> |
| 455 | |
| 456 | This extension module is a front to the Athena and Xlib libraries for Perl |
| 457 | GUI progamming, originally written by by Dominic Giampaolo |
| 458 | <F<dbg@sgi.com>>, then and rewritten for Sx by FrE<eacute>dE<eacute>ric |
| 459 | Chauveau <F<fmc@pasteur.fr>>. It's available for FTP from |
| 460 | |
| 461 | ftp.pasteur.fr:/pub/Perl/Sx.tar.gz |
| 462 | |
| 463 | =item C<Tk> |
| 464 | |
| 465 | This extension module is an object-oriented Perl5 binding to the popular |
| 466 | tcl/tk X11 package. However, you need know no TCL to use it! |
| 467 | It was written by Malcolm Beattie <F<mbeattie@sable.ox.ac.uk>>. |
| 468 | If you are unable to locate it using archie(1L) or a similar |
| 469 | tool, you may try retrieving it from F</private/Tk-october.tar.gz> |
| 470 | from Malcolm's machine listed above. |
| 471 | |
| 472 | =back |