This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
major pod update from Tom Christiansen
[perl5.git] / pod / perlmodlib.pod
1 =head1 NAME
2
3 perlmodlib - constructing new Perl modules and finding existing ones
4
5 =head1 DESCRIPTION
6
7 =head1 THE PERL MODULE LIBRARY
8
9 Many modules are included the Perl distribution.  These are described
10 below, and all end in F<.pm>.  You may discover compiled library
11 file (usually ending in F<.so>) or small pieces of modules to be
12 autoloaded (ending in F<.al>); these were automatically generated
13 by the installation process.  You may also discover files in the
14 library directory that end in either F<.pl> or F<.ph>.  These are
15 old libraries supplied so that old programs that use them still
16 run.  The F<.pl> files will all eventually be converted into standard
17 modules, and the F<.ph> files made by B<h2ph> will probably end up
18 as extension modules made by B<h2xs>.  (Some F<.ph> values may
19 already be available through the POSIX, Errno, or Fcntl modules.)
20 The B<pl2pm> file in the distribution may help in your conversion,
21 but it's just a mechanical process and therefore far from bulletproof.
22
23 =head2 Pragmatic Modules
24
25 They work somewhat like compiler directives (pragmata) in that they
26 tend to affect the compilation of your program, and thus will usually
27 work well only when used within a C<use>, or C<no>.  Most of these
28 are lexically scoped, so an inner BLOCK may countermand them
29 by saying:
30
31     no integer;
32     no strict 'refs';
33
34 which lasts until the end of that BLOCK.
35
36 Some pragmas are lexically scoped--typically those that affect the
37 C<$^H> hints variable.  Others affect the current package instead,
38 like C<use vars> and C<use subs>, whic allow you to predeclare a
39 variables or subroutines within a particular I<file> rather than
40 just a block.  Such declarations are effective for the entire file
41 for which they were declared.  You cannot rescind them with C<no
42 vars> or C<no subs>.
43
44 The following pragmas are defined (and have their own documentation).
45
46 =over 12
47
48 =item attrs
49
50 set/get attributes of a subroutine
51
52 =item autouse
53
54 postpone load of modules until a function is used
55
56 =item base
57
58 Establish IS-A relationship with base class at compile time
59
60 =item blib
61
62 Use MakeMaker's uninstalled version of a package
63
64 =item constant
65
66 declare constants
67
68 =item diagnostics
69
70 Perl compiler pragma to force verbose warning diagnostics
71
72 =item fields
73
74 compile-time class fields
75
76 =item filetest
77
78 control the filetest permission operators
79
80 =item integer
81
82 compute arithmetic in integer instead of double
83
84 =item less
85
86 perl pragma to request less of something from the compiler
87
88 =item lib
89
90 manipulate @INC at compile time
91
92 =item locale
93
94 use and avoid POSIX locales for built-in operations
95
96 =item ops
97
98 restrict unsafe operations when compiling
99
100 =item overload
101
102 Package for overloading perl operations
103
104 =item re
105
106 alter regular expression behavior
107
108 =item sigtrap
109
110 enable simple signal handling
111
112 =item strict
113
114 restrict unsafe constructs
115
116 =item subs
117
118 predeclare sub names
119
120 =item utf8
121
122 turn on UTF-8 and Unicode support
123
124 =item vars
125
126 predeclare global variable names
127
128 =item vmsish
129
130 control VMS-specific language features
131
132 =item warning
133
134 control optional warnings
135
136 =back
137
138 =head2 Standard Modules
139
140 Standard, bundled modules are all expected to behave in a well-defined
141 manner with respect to namespace pollution because they use the
142 Exporter module.  See their own documentation for details.
143
144 =over 12
145
146 =item AnyDBM_File
147
148 provide framework for multiple DBMs
149
150 =item AutoLoader
151
152 load subroutines only on demand
153
154 =item AutoSplit
155
156 split a package for autoloading
157
158 =item B
159
160 The Perl Compiler; See also L<perlcc>.
161
162 =item B::Asmdata
163
164 Autogenerated data about Perl ops, used to generate bytecode
165
166 =item B::Assembler
167
168 Assemble Perl bytecode
169
170 =item B::Bblock
171
172 Walk basic blocks
173
174 =item B::Bytecode
175
176 Perl compiler's bytecode backend
177
178 =item B::C
179
180 Perl compiler's C backend
181
182 =item B::CC
183
184 Perl compiler's optimized C translation backend
185
186 =item B::Debug
187
188 Walk Perl syntax tree, printing debug info about ops
189
190 =item B::Deparse
191
192 Perl compiler backend to produce perl code
193
194 =item B::Disassembler
195
196 Disassemble Perl bytecode
197
198 =item B::Lint
199
200 Perl lint
201
202 =item B::Showlex
203
204 Show lexical variables used in functions or files
205
206 =item B::Stackobj
207
208 Helper module for CC backend
209
210 =item B::Terse
211
212 Walk Perl syntax tree, printing terse info about ops
213
214 =item B::Xref
215
216 Generates cross reference reports for Perl programs
217
218 =item Benchmark
219
220 benchmark running times of code
221
222 =item CGI
223
224 Simple Common Gateway Interface Class
225
226 =item CGI::Apache
227
228 Make things work with CGI.pm against Perl-Apache API
229
230 =item CGI::Carp
231
232 CGI routines for writing to the HTTPD (or other) error log
233
234 =item CGI::Cookie
235
236 Interface to Netscape Cookies
237
238 =item CGI::Fast
239
240 CGI Interface for Fast CGI
241
242 =item CGI::Push
243
244 Simple Interface to Server Push
245
246 =item CGI::Switch
247
248 Try more than one constructors and return the first object available
249
250 =item CPAN
251
252 query, download and build perl modules from CPAN sites
253
254 =item CPAN::FirstTime
255
256 Utility for CPAN::Config file Initialization
257
258 =item CPAN::Nox
259
260 Wrapper around CPAN.pm without using any XS module
261
262 =item Carp
263
264 warn of errors (from perspective of caller)
265
266 =item Class::Struct
267
268 declare struct-like datatypes as Perl classes
269
270 =item Config
271
272 access Perl configuration information
273
274 =item Cwd
275
276 get pathname of current working directory
277
278 =item DB
279
280 programmatic interface to the Perl debugging API 
281
282 =item DB_File
283
284 Perl5 access to Berkeley DB version 1.x
285
286 =item Data::Dumper
287
288 stringified perl data structures, suitable for both printing and C<eval>
289
290 =item Devel::Peek
291
292 A data debugging tool for the XS programmer
293
294 =item Devel::SelfStubber
295
296 generate stubs for a SelfLoading module
297
298 =item DirHandle
299
300 supply object methods for directory handles
301
302 =item Dumpvalue
303
304 provides screen dump of Perl data.
305
306 =item DynaLoader
307
308 Dynamically load C libraries into Perl code
309
310 =item English
311
312 use nice English (or awk) names for ugly punctuation variables
313
314 =item Env
315
316 perl module that imports environment variables
317
318 =item Errno
319
320 System errno constants
321
322 =item Exporter
323
324 Implements default import method for modules
325
326 =item ExtUtils::Command
327
328 utilities to replace common UNIX commands in Makefiles etc.
329
330 =item ExtUtils::Embed
331
332 Utilities for embedding Perl in C/C++ applications
333
334 =item ExtUtils::Install
335
336 install files from here to there
337
338 =item ExtUtils::Installed
339
340 Inventory management of installed modules
341
342 =item ExtUtils::Liblist
343
344 determine libraries to use and how to use them
345
346 =item ExtUtils::MM_OS2
347
348 methods to override UN*X behavior in ExtUtils::MakeMaker
349
350 =item ExtUtils::MM_Unix
351
352 methods used by ExtUtils::MakeMaker
353
354 =item ExtUtils::MM_VMS
355
356 methods to override UN*X behavior in ExtUtils::MakeMaker
357
358 =item ExtUtils::MM_Win32
359
360 methods to override UN*X behavior in ExtUtils::MakeMaker
361
362 =item ExtUtils::MakeMaker
363
364 create an extension Makefile
365
366 =item ExtUtils::Manifest
367
368 utilities to write and check a MANIFEST file
369
370 =item ExtUtils::Miniperl
371
372 write the C code for perlmain.c
373
374 =item ExtUtils::Mkbootstrap
375
376 make a bootstrap file for use by DynaLoader
377
378 =item ExtUtils::Mksymlists
379
380 write linker options files for dynamic extension
381
382 =item ExtUtils::Packlist
383
384 manage .packlist files
385
386 =item ExtUtils::testlib
387
388 add blib/* directories to @INC
389
390 =item Fatal
391
392 replace functions with equivalents which succeed or die
393
394 =item Fcntl
395
396 load the C Fcntl.h defines
397
398 =item File::Basename
399
400 split a pathname into pieces
401
402 =item File::Compare
403
404 Compare files or filehandles
405
406 =item File::Copy
407
408 Copy files or filehandles
409
410 =item File::DosGlob
411
412 DOS like globbing and then some
413
414 =item File::Find
415
416 traverse a file tree
417
418 =item File::Path
419
420 create or remove a series of directories
421
422 =item File::Spec
423
424 portably perform operations on file names
425
426 =item File::Spec::Functions
427
428 portably perform operations on file names
429
430 =item File::Spec::Mac
431
432 File::Spec for MacOS
433
434 =item File::Spec::OS2
435
436 methods for OS/2 file specs
437
438 =item File::Spec::Unix
439
440 methods used by File::Spec
441
442 =item File::Spec::VMS
443
444 methods for VMS file specs
445
446 =item File::Spec::Win32
447
448 methods for Win32 file specs
449
450 =item File::stat
451
452 by-name interface to Perl's built-in stat() functions
453
454 =item FileCache
455
456 keep more files open than the system permits
457
458 =item FileHandle
459
460 supply object methods for filehandles
461
462 =item FindBin
463
464 Locate directory of original perl script
465
466 =item GDBM_File
467
468 Perl5 access to the gdbm library.
469
470 =item Getopt::Long
471
472 extended processing of command line options
473
474 =item Getopt::Std
475
476 Process single-character switches with switch clustering
477
478 =item I18N::Collate
479
480 compare 8-bit scalar data according to the current locale
481
482 =item IO
483
484 load various IO modules
485
486 =item IO::Dir
487
488 supply object methods for directory handles
489
490 =item IO::File
491
492 supply object methods for filehandles
493
494 =item IO::Handle
495
496 supply object methods for I/O handles
497
498 =item IO::Pipe
499
500 supply object methods for pipes
501
502 =item IO::Poll
503
504 Object interface to system poll call
505
506 =item IO::Seekable
507
508 supply seek based methods for I/O objects
509
510 =item IO::Select
511
512 OO interface to the select system call
513
514 =item IO::Socket
515
516 Object interface to socket communications
517
518 =item IO::Socket::INET
519
520 Object interface for AF_INET domain sockets
521
522 =item IO::Socket::UNIX
523
524 Object interface for AF_UNIX domain sockets
525
526 =item IPC::Msg
527
528 SysV Msg IPC object class
529
530 =item IPC::Open2
531
532 open a process for both reading and writing
533
534 =item IPC::Open3
535
536 open a process for reading, writing, and error handling
537
538 =item IPC::Semaphore
539
540 SysV Semaphore IPC object class
541
542 =item IPC::SysV
543
544 SysV IPC constants
545
546 =item Math::BigFloat
547
548 Arbitrary length float math package
549
550 =item Math::BigInt
551
552 Arbitrary size integer math package
553
554 =item Math::Complex
555
556 complex numbers and associated mathematical functions
557
558 =item Math::Trig
559
560 trigonometric functions
561
562 =item NDBM_File
563
564 Tied access to ndbm files
565
566 =item Net::Ping
567
568 check a remote host for reachability
569
570 =item Net::hostent
571
572 by-name interface to Perl's built-in gethost*() functions
573
574 =item Net::netent
575
576 by-name interface to Perl's built-in getnet*() functions
577
578 =item Net::protoent
579
580 by-name interface to Perl's built-in getproto*() functions
581
582 =item Net::servent
583
584 by-name interface to Perl's built-in getserv*() functions
585
586 =item O
587
588 Generic interface to Perl Compiler backends
589
590 =item Opcode
591
592 Disable named opcodes when compiling perl code
593
594 =item POSIX
595
596 Perl interface to IEEE Std 1003.1
597
598 =item Pod::Html
599
600 module to convert pod files to HTML
601
602 =item Pod::Text
603
604 convert POD data to formatted ASCII text
605
606 =item SDBM_File
607
608 Tied access to sdbm files
609
610 =item Safe
611
612 Compile and execute code in restricted compartments
613
614 =item Search::Dict
615
616 search for key in dictionary file
617
618 =item SelectSaver
619
620 save and restore selected file handle
621
622 =item SelfLoader
623
624 load functions only on demand
625
626 =item Shell
627
628 run shell commands transparently within perl
629
630 =item Socket
631
632 load the C socket.h defines and structure manipulators
633
634 =item Symbol
635
636 manipulate Perl symbols and their names
637
638 =item Sys::Hostname
639
640 Try every conceivable way to get hostname
641
642 =item Sys::Syslog
643
644 Perl interface to the UNIX syslog(3) calls
645
646 =item Term::Cap
647
648 Perl termcap interface
649
650 =item Term::Complete
651
652 Perl word completion module
653
654 =item Term::ReadLine
655
656 Perl interface to various C<readline> packages. 
657
658 =item Test
659
660 provides a simple framework for writing test scripts
661
662 =item Test::Harness
663
664 run perl standard test scripts with statistics
665
666 =item Text::Abbrev
667
668 create an abbreviation table from a list
669
670 =item Text::ParseWords
671
672 parse text into an array of tokens or array of arrays
673
674 =item Text::Soundex
675
676 Implementation of the Soundex Algorithm as Described by Knuth
677
678 =item Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1)
679
680 =item Text::Wrap
681
682 line wrapping to form simple paragraphs
683
684 =item Thread 
685
686 multithreading
687
688 =item Thread::Queue 
689
690 thread-safe queues
691
692 =item Thread::Semaphore 
693
694 thread-safe semaphores
695
696 =item Thread::Signal 
697
698 Start a thread which runs signal handlers reliably
699
700 =item Thread::Specific 
701
702 thread-specific keys
703
704 =item Tie::Array
705
706 base class for tied arrays
707
708 =item Tie::Handle
709
710 base class definitions for tied handles
711
712 =item Tie::Hash, Tie::StdHash
713
714 base class definitions for tied hashes
715
716 =item Tie::RefHash
717
718 use references as hash keys
719
720 =item Tie::Scalar, Tie::StdScalar
721
722 base class definitions for tied scalars
723
724 =item Tie::SubstrHash
725
726 Fixed-table-size, fixed-key-length hashing
727
728 =item Time::Local
729
730 efficiently compute time from local and GMT time
731
732 =item Time::gmtime
733
734 by-name interface to Perl's built-in gmtime() function
735
736 =item Time::localtime
737
738 by-name interface to Perl's built-in localtime() function
739
740 =item Time::tm
741
742 internal object used by Time::gmtime and Time::localtime
743
744 =item UNIVERSAL
745
746 base class for ALL classes (blessed references)
747
748 =item User::grent
749
750 by-name interface to Perl's built-in getgr*() functions
751
752 =item User::pwent
753
754 by-name interface to Perl's built-in getpw*() functions
755
756 =back
757
758 To find out I<all> modules installed on your system, including
759 those without documentation or outside the standard release, 
760 jus tdo this:
761
762     % find `perl -e 'print "@INC"'` -name '*.pm' -print
763
764 They should all have their own documentation installed and accessible
765 via your system man(1) command.  If you do not have a B<find>
766 program, you can use the Perl B<find2perl> program instead, which
767 generates Perl code as output you can run through perl.  If you
768 have a B<man> program but it doesn't find your modules, you'll have
769 to fix your manpath.  See L<perl> for details.  If you have no
770 system B<man> command, you might try the B<perldoc> program.
771
772 =head2 Extension Modules
773
774 Extension modules are written in C (or a mix of Perl and C).  They
775 are usually dynamically loaded into Perl if and when you need them,
776 but may also be be linked in statically.  Supported extension modules
777 include Socket, Fcntl, and POSIX.
778
779 Many popular C extension modules do not come bundled (at least, not
780 completely) due to their sizes, volatility, or simply lack of time
781 for adequate testing and configuration across the multitude of
782 platforms on which Perl was beta-tested.  You are encouraged to
783 look for them on CPAN (described below), or using web search engines
784 like Alta Vista or Deja News.
785
786 =head1 CPAN
787
788 CPAN stands for Comprehensive Perl Archive Network; it's a globally
789 replicated trove of Perl materials, including documentation, style
790 guides, tricks and trap, alternate ports to non-Unix systems and
791 occasional binary distributions for these.   Search engines for
792 CPAN can be found at http://cpan.perl.com/ and at
793 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
794
795 Most importantly, CPAN includes around a thousand unbundled modules,
796 some of which require a C compiler to build.  Major categories of
797 modules are:
798
799 =over
800
801 =item *
802 Language Extensions and Documentation Tools
803
804 =item *
805 Development Support
806
807 =item *
808 Operating System Interfaces
809
810 =item *
811 Networking, Device Control (modems) and InterProcess Communication
812
813 =item *
814 Data Types and Data Type Utilities
815
816 =item *
817 Database Interfaces
818
819 =item *
820 User Interfaces
821
822 =item *
823 Interfaces to / Emulations of Other Programming Languages
824
825 =item *
826 File Names, File Systems and File Locking (see also File Handles)
827
828 =item *
829 String Processing, Language Text Processing, Parsing, and Searching
830
831 =item *
832 Option, Argument, Parameter, and Configuration File Processing
833
834 =item *
835 Internationalization and Locale
836
837 =item *
838 Authentication, Security, and Encryption
839
840 =item *
841 World Wide Web, HTML, HTTP, CGI, MIME
842
843 =item *
844 Server and Daemon Utilities
845
846 =item *
847 Archiving and Compression
848
849 =item *
850 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
851
852 =item *
853 Mail and Usenet News
854
855 =item *
856 Control Flow Utilities (callbacks and exceptions etc)
857
858 =item *
859 File Handle and Input/Output Stream Utilities
860
861 =item *
862 Miscellaneous Modules
863
864 =back
865
866 Registered CPAN sites as of this writing include the following.
867 You should try to choose one close to you:
868
869 =over
870
871 =item Africa
872
873    South Africa    ftp://ftp.is.co.za/programming/perl/CPAN/
874                    ftp://ftpza.co.za/pub/mirrors/cpan/
875
876 =item Asia
877
878    China           ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
879    Hong Kong       ftp://ftp.hkstar.com/pub/CPAN/
880    Israel          ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
881    Japan           ftp://ftp.dti.ad.jp/pub/lang/CPAN/
882                    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
883                    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
884                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
885                    ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
886                    ftp://mirror.nucba.ac.jp/mirror/Perl/
887    Singapore       ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
888    South Korea     ftp://ftp.bora.net/pub/CPAN/
889                    ftp://ftp.nuri.net/pub/CPAN/
890    Taiwan          ftp://ftp.wownet.net/pub2/PERL/
891                    ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
892    Thailand        ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
893                    ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
894
895 =item Australasia
896
897    Australia       ftp://cpan.topend.com.au/pub/CPAN/
898                    ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
899                    ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
900                    ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
901    New Zealand     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
902                    ftp://sunsite.net.nz/pub/languages/perl/CPAN/
903
904 Central America
905
906    Costa Rica      ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
907
908 =item Europe
909
910    Austria         ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
911    Belgium         ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
912    Bulgaria        ftp://ftp.ntrl.net/pub/mirrors/CPAN/
913    Croatia         ftp://ftp.linux.hr/pub/CPAN/
914    Czech Republic  ftp://ftp.fi.muni.cz/pub/perl/
915                    ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
916    Denmark         ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
917    Estonia         ftp://ftp.ut.ee/pub/languages/perl/CPAN/
918    Finland         ftp://ftp.funet.fi/pub/languages/perl/CPAN/
919    France          ftp://ftp.lip6.fr/pub/perl/CPAN/
920                    ftp://ftp.oleane.net/pub/mirrors/CPAN/
921                    ftp://ftp.pasteur.fr/pub/computing/CPAN/
922    Germany         ftp://ftp.archive.de.uu.net/pub/CPAN/
923                    ftp://ftp.gmd.de/packages/CPAN/
924                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
925                    ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/
926                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
927                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
928                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
929                    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
930    Greece          ftp://ftp.ntua.gr/pub/lang/perl/
931    Hungary         ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
932    Ireland         ftp://sunsite.compapp.dcu.ie/pub/perl/
933    Italy           ftp://cis.uniRoma2.it/CPAN/
934                    ftp://ftp.flashnet.it/pub/CPAN/
935                    ftp://ftp.unina.it/pub/Other/CPAN/
936                    ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
937    Netherlands     ftp://ftp.cs.uu.nl/mirror/CPAN/
938                    ftp://ftp.EU.net/packages/cpan/
939                    ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
940    Norway          ftp://ftp.uit.no/pub/languages/perl/cpan/
941                    ftp://sunsite.uio.no/pub/languages/perl/CPAN/
942    Poland          ftp://ftp.man.szczecin.pl/pub/perl/CPAN/
943                    ftp://ftp.man.torun.pl/pub/doc/CPAN/
944                    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
945                    ftp://sunsite.icm.edu.pl/pub/CPAN/
946    Portugal        ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
947                    ftp://ftp.ist.utl.pt/pub/CPAN/
948                    ftp://ftp.ua.pt/pub/CPAN/
949    Romania         ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
950                    ftp://ftp.dnttm.ro/pub/CPAN/
951     Russia         ftp://ftp.chg.ru/pub/lang/perl/CPAN/
952                    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
953    Slovakia        ftp://ftp.entry.sk/pub/languages/perl/CPAN/
954    Slovenia        ftp://ftp.arnes.si/software/perl/CPAN/
955    Spain           ftp://ftp.etse.urv.es/pub/perl/
956                    ftp://ftp.rediris.es/mirror/CPAN/
957    Sweden          ftp://ftp.sunet.se/pub/lang/perl/CPAN/
958    Switzerland     ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
959    Turkey          ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
960    United Kingdom  ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
961                    ftp://ftp.flirble.org/pub/languages/perl/CPAN/
962                    ftp://ftp.plig.org/pub/CPAN/
963                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
964                    ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
965
966 =item North America
967
968    Alberta         ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
969     California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
970                    ftp://ftp.cdrom.com/pub/perl/CPAN/
971                    ftp://ftp.digital.com/pub/plan/perl/CPAN/
972    Colorado        ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
973    Florida         ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
974    Illinois        ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
975    Indiana         ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
976                    ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
977    Manitoba        ftp://theory.uwinnipeg.ca/pub/CPAN/
978    Massachusetts   ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
979                    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
980     Mexico         ftp://ftp.msg.com.mx/pub/CPAN/
981     Minnesota      ftp://ftp.midearthbbs.com/CPAN/
982    New York        ftp://ftp.rge.com/pub/languages/perl/
983    North Carolina  ftp://ftp.duke.edu/pub/perl/
984    Oklahoma        ftp://ftp.ou.edu/mirrors/CPAN/
985     Ontario        ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
986    Oregon          ftp://ftp.orst.edu/pub/packages/CPAN/
987    Pennsylvania    ftp://ftp.epix.net/pub/languages/perl/
988    Texas           ftp://ftp.sedl.org/pub/mirrors/CPAN/
989    Utah            ftp://mirror.xmission.com/CPAN/
990    Virginia        ftp://ftp.perl.org/pub/perl/CPAN/
991                    ftp://ruff.cs.jmu.edu/pub/CPAN/
992     Washington     ftp://ftp-mirror.internap.com/pub/CPAN/
993                    ftp://ftp.spu.edu/pub/CPAN/
994
995 =item South America
996
997    Brazil          ftp://cpan.if.usp.br/pub/mirror/CPAN/
998     Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
999
1000 =back
1001
1002 For an up-to-date listing of CPAN sites,
1003 see http://www.perl.com/perl/CPAN or ftp://www.perl.com/perl/ .
1004
1005 =head1 Modules: Creation, Use, and Abuse
1006
1007 (The following section is borrowed directly from Tim Bunce's modules
1008 file, available at your nearest CPAN site.)
1009
1010 Perl implements a class using a package, but the presence of a
1011 package doesn't imply the presence of a class.  A package is just a
1012 namespace.  A class is a package that provides subroutines that can be
1013 used as methods.  A method is just a subroutine that expects, as its
1014 first argument, either the name of a package (for "static" methods),
1015 or a reference to something (for "virtual" methods).
1016
1017 A module is a file that (by convention) provides a class of the same
1018 name (sans the .pm), plus an import method in that class that can be
1019 called to fetch exported symbols.  This module may implement some of
1020 its methods by loading dynamic C or C++ objects, but that should be
1021 totally transparent to the user of the module.  Likewise, the module
1022 might set up an AUTOLOAD function to slurp in subroutine definitions on
1023 demand, but this is also transparent.  Only the F<.pm> file is required to
1024 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about 
1025 the AUTOLOAD mechanism.
1026
1027 =head2 Guidelines for Module Creation
1028
1029 =over 4
1030
1031 =item Do similar modules already exist in some form?
1032
1033 If so, please try to reuse the existing modules either in whole or
1034 by inheriting useful features into a new class.  If this is not
1035 practical try to get together with the module authors to work on
1036 extending or enhancing the functionality of the existing modules.
1037 A perfect example is the plethora of packages in perl4 for dealing
1038 with command line options.
1039
1040 If you are writing a module to expand an already existing set of
1041 modules, please coordinate with the author of the package.  It
1042 helps if you follow the same naming scheme and module interaction
1043 scheme as the original author.
1044
1045 =item Try to design the new module to be easy to extend and reuse.
1046
1047 Always use B<-w>.  
1048
1049 Use blessed references.  Use the two argument form of bless to bless
1050 into the class name given as the first parameter of the constructor,
1051 e.g.,:
1052
1053  sub new {
1054         my $class = shift;
1055         return bless {}, $class;
1056  }
1057
1058 or even this if you'd like it to be used as either a static
1059 or a virtual method.
1060
1061  sub new {
1062         my $self  = shift;
1063         my $class = ref($self) || $self;
1064         return bless {}, $class;
1065  }
1066
1067 Pass arrays as references so more parameters can be added later
1068 (it's also faster).  Convert functions into methods where
1069 appropriate.  Split large methods into smaller more flexible ones.
1070 Inherit methods from other modules if appropriate.
1071
1072 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1073 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1074 Let the objects look after themselves! Generally, avoid hard-wired
1075 class names as far as possible.
1076
1077 Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
1078 C<$r-E<gt>func()> would work (see L<perlbot> for more details).
1079
1080 Use autosplit so little used or newly added functions won't be a
1081 burden to programs that don't use them. Add test functions to
1082 the module after __END__ either using AutoSplit or by saying:
1083
1084  eval join('',<main::DATA>) || die $@ unless caller();
1085
1086 Does your module pass the 'empty subclass' test? If you say
1087 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1088 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1089 does your application still work if you change:  C<$obj = new YOURCLASS;>
1090 into: C<$obj = new SUBCLASS;> ?
1091
1092 Avoid keeping any state information in your packages. It makes it
1093 difficult for multiple other packages to use yours. Keep state
1094 information in objects.
1095
1096 Always use B<-w>.  
1097
1098 Try to C<use strict;> (or C<use strict qw(...);>).
1099 Remember that you can add C<no strict qw(...);> to individual blocks
1100 of code that need less strictness.  
1101
1102 Always use B<-w>.  
1103
1104 Follow the guidelines in the perlstyle(1) manual.
1105
1106 Always use B<-w>.
1107
1108 =item Some simple style guidelines
1109
1110 The perlstyle manual supplied with Perl has many helpful points.
1111
1112 Coding style is a matter of personal taste. Many people evolve their
1113 style over several years as they learn what helps them write and
1114 maintain good code.  Here's one set of assorted suggestions that
1115 seem to be widely used by experienced developers:
1116
1117 Use underscores to separate words.  It is generally easier to read
1118 $var_names_like_this than $VarNamesLikeThis, especially for
1119 non-native speakers of English. It's also a simple rule that works
1120 consistently with VAR_NAMES_LIKE_THIS.
1121
1122 Package/Module names are an exception to this rule. Perl informally
1123 reserves lowercase module names for 'pragma' modules like integer
1124 and strict. Other modules normally begin with a capital letter and
1125 use mixed case with no underscores (need to be short and portable).
1126
1127 You may find it helpful to use letter case to indicate the scope
1128 or nature of a variable. For example:
1129
1130  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1131  $Some_Caps_Here  package-wide global/static
1132  $no_caps_here    function scope my() or local() variables
1133
1134 Function and method names seem to work best as all lowercase.
1135 e.g., C<$obj-E<gt>as_string()>.
1136
1137 You can use a leading underscore to indicate that a variable or
1138 function should not be used outside the package that defined it.
1139
1140 =item Select what to export.
1141
1142 Do NOT export method names!
1143
1144 Do NOT export anything else by default without a good reason!
1145
1146 Exports pollute the namespace of the module user.  If you must
1147 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1148 short or common names to reduce the risk of name clashes.
1149
1150 Generally anything not exported is still accessible from outside the
1151 module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
1152 syntax.  By convention you can use a leading underscore on names to
1153 indicate informally that they are 'internal' and not for public use.
1154
1155 (It is actually possible to get private functions by saying:
1156 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
1157 directly as a method, because a method must have a name in the symbol
1158 table.)
1159
1160 As a general rule, if the module is trying to be object oriented
1161 then export nothing. If it's just a collection of functions then
1162 @EXPORT_OK anything but use @EXPORT with caution.
1163
1164 =item Select a name for the module.
1165
1166 This name should be as descriptive, accurate, and complete as
1167 possible.  Avoid any risk of ambiguity. Always try to use two or
1168 more whole words.  Generally the name should reflect what is special
1169 about what the module does rather than how it does it.  Please use
1170 nested module names to group informally or categorize a module.
1171 There should be a very good reason for a module not to have a nested name.
1172 Module names should begin with a capital letter.
1173
1174 Having 57 modules all called Sort will not make life easy for anyone
1175 (though having 23 called Sort::Quick is only marginally better :-).
1176 Imagine someone trying to install your module alongside many others.
1177 If in any doubt ask for suggestions in comp.lang.perl.misc.
1178
1179 If you are developing a suite of related modules/classes it's good
1180 practice to use nested classes with a common prefix as this will
1181 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1182 Xyz::Model etc. Use the modules in this list as a naming guide.
1183
1184 If adding a new module to a set, follow the original author's
1185 standards for naming modules and the interface to methods in
1186 those modules.
1187
1188 To be portable each component of a module name should be limited to
1189 11 characters. If it might be used on MS-DOS then try to ensure each is
1190 unique in the first 8 characters. Nested modules make this easier.
1191
1192 =item Have you got it right?
1193
1194 How do you know that you've made the right decisions? Have you
1195 picked an interface design that will cause problems later? Have
1196 you picked the most appropriate name? Do you have any questions?
1197
1198 The best way to know for sure, and pick up many helpful suggestions,
1199 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1200 all the people who develop modules and it's the best place to ask.
1201
1202 All you need to do is post a short summary of the module, its
1203 purpose and interfaces. A few lines on each of the main methods is
1204 probably enough. (If you post the whole module it might be ignored
1205 by busy people - generally the very people you want to read it!)
1206
1207 Don't worry about posting if you can't say when the module will be
1208 ready - just say so in the message. It might be worth inviting
1209 others to help you, they may be able to complete it for you!
1210
1211 =item README and other Additional Files.
1212
1213 It's well known that software developers usually fully document the
1214 software they write. If, however, the world is in urgent need of
1215 your software and there is not enough time to write the full
1216 documentation please at least provide a README file containing:
1217
1218 =over 10
1219
1220 =item *
1221 A description of the module/package/extension etc.
1222
1223 =item *
1224 A copyright notice - see below.
1225
1226 =item *
1227 Prerequisites - what else you may need to have.
1228
1229 =item *
1230 How to build it - possible changes to Makefile.PL etc.
1231
1232 =item *
1233 How to install it.
1234
1235 =item *
1236 Recent changes in this release, especially incompatibilities
1237
1238 =item *
1239 Changes / enhancements you plan to make in the future.
1240
1241 =back
1242
1243 If the README file seems to be getting too large you may wish to
1244 split out some of the sections into separate files: INSTALL,
1245 Copying, ToDo etc.
1246
1247 =over 4
1248
1249 =item Adding a Copyright Notice.
1250
1251 How you choose to license your work is a personal decision.
1252 The general mechanism is to assert your Copyright and then make
1253 a declaration of how others may copy/use/modify your work.
1254
1255 Perl, for example, is supplied with two types of licence: The GNU
1256 GPL and The Artistic Licence (see the files README, Copying, and
1257 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
1258
1259 My personal recommendation, out of respect for Larry, Perl, and the
1260 Perl community at large is to state something simply like:
1261
1262  Copyright (c) 1995 Your Name. All rights reserved.
1263  This program is free software; you can redistribute it and/or
1264  modify it under the same terms as Perl itself.
1265
1266 This statement should at least appear in the README file. You may
1267 also wish to include it in a Copying file and your source files.
1268 Remember to include the other words in addition to the Copyright.
1269
1270 =item Give the module a version/issue/release number.
1271
1272 To be fully compatible with the Exporter and MakeMaker modules you
1273 should store your module's version number in a non-my package
1274 variable called $VERSION.  This should be a floating point
1275 number with at least two digits after the decimal (i.e., hundredths,
1276 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
1277 See L<Exporter> for details.
1278
1279 It may be handy to add a function or method to retrieve the number.
1280 Use the number in announcements and archive file names when
1281 releasing the module (ModuleName-1.02.tar.Z).
1282 See perldoc ExtUtils::MakeMaker.pm for details.
1283
1284 =item How to release and distribute a module.
1285
1286 It's good idea to post an announcement of the availability of your
1287 module (or the module itself if small) to the comp.lang.perl.announce
1288 Usenet newsgroup.  This will at least ensure very wide once-off
1289 distribution.
1290
1291 If possible, register the module with CPAN.  You should 
1292 include details of its location in your announcement.
1293
1294 Some notes about ftp archives: Please use a long descriptive file
1295 name that includes the version number. Most incoming directories
1296 will not be readable/listable, i.e., you won't be able to see your
1297 file after uploading it. Remember to send your email notification
1298 message as soon as possible after uploading else your file may get
1299 deleted automatically. Allow time for the file to be processed
1300 and/or check the file has been processed before announcing its
1301 location.
1302
1303 FTP Archives for Perl Modules:
1304
1305 Follow the instructions and links on
1306
1307    http://franz.ww.tu-berlin.de/modulelist
1308
1309 or upload to one of these sites:
1310
1311    ftp://franz.ww.tu-berlin.de/incoming
1312    ftp://ftp.cis.ufl.edu/incoming
1313
1314 and notify <F<upload@franz.ww.tu-berlin.de>>.
1315
1316 By using the WWW interface you can ask the Upload Server to mirror
1317 your modules from your ftp or WWW site into your own directory on
1318 CPAN!
1319
1320 Please remember to send me an updated entry for the Module list!
1321
1322 =item Take care when changing a released module.
1323
1324 Always strive to remain compatible with previous released versions.
1325 Otherwise try to add a mechanism to revert to the
1326 old behavior if people rely on it.  Document incompatible changes.
1327
1328 =back
1329
1330 =back
1331
1332 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1333
1334 =over 4
1335
1336 =item There is no requirement to convert anything.
1337
1338 If it ain't broke, don't fix it! Perl 4 library scripts should
1339 continue to work with no problems. You may need to make some minor
1340 changes (like escaping non-array @'s in double quoted strings) but
1341 there is no need to convert a .pl file into a Module for just that.
1342
1343 =item Consider the implications.
1344
1345 All Perl applications that make use of the script will need to
1346 be changed (slightly) if the script is converted into a module.  Is
1347 it worth it unless you plan to make other changes at the same time?
1348
1349 =item Make the most of the opportunity.
1350
1351 If you are going to convert the script to a module you can use the
1352 opportunity to redesign the interface.  The guidelines for module
1353 creation above include many of the issues you should consider.
1354
1355 =item The pl2pm utility will get you started.
1356
1357 This utility will read *.pl files (given as parameters) and write
1358 corresponding *.pm files. The pl2pm utilities does the following:
1359
1360 =over 10
1361
1362 =item *
1363 Adds the standard Module prologue lines
1364
1365 =item *
1366 Converts package specifiers from ' to ::
1367
1368 =item *
1369 Converts die(...) to croak(...)
1370
1371 =item *
1372 Several other minor changes
1373
1374 =back
1375
1376 Being a mechanical process pl2pm is not bullet proof. The converted
1377 code will need careful checking, especially any package statements.
1378 Don't delete the original .pl file till the new .pm one works!
1379
1380 =back
1381
1382 =head2 Guidelines for Reusing Application Code
1383
1384 =over 4
1385
1386 =item Complete applications rarely belong in the Perl Module Library.
1387
1388 =item Many applications contain some Perl code that could be reused.
1389
1390 Help save the world! Share your code in a form that makes it easy
1391 to reuse.
1392
1393 =item Break-out the reusable code into one or more separate module files.
1394
1395 =item Take the opportunity to reconsider and redesign the interfaces.
1396
1397 =item In some cases the 'application' can then be reduced to a small
1398
1399 fragment of code built on top of the reusable modules. In these cases
1400 the application could invoked as:
1401
1402      % perl -e 'use Module::Name; method(@ARGV)' ...
1403 or
1404      % perl -mModule::Name ...    (in perl5.002 or higher)
1405
1406 =back
1407
1408 =head1 NOTE
1409
1410 Perl does not enforce private and public parts of its modules as you may
1411 have been used to in other languages like C++, Ada, or Modula-17.  Perl
1412 doesn't have an infatuation with enforced privacy.  It would prefer
1413 that you stayed out of its living room because you weren't invited, not
1414 because it has a shotgun.
1415
1416 The module and its user have a contract, part of which is common law,
1417 and part of which is "written".  Part of the common law contract is
1418 that a module doesn't pollute any namespace it wasn't asked to.  The
1419 written contract for the module (A.K.A. documentation) may make other
1420 provisions.  But then you know when you C<use RedefineTheWorld> that
1421 you're redefining the world and willing to take the consequences.