This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[dummy merge]
[perl5.git] / pod / perlmod.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlmod - Perl modules (packages)
4
5=head1 DESCRIPTION
6
7=head2 Packages
8
748a9306 9Perl provides a mechanism for alternative namespaces to protect packages
d0c42abe 10from stomping on each other's variables. In fact, apart from certain
cb1a09d0
AD
11magical variables, there's really no such thing as a global variable in
12Perl. The package statement declares the compilation unit as being in the
13given namespace. The scope of the package declaration is from the
14declaration itself through the end of the enclosing block (the same scope
15as the local() operator). All further unqualified dynamic identifiers
5f05dabc 16will be in this namespace. A package statement affects only dynamic
cb1a09d0
AD
17variables--including those you've used local() on--but I<not> lexical
18variables created with my(). Typically it would be the first declaration
19in a file to be included by the C<require> or C<use> operator. You can
5f05dabc 20switch into a package in more than one place; it influences merely which
a0d0e21e
LW
21symbol table is used by the compiler for the rest of that block. You can
22refer to variables and filehandles in other packages by prefixing the
23identifier with the package name and a double colon:
24C<$Package::Variable>. If the package name is null, the C<main> package
d0c42abe 25is assumed. That is, C<$::sail> is equivalent to C<$main::sail>.
a0d0e21e
LW
26
27(The old package delimiter was a single quote, but double colon
28is now the preferred delimiter, in part because it's more readable
29to humans, and in part because it's more readable to B<emacs> macros.
30It also makes C++ programmers feel like they know what's going on.)
31
32Packages may be nested inside other packages: C<$OUTER::INNER::var>. This
33implies nothing about the order of name lookups, however. All symbols
34are either local to the current package, or must be fully qualified
35from the outer package name down. For instance, there is nowhere
36within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>.
37It would treat package C<INNER> as a totally separate global package.
38
39Only identifiers starting with letters (or underscore) are stored in a
cb1a09d0
AD
40package's symbol table. All other symbols are kept in package C<main>,
41including all of the punctuation variables like $_. In addition, the
5f05dabc 42identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC, and SIG are
cb1a09d0
AD
43forced to be in package C<main>, even when used for other purposes than
44their built-in one. Note also that, if you have a package called C<m>,
5f05dabc 45C<s>, or C<y>, then you can't use the qualified form of an identifier
cb1a09d0
AD
46because it will be interpreted instead as a pattern match, a substitution,
47or a translation.
a0d0e21e
LW
48
49(Variables beginning with underscore used to be forced into package
50main, but we decided it was more useful for package writers to be able
cb1a09d0
AD
51to use leading underscore to indicate private variables and method names.
52$_ is still global though.)
a0d0e21e
LW
53
54Eval()ed strings are compiled in the package in which the eval() was
55compiled. (Assignments to C<$SIG{}>, however, assume the signal
748a9306 56handler specified is in the C<main> package. Qualify the signal handler
a0d0e21e
LW
57name if you wish to have a signal handler in a package.) For an
58example, examine F<perldb.pl> in the Perl library. It initially switches
59to the C<DB> package so that the debugger doesn't interfere with variables
60in the script you are trying to debug. At various points, however, it
61temporarily switches back to the C<main> package to evaluate various
62expressions in the context of the C<main> package (or wherever you came
63from). See L<perldebug>.
64
5f05dabc 65See L<perlsub> for other scoping issues related to my() and local(),
cb1a09d0
AD
66or L<perlref> regarding closures.
67
a0d0e21e
LW
68=head2 Symbol Tables
69
aa689395
PP
70The symbol table for a package happens to be stored in the hash of that
71name with two colons appended. The main symbol table's name is thus
72C<%main::>, or C<%::> for short. Likewise symbol table for the nested
73package mentioned earlier is named C<%OUTER::INNER::>.
74
75The value in each entry of the hash is what you are referring to when you
76use the C<*name> typeglob notation. In fact, the following have the same
77effect, though the first is more efficient because it does the symbol
78table lookups at compile time:
a0d0e21e
LW
79
80 local(*main::foo) = *main::bar; local($main::{'foo'}) =
81 $main::{'bar'};
82
83You can use this to print out all the variables in a package, for
84instance. Here is F<dumpvar.pl> from the Perl library:
85
86 package dumpvar;
87 sub main::dumpvar {
88 ($package) = @_;
89 local(*stab) = eval("*${package}::");
90 while (($key,$val) = each(%stab)) {
91 local(*entry) = $val;
92 if (defined $entry) {
93 print "\$$key = '$entry'\n";
94 }
95
96 if (defined @entry) {
97 print "\@$key = (\n";
98 foreach $num ($[ .. $#entry) {
99 print " $num\t'",$entry[$num],"'\n";
100 }
101 print ")\n";
102 }
103
104 if ($key ne "${package}::" && defined %entry) {
105 print "\%$key = (\n";
106 foreach $key (sort keys(%entry)) {
107 print " $key\t'",$entry{$key},"'\n";
108 }
109 print ")\n";
110 }
111 }
112 }
113
114Note that even though the subroutine is compiled in package C<dumpvar>,
115the name of the subroutine is qualified so that its name is inserted
116into package C<main>.
117
cb1a09d0 118Assignment to a typeglob performs an aliasing operation, i.e.,
a0d0e21e
LW
119
120 *dick = *richard;
121
5f05dabc 122causes variables, subroutines, and file handles accessible via the
d0c42abe 123identifier C<richard> to also be accessible via the identifier C<dick>. If
5f05dabc 124you want to alias only a particular variable or subroutine, you can
a0d0e21e
LW
125assign a reference instead:
126
127 *dick = \$richard;
128
129makes $richard and $dick the same variable, but leaves
130@richard and @dick as separate arrays. Tricky, eh?
131
cb1a09d0
AD
132This mechanism may be used to pass and return cheap references
133into or from subroutines if you won't want to copy the whole
134thing.
135
136 %some_hash = ();
137 *some_hash = fn( \%another_hash );
138 sub fn {
139 local *hashsym = shift;
140 # now use %hashsym normally, and you
141 # will affect the caller's %another_hash
142 my %nhash = (); # do what you want
5f05dabc 143 return \%nhash;
cb1a09d0
AD
144 }
145
5f05dabc 146On return, the reference will overwrite the hash slot in the
cb1a09d0 147symbol table specified by the *some_hash typeglob. This
c36e9b62 148is a somewhat tricky way of passing around references cheaply
cb1a09d0
AD
149when you won't want to have to remember to dereference variables
150explicitly.
151
152Another use of symbol tables is for making "constant" scalars.
153
154 *PI = \3.14159265358979;
155
156Now you cannot alter $PI, which is probably a good thing all in all.
157
55497cff
PP
158You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and
159package the *foo symbol table entry comes from. This may be useful
160in a subroutine which is passed typeglobs as arguments
161
162 sub identify_typeglob {
163 my $glob = shift;
164 print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
165 }
166 identify_typeglob *foo;
167 identify_typeglob *bar::baz;
168
169This prints
170
171 You gave me main::foo
172 You gave me bar::baz
173
174The *foo{THING} notation can also be used to obtain references to the
175individual elements of *foo, see L<perlref>.
176
a0d0e21e
LW
177=head2 Package Constructors and Destructors
178
179There are two special subroutine definitions that function as package
180constructors and destructors. These are the C<BEGIN> and C<END>
181routines. The C<sub> is optional for these routines.
182
183A C<BEGIN> subroutine is executed as soon as possible, that is, the
184moment it is completely defined, even before the rest of the containing
185file is parsed. You may have multiple C<BEGIN> blocks within a
186file--they will execute in order of definition. Because a C<BEGIN>
187block executes immediately, it can pull in definitions of subroutines
188and such from other files in time to be visible to the rest of the
189file.
190
191An C<END> subroutine is executed as late as possible, that is, when the
192interpreter is being exited, even if it is exiting as a result of a
193die() function. (But not if it's is being blown out of the water by a
194signal--you have to trap that yourself (if you can).) You may have
748a9306 195multiple C<END> blocks within a file--they will execute in reverse
a0d0e21e
LW
196order of definition; that is: last in, first out (LIFO).
197
c36e9b62
PP
198Inside an C<END> subroutine C<$?> contains the value that the script is
199going to pass to C<exit()>. You can modify C<$?> to change the exit
5f05dabc 200value of the script. Beware of changing C<$?> by accident (e.g.,, by
c36e9b62
PP
201running something via C<system>).
202
a0d0e21e
LW
203Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN>
204and C<END> work just as they do in B<awk>, as a degenerate case.
205
206=head2 Perl Classes
207
4633a7c4 208There is no special class syntax in Perl, but a package may function
a0d0e21e
LW
209as a class if it provides subroutines that function as methods. Such a
210package may also derive some of its methods from another class package
5f05dabc 211by listing the other package name in its @ISA array.
4633a7c4
LW
212
213For more on this, see L<perlobj>.
a0d0e21e
LW
214
215=head2 Perl Modules
216
c07a80fd 217A module is just a package that is defined in a library file of
a0d0e21e
LW
218the same name, and is designed to be reusable. It may do this by
219providing a mechanism for exporting some of its symbols into the symbol
220table of any package using it. Or it may function as a class
221definition and make its semantics available implicitly through method
222calls on the class and its objects, without explicit exportation of any
223symbols. Or it can do a little of both.
224
4633a7c4
LW
225For example, to start a normal module called Fred, create
226a file called Fred.pm and put this at the start of it:
227
5f05dabc
PP
228 package Fred;
229 use strict;
230 use Exporter ();
231 use vars qw(@ISA @EXPORT @EXPORT_OK);
4633a7c4 232 @ISA = qw(Exporter);
5f05dabc
PP
233 @EXPORT = qw(&func1 &func2);
234 @EXPORT_OK = qw($sally @listabob %harry &func3);
235 use vars qw($sally @listabob %harry);
4633a7c4
LW
236
237Then go on to declare and use your variables in functions
238without any qualifications.
5f05dabc 239See L<Exporter> and the I<Perl Modules File> for details on
4633a7c4
LW
240mechanics and style issues in module creation.
241
242Perl modules are included into your program by saying
a0d0e21e
LW
243
244 use Module;
245
246or
247
248 use Module LIST;
249
250This is exactly equivalent to
251
252 BEGIN { require "Module.pm"; import Module; }
253
254or
255
256 BEGIN { require "Module.pm"; import Module LIST; }
257
cb1a09d0
AD
258As a special case
259
260 use Module ();
261
262is exactly equivalent to
263
264 BEGIN { require "Module.pm"; }
265
a0d0e21e
LW
266All Perl module files have the extension F<.pm>. C<use> assumes this so
267that you don't have to spell out "F<Module.pm>" in quotes. This also
268helps to differentiate new modules from old F<.pl> and F<.ph> files.
269Module names are also capitalized unless they're functioning as pragmas,
270"Pragmas" are in effect compiler directives, and are sometimes called
271"pragmatic modules" (or even "pragmata" if you're a classicist).
272
273Because the C<use> statement implies a C<BEGIN> block, the importation
274of semantics happens at the moment the C<use> statement is compiled,
275before the rest of the file is compiled. This is how it is able
276to function as a pragma mechanism, and also how modules are able to
277declare subroutines that are then visible as list operators for
278the rest of the current file. This will not work if you use C<require>
cb1a09d0 279instead of C<use>. With require you can get into this problem:
a0d0e21e
LW
280
281 require Cwd; # make Cwd:: accessible
282 $here = Cwd::getcwd();
283
5f05dabc 284 use Cwd; # import names from Cwd::
a0d0e21e
LW
285 $here = getcwd();
286
287 require Cwd; # make Cwd:: accessible
288 $here = getcwd(); # oops! no main::getcwd()
289
cb1a09d0
AD
290In general C<use Module ();> is recommended over C<require Module;>.
291
a0d0e21e
LW
292Perl packages may be nested inside other package names, so we can have
293package names containing C<::>. But if we used that package name
294directly as a filename it would makes for unwieldy or impossible
295filenames on some systems. Therefore, if a module's name is, say,
296C<Text::Soundex>, then its definition is actually found in the library
297file F<Text/Soundex.pm>.
298
299Perl modules always have a F<.pm> file, but there may also be dynamically
300linked executables or autoloaded subroutine definitions associated with
301the module. If so, these will be entirely transparent to the user of
302the module. It is the responsibility of the F<.pm> file to load (or
303arrange to autoload) any additional functionality. The POSIX module
304happens to do both dynamic loading and autoloading, but the user can
5f05dabc 305say just C<use POSIX> to get it all.
a0d0e21e 306
8e07c86e 307For more information on writing extension modules, see L<perlxs>
a0d0e21e
LW
308and L<perlguts>.
309
310=head1 NOTE
311
312Perl does not enforce private and public parts of its modules as you may
313have been used to in other languages like C++, Ada, or Modula-17. Perl
314doesn't have an infatuation with enforced privacy. It would prefer
315that you stayed out of its living room because you weren't invited, not
316because it has a shotgun.
317
318The module and its user have a contract, part of which is common law,
319and part of which is "written". Part of the common law contract is
320that a module doesn't pollute any namespace it wasn't asked to. The
5f05dabc 321written contract for the module (A.K.A. documentation) may make other
a0d0e21e
LW
322provisions. But then you know when you C<use RedefineTheWorld> that
323you're redefining the world and willing to take the consequences.
324
325=head1 THE PERL MODULE LIBRARY
326
5f05dabc
PP
327A number of modules are included the Perl distribution. These are
328described below, and all end in F<.pm>. You may also discover files in
a0d0e21e 329the library directory that end in either F<.pl> or F<.ph>. These are old
748a9306 330libraries supplied so that old programs that use them still run. The
a0d0e21e
LW
331F<.pl> files will all eventually be converted into standard modules, and
332the F<.ph> files made by B<h2ph> will probably end up as extension modules
333made by B<h2xs>. (Some F<.ph> values may already be available through the
334POSIX module.) The B<pl2pm> file in the distribution may help in your
4fdae800
PP
335conversion, but it's just a mechanical process and therefore far from
336bulletproof.
a0d0e21e
LW
337
338=head2 Pragmatic Modules
339
340They work somewhat like pragmas in that they tend to affect the compilation of
5f05dabc 341your program, and thus will usually work well only when used within a
55497cff
PP
342C<use>, or C<no>. Most of these are locally scoped, so an inner BLOCK
343may countermand any of these by saying:
a0d0e21e
LW
344
345 no integer;
346 no strict 'refs';
347
348which lasts until the end of that BLOCK.
349
5f05dabc 350Unlike the pragmas that effect the C<$^H> hints variable, the C<use
55497cff
PP
351vars> and C<use subs> declarations are not BLOCK-scoped. They allow
352you to pre-declare a variables or subroutines within a particular
4fdae800 353I<file> rather than just a block. Such declarations are effective
55497cff
PP
354for the entire file for which they were declared. You cannot rescind
355them with C<no vars> or C<no subs>.
356
357The following pragmas are defined (and have their own documentation).
a0d0e21e
LW
358
359=over 12
360
5f05dabc
PP
361=item blib
362
363manipulate @INC at compile time to use MakeMaker's uninstalled version
364of a package
365
cb1a09d0 366=item diagnostics
4633a7c4 367
55497cff 368force verbose warning diagnostics
4633a7c4 369
cb1a09d0 370=item integer
a0d0e21e 371
55497cff 372compute arithmetic in integer instead of double
a0d0e21e 373
cb1a09d0 374=item less
a0d0e21e 375
55497cff
PP
376request less of something from the compiler
377
378=item lib
379
380manipulate @INC at compile time
a0d0e21e 381
5f05dabc
PP
382=item locale
383
71be2cbc 384use or ignore current locale for built-in operations (see L<perllocale>)
5f05dabc 385
d0c42abe
PP
386=item ops
387
5f05dabc 388restrict named opcodes when compiling or running Perl code
d0c42abe 389
cb1a09d0
AD
390=item overload
391
5f05dabc 392overload basic Perl operations
cb1a09d0
AD
393
394=item sigtrap
a0d0e21e 395
55497cff 396enable simple signal handling
a0d0e21e 397
cb1a09d0 398=item strict
a0d0e21e 399
55497cff 400restrict unsafe constructs
a0d0e21e 401
cb1a09d0 402=item subs
a0d0e21e 403
5f05dabc 404pre-declare sub names
a0d0e21e 405
ff0cee69
PP
406=item vmsish
407
408adopt certain VMS-specific behaviors
409
d0c42abe
PP
410=item vars
411
5f05dabc 412pre-declare global variable names
d0c42abe 413
a0d0e21e
LW
414=back
415
416=head2 Standard Modules
417
4633a7c4 418Standard, bundled modules are all expected to behave in a well-defined
a0d0e21e 419manner with respect to namespace pollution because they use the
4633a7c4 420Exporter module. See their own documentation for details.
a0d0e21e 421
cb1a09d0
AD
422=over 12
423
424=item AnyDBM_File
425
426provide framework for multiple DBMs
427
428=item AutoLoader
429
430load functions only on demand
431
432=item AutoSplit
433
434split a package for autoloading
435
436=item Benchmark
437
438benchmark running times of code
439
71be2cbc
PP
440=item CPAN
441
442interface to Comprehensive Perl Archive Network
443
444=item CPAN::FirstTime
445
446create a CPAN configuration file
447
448=item CPAN::Nox
449
450run CPAN while avoiding compiled extensions
451
cb1a09d0
AD
452=item Carp
453
454warn of errors (from perspective of caller)
455
5f05dabc
PP
456=item Class::Template
457
458struct/member template builder
459
cb1a09d0
AD
460=item Config
461
55497cff 462access Perl configuration information
cb1a09d0
AD
463
464=item Cwd
465
466get pathname of current working directory
467
468=item DB_File
469
55497cff 470access to Berkeley DB
cb1a09d0
AD
471
472=item Devel::SelfStubber
473
474generate stubs for a SelfLoading module
475
55497cff
PP
476=item DirHandle
477
478supply object methods for directory handles
479
cb1a09d0
AD
480=item DynaLoader
481
5f05dabc 482dynamically load C libraries into Perl code
cb1a09d0
AD
483
484=item English
485
55497cff 486use nice English (or awk) names for ugly punctuation variables
cb1a09d0
AD
487
488=item Env
489
55497cff 490import environment variables
cb1a09d0
AD
491
492=item Exporter
493
55497cff
PP
494implements default import method for modules
495
496=item ExtUtils::Embed
497
5f05dabc 498utilities for embedding Perl in C/C++ applications
55497cff
PP
499
500=item ExtUtils::Install
501
502install files from here to there
cb1a09d0
AD
503
504=item ExtUtils::Liblist
505
506determine libraries to use and how to use them
507
5f05dabc
PP
508=item ExtUtils::MM_OS2
509
510methods to override UN*X behaviour in ExtUtils::MakeMaker
511
512=item ExtUtils::MM_Unix
513
514methods used by ExtUtils::MakeMaker
515
516=item ExtUtils::MM_VMS
517
518methods to override UN*X behaviour in ExtUtils::MakeMaker
519
cb1a09d0
AD
520=item ExtUtils::MakeMaker
521
522create an extension Makefile
523
524=item ExtUtils::Manifest
525
526utilities to write and check a MANIFEST file
527
528=item ExtUtils::Mkbootstrap
529
530make a bootstrap file for use by DynaLoader
531
55497cff
PP
532=item ExtUtils::Mksymlists
533
534write linker options files for dynamic extension
535
5f05dabc 536=item ExtUtils::testlib
55497cff 537
5f05dabc 538add blib/* directories to @INC
55497cff 539
cb1a09d0
AD
540=item Fcntl
541
542load the C Fcntl.h defines
543
544=item File::Basename
545
5f05dabc 546split a pathname into pieces
55497cff 547
cb1a09d0
AD
548=item File::CheckTree
549
550run many filetest checks on a tree
551
5f05dabc
PP
552=item File::Compare
553
554compare files or filehandles
555
55497cff
PP
556=item File::Copy
557
5f05dabc 558copy files or filehandles
55497cff 559
cb1a09d0
AD
560=item File::Find
561
562traverse a file tree
563
cb1a09d0
AD
564=item File::Path
565
566create or remove a series of directories
567
5f05dabc
PP
568=item File::stat
569
570by-name interface to Perl's built-in stat() functions
571
572=item FileCache
573
574keep more files open than the system permits
575
576=item FileHandle
577
578supply object methods for filehandles
579
55497cff
PP
580=item FindBin
581
582locate directory of original perl script
583
584=item GDBM_File
585
5f05dabc 586access to the gdbm library
55497cff 587
cb1a09d0
AD
588=item Getopt::Long
589
55497cff 590extended processing of command line options
cb1a09d0
AD
591
592=item Getopt::Std
593
55497cff 594process single-character switches with switch clustering
cb1a09d0
AD
595
596=item I18N::Collate
597
598compare 8-bit scalar data according to the current locale
599
55497cff
PP
600=item IO
601
602load various IO modules
603
604=item IO::File
605
606supply object methods for filehandles
607
608=item IO::Handle
609
610supply object methods for I/O handles
611
612=item IO::Pipe
613
614supply object methods for pipes
615
616=item IO::Seekable
617
618supply seek based methods for I/O objects
619
620=item IO::Select
621
622OO interface to the select system call
623
624=item IO::Socket
625
626object interface to socket communications
627
cb1a09d0
AD
628=item IPC::Open2
629
55497cff 630open a process for both reading and writing
cb1a09d0
AD
631
632=item IPC::Open3
633
634open a process for reading, writing, and error handling
635
55497cff
PP
636=item Math::BigFloat
637
638arbitrary length float math package
639
640=item Math::BigInt
641
642arbitrary size integer math package
643
644=item Math::Complex
645
646complex numbers and associated mathematical functions
647
648=item NDBM_File
649
650tied access to ndbm files
651
7e1af8bc
PP
652=item Net::Ping
653
654Hello, anybody home?
655
5f05dabc
PP
656=item Net::hostent
657
658by-name interface to Perl's built-in gethost*() functions
659
660=item Net::netent
661
662by-name interface to Perl's built-in getnet*() functions
663
664=item Net::protoent
665
666by-name interface to Perl's built-in getproto*() functions
667
668=item Net::servent
669
670by-name interface to Perl's built-in getserv*() functions
671
55497cff
PP
672=item Opcode
673
5f05dabc 674disable named opcodes when compiling or running perl code
55497cff
PP
675
676=item Pod::Text
677
678convert POD data to formatted ASCII text
679
cb1a09d0
AD
680=item POSIX
681
5f05dabc 682interface to IEEE Standard 1003.1
55497cff
PP
683
684=item SDBM_File
685
686tied access to sdbm files
687
5f05dabc
PP
688=item Safe
689
690compile and execute code in restricted compartments
691
55497cff
PP
692=item Search::Dict
693
694search for key in dictionary file
695
696=item SelectSaver
697
698save and restore selected file handle
cb1a09d0
AD
699
700=item SelfLoader
701
702load functions only on demand
703
55497cff 704=item Shell
a2927560 705
55497cff 706run shell commands transparently within perl
a2927560 707
cb1a09d0
AD
708=item Socket
709
710load the C socket.h defines and structure manipulators
711
55497cff
PP
712=item Symbol
713
714manipulate Perl symbols and their names
715
716=item Sys::Hostname
717
718try every conceivable way to get hostname
719
720=item Sys::Syslog
721
722interface to the UNIX syslog(3) calls
723
724=item Term::Cap
725
5f05dabc 726termcap interface
55497cff
PP
727
728=item Term::Complete
729
730word completion module
731
732=item Term::ReadLine
733
5f05dabc 734interface to various C<readline> packages
55497cff 735
cb1a09d0
AD
736=item Test::Harness
737
738run perl standard test scripts with statistics
739
740=item Text::Abbrev
741
c36e9b62 742create an abbreviation table from a list
cb1a09d0 743
55497cff
PP
744=item Text::ParseWords
745
746parse text into an array of tokens
747
748=item Text::Soundex
749
5f05dabc 750implementation of the Soundex Algorithm as described by Knuth
55497cff
PP
751
752=item Text::Tabs
753
754expand and unexpand tabs per the unix expand(1) and unexpand(1)
755
756=item Text::Wrap
757
758line wrapping to form simple paragraphs
759
760=item Tie::Hash
761
762base class definitions for tied hashes
763
5f05dabc
PP
764=item Tie::RefHash
765
766base class definitions for tied hashes with references as keys
767
55497cff
PP
768=item Tie::Scalar
769
770base class definitions for tied scalars
771
772=item Tie::SubstrHash
773
774fixed-table-size, fixed-key-length hashing
775
776=item Time::Local
777
778efficiently compute time from local and GMT time
779
5f05dabc
PP
780=item Time::gmtime
781
782by-name interface to Perl's built-in gmtime() function
783
784=item Time::localtime
785
786by-name interface to Perl's built-in localtime() function
787
788=item Time::tm
789
790internal object used by Time::gmtime and Time::localtime
791
55497cff
PP
792=item UNIVERSAL
793
794base class for ALL classes (blessed references)
795
5f05dabc
PP
796=item User::grent
797
798by-name interface to Perl's built-in getgr*() functions
799
800=item User::pwent
801
802by-name interface to Perl's built-in getpw*() functions
803
cb1a09d0
AD
804=back
805
806To find out I<all> the modules installed on your system, including
807those without documentation or outside the standard release, do this:
a0d0e21e 808
4633a7c4 809 find `perl -e 'print "@INC"'` -name '*.pm' -print
a0d0e21e 810
4633a7c4
LW
811They should all have their own documentation installed and accessible via
812your system man(1) command. If that fails, try the I<perldoc> program.
a0d0e21e 813
4633a7c4 814=head2 Extension Modules
a0d0e21e 815
4633a7c4
LW
816Extension modules are written in C (or a mix of Perl and C) and get
817dynamically loaded into Perl if and when you need them. Supported
818extension modules include the Socket, Fcntl, and POSIX modules.
a0d0e21e 819
cb1a09d0 820Many popular C extension modules do not come bundled (at least, not
5f05dabc 821completely) due to their sizes, volatility, or simply lack of time for
cb1a09d0
AD
822adequate testing and configuration across the multitude of platforms on
823which Perl was beta-tested. You are encouraged to look for them in
824archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
825authors before randomly posting asking for their present condition and
826disposition.
a0d0e21e 827
cb1a09d0 828=head1 CPAN
a0d0e21e 829
4633a7c4 830CPAN stands for the Comprehensive Perl Archive Network. This is a globally
5f05dabc 831replicated collection of all known Perl materials, including hundreds
c36e9b62 832of unbundled modules. Here are the major categories of modules:
a0d0e21e 833
4633a7c4 834=over
a0d0e21e 835
4633a7c4 836=item *
5f05dabc 837Language Extensions and Documentation Tools
a0d0e21e 838
4633a7c4
LW
839=item *
840Development Support
a0d0e21e 841
4633a7c4
LW
842=item *
843Operating System Interfaces
a0d0e21e 844
4633a7c4
LW
845=item *
846Networking, Device Control (modems) and InterProcess Communication
a0d0e21e 847
4633a7c4
LW
848=item *
849Data Types and Data Type Utilities
a0d0e21e 850
4633a7c4
LW
851=item *
852Database Interfaces
a0d0e21e 853
4633a7c4
LW
854=item *
855User Interfaces
a0d0e21e 856
4633a7c4
LW
857=item *
858Interfaces to / Emulations of Other Programming Languages
a0d0e21e 859
4633a7c4
LW
860=item *
861File Names, File Systems and File Locking (see also File Handles)
a0d0e21e 862
4633a7c4 863=item *
5f05dabc 864String Processing, Language Text Processing, Parsing, and Searching
a0d0e21e 865
4633a7c4 866=item *
5f05dabc 867Option, Argument, Parameter, and Configuration File Processing
a0d0e21e 868
4633a7c4
LW
869=item *
870Internationalization and Locale
a0d0e21e 871
4633a7c4 872=item *
5f05dabc 873Authentication, Security, and Encryption
a0d0e21e 874
4633a7c4
LW
875=item *
876World Wide Web, HTML, HTTP, CGI, MIME
a0d0e21e 877
4633a7c4
LW
878=item *
879Server and Daemon Utilities
a0d0e21e 880
4633a7c4
LW
881=item *
882Archiving and Compression
a0d0e21e 883
4633a7c4 884=item *
5f05dabc 885Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
a0d0e21e 886
4633a7c4
LW
887=item *
888Mail and Usenet News
a0d0e21e 889
4633a7c4
LW
890=item *
891Control Flow Utilities (callbacks and exceptions etc)
a0d0e21e 892
4633a7c4
LW
893=item *
894File Handle and Input/Output Stream Utilities
a0d0e21e 895
4633a7c4
LW
896=item *
897Miscellaneous Modules
a0d0e21e 898
4633a7c4 899=back
a0d0e21e 900
d0c42abe 901The registered CPAN sites as of this writing include the following.
4633a7c4 902You should try to choose one close to you:
a0d0e21e 903
4633a7c4 904=over
a0d0e21e 905
4633a7c4
LW
906=item *
907ftp://ftp.sterling.com/programming/languages/perl/
a0d0e21e 908
4633a7c4
LW
909=item *
910ftp://ftp.sedl.org/pub/mirrors/CPAN/
a0d0e21e 911
4633a7c4
LW
912=item *
913ftp://ftp.uoknor.edu/mirrors/CPAN/
a0d0e21e 914
4633a7c4
LW
915=item *
916ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/
a0d0e21e 917
4633a7c4
LW
918=item *
919ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/
a0d0e21e 920
4633a7c4
LW
921=item *
922ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
a0d0e21e 923
4633a7c4
LW
924=item *
925ftp://ftp.switch.ch/mirror/CPAN/
a0d0e21e 926
4633a7c4
LW
927=item *
928ftp://ftp.sunet.se/pub/lang/perl/CPAN/
a0d0e21e 929
4633a7c4
LW
930=item *
931ftp://ftp.ci.uminho.pt/pub/lang/perl/
a0d0e21e 932
4633a7c4
LW
933=item *
934ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
a0d0e21e 935
4633a7c4
LW
936=item *
937ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
a0d0e21e 938
4633a7c4
LW
939=item *
940ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/
a0d0e21e 941
4633a7c4
LW
942=item *
943ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/
a0d0e21e 944
4633a7c4
LW
945=item *
946ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
a0d0e21e 947
4633a7c4
LW
948=item *
949ftp://ftp.ibp.fr/pub/perl/CPAN/
a0d0e21e 950
4633a7c4
LW
951=item *
952ftp://ftp.funet.fi/pub/languages/perl/CPAN/
a0d0e21e 953
4633a7c4
LW
954=item *
955ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/
a0d0e21e 956
4633a7c4
LW
957=item *
958ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/
a0d0e21e 959
4633a7c4
LW
960=item *
961ftp://coombs.anu.edu.au/pub/perl/
a0d0e21e 962
4633a7c4
LW
963=item *
964ftp://dongpo.math.ncu.edu.tw/perl/CPAN/
a0d0e21e 965
4633a7c4
LW
966=item *
967ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
a0d0e21e 968
4633a7c4
LW
969=item *
970ftp://ftp.is.co.za/programming/perl/CPAN/
a0d0e21e
LW
971
972=back
4633a7c4 973
5f05dabc 974For an up-to-date listing of CPAN sites,
d0c42abe 975see F<http://www.perl.com/perl/CPAN> or F<ftp://ftp.perl.com/perl/>.
cb1a09d0 976
5f05dabc 977=head1 Modules: Creation, Use, and Abuse
cb1a09d0
AD
978
979(The following section is borrowed directly from Tim Bunce's modules
980file, available at your nearest CPAN site.)
981
5f05dabc 982Perl implements a class using a package, but the presence of a
cb1a09d0
AD
983package doesn't imply the presence of a class. A package is just a
984namespace. A class is a package that provides subroutines that can be
985used as methods. A method is just a subroutine that expects, as its
986first argument, either the name of a package (for "static" methods),
987or a reference to something (for "virtual" methods).
988
989A module is a file that (by convention) provides a class of the same
990name (sans the .pm), plus an import method in that class that can be
991called to fetch exported symbols. This module may implement some of
992its methods by loading dynamic C or C++ objects, but that should be
993totally transparent to the user of the module. Likewise, the module
994might set up an AUTOLOAD function to slurp in subroutine definitions on
995demand, but this is also transparent. Only the .pm file is required to
996exist.
997
998=head2 Guidelines for Module Creation
999
1000=over 4
1001
1002=item Do similar modules already exist in some form?
1003
1004If so, please try to reuse the existing modules either in whole or
1005by inheriting useful features into a new class. If this is not
1006practical try to get together with the module authors to work on
1007extending or enhancing the functionality of the existing modules.
1008A perfect example is the plethora of packages in perl4 for dealing
1009with command line options.
1010
1011If you are writing a module to expand an already existing set of
1012modules, please coordinate with the author of the package. It
1013helps if you follow the same naming scheme and module interaction
1014scheme as the original author.
1015
1016=item Try to design the new module to be easy to extend and reuse.
1017
1018Use blessed references. Use the two argument form of bless to bless
1019into the class name given as the first parameter of the constructor,
5f05dabc 1020e.g.,:
cb1a09d0 1021
5f05dabc 1022 sub new {
cb1a09d0
AD
1023 my $class = shift;
1024 return bless {}, $class;
1025 }
1026
1027or even this if you'd like it to be used as either a static
1028or a virtual method.
1029
5f05dabc 1030 sub new {
cb1a09d0
AD
1031 my $self = shift;
1032 my $class = ref($self) || $self;
1033 return bless {}, $class;
1034 }
1035
1036Pass arrays as references so more parameters can be added later
1037(it's also faster). Convert functions into methods where
1038appropriate. Split large methods into smaller more flexible ones.
1039Inherit methods from other modules if appropriate.
1040
c36e9b62
PP
1041Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1042Generally you can delete the "C<eq 'FOO'>" part with no harm at all.
cb1a09d0
AD
1043Let the objects look after themselves! Generally, avoid hardwired
1044class names as far as possible.
1045
c36e9b62
PP
1046Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
1047C<$r-E<gt>func()> would work (see L<perlbot> for more details).
cb1a09d0
AD
1048
1049Use autosplit so little used or newly added functions won't be a
1050burden to programs which don't use them. Add test functions to
1051the module after __END__ either using AutoSplit or by saying:
1052
1053 eval join('',<main::DATA>) || die $@ unless caller();
1054
1055Does your module pass the 'empty sub-class' test? If you say
c36e9b62 1056"C<@SUBCLASS::ISA = qw(YOURCLASS);>" your applications should be able
cb1a09d0 1057to use SUBCLASS in exactly the same way as YOURCLASS. For example,
c36e9b62
PP
1058does your application still work if you change: C<$obj = new YOURCLASS;>
1059into: C<$obj = new SUBCLASS;> ?
cb1a09d0
AD
1060
1061Avoid keeping any state information in your packages. It makes it
1062difficult for multiple other packages to use yours. Keep state
1063information in objects.
1064
c36e9b62 1065Always use B<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
cb1a09d0 1066Remember that you can add C<no strict qw(...);> to individual blocks
c36e9b62 1067of code which need less strictness. Always use B<-w>. Always use B<-w>!
cb1a09d0
AD
1068Follow the guidelines in the perlstyle(1) manual.
1069
1070=item Some simple style guidelines
1071
1072The perlstyle manual supplied with perl has many helpful points.
1073
1074Coding style is a matter of personal taste. Many people evolve their
1075style over several years as they learn what helps them write and
1076maintain good code. Here's one set of assorted suggestions that
1077seem to be widely used by experienced developers:
1078
1079Use underscores to separate words. It is generally easier to read
1080$var_names_like_this than $VarNamesLikeThis, especially for
1081non-native speakers of English. It's also a simple rule that works
1082consistently with VAR_NAMES_LIKE_THIS.
1083
1084Package/Module names are an exception to this rule. Perl informally
1085reserves lowercase module names for 'pragma' modules like integer
1086and strict. Other modules normally begin with a capital letter and
1087use mixed case with no underscores (need to be short and portable).
1088
1089You may find it helpful to use letter case to indicate the scope
1090or nature of a variable. For example:
1091
1092 $ALL_CAPS_HERE constants only (beware clashes with perl vars)
1093 $Some_Caps_Here package-wide global/static
1094 $no_caps_here function scope my() or local() variables
1095
1096Function and method names seem to work best as all lowercase.
5f05dabc 1097e.g.,, C<$obj-E<gt>as_string()>.
cb1a09d0
AD
1098
1099You can use a leading underscore to indicate that a variable or
1100function should not be used outside the package that defined it.
1101
1102=item Select what to export.
1103
1104Do NOT export method names!
1105
1106Do NOT export anything else by default without a good reason!
1107
1108Exports pollute the namespace of the module user. If you must
1109export try to use @EXPORT_OK in preference to @EXPORT and avoid
1110short or common names to reduce the risk of name clashes.
1111
1112Generally anything not exported is still accessible from outside the
c36e9b62 1113module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
cb1a09d0 1114syntax. By convention you can use a leading underscore on names to
5f05dabc 1115indicate informally that they are 'internal' and not for public use.
cb1a09d0
AD
1116
1117(It is actually possible to get private functions by saying:
c36e9b62 1118C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
5f05dabc 1119directly as a method, because a method must have a name in the symbol
cb1a09d0
AD
1120table.)
1121
1122As a general rule, if the module is trying to be object oriented
1123then export nothing. If it's just a collection of functions then
1124@EXPORT_OK anything but use @EXPORT with caution.
1125
1126=item Select a name for the module.
1127
5f05dabc 1128This name should be as descriptive, accurate, and complete as
cb1a09d0
AD
1129possible. Avoid any risk of ambiguity. Always try to use two or
1130more whole words. Generally the name should reflect what is special
1131about what the module does rather than how it does it. Please use
5f05dabc
PP
1132nested module names to group informally or categorize a module.
1133There should be a very good reason for a module not to have a nested name.
cb1a09d0
AD
1134Module names should begin with a capital letter.
1135
1136Having 57 modules all called Sort will not make life easy for anyone
1137(though having 23 called Sort::Quick is only marginally better :-).
1138Imagine someone trying to install your module alongside many others.
1139If in any doubt ask for suggestions in comp.lang.perl.misc.
1140
1141If you are developing a suite of related modules/classes it's good
1142practice to use nested classes with a common prefix as this will
1143avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1144Xyz::Model etc. Use the modules in this list as a naming guide.
1145
1146If adding a new module to a set, follow the original author's
1147standards for naming modules and the interface to methods in
1148those modules.
1149
1150To be portable each component of a module name should be limited to
115111 characters. If it might be used on DOS then try to ensure each is
1152unique in the first 8 characters. Nested modules make this easier.
1153
1154=item Have you got it right?
1155
1156How do you know that you've made the right decisions? Have you
1157picked an interface design that will cause problems later? Have
1158you picked the most appropriate name? Do you have any questions?
1159
1160The best way to know for sure, and pick up many helpful suggestions,
1161is to ask someone who knows. Comp.lang.perl.misc is read by just about
1162all the people who develop modules and it's the best place to ask.
1163
1164All you need to do is post a short summary of the module, its
1165purpose and interfaces. A few lines on each of the main methods is
1166probably enough. (If you post the whole module it might be ignored
1167by busy people - generally the very people you want to read it!)
1168
1169Don't worry about posting if you can't say when the module will be
1170ready - just say so in the message. It might be worth inviting
1171others to help you, they may be able to complete it for you!
1172
1173=item README and other Additional Files.
1174
1175It's well known that software developers usually fully document the
1176software they write. If, however, the world is in urgent need of
1177your software and there is not enough time to write the full
1178documentation please at least provide a README file containing:
1179
1180=over 10
1181
1182=item *
1183A description of the module/package/extension etc.
1184
1185=item *
1186A copyright notice - see below.
1187
1188=item *
1189Prerequisites - what else you may need to have.
1190
1191=item *
1192How to build it - possible changes to Makefile.PL etc.
1193
1194=item *
1195How to install it.
1196
1197=item *
1198Recent changes in this release, especially incompatibilities
1199
1200=item *
1201Changes / enhancements you plan to make in the future.
1202
1203=back
1204
1205If the README file seems to be getting too large you may wish to
1206split out some of the sections into separate files: INSTALL,
1207Copying, ToDo etc.
1208
d0c42abe
PP
1209=over 4
1210
cb1a09d0
AD
1211=item Adding a Copyright Notice.
1212
5f05dabc 1213How you choose to license your work is a personal decision.
cb1a09d0
AD
1214The general mechanism is to assert your Copyright and then make
1215a declaration of how others may copy/use/modify your work.
1216
c36e9b62 1217Perl, for example, is supplied with two types of license: The GNU
5f05dabc 1218GPL and The Artistic License (see the files README, Copying, and
cb1a09d0
AD
1219Artistic). Larry has good reasons for NOT just using the GNU GPL.
1220
5f05dabc
PP
1221My personal recommendation, out of respect for Larry, Perl, and the
1222perl community at large is to state something simply like:
cb1a09d0
AD
1223
1224 Copyright (c) 1995 Your Name. All rights reserved.
1225 This program is free software; you can redistribute it and/or
1226 modify it under the same terms as Perl itself.
1227
1228This statement should at least appear in the README file. You may
1229also wish to include it in a Copying file and your source files.
1230Remember to include the other words in addition to the Copyright.
1231
1232=item Give the module a version/issue/release number.
1233
1234To be fully compatible with the Exporter and MakeMaker modules you
1235should store your module's version number in a non-my package
5f05dabc
PP
1236variable called $VERSION. This should be a floating point
1237number with at least two digits after the decimal (i.e., hundredths,
c36e9b62 1238e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
cb1a09d0
AD
1239See Exporter.pm in Perl5.001m or later for details.
1240
1241It may be handy to add a function or method to retrieve the number.
1242Use the number in announcements and archive file names when
1243releasing the module (ModuleName-1.02.tar.Z).
1244See perldoc ExtUtils::MakeMaker.pm for details.
1245
1246=item How to release and distribute a module.
1247
1248It's good idea to post an announcement of the availability of your
1249module (or the module itself if small) to the comp.lang.perl.announce
1250Usenet newsgroup. This will at least ensure very wide once-off
1251distribution.
1252
1253If possible you should place the module into a major ftp archive and
5f05dabc 1254include details of its location in your announcement.
cb1a09d0
AD
1255
1256Some notes about ftp archives: Please use a long descriptive file
1257name which includes the version number. Most incoming directories
1258will not be readable/listable, i.e., you won't be able to see your
1259file after uploading it. Remember to send your email notification
1260message as soon as possible after uploading else your file may get
1261deleted automatically. Allow time for the file to be processed
1262and/or check the file has been processed before announcing its
1263location.
1264
1265FTP Archives for Perl Modules:
1266
1267Follow the instructions and links on
1268
1269 http://franz.ww.tu-berlin.de/modulelist
1270
5f05dabc 1271or upload to one of these sites:
cb1a09d0
AD
1272
1273 ftp://franz.ww.tu-berlin.de/incoming
5f05dabc 1274 ftp://ftp.cis.ufl.edu/incoming
cb1a09d0
AD
1275
1276and notify upload@franz.ww.tu-berlin.de.
1277
1278By using the WWW interface you can ask the Upload Server to mirror
1279your modules from your ftp or WWW site into your own directory on
1280CPAN!
1281
1282Please remember to send me an updated entry for the Module list!
1283
1284=item Take care when changing a released module.
1285
1286Always strive to remain compatible with previous released versions
1287(see 2.2 above) Otherwise try to add a mechanism to revert to the
1288old behaviour if people rely on it. Document incompatible changes.
1289
1290=back
1291
d0c42abe
PP
1292=back
1293
cb1a09d0
AD
1294=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1295
1296=over 4
1297
1298=item There is no requirement to convert anything.
1299
1300If it ain't broke, don't fix it! Perl 4 library scripts should
1301continue to work with no problems. You may need to make some minor
1302changes (like escaping non-array @'s in double quoted strings) but
1303there is no need to convert a .pl file into a Module for just that.
1304
1305=item Consider the implications.
1306
1307All the perl applications which make use of the script will need to
1308be changed (slightly) if the script is converted into a module. Is
1309it worth it unless you plan to make other changes at the same time?
1310
1311=item Make the most of the opportunity.
1312
1313If you are going to convert the script to a module you can use the
1314opportunity to redesign the interface. The 'Guidelines for Module
1315Creation' above include many of the issues you should consider.
1316
1317=item The pl2pm utility will get you started.
1318
1319This utility will read *.pl files (given as parameters) and write
1320corresponding *.pm files. The pl2pm utilities does the following:
1321
1322=over 10
1323
1324=item *
1325Adds the standard Module prologue lines
1326
1327=item *
1328Converts package specifiers from ' to ::
1329
1330=item *
1331Converts die(...) to croak(...)
1332
1333=item *
1334Several other minor changes
1335
1336=back
1337
1338Being a mechanical process pl2pm is not bullet proof. The converted
1339code will need careful checking, especially any package statements.
1340Don't delete the original .pl file till the new .pm one works!
1341
1342=back
1343
1344=head2 Guidelines for Reusing Application Code
1345
1346=over 4
1347
1348=item Complete applications rarely belong in the Perl Module Library.
1349
1350=item Many applications contain some perl code which could be reused.
1351
1352Help save the world! Share your code in a form that makes it easy
1353to reuse.
1354
1355=item Break-out the reusable code into one or more separate module files.
1356
1357=item Take the opportunity to reconsider and redesign the interfaces.
1358
1359=item In some cases the 'application' can then be reduced to a small
1360
1361fragment of code built on top of the reusable modules. In these cases
1362the application could invoked as:
1363
1364 perl -e 'use Module::Name; method(@ARGV)' ...
5f05dabc 1365or
d0c42abe 1366 perl -mModule::Name ... (in perl5.002)
cb1a09d0
AD
1367
1368=back