Integrate perlio:
[p5sagit/p5-mst-13.2.git] / pod / perlmodlib.pod
1 =for maintainers
2 Generated by perlmodlib.PL -- DO NOT EDIT!
3
4 =head1 NAME
5
6 perlmodlib - constructing new Perl modules and finding existing ones
7
8 =head1 DESCRIPTION
9
10 =head1 THE PERL MODULE LIBRARY
11
12 Many modules are included the Perl distribution.  These are described
13 below, and all end in F<.pm>.  You may discover compiled library
14 file (usually ending in F<.so>) or small pieces of modules to be
15 autoloaded (ending in F<.al>); these were automatically generated
16 by the installation process.  You may also discover files in the
17 library directory that end in either F<.pl> or F<.ph>.  These are
18 old libraries supplied so that old programs that use them still
19 run.  The F<.pl> files will all eventually be converted into standard
20 modules, and the F<.ph> files made by B<h2ph> will probably end up
21 as extension modules made by B<h2xs>.  (Some F<.ph> values may
22 already be available through the POSIX, Errno, or Fcntl modules.)
23 The B<pl2pm> file in the distribution may help in your conversion,
24 but it's just a mechanical process and therefore far from bulletproof.
25
26 =head2 Pragmatic Modules
27
28 They work somewhat like compiler directives (pragmata) in that they
29 tend to affect the compilation of your program, and thus will usually
30 work well only when used within a C<use>, or C<no>.  Most of these
31 are lexically scoped, so an inner BLOCK may countermand them
32 by saying:
33
34     no integer;
35     no strict 'refs';
36     no warnings;
37
38 which lasts until the end of that BLOCK.
39
40 Some pragmas are lexically scoped--typically those that affect the
41 C<$^H> hints variable.  Others affect the current package instead,
42 like C<use vars> and C<use subs>, which allow you to predeclare a
43 variables or subroutines within a particular I<file> rather than
44 just a block.  Such declarations are effective for the entire file
45 for which they were declared.  You cannot rescind them with C<no
46 vars> or C<no subs>.
47
48 The following pragmas are defined (and have their own documentation).
49
50 =over 12
51
52 =item attributes
53
54 Get/set subroutine or variable attributes
55
56 =item attrs
57
58 Set/get attributes of a subroutine (deprecated)
59
60 =item autouse
61
62 Postpone load of modules until a function is used
63
64 =item base
65
66 Establish IS-A relationship with base class at compile time
67
68 =item blib
69
70 Use MakeMaker's uninstalled version of a package
71
72 =item bytes
73
74 Force byte semantics rather than character semantics
75
76 =item charnames
77
78 Define character names for C<\N{named}> string literal escapes.
79
80 =item constant
81
82 Declare constants
83
84 =item diagnostics
85
86 Perl compiler pragma to force verbose warning diagnostics
87
88 =item encoding
89
90 Pragma to control the conversion of legacy data into Unicode
91
92 =item fields
93
94 Compile-time class fields
95
96 =item filetest
97
98 Control the filetest permission operators
99
100 =item if
101
102 C<use> a Perl module if a condition holds
103
104 =item integer
105
106 Use integer arithmetic instead of floating point
107
108 =item less
109
110 Request less of something from the compiler
111
112 =item locale
113
114 Use and avoid POSIX locales for built-in operations
115
116 =item open
117
118 Set default disciplines for input and output
119
120 =item ops
121
122 Restrict unsafe operations when compiling
123
124 =item overload
125
126 Package for overloading perl operations
127
128 =item re
129
130 Alter regular expression behaviour
131
132 =item sigtrap
133
134 Enable simple signal handling
135
136 =item sort
137
138 Control sort() behaviour
139
140 =item strict
141
142 Restrict unsafe constructs
143
144 =item subs
145
146 Predeclare sub names
147
148 =item threads
149
150 Perl extension allowing use of interpreter based threads from perl
151
152 =item utf8
153
154 Enable/disable UTF-8 (or UTF-EBCDIC) in source code
155
156 =item vars
157
158 Predeclare global variable names (obsolete)
159
160 =item vmsish
161
162 Control VMS-specific language features
163
164 =item warnings
165
166 Control optional warnings
167
168 =item warnings::register
169
170 Warnings import function
171
172 =back
173
174 =head2 Standard Modules
175
176 Standard, bundled modules are all expected to behave in a well-defined
177 manner with respect to namespace pollution because they use the
178 Exporter module.  See their own documentation for details.
179
180 =over 12
181
182 =item AnyDBM_File
183
184 Provide framework for multiple DBMs
185
186 =item Attribute::Handlers
187
188 Simpler definition of attribute handlers
189
190 =item AutoLoader
191
192 Load subroutines only on demand
193
194 =item AutoSplit
195
196 Split a package for autoloading
197
198 =item B
199
200 The Perl Compiler
201
202 =item B::Asmdata
203
204 Autogenerated data about Perl ops, used to generate bytecode
205
206 =item B::Assembler
207
208 Assemble Perl bytecode
209
210 =item B::Bblock
211
212 Walk basic blocks
213
214 =item B::Bytecode
215
216 Perl compiler's bytecode backend
217
218 =item B::C
219
220 Perl compiler's C backend
221
222 =item B::CC
223
224 Perl compiler's optimized C translation backend
225
226 =item B::Concise
227
228 Walk Perl syntax tree, printing concise info about ops
229
230 =item B::Debug
231
232 Walk Perl syntax tree, printing debug info about ops
233
234 =item B::Deparse
235
236 Perl compiler backend to produce perl code
237
238 =item B::Disassembler
239
240 Disassemble Perl bytecode
241
242 =item B::Lint
243
244 Perl lint
245
246 =item B::Showlex
247
248 Show lexical variables used in functions or files
249
250 =item B::Stackobj
251
252 Helper module for CC backend
253
254 =item B::Stash
255
256 Show what stashes are loaded
257
258 =item B::Terse
259
260 Walk Perl syntax tree, printing terse info about ops
261
262 =item B::Xref
263
264 Generates cross reference reports for Perl programs
265
266 =item Benchmark
267
268 Benchmark running times of Perl code
269
270 =item ByteLoader
271
272 Load byte compiled perl code
273
274 =item CGI
275
276 Simple Common Gateway Interface Class
277
278 =item CGI::Apache
279
280 Backward compatibility module for CGI.pm
281
282 =item CGI::Carp
283
284 CGI routines for writing to the HTTPD (or other) error log
285
286 =item CGI::Cookie
287
288 Interface to Netscape Cookies
289
290 =item CGI::Fast
291
292 CGI Interface for Fast CGI
293
294 =item CGI::Pretty
295
296 Module to produce nicely formatted HTML code
297
298 =item CGI::Push
299
300 Simple Interface to Server Push
301
302 =item CGI::Switch
303
304 Backward compatibility module for defunct CGI::Switch
305
306 =item CGI::Util
307
308 Internal utilities used by CGI module
309
310 =item CPAN
311
312 Query, download and build perl modules from CPAN sites
313
314 =item CPAN::FirstTime
315
316 Utility for CPAN::Config file Initialization
317
318 =item CPAN::Nox
319
320 Wrapper around CPAN.pm without using any XS module
321
322 =item Carp
323
324 Warn of errors (from perspective of caller)
325
326 =item Carp::Heavy
327
328 No user serviceable parts inside
329
330 =item Class::ISA
331
332 Report the search path for a class's ISA tree
333
334 =item Class::Struct
335
336 Declare struct-like datatypes as Perl classes
337
338 =item Cwd
339
340 Get pathname of current working directory
341
342 =item DB
343
344 Programmatic interface to the Perl debugging API (draft, subject to
345
346 =item DB_File
347
348 Perl5 access to Berkeley DB version 1.x
349
350 =item Devel::SelfStubber
351
352 Generate stubs for a SelfLoading module
353
354 =item Digest
355
356 Modules that calculate message digests
357
358 =item DirHandle
359
360 Supply object methods for directory handles
361
362 =item Dumpvalue
363
364 Provides screen dump of Perl data.
365
366 =item Encode
367
368 Character encodings
369
370 =item English
371
372 Use nice English (or awk) names for ugly punctuation variables
373
374 =item Env
375
376 Perl module that imports environment variables as scalars or arrays
377
378 =item Exporter
379
380 Implements default import method for modules
381
382 =item Exporter::Heavy
383
384 Exporter guts
385
386 =item ExtUtils::Command
387
388 Utilities to replace common UNIX commands in Makefiles etc.
389
390 =item ExtUtils::Constant
391
392 Generate XS code to import C header constants
393
394 =item ExtUtils::Embed
395
396 Utilities for embedding Perl in C/C++ applications
397
398 =item ExtUtils::Install
399
400 Install files from here to there
401
402 =item ExtUtils::Installed
403
404 Inventory management of installed modules
405
406 =item ExtUtils::Liblist
407
408 Determine libraries to use and how to use them
409
410 =item ExtUtils::MM_BeOS
411
412 Methods to override UN*X behaviour in ExtUtils::MakeMaker
413
414 =item ExtUtils::MM_Cygwin
415
416 Methods to override UN*X behaviour in ExtUtils::MakeMaker
417
418 =item ExtUtils::MM_NW5
419
420 Methods to override UN*X behaviour in ExtUtils::MakeMaker
421
422 =item ExtUtils::MM_OS2
423
424 Methods to override UN*X behaviour in ExtUtils::MakeMaker
425
426 =item ExtUtils::MM_Unix
427
428 Methods used by ExtUtils::MakeMaker
429
430 =item ExtUtils::MM_VMS
431
432 Methods to override UN*X behaviour in ExtUtils::MakeMaker
433
434 =item ExtUtils::MM_Win32
435
436 Methods to override UN*X behaviour in ExtUtils::MakeMaker
437
438 =item ExtUtils::MakeMaker
439
440 Create an extension Makefile
441
442 =item ExtUtils::Manifest
443
444 Utilities to write and check a MANIFEST file
445
446 =item ExtUtils::Mkbootstrap
447
448 Make a bootstrap file for use by DynaLoader
449
450 =item ExtUtils::Mksymlists
451
452 Write linker options files for dynamic extension
453
454 =item ExtUtils::Packlist
455
456 Manage .packlist files
457
458 =item ExtUtils::testlib
459
460 Add blib/* directories to @INC
461
462 =item Fatal
463
464 Replace functions with equivalents which succeed or die
465
466 =item Fcntl
467
468 Load the C Fcntl.h defines
469
470 =item File::Basename
471
472 Split a pathname into pieces
473
474 =item File::CheckTree
475
476 Run many filetest checks on a tree
477
478 =item File::Compare
479
480 Compare files or filehandles
481
482 =item File::Copy
483
484 Copy files or filehandles
485
486 =item File::DosGlob
487
488 DOS like globbing and then some
489
490 =item File::Find
491
492 Traverse a directory tree.
493
494 =item File::Path
495
496 Create or remove directory trees
497
498 =item File::Spec
499
500 Portably perform operations on file names
501
502 =item File::Spec::Cygwin
503
504 Methods for Cygwin file specs
505
506 =item File::Spec::Epoc
507
508 Methods for Epoc file specs
509
510 =item File::Spec::Functions
511
512 Portably perform operations on file names
513
514 =item File::Spec::Mac
515
516 File::Spec for Mac OS (Classic)
517
518 =item File::Spec::OS2
519
520 Methods for OS/2 file specs
521
522 =item File::Spec::Unix
523
524 File::Spec for Unix, base for other File::Spec modules
525
526 =item File::Spec::VMS
527
528 Methods for VMS file specs
529
530 =item File::Spec::Win32
531
532 Methods for Win32 file specs
533
534 =item File::Temp
535
536 Return name and handle of a temporary file safely
537
538 =item File::stat
539
540 By-name interface to Perl's built-in stat() functions
541
542 =item FileCache
543
544 Keep more files open than the system permits
545
546 =item FileHandle
547
548 Supply object methods for filehandles
549
550 =item Filter::Simple
551
552 Simplified source filtering
553
554 =item FindBin
555
556 Locate directory of original perl script
557
558 =item Getopt::Long
559
560 Extended processing of command line options
561
562 =item Getopt::Std
563
564 Process single-character switches with switch clustering
565
566 =item Hash::Util
567
568 A selection of general-utility hash subroutines
569
570 =item I18N::Collate
571
572 Compare 8-bit scalar data according to the current locale
573
574 =item I18N::LangTags
575
576 Functions for dealing with RFC3066-style language tags
577
578 =item I18N::LangTags::List
579
580 Tags and names for human languages
581
582 =item IO
583
584 Load various IO modules
585
586 =item IPC::Open2
587
588 Open a process for both reading and writing
589
590 =item IPC::Open3
591
592 Open a process for reading, writing, and error handling
593
594 =item Locale::Constants
595
596 Constants for Locale codes
597
598 =item Locale::Country
599
600 ISO codes for country identification (ISO 3166)
601
602 =item Locale::Currency
603
604 ISO three letter codes for currency identification (ISO 4217)
605
606 =item Locale::Language
607
608 ISO two letter codes for language identification (ISO 639)
609
610 =item Locale::Maketext
611
612 Framework for localization
613
614 =item Locale::Maketext::TPJ13
615
616 Article about software localization
617
618 =item Locale::Script
619
620 ISO codes for script identification (ISO 15924)
621
622 =item Math::BigFloat
623
624 Arbitrary size floating point math package
625
626 =item Math::BigInt
627
628 Arbitrary size integer math package
629
630 =item Math::BigInt::Calc
631
632 Pure Perl module to support Math::BigInt
633
634 =item Math::Complex
635
636 Complex numbers and associated mathematical functions
637
638 =item Math::Trig
639
640 Trigonometric functions
641
642 =item Memoize
643
644 Make your functions faster by trading space for time
645
646 =item Memoize::AnyDBM_File
647
648 Glue to provide EXISTS for AnyDBM_File for Storable use
649
650 =item Memoize::Expire
651
652 Plug-in module for automatic expiration of memoized values
653
654 =item Memoize::ExpireFile
655
656 Test for Memoize expiration semantics
657
658 =item Memoize::ExpireTest
659
660 Test for Memoize expiration semantics
661
662 =item Memoize::NDBM_File
663
664 Glue to provide EXISTS for NDBM_File for Storable use
665
666 =item Memoize::SDBM_File
667
668 Glue to provide EXISTS for SDBM_File for Storable use
669
670 =item Memoize::Storable
671
672 Store Memoized data in Storable database
673
674 =item NDBM_File
675
676 Tied access to ndbm files
677
678 =item NEXT
679
680 Provide a pseudo-class NEXT that allows method redispatch
681
682 =item Net::Cmd
683
684 Network Command class (as used by FTP, SMTP etc)
685
686 =item Net::Config
687
688 Local configuration data for libnet
689
690 =item Net::Domain
691
692 Attempt to evaluate the current host's internet name and domain
693
694 =item Net::FTP
695
696 FTP Client class
697
698 =item Net::NNTP
699
700 NNTP Client class
701
702 =item Net::Netrc
703
704 OO interface to users netrc file
705
706 =item Net::POP3
707
708 Post Office Protocol 3 Client class (RFC1939)
709
710 =item Net::Ping
711
712 Check a remote host for reachability
713
714 =item Net::SMTP
715
716 Simple Mail Transfer Protocol Client
717
718 =item Net::Time
719
720 Time and daytime network client interface
721
722 =item Net::hostent
723
724 By-name interface to Perl's built-in gethost*() functions
725
726 =item Net::libnetFAQ
727
728 Libnet Frequently Asked Questions
729
730 =item Net::netent
731
732 By-name interface to Perl's built-in getnet*() functions
733
734 =item Net::protoent
735
736 By-name interface to Perl's built-in getproto*() functions
737
738 =item Net::servent
739
740 By-name interface to Perl's built-in getserv*() functions
741
742 =item O
743
744 Generic interface to Perl Compiler backends
745
746 =item ODBM_File
747
748 Tied access to odbm files
749
750 =item Opcode
751
752 Disable named opcodes when compiling perl code
753
754 =item POSIX
755
756 Perl interface to IEEE Std 1003.1
757
758 =item PerlIO
759
760 On demand loader for PerlIO layers and root of PerlIO::* name space
761
762 =item Pod::Checker
763
764 Check pod documents for syntax errors
765
766 =item Pod::Find
767
768 Find POD documents in directory trees
769
770 =item Pod::Functions
771
772 Group Perl's functions a la perlfunc.pod
773
774 =item Pod::Html
775
776 Module to convert pod files to HTML
777
778 =item Pod::InputObjects
779
780 Objects representing POD input paragraphs, commands, etc.
781
782 =item Pod::LaTeX
783
784 Convert Pod data to formatted Latex
785
786 =item Pod::Man
787
788 Convert POD data to formatted *roff input
789
790 =item Pod::ParseLink
791
792 Parse an LE<lt>E<gt> formatting code in POD text
793
794 =item Pod::ParseUtils
795
796 Helpers for POD parsing and conversion
797
798 =item Pod::Parser
799
800 Base class for creating POD filters and translators
801
802 =item Pod::Plainer
803
804 Perl extension for converting Pod to old style Pod.
805
806 =item Pod::Select
807
808 Extract selected sections of POD from input
809
810 =item Pod::Text
811
812 Convert POD data to formatted ASCII text
813
814 =item Pod::Text::Color
815
816 Convert POD data to formatted color ASCII text
817
818 =item Pod::Text::Overstrike
819
820 Convert POD data to formatted overstrike text
821
822 =item Pod::Text::Termcap
823
824 Convert POD data to ASCII text with format escapes
825
826 =item Pod::Usage
827
828 Print a usage message from embedded pod documentation
829
830 =item Pod::t::basic
831
832 Test of various basic POD features in translators.
833
834 =item SDBM_File
835
836 Tied access to sdbm files
837
838 =item Safe
839
840 Compile and execute code in restricted compartments
841
842 =item Search::Dict
843
844 Search for key in dictionary file
845
846 =item SelectSaver
847
848 Save and restore selected file handle
849
850 =item SelfLoader
851
852 Load functions only on demand
853
854 =item Shell
855
856 Run shell commands transparently within perl
857
858 =item Socket
859
860 Load the C socket.h defines and structure manipulators 
861
862 =item Storable
863
864 Persistency for perl data structures
865
866 =item Switch
867
868 A switch statement for Perl
869
870 =item Symbol
871
872 Manipulate Perl symbols and their names
873
874 =item Term::ANSIColor
875
876 Color screen output using ANSI escape sequences
877
878 =item Term::Cap
879
880 Perl termcap interface
881
882 =item Term::Complete
883
884 Perl word completion module
885
886 =item Term::ReadLine
887
888 Perl interface to various C<readline> packages. If
889
890 =item Test
891
892 Provides a simple framework for writing test scripts
893
894 =item Test::Builder
895
896 Backend for building test libraries
897
898 =item Test::Harness
899
900 Run perl standard test scripts with statistics
901
902 =item Test::Harness::Assert
903
904 Simple assert
905
906 =item Test::Harness::Iterator
907
908 Internal Test::Harness Iterator
909
910 =item Test::Harness::Straps
911
912 Detailed analysis of test results
913
914 =item Test::More
915
916 Yet another framework for writing test scripts
917
918 =item Test::Simple
919
920 Basic utilities for writing tests.
921
922 =item Test::Tutorial
923
924 A tutorial about writing really basic tests
925
926 =item Text::Abbrev
927
928 Create an abbreviation table from a list
929
930 =item Text::Balanced
931
932 Extract delimited text sequences from strings.
933
934 =item Text::ParseWords
935
936 Parse text into an array of tokens or array of arrays
937
938 =item Text::Soundex
939
940 Implementation of the Soundex Algorithm as Described by Knuth
941
942 =item Text::Tabs
943
944 Expand and unexpand tabs per the unix expand(1) and unexpand(1)
945
946 =item Text::Wrap
947
948 Line wrapping to form simple paragraphs
949
950 =item Thread
951
952 Manipulate threads in Perl
953
954 =item Tie::Array
955
956 Base class for tied arrays
957
958 =item Tie::File
959
960 Access the lines of a disk file via a Perl array
961
962 =item Tie::Handle
963
964 Base class definitions for tied handles
965
966 =item Tie::Hash
967
968 Base class definitions for tied hashes
969
970 =item Tie::Memoize
971
972 Add data to hash when needed
973
974 =item Tie::RefHash
975
976 Use references as hash keys
977
978 =item Tie::Scalar
979
980 Base class definitions for tied scalars
981
982 =item Tie::SubstrHash
983
984 Fixed-table-size, fixed-key-length hashing
985
986 =item Time::Local
987
988 Efficiently compute time from local and GMT time
989
990 =item Time::gmtime
991
992 By-name interface to Perl's built-in gmtime() function
993
994 =item Time::localtime
995
996 By-name interface to Perl's built-in localtime() function
997
998 =item Time::tm
999
1000 Internal object used by Time::gmtime and Time::localtime
1001
1002 =item UNIVERSAL
1003
1004 Base class for ALL classes (blessed references)
1005
1006 =item Unicode::Collate
1007
1008 Use UCA (Unicode Collation Algorithm)
1009
1010 =item Unicode::UCD
1011
1012 Unicode character database
1013
1014 =item User::grent
1015
1016 By-name interface to Perl's built-in getgr*() functions
1017
1018 =item User::pwent
1019
1020 By-name interface to Perl's built-in getpw*() functions
1021
1022 =item Win32
1023
1024 Interfaces to some Win32 API Functions
1025
1026 =back
1027
1028 To find out I<all> modules installed on your system, including
1029 those without documentation or outside the standard release,
1030 just do this:
1031
1032     % find `perl -e 'print "@INC"'` -name '*.pm' -print
1033
1034 They should all have their own documentation installed and accessible
1035 via your system man(1) command.  If you do not have a B<find>
1036 program, you can use the Perl B<find2perl> program instead, which
1037 generates Perl code as output you can run through perl.  If you
1038 have a B<man> program but it doesn't find your modules, you'll have
1039 to fix your manpath.  See L<perl> for details.  If you have no
1040 system B<man> command, you might try the B<perldoc> program.
1041
1042 =head2 Extension Modules
1043
1044 Extension modules are written in C (or a mix of Perl and C).  They
1045 are usually dynamically loaded into Perl if and when you need them,
1046 but may also be linked in statically.  Supported extension modules
1047 include Socket, Fcntl, and POSIX.
1048
1049 Many popular C extension modules do not come bundled (at least, not
1050 completely) due to their sizes, volatility, or simply lack of time
1051 for adequate testing and configuration across the multitude of
1052 platforms on which Perl was beta-tested.  You are encouraged to
1053 look for them on CPAN (described below), or using web search engines
1054 like Alta Vista or Deja News.
1055
1056 =head1 CPAN
1057
1058 CPAN stands for Comprehensive Perl Archive Network; it's a globally
1059 replicated trove of Perl materials, including documentation, style
1060 guides, tricks and traps, alternate ports to non-Unix systems and
1061 occasional binary distributions for these.   Search engines for
1062 CPAN can be found at http://www.cpan.org/.
1063
1064 Most importantly, CPAN includes around a thousand unbundled modules,
1065 some of which require a C compiler to build.  Major categories of
1066 modules are:
1067
1068 =over
1069
1070 =item *
1071
1072 Language Extensions and Documentation Tools
1073
1074 =item *
1075
1076 Development Support
1077
1078 =item *
1079
1080 Operating System Interfaces
1081
1082 =item *
1083
1084 Networking, Device Control (modems) and InterProcess Communication
1085
1086 =item *
1087
1088 Data Types and Data Type Utilities
1089
1090 =item *
1091
1092 Database Interfaces
1093
1094 =item *
1095
1096 User Interfaces
1097
1098 =item *
1099
1100 Interfaces to / Emulations of Other Programming Languages
1101
1102 =item *
1103
1104 File Names, File Systems and File Locking (see also File Handles)
1105
1106 =item *
1107
1108 String Processing, Language Text Processing, Parsing, and Searching
1109
1110 =item *
1111
1112 Option, Argument, Parameter, and Configuration File Processing
1113
1114 =item *
1115
1116 Internationalization and Locale
1117
1118 =item *
1119
1120 Authentication, Security, and Encryption
1121
1122 =item *
1123
1124 World Wide Web, HTML, HTTP, CGI, MIME
1125
1126 =item *
1127
1128 Server and Daemon Utilities
1129
1130 =item *
1131
1132 Archiving and Compression
1133
1134 =item *
1135
1136 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
1137
1138 =item *
1139
1140 Mail and Usenet News
1141
1142 =item *
1143
1144 Control Flow Utilities (callbacks and exceptions etc)
1145
1146 =item *
1147
1148 File Handle and Input/Output Stream Utilities
1149
1150 =item *
1151
1152 Miscellaneous Modules
1153
1154 =back
1155
1156 Registered CPAN sites as of this writing include the following.
1157 You should try to choose one close to you:
1158
1159 =head2 Africa
1160
1161 =over 4
1162
1163 =item *
1164
1165 South Africa
1166
1167     ftp://ftp.is.co.za/programming/perl/CPAN/
1168     ftp://ftp.mweb.co.za/pub/mirrors/cpan/
1169     ftp://ftp.saix.net/pub/CPAN/
1170     ftp://ftp.sun.ac.za/CPAN/
1171
1172 =back
1173
1174 =head2 Asia
1175
1176 =over 4
1177
1178 =item *
1179
1180 China
1181
1182     ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
1183     http://www2.linuxforum.net/mirror/CPAN/
1184     http://CPAN.pacific.net.hk/
1185     ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
1186     http://cpan.shellhung.org/
1187     ftp://ftp.shellhung.org/pub/CPAN
1188
1189 =item *
1190
1191 India
1192
1193     http://cpan.in.freeos.com
1194     ftp://cpan.in.freeos.com/pub/CPAN/
1195
1196 =item *
1197
1198 Indonesia
1199
1200     http://cpan.itb.web.id/
1201     ftp://mirrors.piksi.itb.ac.id/CPAN/
1202     http://CPAN.mweb.co.id/
1203     ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
1204
1205 =item *
1206
1207 Israel
1208
1209     http://www.iglu.org.il:/pub/CPAN/
1210     ftp://ftp.iglu.org.il/pub/CPAN/
1211     http://cpan.lerner.co.il/
1212     http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1213     ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1214
1215 =item *
1216
1217 Japan
1218
1219     ftp://ftp.u-aizu.ac.jp/pub/CPAN
1220     ftp://ftp.kddlabs.co.jp/CPAN/
1221     http://mirror.nucba.ac.jp/mirror/Perl/
1222     ftp://mirror.nucba.ac.jp/mirror/Perl/
1223     ftp://ftp.meisei-u.ac.jp/pub/CPAN/
1224     ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
1225     ftp://ftp.dti.ad.jp/pub/lang/CPAN/
1226     ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
1227
1228 =item *
1229
1230 Korea
1231
1232     http://mirror.Mazic.org/pub/CPAN
1233     ftp://mirror.Mazic.org/pub/CPAN
1234
1235 =item *
1236
1237 Philippines
1238
1239     http://www.adzu.edu.ph/CPAN
1240
1241 =item *
1242
1243 Russian Federation
1244
1245     http://cpan.tomsk.ru
1246     ftp://cpan.tomsk.ru/pub/CPAN
1247
1248 =item *
1249
1250 Saudi Arabia
1251
1252     ftp://ftp.isu.net.sa/pub/CPAN/
1253
1254 =item *
1255
1256 Singapore
1257
1258     http://cpan.hjc.edu.sg
1259
1260 =item *
1261
1262 South Korea
1263
1264     http://CPAN.bora.net/
1265     ftp://ftp.bora.net/pub/CPAN/
1266     http://ftp.kornet.net/pub/CPAN/
1267     ftp://ftp.kornet.net/pub/CPAN/
1268     ftp://ftp.nuri.net/pub/CPAN/
1269
1270 =item *
1271
1272 Taiwan
1273
1274     ftp://coda.nctu.edu.tw/UNIX/perl/CPAN
1275     ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
1276     ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
1277     http://ftp.tku.edu.tw/pub/CPAN/
1278     ftp://ftp.tku.edu.tw/pub/CPAN/
1279
1280 =item *
1281
1282 Thailand
1283
1284     http://download.nectec.or.th/CPAN/
1285     ftp://ftp.nectec.or.th/pub/languages/CPAN/
1286     ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
1287
1288 =back
1289
1290 =head2 Central America
1291
1292 =over 4
1293
1294 =item *
1295
1296 Costa Rica
1297
1298     ftp://ftp.linux.co.cr/mirrors/CPAN/
1299     http://ftp.ucr.ac.cr/Unix/CPAN/
1300     ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
1301
1302 =back
1303
1304 =head2 Europe
1305
1306 =over 4
1307
1308 =item *
1309
1310 Austria
1311
1312     ftp://ftp.tuwien.ac.at/pub/CPAN/
1313
1314 =item *
1315
1316 Belgium
1317
1318     http://ftp.easynet.be/pub/CPAN/
1319     ftp://ftp.easynet.be/pub/CPAN/
1320     http://cpan.skynet.be
1321     ftp://ftp.skynet.be/pub/CPAN
1322     ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
1323
1324 =item *
1325
1326 Bulgaria
1327
1328     ftp://ftp.ntrl.net/pub/mirrors/CPAN/
1329
1330 =item *
1331
1332 Croatia
1333
1334     ftp://ftp.linux.hr/pub/CPAN/
1335
1336 =item *
1337
1338 Czech Republic
1339
1340     http://ftp.fi.muni.cz/pub/CPAN/
1341     ftp://ftp.fi.muni.cz/pub/CPAN/
1342     ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
1343
1344 =item *
1345
1346 Denmark
1347
1348     http://mirrors.sunsite.dk/cpan/
1349     ftp://sunsite.dk/mirrors/cpan/
1350     http://www.cpan.dk/CPAN/
1351     ftp://www.cpan.dk/ftp.cpan.org/CPAN/
1352
1353 =item *
1354
1355 England
1356
1357     http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
1358     ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
1359     http://cpan.crazygreek.co.uk
1360     ftp://ftp.demon.co.uk/pub/CPAN/
1361     ftp://ftp.flirble.org/pub/languages/perl/CPAN/
1362     ftp://ftp.plig.org/pub/CPAN/
1363     ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
1364     http://mirror.uklinux.net/CPAN/
1365     ftp://mirror.uklinux.net/pub/CPAN/
1366     ftp://usit.shef.ac.uk/pub/packages/CPAN/
1367
1368 =item *
1369
1370 Estonia
1371
1372     ftp://ftp.ut.ee/pub/languages/perl/CPAN/
1373
1374 =item *
1375
1376 Finland
1377
1378     ftp://ftp.funet.fi/pub/languages/perl/CPAN/
1379     http://cpan.kpnqwest.fi/
1380
1381 =item *
1382
1383 France
1384
1385     ftp://cpan.ftp.worldonline.fr/pub/CPAN/
1386     http://cpan.mirrors.easynet.fr/
1387     ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
1388     ftp://ftp.club-internet.fr/pub/perl/CPAN/
1389     http://fr.cpan.org/
1390     ftp://ftp.lip6.fr/pub/perl/CPAN/
1391     ftp://ftp.oleane.net/pub/mirrors/CPAN/
1392     ftp://ftp.pasteur.fr/pub/computing/CPAN/
1393     http://cpan.cict.fr/
1394     ftp://cpan.cict.fr/pub/CPAN/
1395     ftp://ftp.uvsq.fr/pub/perl/CPAN/
1396
1397 =item *
1398
1399 Germany
1400
1401     ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
1402     ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
1403     ftp://ftp.uni-erlangen.de/pub/source/CPAN/
1404     ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
1405     ftp://ftp.gigabell.net/pub/CPAN/
1406     http://ftp.gwdg.de/pub/languages/perl/CPAN/
1407     ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
1408     ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
1409     ftp://ftp.leo.org/pub/CPAN/
1410     http://cpan.noris.de/
1411     ftp://cpan.noris.de/pub/CPAN/
1412     ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
1413     ftp://ftp.gmd.de/mirrors/CPAN/
1414
1415 =item *
1416
1417 Greece
1418
1419     ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
1420     ftp://ftp.ntua.gr/pub/lang/perl/
1421
1422 =item *
1423
1424 Hungary
1425
1426     http://cpan.artifact.hu/
1427     ftp://cpan.artifact.hu/CPAN/
1428     http://ftp.kfki.hu/pub/CPAN/
1429     ftp://ftp.kfki.hu/pub/CPAN/
1430
1431 =item *
1432
1433 Iceland
1434
1435     http://ftp.rhnet.is/pub/CPAN/
1436     ftp://ftp.rhnet.is/pub/CPAN/
1437
1438 =item *
1439
1440 Ireland
1441
1442     http://cpan.indigo.ie/
1443     ftp://cpan.indigo.ie/pub/CPAN/
1444     http://sunsite.compapp.dcu.ie/pub/perl/
1445     ftp://sunsite.compapp.dcu.ie/pub/perl/
1446
1447 =item *
1448
1449 Italy
1450
1451     http://cpan.nettuno.it/
1452     http://gusp.dyndns.org/CPAN/
1453     ftp://gusp.dyndns.org/pub/CPAN
1454     http://softcity.iol.it/cpan
1455     ftp://softcity.iol.it/pub/cpan
1456     ftp://ftp.unina.it/pub/Other/CPAN/
1457     ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
1458     ftp://cis.uniRoma2.it/CPAN/
1459     ftp://ftp.edisontel.it/pub/CPAN_Mirror/
1460     ftp://ftp.flashnet.it/pub/CPAN/
1461
1462 =item *
1463
1464 Latvia
1465
1466     http://kvin.lv/pub/CPAN/
1467
1468 =item *
1469
1470 Lithuania
1471
1472     ftp://ftp.unix.lt/pub/CPAN/
1473
1474 =item *
1475
1476 Netherlands
1477
1478     ftp://download.xs4all.nl/pub/mirror/CPAN/
1479     ftp://ftp.nl.uu.net/pub/CPAN/
1480     ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
1481     http://cpan.cybercomm.nl/
1482     ftp://mirror.cybercomm.nl/pub/cpan/
1483     ftp://ftp.cpan.nl/pub/CPAN/
1484     http://www.cs.uu.nl/mirror/CPAN/
1485     ftp://ftp.cs.uu.nl/mirror/CPAN/
1486
1487 =item *
1488
1489 Norway
1490
1491     ftp://ftp.uninett.no/pub/languages/perl/CPAN
1492     ftp://ftp.uit.no/pub/languages/perl/cpan/
1493
1494 =item *
1495
1496 Poland
1497
1498     ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
1499     http://www.fic.uni.lodz.pl/pub/CPAN
1500     ftp://ftp.fic.uni.lodz.pl/pub/CPAN
1501     ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
1502     ftp://ftp.man.torun.pl/pub/doc/CPAN/
1503     ftp://sunsite.icm.edu.pl/pub/CPAN/
1504
1505 =item *
1506
1507 Portugal
1508
1509     ftp://ftp.ua.pt/pub/CPAN/
1510     ftp://perl.di.uminho.pt/pub/CPAN/
1511     http://cpan.ip.pt/
1512     ftp://cpan.ip.pt/pub/perl/
1513     ftp://ftp.ist.utl.pt/pub/CPAN/
1514     http://cpan.ip.pt/
1515     ftp://cpan.ip.pt/pub/cpan/
1516     ftp://ftp.netc.pt/pub/CPAN/
1517     ftp://ftp.up.pt/pub/CPAN
1518
1519 =item *
1520
1521 Romania
1522
1523     ftp://archive.logicnet.ro/mirrors/ftp.cpan.org/CPAN/
1524     ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
1525     ftp://ftp.dntis.ro/pub/cpan/
1526     ftp://ftp.opsynet.com/cpan/
1527     ftp://ftp.dnttm.ro/pub/CPAN/
1528     ftp://ftp.lasting.ro/pub/CPAN
1529     ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
1530
1531 =item *
1532
1533 Russia
1534
1535     ftp://ftp.chg.ru/pub/lang/perl/CPAN/
1536     http://cpan.rinet.ru/
1537     ftp://cpan.rinet.ru/pub/mirror/CPAN/
1538     ftp://ftp.aha.ru/pub/CPAN/
1539     http://cpan.sai.msu.ru/
1540     ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
1541
1542 =item *
1543
1544 Slovakia
1545
1546     ftp://ftp.entry.sk/pub/languages/perl/CPAN/
1547
1548 =item *
1549
1550 Slovenia
1551
1552     ftp://ftp.arnes.si/software/perl/CPAN/
1553
1554 =item *
1555
1556 Spain
1557
1558     ftp://ftp.rediris.es/mirror/CPAN/
1559     ftp://ftp.etse.urv.es/pub/perl/
1560
1561 =item *
1562
1563 Sweden
1564
1565     http://ftp.du.se/CPAN/
1566     ftp://ftp.du.se/pub/CPAN/
1567     ftp://mirror.dataphone.se/pub/CPAN
1568     ftp://ftp.sunet.se/pub/lang/perl/CPAN/
1569
1570 =item *
1571
1572 Switzerland
1573
1574     ftp://ftp.danyk.ch/CPAN/
1575     ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
1576
1577 =item *
1578
1579 Turkey
1580
1581     ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
1582
1583 =item *
1584
1585 Ukraine
1586
1587     http://cpan.org.ua/
1588     ftp://cpan.org.ua/
1589     ftp://ftp.perl.org.ua/pub/CPAN/
1590
1591 =back
1592
1593 =head2 North America
1594
1595 =over 4
1596
1597 =item *
1598
1599 Canada
1600
1601 =over 8
1602
1603 =item *
1604
1605 Alberta
1606
1607     http://sunsite.ualberta.ca/pub/Mirror/CPAN/
1608     ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
1609
1610 =item *
1611
1612 Manitoba
1613
1614     http://theoryx5.uwinnipeg.ca/pub/CPAN/
1615     ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
1616
1617 =item *
1618
1619 Nova Scotia
1620
1621     ftp://cpan.chebucto.ns.ca/pub/CPAN/
1622
1623 =item *
1624
1625 Ontario
1626
1627     ftp://ftp.crc.ca/pub/CPAN/
1628
1629 =item *
1630
1631 Quebec
1632
1633     http://cpan.mirror.smartworker.org/
1634     ftp://cpan.mirror.smartworker.org/pub/CPAN
1635
1636 =back
1637
1638 =item *
1639
1640 Mexico
1641
1642     http://cpan.azc.uam.mx
1643     ftp://cpan.azc.uam.mx/mirrors/CPAN
1644     http://cpan.unam.mx/
1645     ftp://cpan.unam.mx/pub/CPAN
1646     http://www.msg.com.mx/CPAN/
1647     ftp://ftp.msg.com.mx/pub/CPAN/
1648
1649 =item *
1650
1651 United States
1652
1653 =over 8
1654
1655 =item *
1656
1657 Alabama
1658
1659     http://mirror.hiwaay.net/CPAN/
1660     ftp://mirror.hiwaay.net/CPAN/
1661
1662 =item *
1663
1664 California
1665
1666     http://www.cpan.org/
1667     ftp://cpan.valueclick.com/pub/CPAN/
1668     http://mirrors.gossamer-threads.com/CPAN
1669     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
1670     ftp://ftp.digital.com/pub/plan/perl/CPAN/
1671     http://mirrors.kernel.org/cpan/
1672     ftp://mirrors.kernel.org/pub/CPAN
1673     http://cpan.digisle.net/
1674     ftp://cpan.digisle.net/pub/CPAN
1675     http://www.linuxjar.com/CPAN
1676     ftp://linuxjar.com/pub/CPAN
1677     http://www.perl.com/CPAN/
1678     http://download.sourceforge.net/mirrors/CPAN/
1679
1680 =item *
1681
1682 Colorado
1683
1684     ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
1685
1686 =item *
1687
1688 District of Columbia
1689
1690     ftp://ftp.dc.us.telia.net/pub/cpan/
1691
1692 =item *
1693
1694 Florida
1695
1696     ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
1697     http://mirror.csit.fsu.edu/pub/CPAN/
1698     ftp://mirror.csit.fsu.edu/pub/CPAN/
1699
1700 =item *
1701
1702 Illinois
1703
1704     http://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
1705     ftp://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
1706
1707 =item *
1708
1709 Indiana
1710
1711     ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
1712     http://cpan.nitco.com/
1713     ftp://cpan.nitco.com/pub/CPAN/
1714     http://archive.progeny.com/CPAN/
1715     ftp://archive.progeny.com/CPAN/
1716     ftp://cpan.in-span.net/
1717     http://csociety-ftp.ecn.purdue.edu/pub/CPAN
1718     ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
1719
1720 =item *
1721
1722 Kentucky
1723
1724     http://cpan.uky.edu/
1725     ftp://cpan.uky.edu/pub/CPAN/
1726
1727 =item *
1728
1729 Massachusetts
1730
1731     ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
1732     http://cpan.mirrors.netnumina.com/
1733     ftp://mirrors.netnumina.com/cpan/
1734     ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
1735
1736 =item *
1737
1738 Michigan
1739
1740     ftp://cpan.cse.msu.edu/
1741
1742 =item *
1743
1744 New Jersey
1745
1746     ftp://ftp.cpanel.net/pub/CPAN/
1747
1748 =item *
1749
1750 New York
1751
1752     ftp://ftp.freesoftware.com/pub/perl/CPAN/
1753     ftp://ftp.stealth.net/pub/CPAN/
1754     http://www.rge.com/pub/languages/perl/
1755     ftp://ftp.rge.com/pub/languages/perl/
1756     ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
1757
1758 =item *
1759
1760 North Carolina
1761
1762     ftp://ftp.duke.edu/pub/perl/
1763
1764 =item *
1765
1766 Ohio
1767
1768     ftp://ftp.loaded.net/pub/CPAN/
1769
1770 =item *
1771
1772 Oklahoma
1773
1774     ftp://ftp.ou.edu/mirrors/CPAN/
1775
1776 =item *
1777
1778 Oregon
1779
1780     ftp://ftp.orst.edu/pub/CPAN
1781
1782 =item *
1783
1784 Pennsylvania
1785
1786     http://ftp.epix.net/CPAN/
1787     ftp://ftp.epix.net/pub/languages/perl/
1788     http://mirrors.phenominet.com/pub/CPAN/
1789     ftp://mirrors.phenominet.com/pub/CPAN/
1790     ftp://carroll.cac.psu.edu/pub/CPAN/
1791
1792 =item *
1793
1794 Tennessee
1795
1796     ftp://ftp.sunsite.utk.edu/pub/CPAN/
1797
1798 =item *
1799
1800 Texas
1801
1802     http://ftp.sedl.org/pub/mirrors/CPAN/
1803
1804 =item *
1805
1806 Utah
1807
1808     ftp://mirror.xmission.com/CPAN/
1809
1810 =item *
1811
1812 Virginia
1813
1814     http://mirrors.rcn.net/pub/lang/CPAN/
1815     ftp://mirrors.rcn.net/pub/lang/CPAN/
1816     ftp://ruff.cs.jmu.edu/pub/CPAN/
1817     http://perl.Liquidation.com/CPAN/
1818
1819 =item *
1820
1821 Washington
1822
1823     http://cpan.llarian.net/
1824     ftp://cpan.llarian.net/pub/CPAN/
1825     http://cpan.mirrorcentral.com/
1826     ftp://ftp.mirrorcentral.com/pub/CPAN/
1827     ftp://ftp-mirror.internap.com/pub/CPAN/
1828
1829 =back
1830
1831 =back
1832
1833 =head2 Oceania
1834
1835 =over 4
1836
1837 =item *
1838
1839 Australia
1840
1841     http://ftp.planetmirror.com/pub/CPAN/
1842     ftp://ftp.planetmirror.com/pub/CPAN/
1843     ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
1844     ftp://cpan.topend.com.au/pub/CPAN/
1845
1846 =item *
1847
1848 New Zealand
1849     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
1850
1851 =back
1852
1853 =head2 South America
1854
1855 =over 4
1856
1857 =item *
1858
1859 Argentina
1860
1861     ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
1862
1863 =item *
1864
1865 Brazil
1866
1867     ftp://cpan.pop-mg.com.br/pub/CPAN/
1868     ftp://ftp.matrix.com.br/pub/perl/CPAN/
1869
1870 =item *
1871
1872 Chile
1873
1874     ftp://ftp.psinet.cl/pub/programming/perl/CPAN/
1875     ftp://sunsite.dcc.uchile.cl/pub/lang/perl/
1876
1877 =back
1878
1879
1880 For an up-to-date listing of CPAN sites,
1881 see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
1882
1883 =head1 Modules: Creation, Use, and Abuse
1884
1885 (The following section is borrowed directly from Tim Bunce's modules
1886 file, available at your nearest CPAN site.)
1887
1888 Perl implements a class using a package, but the presence of a
1889 package doesn't imply the presence of a class.  A package is just a
1890 namespace.  A class is a package that provides subroutines that can be
1891 used as methods.  A method is just a subroutine that expects, as its
1892 first argument, either the name of a package (for "static" methods),
1893 or a reference to something (for "virtual" methods).
1894
1895 A module is a file that (by convention) provides a class of the same
1896 name (sans the .pm), plus an import method in that class that can be
1897 called to fetch exported symbols.  This module may implement some of
1898 its methods by loading dynamic C or C++ objects, but that should be
1899 totally transparent to the user of the module.  Likewise, the module
1900 might set up an AUTOLOAD function to slurp in subroutine definitions on
1901 demand, but this is also transparent.  Only the F<.pm> file is required to
1902 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1903 the AUTOLOAD mechanism.
1904
1905 =head2 Guidelines for Module Creation
1906
1907 =over 4
1908
1909 =item  *
1910
1911 Do similar modules already exist in some form?
1912
1913 If so, please try to reuse the existing modules either in whole or
1914 by inheriting useful features into a new class.  If this is not
1915 practical try to get together with the module authors to work on
1916 extending or enhancing the functionality of the existing modules.
1917 A perfect example is the plethora of packages in perl4 for dealing
1918 with command line options.
1919
1920 If you are writing a module to expand an already existing set of
1921 modules, please coordinate with the author of the package.  It
1922 helps if you follow the same naming scheme and module interaction
1923 scheme as the original author.
1924
1925 =item  *
1926
1927 Try to design the new module to be easy to extend and reuse.
1928
1929 Try to C<use warnings;> (or C<use warnings qw(...);>).
1930 Remember that you can add C<no warnings qw(...);> to individual blocks
1931 of code that need less warnings.
1932
1933 Use blessed references.  Use the two argument form of bless to bless
1934 into the class name given as the first parameter of the constructor,
1935 e.g.,:
1936
1937  sub new {
1938      my $class = shift;
1939      return bless {}, $class;
1940  }
1941
1942 or even this if you'd like it to be used as either a static
1943 or a virtual method.
1944
1945  sub new {
1946      my $self  = shift;
1947      my $class = ref($self) || $self;
1948      return bless {}, $class;
1949  }
1950
1951 Pass arrays as references so more parameters can be added later
1952 (it's also faster).  Convert functions into methods where
1953 appropriate.  Split large methods into smaller more flexible ones.
1954 Inherit methods from other modules if appropriate.
1955
1956 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1957 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1958 Let the objects look after themselves! Generally, avoid hard-wired
1959 class names as far as possible.
1960
1961 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1962 C<< $r->func() >> would work (see L<perlbot> for more details).
1963
1964 Use autosplit so little used or newly added functions won't be a
1965 burden to programs that don't use them. Add test functions to
1966 the module after __END__ either using AutoSplit or by saying:
1967
1968  eval join('',<main::DATA>) || die $@ unless caller();
1969
1970 Does your module pass the 'empty subclass' test? If you say
1971 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1972 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1973 does your application still work if you change:  C<$obj = new YOURCLASS;>
1974 into: C<$obj = new SUBCLASS;> ?
1975
1976 Avoid keeping any state information in your packages. It makes it
1977 difficult for multiple other packages to use yours. Keep state
1978 information in objects.
1979
1980 Always use B<-w>.
1981
1982 Try to C<use strict;> (or C<use strict qw(...);>).
1983 Remember that you can add C<no strict qw(...);> to individual blocks
1984 of code that need less strictness.
1985
1986 Always use B<-w>.
1987
1988 Follow the guidelines in the perlstyle(1) manual.
1989
1990 Always use B<-w>.
1991
1992 =item  *
1993
1994 Some simple style guidelines
1995
1996 The perlstyle manual supplied with Perl has many helpful points.
1997
1998 Coding style is a matter of personal taste. Many people evolve their
1999 style over several years as they learn what helps them write and
2000 maintain good code.  Here's one set of assorted suggestions that
2001 seem to be widely used by experienced developers:
2002
2003 Use underscores to separate words.  It is generally easier to read
2004 $var_names_like_this than $VarNamesLikeThis, especially for
2005 non-native speakers of English. It's also a simple rule that works
2006 consistently with VAR_NAMES_LIKE_THIS.
2007
2008 Package/Module names are an exception to this rule. Perl informally
2009 reserves lowercase module names for 'pragma' modules like integer
2010 and strict. Other modules normally begin with a capital letter and
2011 use mixed case with no underscores (need to be short and portable).
2012
2013 You may find it helpful to use letter case to indicate the scope
2014 or nature of a variable. For example:
2015
2016  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
2017  $Some_Caps_Here  package-wide global/static
2018  $no_caps_here    function scope my() or local() variables
2019
2020 Function and method names seem to work best as all lowercase.
2021 e.g., C<< $obj->as_string() >>.
2022
2023 You can use a leading underscore to indicate that a variable or
2024 function should not be used outside the package that defined it.
2025
2026 =item  *
2027
2028 Select what to export.
2029
2030 Do NOT export method names!
2031
2032 Do NOT export anything else by default without a good reason!
2033
2034 Exports pollute the namespace of the module user.  If you must
2035 export try to use @EXPORT_OK in preference to @EXPORT and avoid
2036 short or common names to reduce the risk of name clashes.
2037
2038 Generally anything not exported is still accessible from outside the
2039 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
2040 syntax.  By convention you can use a leading underscore on names to
2041 indicate informally that they are 'internal' and not for public use.
2042
2043 (It is actually possible to get private functions by saying:
2044 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
2045 directly as a method, because a method must have a name in the symbol
2046 table.)
2047
2048 As a general rule, if the module is trying to be object oriented
2049 then export nothing. If it's just a collection of functions then
2050 @EXPORT_OK anything but use @EXPORT with caution.
2051
2052 =item  *
2053
2054 Select a name for the module.
2055
2056 This name should be as descriptive, accurate, and complete as
2057 possible.  Avoid any risk of ambiguity. Always try to use two or
2058 more whole words.  Generally the name should reflect what is special
2059 about what the module does rather than how it does it.  Please use
2060 nested module names to group informally or categorize a module.
2061 There should be a very good reason for a module not to have a nested name.
2062 Module names should begin with a capital letter.
2063
2064 Having 57 modules all called Sort will not make life easy for anyone
2065 (though having 23 called Sort::Quick is only marginally better :-).
2066 Imagine someone trying to install your module alongside many others.
2067 If in any doubt ask for suggestions in comp.lang.perl.misc.
2068
2069 If you are developing a suite of related modules/classes it's good
2070 practice to use nested classes with a common prefix as this will
2071 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
2072 Xyz::Model etc. Use the modules in this list as a naming guide.
2073
2074 If adding a new module to a set, follow the original author's
2075 standards for naming modules and the interface to methods in
2076 those modules.
2077
2078 If developing modules for private internal or project specific use,
2079 that will never be released to the public, then you should ensure
2080 that their names will not clash with any future public module. You
2081 can do this either by using the reserved Local::* category or by
2082 using a category name that includes an underscore like Foo_Corp::*.
2083
2084 To be portable each component of a module name should be limited to
2085 11 characters. If it might be used on MS-DOS then try to ensure each is
2086 unique in the first 8 characters. Nested modules make this easier.
2087
2088 =item  *
2089
2090 Have you got it right?
2091
2092 How do you know that you've made the right decisions? Have you
2093 picked an interface design that will cause problems later? Have
2094 you picked the most appropriate name? Do you have any questions?
2095
2096 The best way to know for sure, and pick up many helpful suggestions,
2097 is to ask someone who knows. Comp.lang.perl.misc is read by just about
2098 all the people who develop modules and it's the best place to ask.
2099
2100 All you need to do is post a short summary of the module, its
2101 purpose and interfaces. A few lines on each of the main methods is
2102 probably enough. (If you post the whole module it might be ignored
2103 by busy people - generally the very people you want to read it!)
2104
2105 Don't worry about posting if you can't say when the module will be
2106 ready - just say so in the message. It might be worth inviting
2107 others to help you, they may be able to complete it for you!
2108
2109 =item  *
2110
2111 README and other Additional Files.
2112
2113 It's well known that software developers usually fully document the
2114 software they write. If, however, the world is in urgent need of
2115 your software and there is not enough time to write the full
2116 documentation please at least provide a README file containing:
2117
2118 =over 10
2119
2120 =item *
2121
2122 A description of the module/package/extension etc.
2123
2124 =item *
2125
2126 A copyright notice - see below.
2127
2128 =item *
2129
2130 Prerequisites - what else you may need to have.
2131
2132 =item *
2133
2134 How to build it - possible changes to Makefile.PL etc.
2135
2136 =item *
2137
2138 How to install it.
2139
2140 =item *
2141
2142 Recent changes in this release, especially incompatibilities
2143
2144 =item *
2145
2146 Changes / enhancements you plan to make in the future.
2147
2148 =back
2149
2150 If the README file seems to be getting too large you may wish to
2151 split out some of the sections into separate files: INSTALL,
2152 Copying, ToDo etc.
2153
2154 =over 4
2155
2156 =item *
2157
2158 Adding a Copyright Notice.
2159
2160 How you choose to license your work is a personal decision.
2161 The general mechanism is to assert your Copyright and then make
2162 a declaration of how others may copy/use/modify your work.
2163
2164 Perl, for example, is supplied with two types of licence: The GNU
2165 GPL and The Artistic Licence (see the files README, Copying, and
2166 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
2167
2168 My personal recommendation, out of respect for Larry, Perl, and the
2169 Perl community at large is to state something simply like:
2170
2171  Copyright (c) 1995 Your Name. All rights reserved.
2172  This program is free software; you can redistribute it and/or
2173  modify it under the same terms as Perl itself.
2174
2175 This statement should at least appear in the README file. You may
2176 also wish to include it in a Copying file and your source files.
2177 Remember to include the other words in addition to the Copyright.
2178
2179 =item  *
2180
2181 Give the module a version/issue/release number.
2182
2183 To be fully compatible with the Exporter and MakeMaker modules you
2184 should store your module's version number in a non-my package
2185 variable called $VERSION.  This should be a floating point
2186 number with at least two digits after the decimal (i.e., hundredths,
2187 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
2188 See L<Exporter> for details.
2189
2190 It may be handy to add a function or method to retrieve the number.
2191 Use the number in announcements and archive file names when
2192 releasing the module (ModuleName-1.02.tar.Z).
2193 See perldoc ExtUtils::MakeMaker.pm for details.
2194
2195 =item  *
2196
2197 How to release and distribute a module.
2198
2199 It's good idea to post an announcement of the availability of your
2200 module (or the module itself if small) to the comp.lang.perl.announce
2201 Usenet newsgroup.  This will at least ensure very wide once-off
2202 distribution.
2203
2204 If possible, register the module with CPAN.  You should
2205 include details of its location in your announcement.
2206
2207 Some notes about ftp archives: Please use a long descriptive file
2208 name that includes the version number. Most incoming directories
2209 will not be readable/listable, i.e., you won't be able to see your
2210 file after uploading it. Remember to send your email notification
2211 message as soon as possible after uploading else your file may get
2212 deleted automatically. Allow time for the file to be processed
2213 and/or check the file has been processed before announcing its
2214 location.
2215
2216 FTP Archives for Perl Modules:
2217
2218 Follow the instructions and links on:
2219
2220    http://www.cpan.org/modules/00modlist.long.html
2221    http://www.cpan.org/modules/04pause.html
2222
2223 or upload to one of these sites:
2224
2225    https://pause.kbx.de/pause/
2226    http://pause.perl.org/pause/
2227
2228 and notify <modules@perl.org>.
2229
2230 By using the WWW interface you can ask the Upload Server to mirror
2231 your modules from your ftp or WWW site into your own directory on
2232 CPAN!
2233
2234 Please remember to send me an updated entry for the Module list!
2235
2236 =item  *
2237
2238 Take care when changing a released module.
2239
2240 Always strive to remain compatible with previous released versions.
2241 Otherwise try to add a mechanism to revert to the
2242 old behavior if people rely on it.  Document incompatible changes.
2243
2244 =back
2245
2246 =back
2247
2248 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
2249
2250 =over 4
2251
2252 =item  *
2253
2254 There is no requirement to convert anything.
2255
2256 If it ain't broke, don't fix it! Perl 4 library scripts should
2257 continue to work with no problems. You may need to make some minor
2258 changes (like escaping non-array @'s in double quoted strings) but
2259 there is no need to convert a .pl file into a Module for just that.
2260
2261 =item  *
2262
2263 Consider the implications.
2264
2265 All Perl applications that make use of the script will need to
2266 be changed (slightly) if the script is converted into a module.  Is
2267 it worth it unless you plan to make other changes at the same time?
2268
2269 =item  *
2270
2271 Make the most of the opportunity.
2272
2273 If you are going to convert the script to a module you can use the
2274 opportunity to redesign the interface.  The guidelines for module
2275 creation above include many of the issues you should consider.
2276
2277 =item  *
2278
2279 The pl2pm utility will get you started.
2280
2281 This utility will read *.pl files (given as parameters) and write
2282 corresponding *.pm files. The pl2pm utilities does the following:
2283
2284 =over 10
2285
2286 =item *
2287
2288 Adds the standard Module prologue lines
2289
2290 =item *
2291
2292 Converts package specifiers from ' to ::
2293
2294 =item *
2295
2296 Converts die(...) to croak(...)
2297
2298 =item *
2299
2300 Several other minor changes
2301
2302 =back
2303
2304 Being a mechanical process pl2pm is not bullet proof. The converted
2305 code will need careful checking, especially any package statements.
2306 Don't delete the original .pl file till the new .pm one works!
2307
2308 =back
2309
2310 =head2 Guidelines for Reusing Application Code
2311
2312 =over 4
2313
2314 =item  *
2315
2316 Complete applications rarely belong in the Perl Module Library.
2317
2318 =item  *
2319
2320 Many applications contain some Perl code that could be reused.
2321
2322 Help save the world! Share your code in a form that makes it easy
2323 to reuse.
2324
2325 =item  *
2326
2327 Break-out the reusable code into one or more separate module files.
2328
2329 =item  *
2330
2331 Take the opportunity to reconsider and redesign the interfaces.
2332
2333 =item  *
2334
2335 In some cases the 'application' can then be reduced to a small
2336
2337 fragment of code built on top of the reusable modules. In these cases
2338 the application could invoked as:
2339
2340      % perl -e 'use Module::Name; method(@ARGV)' ...
2341 or
2342      % perl -mModule::Name ...    (in perl5.002 or higher)
2343
2344 =back
2345
2346 =head1 NOTE
2347
2348 Perl does not enforce private and public parts of its modules as you may
2349 have been used to in other languages like C++, Ada, or Modula-17.  Perl
2350 doesn't have an infatuation with enforced privacy.  It would prefer
2351 that you stayed out of its living room because you weren't invited, not
2352 because it has a shotgun.
2353
2354 The module and its user have a contract, part of which is common law,
2355 and part of which is "written".  Part of the common law contract is
2356 that a module doesn't pollute any namespace it wasn't asked to.  The
2357 written contract for the module (A.K.A. documentation) may make other
2358 provisions.  But then you know when you C<use RedefineTheWorld> that
2359 you're redefining the world and willing to take the consequences.