This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
mention how to look up perllocal.pod (from Michael G Schwern)
[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 just do this:
806
807     % find `perl -e 'print "@INC"'` -name '*.pm' -print
808
809 To get a log of all module distributions which have been installed
810 since perl was installed, just do:
811
812     % perldoc perllocal
813
814 Modules should all have their own documentation installed and accessible
815 via your system man(1) command, or via the C<perldoc> program.  If you do
816 not have a B<find>
817 program, you can use the Perl B<find2perl> program instead, which
818 generates Perl code as output you can run through perl.  If you
819 have a B<man> program but it doesn't find your modules, you'll have
820 to fix your manpath.  See L<perl> for details.
821
822 =head2 Extension Modules
823
824 Extension modules are written in C (or a mix of Perl and C).  They
825 are usually dynamically loaded into Perl if and when you need them,
826 but may also be be linked in statically.  Supported extension modules
827 include Socket, Fcntl, and POSIX.
828
829 Many popular C extension modules do not come bundled (at least, not
830 completely) due to their sizes, volatility, or simply lack of time
831 for adequate testing and configuration across the multitude of
832 platforms on which Perl was beta-tested.  You are encouraged to
833 look for them on CPAN (described below), or using web search engines
834 like Alta Vista or Deja News.
835
836 =head1 CPAN
837
838 CPAN stands for Comprehensive Perl Archive Network; it's a globally
839 replicated trove of Perl materials, including documentation, style
840 guides, tricks and trap, alternate ports to non-Unix systems and
841 occasional binary distributions for these.   Search engines for
842 CPAN can be found at http://cpan.perl.com/ and at
843 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
844
845 Most importantly, CPAN includes around a thousand unbundled modules,
846 some of which require a C compiler to build.  Major categories of
847 modules are:
848
849 =over
850
851 =item *
852 Language Extensions and Documentation Tools
853
854 =item *
855 Development Support
856
857 =item *
858 Operating System Interfaces
859
860 =item *
861 Networking, Device Control (modems) and InterProcess Communication
862
863 =item *
864 Data Types and Data Type Utilities
865
866 =item *
867 Database Interfaces
868
869 =item *
870 User Interfaces
871
872 =item *
873 Interfaces to / Emulations of Other Programming Languages
874
875 =item *
876 File Names, File Systems and File Locking (see also File Handles)
877
878 =item *
879 String Processing, Language Text Processing, Parsing, and Searching
880
881 =item *
882 Option, Argument, Parameter, and Configuration File Processing
883
884 =item *
885 Internationalization and Locale
886
887 =item *
888 Authentication, Security, and Encryption
889
890 =item *
891 World Wide Web, HTML, HTTP, CGI, MIME
892
893 =item *
894 Server and Daemon Utilities
895
896 =item *
897 Archiving and Compression
898
899 =item *
900 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
901
902 =item *
903 Mail and Usenet News
904
905 =item *
906 Control Flow Utilities (callbacks and exceptions etc)
907
908 =item *
909 File Handle and Input/Output Stream Utilities
910
911 =item *
912 Miscellaneous Modules
913
914 =back
915
916 Registered CPAN sites as of this writing include the following.
917 You should try to choose one close to you:
918
919 =over
920
921 =item Africa
922
923     South Africa   ftp://ftp.is.co.za/programming/perl/CPAN/
924                    ftp://ftp.saix.net/pub/CPAN/
925                    ftp://ftp.sun.ac.za/CPAN/
926                    ftp://ftpza.co.za/pub/mirrors/cpan/
927
928
929 =item Asia
930
931     China          ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
932     Hong Kong      ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
933     Indonesia      ftp://malone.piksi.itb.ac.id/pub/CPAN/
934     Israel         ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
935     Japan          ftp://ftp.dti.ad.jp/pub/lang/CPAN/
936                    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
937                    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
938                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
939                    ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
940                    ftp://mirror.nucba.ac.jp/mirror/Perl/
941     Saudi-Arabia   ftp://ftp.isu.net.sa/pub/CPAN/
942     Singapore      ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
943     South Korea    ftp://ftp.bora.net/pub/CPAN/
944                    ftp://ftp.kornet.net/pub/CPAN/
945                    ftp://ftp.nuri.net/pub/CPAN/
946     Taiwan         ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
947                    ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/
948                    ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
949     Thailand       ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
950
951
952 =item Australasia
953
954     Australia      ftp://cpan.topend.com.au/pub/CPAN/
955                    ftp://ftp.labyrinth.net.au/pub/perl-CPAN/
956                    ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
957                    ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
958     New Zealand    ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
959                    ftp://sunsite.net.nz/pub/languages/perl/CPAN/
960
961
962 =item Central America
963
964     Costa Rica     ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
965
966
967 =item Europe
968
969     Austria        ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
970     Belgium        ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
971     Bulgaria       ftp://ftp.ntrl.net/pub/mirrors/CPAN/
972     Croatia        ftp://ftp.linux.hr/pub/CPAN/
973     Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
974                    ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
975     Denmark        ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
976     Estonia        ftp://ftp.ut.ee/pub/languages/perl/CPAN/
977     Finland        ftp://ftp.funet.fi/pub/languages/perl/CPAN/
978     France         ftp://ftp.grolier.fr/pub/perl/CPAN/
979                    ftp://ftp.lip6.fr/pub/perl/CPAN/
980                    ftp://ftp.oleane.net/pub/mirrors/CPAN/
981                    ftp://ftp.pasteur.fr/pub/computing/CPAN/
982                    ftp://ftp.uvsq.fr/pub/perl/CPAN/
983     German         ftp://ftp.gigabell.net/pub/CPAN/
984     Germany        ftp://ftp.archive.de.uu.net/pub/CPAN/
985                    ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
986                    ftp://ftp.gmd.de/packages/CPAN/
987                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
988                    ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
989                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
990                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
991                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
992                    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
993     Germany        ftp://ftp.archive.de.uu.net/pub/CPAN/
994                    ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
995                    ftp://ftp.gmd.de/packages/CPAN/
996                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
997                    ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
998                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
999                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
1000                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
1001                    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
1002     Greece         ftp://ftp.ntua.gr/pub/lang/perl/
1003     Hungary        ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
1004     Iceland        ftp://ftp.gm.is/pub/CPAN/
1005     Ireland        ftp://cpan.indigo.ie/pub/CPAN/
1006                    ftp://sunsite.compapp.dcu.ie/pub/perl/
1007     Italy          ftp://cis.uniRoma2.it/CPAN/
1008                    ftp://ftp.flashnet.it/pub/CPAN/
1009                    ftp://ftp.unina.it/pub/Other/CPAN/
1010                    ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
1011     Netherlands    ftp://ftp.cs.uu.nl/mirror/CPAN/
1012                    ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
1013     Norway         ftp://ftp.uit.no/pub/languages/perl/cpan/
1014                    ftp://sunsite.uio.no/pub/languages/perl/CPAN/
1015     Poland         ftp://ftp.man.torun.pl/pub/CPAN/
1016                    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
1017                    ftp://sunsite.icm.edu.pl/pub/CPAN/
1018     Portugal       ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
1019                    ftp://ftp.ist.utl.pt/pub/CPAN/
1020                    ftp://ftp.ua.pt/pub/CPAN/
1021     Romania        ftp://ftp.dnttm.ro/pub/CPAN/
1022     Russia         ftp://ftp.chg.ru/pub/lang/perl/CPAN/
1023                    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
1024     Slovakia       ftp://ftp.entry.sk/pub/languages/perl/CPAN/
1025     Slovenia       ftp://ftp.arnes.si/software/perl/CPAN/
1026     Spain          ftp://ftp.etse.urv.es/pub/perl/
1027                    ftp://ftp.rediris.es/mirror/CPAN/
1028     Sweden         ftp://ftp.sunet.se/pub/lang/perl/CPAN/
1029     Switzerland    ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
1030     Turkey         ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
1031     United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
1032                    ftp://ftp.flirble.org/pub/languages/perl/CPAN/
1033                    ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
1034                    ftp://ftp.plig.org/pub/CPAN/
1035                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
1036
1037
1038 =item North America
1039
1040     Alberta        ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
1041     California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
1042                    ftp://cpan.valueclick.com/CPAN/
1043                    ftp://ftp.cdrom.com/pub/perl/CPAN/
1044                    http://download.sourceforge.net/mirrors/CPAN/
1045     Colorado       ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
1046     Florida        ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
1047     Georgia        ftp://ftp.twoguys.org/CPAN/
1048     Illinois       ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
1049     Indiana        ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
1050                    ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
1051     Kentucky       ftp://ftp.uky.edu/CPAN/
1052     Manitoba       ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
1053     Massachusetts  ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
1054                    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
1055     Mexico         ftp://ftp.msg.com.mx/pub/CPAN/
1056     New York       ftp://ftp.deao.net/pub/CPAN/
1057                    ftp://ftp.rge.com/pub/languages/perl/
1058     North Carolina ftp://ftp.duke.edu/pub/perl/
1059     Nova Scotia    ftp://cpan.chebucto.ns.ca/pub/CPAN/
1060     Oklahoma       ftp://ftp.ou.edu/mirrors/CPAN/
1061     Ontario        ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
1062     Oregon         ftp://ftp.orst.edu/pub/packages/CPAN/
1063     Pennsylvania   ftp://ftp.epix.net/pub/languages/perl/
1064     Tennessee      ftp://ftp.sunsite.utk.edu/pub/CPAN/
1065     Texas          ftp://ftp.sedl.org/pub/mirrors/CPAN/
1066                    ftp://jhcloos.com/pub/mirror/CPAN/
1067     Utah           ftp://mirror.xmission.com/CPAN/
1068     Virginia       ftp://ftp.perl.org/pub/perl/CPAN/
1069                    ftp://ruff.cs.jmu.edu/pub/CPAN/
1070     Washington     ftp://ftp-mirror.internap.com/pub/CPAN/
1071                    ftp://ftp.llarian.net/pub/CPAN/
1072                    ftp://ftp.spu.edu/pub/CPAN/
1073
1074
1075 =item South America
1076
1077     Brazil         ftp://cpan.if.usp.br/pub/mirror/CPAN/
1078                    ftp://ftp.matrix.com.br/pub/perl/
1079     Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/
1080
1081 =back
1082
1083 For an up-to-date listing of CPAN sites,
1084 see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
1085
1086 =head1 Modules: Creation, Use, and Abuse
1087
1088 (The following section is borrowed directly from Tim Bunce's modules
1089 file, available at your nearest CPAN site.)
1090
1091 Perl implements a class using a package, but the presence of a
1092 package doesn't imply the presence of a class.  A package is just a
1093 namespace.  A class is a package that provides subroutines that can be
1094 used as methods.  A method is just a subroutine that expects, as its
1095 first argument, either the name of a package (for "static" methods),
1096 or a reference to something (for "virtual" methods).
1097
1098 A module is a file that (by convention) provides a class of the same
1099 name (sans the .pm), plus an import method in that class that can be
1100 called to fetch exported symbols.  This module may implement some of
1101 its methods by loading dynamic C or C++ objects, but that should be
1102 totally transparent to the user of the module.  Likewise, the module
1103 might set up an AUTOLOAD function to slurp in subroutine definitions on
1104 demand, but this is also transparent.  Only the F<.pm> file is required to
1105 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about 
1106 the AUTOLOAD mechanism.
1107
1108 =head2 Guidelines for Module Creation
1109
1110 =over 4
1111
1112 =item Do similar modules already exist in some form?
1113
1114 If so, please try to reuse the existing modules either in whole or
1115 by inheriting useful features into a new class.  If this is not
1116 practical try to get together with the module authors to work on
1117 extending or enhancing the functionality of the existing modules.
1118 A perfect example is the plethora of packages in perl4 for dealing
1119 with command line options.
1120
1121 If you are writing a module to expand an already existing set of
1122 modules, please coordinate with the author of the package.  It
1123 helps if you follow the same naming scheme and module interaction
1124 scheme as the original author.
1125
1126 =item Try to design the new module to be easy to extend and reuse.
1127
1128 Try to C<use warnings;> (or C<use warnings qw(...);>).
1129 Remember that you can add C<no warnings qw(...);> to individual blocks
1130 of code that need less warnings.  
1131
1132 Use blessed references.  Use the two argument form of bless to bless
1133 into the class name given as the first parameter of the constructor,
1134 e.g.,:
1135
1136  sub new {
1137         my $class = shift;
1138         return bless {}, $class;
1139  }
1140
1141 or even this if you'd like it to be used as either a static
1142 or a virtual method.
1143
1144  sub new {
1145         my $self  = shift;
1146         my $class = ref($self) || $self;
1147         return bless {}, $class;
1148  }
1149
1150 Pass arrays as references so more parameters can be added later
1151 (it's also faster).  Convert functions into methods where
1152 appropriate.  Split large methods into smaller more flexible ones.
1153 Inherit methods from other modules if appropriate.
1154
1155 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1156 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1157 Let the objects look after themselves! Generally, avoid hard-wired
1158 class names as far as possible.
1159
1160 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1161 C<< $r->func() >> would work (see L<perlbot> for more details).
1162
1163 Use autosplit so little used or newly added functions won't be a
1164 burden to programs that don't use them. Add test functions to
1165 the module after __END__ either using AutoSplit or by saying:
1166
1167  eval join('',<main::DATA>) || die $@ unless caller();
1168
1169 Does your module pass the 'empty subclass' test? If you say
1170 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1171 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1172 does your application still work if you change:  C<$obj = new YOURCLASS;>
1173 into: C<$obj = new SUBCLASS;> ?
1174
1175 Avoid keeping any state information in your packages. It makes it
1176 difficult for multiple other packages to use yours. Keep state
1177 information in objects.
1178
1179 Always use B<-w>.  
1180
1181 Try to C<use strict;> (or C<use strict qw(...);>).
1182 Remember that you can add C<no strict qw(...);> to individual blocks
1183 of code that need less strictness.  
1184
1185 Always use B<-w>.  
1186
1187 Follow the guidelines in the perlstyle(1) manual.
1188
1189 Always use B<-w>.
1190
1191 =item Some simple style guidelines
1192
1193 The perlstyle manual supplied with Perl has many helpful points.
1194
1195 Coding style is a matter of personal taste. Many people evolve their
1196 style over several years as they learn what helps them write and
1197 maintain good code.  Here's one set of assorted suggestions that
1198 seem to be widely used by experienced developers:
1199
1200 Use underscores to separate words.  It is generally easier to read
1201 $var_names_like_this than $VarNamesLikeThis, especially for
1202 non-native speakers of English. It's also a simple rule that works
1203 consistently with VAR_NAMES_LIKE_THIS.
1204
1205 Package/Module names are an exception to this rule. Perl informally
1206 reserves lowercase module names for 'pragma' modules like integer
1207 and strict. Other modules normally begin with a capital letter and
1208 use mixed case with no underscores (need to be short and portable).
1209
1210 You may find it helpful to use letter case to indicate the scope
1211 or nature of a variable. For example:
1212
1213  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1214  $Some_Caps_Here  package-wide global/static
1215  $no_caps_here    function scope my() or local() variables
1216
1217 Function and method names seem to work best as all lowercase.
1218 e.g., C<< $obj->as_string() >>.
1219
1220 You can use a leading underscore to indicate that a variable or
1221 function should not be used outside the package that defined it.
1222
1223 =item Select what to export.
1224
1225 Do NOT export method names!
1226
1227 Do NOT export anything else by default without a good reason!
1228
1229 Exports pollute the namespace of the module user.  If you must
1230 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1231 short or common names to reduce the risk of name clashes.
1232
1233 Generally anything not exported is still accessible from outside the
1234 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1235 syntax.  By convention you can use a leading underscore on names to
1236 indicate informally that they are 'internal' and not for public use.
1237
1238 (It is actually possible to get private functions by saying:
1239 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
1240 directly as a method, because a method must have a name in the symbol
1241 table.)
1242
1243 As a general rule, if the module is trying to be object oriented
1244 then export nothing. If it's just a collection of functions then
1245 @EXPORT_OK anything but use @EXPORT with caution.
1246
1247 =item Select a name for the module.
1248
1249 This name should be as descriptive, accurate, and complete as
1250 possible.  Avoid any risk of ambiguity. Always try to use two or
1251 more whole words.  Generally the name should reflect what is special
1252 about what the module does rather than how it does it.  Please use
1253 nested module names to group informally or categorize a module.
1254 There should be a very good reason for a module not to have a nested name.
1255 Module names should begin with a capital letter.
1256
1257 Having 57 modules all called Sort will not make life easy for anyone
1258 (though having 23 called Sort::Quick is only marginally better :-).
1259 Imagine someone trying to install your module alongside many others.
1260 If in any doubt ask for suggestions in comp.lang.perl.misc.
1261
1262 If you are developing a suite of related modules/classes it's good
1263 practice to use nested classes with a common prefix as this will
1264 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1265 Xyz::Model etc. Use the modules in this list as a naming guide.
1266
1267 If adding a new module to a set, follow the original author's
1268 standards for naming modules and the interface to methods in
1269 those modules.
1270
1271 To be portable each component of a module name should be limited to
1272 11 characters. If it might be used on MS-DOS then try to ensure each is
1273 unique in the first 8 characters. Nested modules make this easier.
1274
1275 =item Have you got it right?
1276
1277 How do you know that you've made the right decisions? Have you
1278 picked an interface design that will cause problems later? Have
1279 you picked the most appropriate name? Do you have any questions?
1280
1281 The best way to know for sure, and pick up many helpful suggestions,
1282 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1283 all the people who develop modules and it's the best place to ask.
1284
1285 All you need to do is post a short summary of the module, its
1286 purpose and interfaces. A few lines on each of the main methods is
1287 probably enough. (If you post the whole module it might be ignored
1288 by busy people - generally the very people you want to read it!)
1289
1290 Don't worry about posting if you can't say when the module will be
1291 ready - just say so in the message. It might be worth inviting
1292 others to help you, they may be able to complete it for you!
1293
1294 =item README and other Additional Files.
1295
1296 It's well known that software developers usually fully document the
1297 software they write. If, however, the world is in urgent need of
1298 your software and there is not enough time to write the full
1299 documentation please at least provide a README file containing:
1300
1301 =over 10
1302
1303 =item *
1304 A description of the module/package/extension etc.
1305
1306 =item *
1307 A copyright notice - see below.
1308
1309 =item *
1310 Prerequisites - what else you may need to have.
1311
1312 =item *
1313 How to build it - possible changes to Makefile.PL etc.
1314
1315 =item *
1316 How to install it.
1317
1318 =item *
1319 Recent changes in this release, especially incompatibilities
1320
1321 =item *
1322 Changes / enhancements you plan to make in the future.
1323
1324 =back
1325
1326 If the README file seems to be getting too large you may wish to
1327 split out some of the sections into separate files: INSTALL,
1328 Copying, ToDo etc.
1329
1330 =over 4
1331
1332 =item Adding a Copyright Notice.
1333
1334 How you choose to license your work is a personal decision.
1335 The general mechanism is to assert your Copyright and then make
1336 a declaration of how others may copy/use/modify your work.
1337
1338 Perl, for example, is supplied with two types of licence: The GNU
1339 GPL and The Artistic Licence (see the files README, Copying, and
1340 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
1341
1342 My personal recommendation, out of respect for Larry, Perl, and the
1343 Perl community at large is to state something simply like:
1344
1345  Copyright (c) 1995 Your Name. All rights reserved.
1346  This program is free software; you can redistribute it and/or
1347  modify it under the same terms as Perl itself.
1348
1349 This statement should at least appear in the README file. You may
1350 also wish to include it in a Copying file and your source files.
1351 Remember to include the other words in addition to the Copyright.
1352
1353 =item Give the module a version/issue/release number.
1354
1355 To be fully compatible with the Exporter and MakeMaker modules you
1356 should store your module's version number in a non-my package
1357 variable called $VERSION.  This should be a floating point
1358 number with at least two digits after the decimal (i.e., hundredths,
1359 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
1360 See L<Exporter> for details.
1361
1362 It may be handy to add a function or method to retrieve the number.
1363 Use the number in announcements and archive file names when
1364 releasing the module (ModuleName-1.02.tar.Z).
1365 See perldoc ExtUtils::MakeMaker.pm for details.
1366
1367 =item How to release and distribute a module.
1368
1369 It's good idea to post an announcement of the availability of your
1370 module (or the module itself if small) to the comp.lang.perl.announce
1371 Usenet newsgroup.  This will at least ensure very wide once-off
1372 distribution.
1373
1374 If possible, register the module with CPAN.  You should 
1375 include details of its location in your announcement.
1376
1377 Some notes about ftp archives: Please use a long descriptive file
1378 name that includes the version number. Most incoming directories
1379 will not be readable/listable, i.e., you won't be able to see your
1380 file after uploading it. Remember to send your email notification
1381 message as soon as possible after uploading else your file may get
1382 deleted automatically. Allow time for the file to be processed
1383 and/or check the file has been processed before announcing its
1384 location.
1385
1386 FTP Archives for Perl Modules:
1387
1388 Follow the instructions and links on:
1389
1390    http://www.perl.com/CPAN/modules/00modlist.long.html
1391    http://www.perl.com/CPAN/modules/04pause.html
1392
1393 or upload to one of these sites:
1394
1395    https://pause.kbx.de/pause/
1396    http://pause.perl.org/pause/
1397
1398 and notify <modules@perl.org>.
1399
1400 By using the WWW interface you can ask the Upload Server to mirror
1401 your modules from your ftp or WWW site into your own directory on
1402 CPAN!
1403
1404 Please remember to send me an updated entry for the Module list!
1405
1406 =item Take care when changing a released module.
1407
1408 Always strive to remain compatible with previous released versions.
1409 Otherwise try to add a mechanism to revert to the
1410 old behavior if people rely on it.  Document incompatible changes.
1411
1412 =back
1413
1414 =back
1415
1416 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1417
1418 =over 4
1419
1420 =item There is no requirement to convert anything.
1421
1422 If it ain't broke, don't fix it! Perl 4 library scripts should
1423 continue to work with no problems. You may need to make some minor
1424 changes (like escaping non-array @'s in double quoted strings) but
1425 there is no need to convert a .pl file into a Module for just that.
1426
1427 =item Consider the implications.
1428
1429 All Perl applications that make use of the script will need to
1430 be changed (slightly) if the script is converted into a module.  Is
1431 it worth it unless you plan to make other changes at the same time?
1432
1433 =item Make the most of the opportunity.
1434
1435 If you are going to convert the script to a module you can use the
1436 opportunity to redesign the interface.  The guidelines for module
1437 creation above include many of the issues you should consider.
1438
1439 =item The pl2pm utility will get you started.
1440
1441 This utility will read *.pl files (given as parameters) and write
1442 corresponding *.pm files. The pl2pm utilities does the following:
1443
1444 =over 10
1445
1446 =item *
1447 Adds the standard Module prologue lines
1448
1449 =item *
1450 Converts package specifiers from ' to ::
1451
1452 =item *
1453 Converts die(...) to croak(...)
1454
1455 =item *
1456 Several other minor changes
1457
1458 =back
1459
1460 Being a mechanical process pl2pm is not bullet proof. The converted
1461 code will need careful checking, especially any package statements.
1462 Don't delete the original .pl file till the new .pm one works!
1463
1464 =back
1465
1466 =head2 Guidelines for Reusing Application Code
1467
1468 =over 4
1469
1470 =item Complete applications rarely belong in the Perl Module Library.
1471
1472 =item Many applications contain some Perl code that could be reused.
1473
1474 Help save the world! Share your code in a form that makes it easy
1475 to reuse.
1476
1477 =item Break-out the reusable code into one or more separate module files.
1478
1479 =item Take the opportunity to reconsider and redesign the interfaces.
1480
1481 =item In some cases the 'application' can then be reduced to a small
1482
1483 fragment of code built on top of the reusable modules. In these cases
1484 the application could invoked as:
1485
1486      % perl -e 'use Module::Name; method(@ARGV)' ...
1487 or
1488      % perl -mModule::Name ...    (in perl5.002 or higher)
1489
1490 =back
1491
1492 =head1 NOTE
1493
1494 Perl does not enforce private and public parts of its modules as you may
1495 have been used to in other languages like C++, Ada, or Modula-17.  Perl
1496 doesn't have an infatuation with enforced privacy.  It would prefer
1497 that you stayed out of its living room because you weren't invited, not
1498 because it has a shotgun.
1499
1500 The module and its user have a contract, part of which is common law,
1501 and part of which is "written".  Part of the common law contract is
1502 that a module doesn't pollute any namespace it wasn't asked to.  The
1503 written contract for the module (A.K.A. documentation) may make other
1504 provisions.  But then you know when you C<use RedefineTheWorld> that
1505 you're redefining the world and willing to take the consequences.