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