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