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