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