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