This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Rename warning to warnings, from Paul Marquess.
[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>, whic 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 attrs
50
51 set/get attributes of a subroutine
52
53 =item autouse
54
55 postpone load of modules until a function is used
56
57 =item base
58
59 Establish IS-A relationship with base class at compile time
60
61 =item blib
62
63 Use MakeMaker's uninstalled version of a package
64
65 =item constant
66
67 declare constants
68
69 =item diagnostics
70
71 Perl compiler pragma to force verbose warning diagnostics
72
73 =item fields
74
75 compile-time class fields
76
77 =item filetest
78
79 control the filetest permission operators
80
81 =item integer
82
83 compute arithmetic in integer instead of double
84
85 =item less
86
87 perl pragma to request less of something from the compiler
88
89 =item lib
90
91 manipulate @INC at compile time
92
93 =item locale
94
95 use and avoid POSIX locales for built-in operations
96
97 =item ops
98
99 restrict unsafe operations when compiling
100
101 =item overload
102
103 Package for overloading perl operations
104
105 =item re
106
107 alter regular expression behavior
108
109 =item sigtrap
110
111 enable simple signal handling
112
113 =item strict
114
115 restrict unsafe constructs
116
117 =item subs
118
119 predeclare sub names
120
121 =item utf8
122
123 turn on UTF-8 and Unicode support
124
125 =item vars
126
127 predeclare global variable names
128
129 =item warnings
130
131 control optional warnings
132
133 =item vmsish
134
135 control VMS-specific language features
136
137 =back
138
139 =head2 Standard Modules
140
141 Standard, bundled modules are all expected to behave in a well-defined
142 manner with respect to namespace pollution because they use the
143 Exporter module.  See their own documentation for details.
144
145 =over 12
146
147 =item AnyDBM_File
148
149 provide framework for multiple DBMs
150
151 =item AutoLoader
152
153 load subroutines only on demand
154
155 =item AutoSplit
156
157 split a package for autoloading
158
159 =item B
160
161 The Perl Compiler; See also L<perlcc>.
162
163 =item B::Asmdata
164
165 Autogenerated data about Perl ops, used to generate bytecode
166
167 =item B::Assembler
168
169 Assemble Perl bytecode
170
171 =item B::Bblock
172
173 Walk basic blocks
174
175 =item B::Bytecode
176
177 Perl compiler's bytecode backend
178
179 =item B::C
180
181 Perl compiler's C backend
182
183 =item B::CC
184
185 Perl compiler's optimized C translation backend
186
187 =item B::Debug
188
189 Walk Perl syntax tree, printing debug info about ops
190
191 =item B::Deparse
192
193 Perl compiler backend to produce perl code
194
195 =item B::Disassembler
196
197 Disassemble Perl bytecode
198
199 =item B::Lint
200
201 Perl lint
202
203 =item B::Showlex
204
205 Show lexical variables used in functions or files
206
207 =item B::Stackobj
208
209 Helper module for CC backend
210
211 =item B::Terse
212
213 Walk Perl syntax tree, printing terse info about ops
214
215 =item B::Xref
216
217 Generates cross reference reports for Perl programs
218
219 =item Benchmark
220
221 benchmark running times of code
222
223 =item CGI
224
225 Simple Common Gateway Interface Class
226
227 =item CGI::Apache
228
229 Make things work with CGI.pm against Perl-Apache API
230
231 =item CGI::Carp
232
233 CGI routines for writing to the HTTPD (or other) error log
234
235 =item CGI::Cookie
236
237 Interface to Netscape Cookies
238
239 =item CGI::Fast
240
241 CGI Interface for Fast CGI
242
243 =item CGI::Push
244
245 Simple Interface to Server Push
246
247 =item CGI::Switch
248
249 Try more than one constructors and return the first object available
250
251 =item CPAN
252
253 query, download and build perl modules from CPAN sites
254
255 =item CPAN::FirstTime
256
257 Utility for CPAN::Config file Initialization
258
259 =item CPAN::Nox
260
261 Wrapper around CPAN.pm without using any XS module
262
263 =item Carp
264
265 warn of errors (from perspective of caller)
266
267 =item Class::Struct
268
269 declare struct-like datatypes as Perl classes
270
271 =item Config
272
273 access Perl configuration information
274
275 =item Cwd
276
277 get pathname of current working directory
278
279 =item DB
280
281 programmatic interface to the Perl debugging API 
282
283 =item DB_File
284
285 Perl5 access to Berkeley DB version 1.x
286
287 =item Data::Dumper
288
289 stringified perl data structures, suitable for both printing and C<eval>
290
291 =item Devel::Peek
292
293 A data debugging tool for the XS programmer
294
295 =item Devel::SelfStubber
296
297 generate stubs for a SelfLoading module
298
299 =item DirHandle
300
301 supply object methods for directory handles
302
303 =item Dumpvalue
304
305 provides screen dump of Perl data.
306
307 =item DynaLoader
308
309 Dynamically load C libraries into Perl code
310
311 =item English
312
313 use nice English (or awk) names for ugly punctuation variables
314
315 =item Env
316
317 perl module that imports environment variables
318
319 =item Errno
320
321 System errno constants
322
323 =item Exporter
324
325 Implements default import method for modules
326
327 =item ExtUtils::Command
328
329 utilities to replace common UNIX commands in Makefiles etc.
330
331 =item ExtUtils::Embed
332
333 Utilities for embedding Perl in C/C++ applications
334
335 =item ExtUtils::Install
336
337 install files from here to there
338
339 =item ExtUtils::Installed
340
341 Inventory management of installed modules
342
343 =item ExtUtils::Liblist
344
345 determine libraries to use and how to use them
346
347 =item ExtUtils::MM_OS2
348
349 methods to override UN*X behavior in ExtUtils::MakeMaker
350
351 =item ExtUtils::MM_Unix
352
353 methods used by ExtUtils::MakeMaker
354
355 =item ExtUtils::MM_VMS
356
357 methods to override UN*X behavior in ExtUtils::MakeMaker
358
359 =item ExtUtils::MM_Win32
360
361 methods to override UN*X behavior in ExtUtils::MakeMaker
362
363 =item ExtUtils::MakeMaker
364
365 create an extension Makefile
366
367 =item ExtUtils::Manifest
368
369 utilities to write and check a MANIFEST file
370
371 =item ExtUtils::Miniperl
372
373 write the C code for perlmain.c
374
375 =item ExtUtils::Mkbootstrap
376
377 make a bootstrap file for use by DynaLoader
378
379 =item ExtUtils::Mksymlists
380
381 write linker options files for dynamic extension
382
383 =item ExtUtils::Packlist
384
385 manage .packlist files
386
387 =item ExtUtils::testlib
388
389 add blib/* directories to @INC
390
391 =item Fatal
392
393 replace functions with equivalents which succeed or die
394
395 =item Fcntl
396
397 load the C Fcntl.h defines
398
399 =item File::Basename
400
401 split a pathname into pieces
402
403 =item File::Compare
404
405 Compare files or filehandles
406
407 =item File::Copy
408
409 Copy files or filehandles
410
411 =item File::DosGlob
412
413 DOS like globbing and then some
414
415 =item File::Find
416
417 traverse a file tree
418
419 =item File::Path
420
421 create or remove a series of directories
422
423 =item File::Spec
424
425 portably perform operations on file names
426
427 =item File::Spec::Functions
428
429 portably perform operations on file names
430
431 =item File::Spec::Mac
432
433 File::Spec for MacOS
434
435 =item File::Spec::OS2
436
437 methods for OS/2 file specs
438
439 =item File::Spec::Unix
440
441 methods used by File::Spec
442
443 =item File::Spec::VMS
444
445 methods for VMS file specs
446
447 =item File::Spec::Win32
448
449 methods for Win32 file specs
450
451 =item File::stat
452
453 by-name interface to Perl's built-in stat() functions
454
455 =item FileCache
456
457 keep more files open than the system permits
458
459 =item FileHandle
460
461 supply object methods for filehandles
462
463 =item FindBin
464
465 Locate directory of original perl script
466
467 =item GDBM_File
468
469 Perl5 access to the gdbm library.
470
471 =item Getopt::Long
472
473 extended processing of command line options
474
475 =item Getopt::Std
476
477 Process single-character switches with switch clustering
478
479 =item I18N::Collate
480
481 compare 8-bit scalar data according to the current locale
482
483 =item IO
484
485 load various IO modules
486
487 =item IO::Dir
488
489 supply object methods for directory handles
490
491 =item IO::File
492
493 supply object methods for filehandles
494
495 =item IO::Handle
496
497 supply object methods for I/O handles
498
499 =item IO::Pipe
500
501 supply object methods for pipes
502
503 =item IO::Poll
504
505 Object interface to system poll call
506
507 =item IO::Seekable
508
509 supply seek based methods for I/O objects
510
511 =item IO::Select
512
513 OO interface to the select system call
514
515 =item IO::Socket
516
517 Object interface to socket communications
518
519 =item IO::Socket::INET
520
521 Object interface for AF_INET domain sockets
522
523 =item IO::Socket::UNIX
524
525 Object interface for AF_UNIX domain sockets
526
527 =item IPC::Msg
528
529 SysV Msg IPC object class
530
531 =item IPC::Open2
532
533 open a process for both reading and writing
534
535 =item IPC::Open3
536
537 open a process for reading, writing, and error handling
538
539 =item IPC::Semaphore
540
541 SysV Semaphore IPC object class
542
543 =item IPC::SysV
544
545 SysV IPC constants
546
547 =item Math::BigFloat
548
549 Arbitrary length float math package
550
551 =item Math::BigInt
552
553 Arbitrary size integer math package
554
555 =item Math::Complex
556
557 complex numbers and associated mathematical functions
558
559 =item Math::Trig
560
561 trigonometric functions
562
563 =item NDBM_File
564
565 Tied access to ndbm files
566
567 =item Net::Ping
568
569 check a remote host for reachability
570
571 =item Net::hostent
572
573 by-name interface to Perl's built-in gethost*() functions
574
575 =item Net::netent
576
577 by-name interface to Perl's built-in getnet*() functions
578
579 =item Net::protoent
580
581 by-name interface to Perl's built-in getproto*() functions
582
583 =item Net::servent
584
585 by-name interface to Perl's built-in getserv*() functions
586
587 =item O
588
589 Generic interface to Perl Compiler backends
590
591 =item Opcode
592
593 Disable named opcodes when compiling perl code
594
595 =item POSIX
596
597 Perl interface to IEEE Std 1003.1
598
599 =item Pod::Html
600
601 module to convert pod files to HTML
602
603 =item Pod::Text
604
605 convert POD data to formatted ASCII text
606
607 =item SDBM_File
608
609 Tied access to sdbm files
610
611 =item Safe
612
613 Compile and execute code in restricted compartments
614
615 =item Search::Dict
616
617 search for key in dictionary file
618
619 =item SelectSaver
620
621 save and restore selected file handle
622
623 =item SelfLoader
624
625 load functions only on demand
626
627 =item Shell
628
629 run shell commands transparently within perl
630
631 =item Socket
632
633 load the C socket.h defines and structure manipulators
634
635 =item Symbol
636
637 manipulate Perl symbols and their names
638
639 =item Sys::Hostname
640
641 Try every conceivable way to get hostname
642
643 =item Sys::Syslog
644
645 Perl interface to the UNIX syslog(3) calls
646
647 =item Term::Cap
648
649 Perl termcap interface
650
651 =item Term::Complete
652
653 Perl word completion module
654
655 =item Term::ReadLine
656
657 Perl interface to various C<readline> packages. 
658
659 =item Test
660
661 provides a simple framework for writing test scripts
662
663 =item Test::Harness
664
665 run perl standard test scripts with statistics
666
667 =item Text::Abbrev
668
669 create an abbreviation table from a list
670
671 =item Text::ParseWords
672
673 parse text into an array of tokens or array of arrays
674
675 =item Text::Soundex
676
677 Implementation of the Soundex Algorithm as Described by Knuth
678
679 =item Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1)
680
681 =item Text::Wrap
682
683 line wrapping to form simple paragraphs
684
685 =item Thread 
686
687 multithreading
688
689 =item Thread::Queue 
690
691 thread-safe queues
692
693 =item Thread::Semaphore 
694
695 thread-safe semaphores
696
697 =item Thread::Signal 
698
699 Start a thread which runs signal handlers reliably
700
701 =item Thread::Specific 
702
703 thread-specific keys
704
705 =item Tie::Array
706
707 base class for tied arrays
708
709 =item Tie::Handle
710
711 base class definitions for tied handles
712
713 =item Tie::Hash, Tie::StdHash
714
715 base class definitions for tied hashes
716
717 =item Tie::RefHash
718
719 use references as hash keys
720
721 =item Tie::Scalar, Tie::StdScalar
722
723 base class definitions for tied scalars
724
725 =item Tie::SubstrHash
726
727 Fixed-table-size, fixed-key-length hashing
728
729 =item Time::Local
730
731 efficiently compute time from local and GMT time
732
733 =item Time::gmtime
734
735 by-name interface to Perl's built-in gmtime() function
736
737 =item Time::localtime
738
739 by-name interface to Perl's built-in localtime() function
740
741 =item Time::tm
742
743 internal object used by Time::gmtime and Time::localtime
744
745 =item UNIVERSAL
746
747 base class for ALL classes (blessed references)
748
749 =item User::grent
750
751 by-name interface to Perl's built-in getgr*() functions
752
753 =item User::pwent
754
755 by-name interface to Perl's built-in getpw*() functions
756
757 =back
758
759 To find out I<all> modules installed on your system, including
760 those without documentation or outside the standard release, 
761 jus tdo this:
762
763     % find `perl -e 'print "@INC"'` -name '*.pm' -print
764
765 They should all have their own documentation installed and accessible
766 via your system man(1) command.  If you do not have a B<find>
767 program, you can use the Perl B<find2perl> program instead, which
768 generates Perl code as output you can run through perl.  If you
769 have a B<man> program but it doesn't find your modules, you'll have
770 to fix your manpath.  See L<perl> for details.  If you have no
771 system B<man> command, you might try the B<perldoc> program.
772
773 =head2 Extension Modules
774
775 Extension modules are written in C (or a mix of Perl and C).  They
776 are usually dynamically loaded into Perl if and when you need them,
777 but may also be be linked in statically.  Supported extension modules
778 include Socket, Fcntl, and POSIX.
779
780 Many popular C extension modules do not come bundled (at least, not
781 completely) due to their sizes, volatility, or simply lack of time
782 for adequate testing and configuration across the multitude of
783 platforms on which Perl was beta-tested.  You are encouraged to
784 look for them on CPAN (described below), or using web search engines
785 like Alta Vista or Deja News.
786
787 =head1 CPAN
788
789 CPAN stands for Comprehensive Perl Archive Network; it's a globally
790 replicated trove of Perl materials, including documentation, style
791 guides, tricks and trap, alternate ports to non-Unix systems and
792 occasional binary distributions for these.   Search engines for
793 CPAN can be found at http://cpan.perl.com/ and at
794 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
795
796 Most importantly, CPAN includes around a thousand unbundled modules,
797 some of which require a C compiler to build.  Major categories of
798 modules are:
799
800 =over
801
802 =item *
803 Language Extensions and Documentation Tools
804
805 =item *
806 Development Support
807
808 =item *
809 Operating System Interfaces
810
811 =item *
812 Networking, Device Control (modems) and InterProcess Communication
813
814 =item *
815 Data Types and Data Type Utilities
816
817 =item *
818 Database Interfaces
819
820 =item *
821 User Interfaces
822
823 =item *
824 Interfaces to / Emulations of Other Programming Languages
825
826 =item *
827 File Names, File Systems and File Locking (see also File Handles)
828
829 =item *
830 String Processing, Language Text Processing, Parsing, and Searching
831
832 =item *
833 Option, Argument, Parameter, and Configuration File Processing
834
835 =item *
836 Internationalization and Locale
837
838 =item *
839 Authentication, Security, and Encryption
840
841 =item *
842 World Wide Web, HTML, HTTP, CGI, MIME
843
844 =item *
845 Server and Daemon Utilities
846
847 =item *
848 Archiving and Compression
849
850 =item *
851 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
852
853 =item *
854 Mail and Usenet News
855
856 =item *
857 Control Flow Utilities (callbacks and exceptions etc)
858
859 =item *
860 File Handle and Input/Output Stream Utilities
861
862 =item *
863 Miscellaneous Modules
864
865 =back
866
867 Registered CPAN sites as of this writing include the following.
868 You should try to choose one close to you:
869
870 =over
871
872 =item Africa
873
874    South Africa    ftp://ftp.is.co.za/programming/perl/CPAN/
875                    ftp://ftpza.co.za/pub/mirrors/cpan/
876
877 =item Asia
878
879    China           ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
880    Hong Kong       ftp://ftp.hkstar.com/pub/CPAN/
881    Israel          ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
882    Japan           ftp://ftp.dti.ad.jp/pub/lang/CPAN/
883                    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
884                    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
885                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
886                    ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
887                    ftp://mirror.nucba.ac.jp/mirror/Perl/
888    Singapore       ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
889    South Korea     ftp://ftp.bora.net/pub/CPAN/
890                    ftp://ftp.nuri.net/pub/CPAN/
891    Taiwan          ftp://ftp.wownet.net/pub2/PERL/
892                    ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
893    Thailand        ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
894                    ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
895
896 =item Australasia
897
898    Australia       ftp://cpan.topend.com.au/pub/CPAN/
899                    ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
900                    ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
901                    ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
902    New Zealand     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
903                    ftp://sunsite.net.nz/pub/languages/perl/CPAN/
904
905 Central America
906
907    Costa Rica      ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
908
909 =item Europe
910
911    Austria         ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
912    Belgium         ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
913    Bulgaria        ftp://ftp.ntrl.net/pub/mirrors/CPAN/
914    Croatia         ftp://ftp.linux.hr/pub/CPAN/
915    Czech Republic  ftp://ftp.fi.muni.cz/pub/perl/
916                    ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
917    Denmark         ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
918    Estonia         ftp://ftp.ut.ee/pub/languages/perl/CPAN/
919    Finland         ftp://ftp.funet.fi/pub/languages/perl/CPAN/
920    France          ftp://ftp.lip6.fr/pub/perl/CPAN/
921                    ftp://ftp.oleane.net/pub/mirrors/CPAN/
922                    ftp://ftp.pasteur.fr/pub/computing/CPAN/
923    Germany         ftp://ftp.archive.de.uu.net/pub/CPAN/
924                    ftp://ftp.gmd.de/packages/CPAN/
925                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
926                    ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/
927                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
928                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
929                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
930                    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
931    Greece          ftp://ftp.ntua.gr/pub/lang/perl/
932    Hungary         ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
933    Ireland         ftp://sunsite.compapp.dcu.ie/pub/perl/
934    Italy           ftp://cis.uniRoma2.it/CPAN/
935                    ftp://ftp.flashnet.it/pub/CPAN/
936                    ftp://ftp.unina.it/pub/Other/CPAN/
937                    ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
938    Netherlands     ftp://ftp.cs.uu.nl/mirror/CPAN/
939                    ftp://ftp.EU.net/packages/cpan/
940                    ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
941    Norway          ftp://ftp.uit.no/pub/languages/perl/cpan/
942                    ftp://sunsite.uio.no/pub/languages/perl/CPAN/
943    Poland          ftp://ftp.man.szczecin.pl/pub/perl/CPAN/
944                    ftp://ftp.man.torun.pl/pub/doc/CPAN/
945                    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
946                    ftp://sunsite.icm.edu.pl/pub/CPAN/
947    Portugal        ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
948                    ftp://ftp.ist.utl.pt/pub/CPAN/
949                    ftp://ftp.ua.pt/pub/CPAN/
950    Romania         ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
951                    ftp://ftp.dnttm.ro/pub/CPAN/
952     Russia         ftp://ftp.chg.ru/pub/lang/perl/CPAN/
953                    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
954    Slovakia        ftp://ftp.entry.sk/pub/languages/perl/CPAN/
955    Slovenia        ftp://ftp.arnes.si/software/perl/CPAN/
956    Spain           ftp://ftp.etse.urv.es/pub/perl/
957                    ftp://ftp.rediris.es/mirror/CPAN/
958    Sweden          ftp://ftp.sunet.se/pub/lang/perl/CPAN/
959    Switzerland     ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
960    Turkey          ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
961    United Kingdom  ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
962                    ftp://ftp.flirble.org/pub/languages/perl/CPAN/
963                    ftp://ftp.plig.org/pub/CPAN/
964                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
965                    ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
966
967 =item North America
968
969    Alberta         ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
970     California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
971                    ftp://ftp.cdrom.com/pub/perl/CPAN/
972                    ftp://ftp.digital.com/pub/plan/perl/CPAN/
973    Colorado        ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
974    Florida         ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
975    Illinois        ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
976    Indiana         ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
977                    ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
978    Manitoba        ftp://theory.uwinnipeg.ca/pub/CPAN/
979    Massachusetts   ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
980                    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
981     Mexico         ftp://ftp.msg.com.mx/pub/CPAN/
982     Minnesota      ftp://ftp.midearthbbs.com/CPAN/
983    New York        ftp://ftp.rge.com/pub/languages/perl/
984    North Carolina  ftp://ftp.duke.edu/pub/perl/
985    Oklahoma        ftp://ftp.ou.edu/mirrors/CPAN/
986     Ontario        ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
987    Oregon          ftp://ftp.orst.edu/pub/packages/CPAN/
988    Pennsylvania    ftp://ftp.epix.net/pub/languages/perl/
989    Texas           ftp://ftp.sedl.org/pub/mirrors/CPAN/
990    Utah            ftp://mirror.xmission.com/CPAN/
991    Virginia        ftp://ftp.perl.org/pub/perl/CPAN/
992                    ftp://ruff.cs.jmu.edu/pub/CPAN/
993     Washington     ftp://ftp-mirror.internap.com/pub/CPAN/
994                    ftp://ftp.spu.edu/pub/CPAN/
995
996 =item South America
997
998    Brazil          ftp://cpan.if.usp.br/pub/mirror/CPAN/
999     Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
1000
1001 =back
1002
1003 For an up-to-date listing of CPAN sites,
1004 see http://www.perl.com/perl/CPAN or ftp://www.perl.com/perl/ .
1005
1006 =head1 Modules: Creation, Use, and Abuse
1007
1008 (The following section is borrowed directly from Tim Bunce's modules
1009 file, available at your nearest CPAN site.)
1010
1011 Perl implements a class using a package, but the presence of a
1012 package doesn't imply the presence of a class.  A package is just a
1013 namespace.  A class is a package that provides subroutines that can be
1014 used as methods.  A method is just a subroutine that expects, as its
1015 first argument, either the name of a package (for "static" methods),
1016 or a reference to something (for "virtual" methods).
1017
1018 A module is a file that (by convention) provides a class of the same
1019 name (sans the .pm), plus an import method in that class that can be
1020 called to fetch exported symbols.  This module may implement some of
1021 its methods by loading dynamic C or C++ objects, but that should be
1022 totally transparent to the user of the module.  Likewise, the module
1023 might set up an AUTOLOAD function to slurp in subroutine definitions on
1024 demand, but this is also transparent.  Only the F<.pm> file is required to
1025 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about 
1026 the AUTOLOAD mechanism.
1027
1028 =head2 Guidelines for Module Creation
1029
1030 =over 4
1031
1032 =item Do similar modules already exist in some form?
1033
1034 If so, please try to reuse the existing modules either in whole or
1035 by inheriting useful features into a new class.  If this is not
1036 practical try to get together with the module authors to work on
1037 extending or enhancing the functionality of the existing modules.
1038 A perfect example is the plethora of packages in perl4 for dealing
1039 with command line options.
1040
1041 If you are writing a module to expand an already existing set of
1042 modules, please coordinate with the author of the package.  It
1043 helps if you follow the same naming scheme and module interaction
1044 scheme as the original author.
1045
1046 =item Try to design the new module to be easy to extend and reuse.
1047
1048 Always use B<-w>.  
1049
1050 Use blessed references.  Use the two argument form of bless to bless
1051 into the class name given as the first parameter of the constructor,
1052 e.g.,:
1053
1054  sub new {
1055         my $class = shift;
1056         return bless {}, $class;
1057  }
1058
1059 or even this if you'd like it to be used as either a static
1060 or a virtual method.
1061
1062  sub new {
1063         my $self  = shift;
1064         my $class = ref($self) || $self;
1065         return bless {}, $class;
1066  }
1067
1068 Pass arrays as references so more parameters can be added later
1069 (it's also faster).  Convert functions into methods where
1070 appropriate.  Split large methods into smaller more flexible ones.
1071 Inherit methods from other modules if appropriate.
1072
1073 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1074 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1075 Let the objects look after themselves! Generally, avoid hard-wired
1076 class names as far as possible.
1077
1078 Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
1079 C<$r-E<gt>func()> would work (see L<perlbot> for more details).
1080
1081 Use autosplit so little used or newly added functions won't be a
1082 burden to programs that don't use them. Add test functions to
1083 the module after __END__ either using AutoSplit or by saying:
1084
1085  eval join('',<main::DATA>) || die $@ unless caller();
1086
1087 Does your module pass the 'empty subclass' test? If you say
1088 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1089 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1090 does your application still work if you change:  C<$obj = new YOURCLASS;>
1091 into: C<$obj = new SUBCLASS;> ?
1092
1093 Avoid keeping any state information in your packages. It makes it
1094 difficult for multiple other packages to use yours. Keep state
1095 information in objects.
1096
1097 Always use B<-w>.  
1098
1099 Try to C<use strict;> (or C<use strict qw(...);>).
1100 Remember that you can add C<no strict qw(...);> to individual blocks
1101 of code that need less strictness.  
1102
1103 Always use B<-w>.  
1104
1105 Follow the guidelines in the perlstyle(1) manual.
1106
1107 Always use B<-w>.
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 MS-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 licence: The GNU
1257 GPL and The Artistic Licence (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 L<Exporter> 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, register the module with CPAN.  You should 
1293 include details of its location in your announcement.
1294
1295 Some notes about ftp archives: Please use a long descriptive file
1296 name that 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 <F<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 Otherwise try to add a mechanism to revert to the
1327 old behavior 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 Perl applications that 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 that 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 or higher)
1406
1407 =back
1408
1409 =head1 NOTE
1410
1411 Perl does not enforce private and public parts of its modules as you may
1412 have been used to in other languages like C++, Ada, or Modula-17.  Perl
1413 doesn't have an infatuation with enforced privacy.  It would prefer
1414 that you stayed out of its living room because you weren't invited, not
1415 because it has a shotgun.
1416
1417 The module and its user have a contract, part of which is common law,
1418 and part of which is "written".  Part of the common law contract is
1419 that a module doesn't pollute any namespace it wasn't asked to.  The
1420 written contract for the module (A.K.A. documentation) may make other
1421 provisions.  But then you know when you C<use RedefineTheWorld> that
1422 you're redefining the world and willing to take the consequences.