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