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