This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Tabs erroneusly expanded to spaces, causing AIX to fail
[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
5df44211
JH
1220The list of the registered CPAN sites as of this writing follows.
1221Please note that the sorting order is alphabetical on fields:
1222
1223Continent
1224 |
1225 |-->Country
1226 |
1227 |-->[state/province]
1228 |
1229 |-->ftp
1230 |
1231 |-->[http]
1232
1233and thus the North American servers happen to be listed between the
1234European and the South American sites.
1235
1236You should try to choose one close to you.
f102b883 1237
4e860d0a
JH
1238=head2 Africa
1239
cea6626f 1240=over 4
f102b883 1241
5df44211 1242=item South Africa
4e860d0a 1243
5df44211
JH
1244 ftp://ftp.is.co.za/programming/perl/CPAN/
1245 ftp://ftp.mweb.co.za/pub/mirrors/cpan/
1246 ftp://ftp.saix.net/pub/CPAN/
1247 ftp://ftp.sun.ac.za/CPAN/CPAN/
4e860d0a
JH
1248
1249=back
1250
1251=head2 Asia
1252
1253=over 4
1254
5df44211 1255=item China
4e860d0a 1256
5df44211
JH
1257 ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
1258 http://www2.linuxforum.net/mirror/CPAN/
1259 http://cpan.shellhung.org/
1260 ftp://ftp.shellhung.org/pub/CPAN
4e860d0a 1261
5df44211 1262=item India
4e860d0a 1263
5df44211
JH
1264 http://cpan.in.freeos.com
1265 ftp://cpan.in.freeos.com/pub/CPAN/
37a78d01 1266
5df44211 1267=item Indonesia
37a78d01 1268
5df44211
JH
1269 http://cpan.itb.web.id/
1270 ftp://mirrors.piksi.itb.ac.id/CPAN/
1271 http://cpan.cbn.net.id/
1272 ftp://ftp.cbn.net.id/mirror/CPAN
1273 http://CPAN.mweb.co.id/
1274 ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
37a78d01 1275
5df44211 1276=item Israel
37a78d01 1277
5df44211
JH
1278 http://www.iglu.org.il:/pub/CPAN/
1279 ftp://ftp.iglu.org.il/pub/CPAN/
1280 http://cpan.lerner.co.il/
1281 http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1282 ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
37a78d01 1283
5df44211 1284=item Japan
37a78d01 1285
5df44211
JH
1286 ftp://ftp.u-aizu.ac.jp/pub/CPAN
1287 ftp://ftp.kddlabs.co.jp/CPAN/
1288 http://mirror.nucba.ac.jp/mirror/Perl/
1289 ftp://mirror.nucba.ac.jp/mirror/Perl/
1290 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
1291 ftp://ftp.ayamura.org/pub/CPAN/
1292 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
1293 ftp://ftp.dti.ad.jp/pub/lang/CPAN/
1294 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
37a78d01 1295
5df44211 1296=item Korea
37a78d01 1297
5df44211
JH
1298 http://mirror.Mazic.org/pub/CPAN
1299 ftp://mirror.Mazic.org/pub/CPAN
37a78d01 1300
5df44211 1301=item Philippines
4e860d0a 1302
5df44211 1303 http://www.adzu.edu.ph/CPAN
4e860d0a 1304
5df44211 1305=item Russian Federation
4e860d0a 1306
5df44211
JH
1307 http://cpan.tomsk.ru
1308 ftp://cpan.tomsk.ru/pub/CPAN
4e860d0a 1309
5df44211 1310=item Saudi Arabia
4e860d0a 1311
5df44211 1312 ftp://ftp.isu.net.sa/pub/CPAN/
4e860d0a 1313
5df44211 1314=item Singapore
4e860d0a 1315
5df44211
JH
1316 http://cpan.hjc.edu.sg
1317 http://mirror.averse.net/pub/CPAN
1318 ftp://mirror.averse.net/pub/CPAN
4e860d0a 1319
5df44211 1320=item South Korea
4e860d0a 1321
5df44211
JH
1322 http://CPAN.bora.net/
1323 ftp://ftp.bora.net/pub/CPAN/
1324 http://ftp.kornet.net/pub/CPAN/
1325 ftp://ftp.kornet.net/pub/CPAN/
1326 ftp://ftp.nuri.net/pub/CPAN/
1327 http://ftp.xgate.co.kr/cpan/
1328 ftp://ftp.xgate.co.kr/pub/mirror/CPAN
4e860d0a 1329
5df44211 1330=item Taiwan
4e860d0a 1331
5df44211
JH
1332 ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN
1333 ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
1334 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
1335 http://ftp.tku.edu.tw/pub/CPAN/
1336 ftp://ftp.tku.edu.tw/pub/CPAN/
4e860d0a 1337
5df44211 1338=item Thailand
4e860d0a 1339
5df44211
JH
1340 ftp://ftp.loxinfo.co.th/pub/cpan/
1341 ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
4e860d0a
JH
1342
1343=back
1344
1345=head2 Central America
1346
1347=over 4
1348
5df44211 1349=item Costa Rica
4e860d0a 1350
5df44211
JH
1351 ftp://ftp.linux.co.cr/mirrors/CPAN/
1352 http://ftp.ucr.ac.cr/Unix/CPAN/
1353 ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
4e860d0a
JH
1354
1355=back
1356
1357=head2 Europe
1358
1359=over 4
1360
5df44211 1361=item Austria
4e860d0a 1362
5df44211 1363 ftp://ftp.tuwien.ac.at/pub/CPAN/
4e860d0a 1364
5df44211 1365=item Belgium
4e860d0a 1366
5df44211
JH
1367 http://ftp.easynet.be/pub/CPAN/
1368 ftp://ftp.easynet.be/pub/CPAN/
1369 http://cpan.skynet.be
1370 ftp://ftp.skynet.be/pub/CPAN
1371 ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
4e860d0a 1372
5df44211 1373=item Bulgaria
4e860d0a 1374
5df44211
JH
1375 http://cpan.lirex.net/
1376 ftp://ftp.lirex.net/pub/mirrors/CPAN
4e860d0a 1377
5df44211 1378=item Croatia
4e860d0a 1379
5df44211
JH
1380 http://ftp.linux.hr/pub/CPAN/
1381 ftp://ftp.linux.hr/pub/CPAN/
4e860d0a 1382
5df44211 1383=item Czech Republic
4e860d0a 1384
5df44211
JH
1385 http://ftp.fi.muni.cz/pub/CPAN/
1386 ftp://ftp.fi.muni.cz/pub/CPAN/
1387 ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
4e860d0a 1388
5df44211 1389=item Denmark
4e860d0a 1390
5df44211
JH
1391 http://mirrors.sunsite.dk/cpan/
1392 ftp://sunsite.dk/mirrors/cpan/
1393 http://cpan.cybercity.dk
1394 http://www.cpan.dk/CPAN/
1395 ftp://www.cpan.dk/ftp.cpan.org/CPAN/
4e860d0a 1396
5df44211 1397=item Estonia
4e860d0a 1398
5df44211 1399 ftp://ftp.ut.ee/pub/languages/perl/CPAN/
4e860d0a 1400
5df44211 1401=item Finland
4e860d0a 1402
5df44211
JH
1403 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
1404 http://cpan.kpnqwest.fi/
4e860d0a 1405
5df44211 1406=item France
37a78d01 1407
5df44211
JH
1408 http://ftp.u-paris10.fr/perl/CPAN
1409 ftp://ftp.u-paris10.fr/perl/CPAN
1410 http://cpan.mirrors.easynet.fr/
1411 ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
1412 ftp://ftp.club-internet.fr/pub/perl/CPAN/
1413 http://fr.cpan.org/
1414 ftp://ftp.lip6.fr/pub/perl/CPAN/
1415 ftp://ftp.oleane.net/pub/mirrors/CPAN/
1416 ftp://ftp.pasteur.fr/pub/computing/CPAN/
1417 http://mir2.ovh.net/ftp.cpan.org
1418 ftp://mir1.ovh.net/ftp.cpan.org
1419 http://ftp.u-strasbg.fr/CPAN
1420 ftp://ftp.u-strasbg.fr/CPAN
1421 http://cpan.cict.fr/
1422 ftp://cpan.cict.fr/pub/CPAN/
1423 ftp://ftp.uvsq.fr/pub/perl/CPAN/
37a78d01 1424
5df44211 1425=item Germany
37a78d01 1426
5df44211
JH
1427 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
1428 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
1429 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
1430 ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
1431 http://pandemonium.tiscali.de/pub/CPAN/
1432 ftp://pandemonium.tiscali.de/pub/CPAN/
1433 http://ftp.gwdg.de/pub/languages/perl/CPAN/
1434 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
1435 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
1436 ftp://ftp.leo.org/pub/CPAN/
1437 http://cpan.noris.de/
1438 ftp://cpan.noris.de/pub/CPAN/
1439 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
1440 ftp://ftp.gmd.de/mirrors/CPAN/
4e860d0a 1441
5df44211 1442=item Greece
4e860d0a 1443
5df44211
JH
1444 ftp://ftp.acn.gr/pub/lang/perl/CPAN
1445 ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
1446 ftp://ftp.ntua.gr/pub/lang/perl/
4e860d0a 1447
5df44211 1448=item Hungary
4e860d0a 1449
5df44211
JH
1450 http://cpan.artifact.hu/
1451 ftp://cpan.artifact.hu/CPAN/
1452 http://ftp.kfki.hu/packages/perl/CPAN/
1453 ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
4e860d0a 1454
5df44211 1455=item Iceland
4e860d0a 1456
5df44211
JH
1457 http://ftp.rhnet.is/pub/CPAN/
1458 ftp://ftp.rhnet.is/pub/CPAN/
4e860d0a 1459
5df44211 1460=item Ireland
4e860d0a 1461
5df44211
JH
1462 http://cpan.indigo.ie/
1463 ftp://cpan.indigo.ie/pub/CPAN/
1464 http://sunsite.compapp.dcu.ie/pub/perl/
1465 ftp://sunsite.compapp.dcu.ie/pub/perl/
4e860d0a 1466
5df44211 1467=item Italy
4e860d0a 1468
5df44211
JH
1469 http://cpan.nettuno.it/
1470 http://gusp.dyndns.org/CPAN/
1471 ftp://gusp.dyndns.org/pub/CPAN
1472 http://softcity.iol.it/cpan
1473 ftp://softcity.iol.it/pub/cpan
1474 ftp://ftp.unina.it/pub/Other/CPAN/CPAN/
1475 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
1476 ftp://cis.uniRoma2.it/CPAN/
1477 ftp://ftp.edisontel.it/pub/CPAN_Mirror/
1478 ftp://ftp.flashnet.it/pub/CPAN/
4e860d0a 1479
5df44211 1480=item Latvia
4e860d0a 1481
5df44211 1482 http://kvin.lv/pub/CPAN/
4e860d0a 1483
5df44211 1484=item Lithuania
4e860d0a 1485
5df44211 1486 ftp://ftp.unix.lt/pub/CPAN/
4e860d0a 1487
5df44211 1488=item Netherlands
4e860d0a 1489
5df44211
JH
1490 ftp://download.xs4all.nl/pub/mirror/CPAN/
1491 ftp://ftp.nl.uu.net/pub/CPAN/
1492 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
1493 http://cpan.cybercomm.nl/
1494 ftp://mirror.cybercomm.nl/pub/CPAN
1495 ftp://ftp.cpan.nl/pub/CPAN/
1496 http://ftp.easynet.nl/mirror/CPAN
1497 ftp://ftp.easynet.nl/mirror/CPAN
1498 http://archive.cs.uu.nl/mirror/CPAN/
1499 ftp://ftp.cs.uu.nl/mirror/CPAN/
4e860d0a 1500
5df44211
JH
1501=item Norway
1502
1503 ftp://ftp.uninett.no/pub/languages/perl/CPAN
1504 ftp://ftp.uit.no/pub/languages/perl/cpan/
1505
1506=item Poland
1507
1508 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
1509 ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
1510 ftp://ftp.man.torun.pl/pub/doc/CPAN/
1511 ftp://sunsite.icm.edu.pl/pub/CPAN/
1512
1513=item Portugal
1514
1515 ftp://ftp.ua.pt/pub/CPAN/
1516 ftp://perl.di.uminho.pt/pub/CPAN/
1517 http://cpan.dei.uc.pt/
1518 ftp://ftp.dei.uc.pt/pub/CPAN
1519 ftp://ftp.ist.utl.pt/pub/CPAN/
1520 http://cpan.ip.pt/
1521 ftp://cpan.ip.pt/pub/cpan/
1522 ftp://ftp.netc.pt/pub/CPAN/
1523 ftp://ftp.up.pt/pub/CPAN
4e860d0a 1524
5df44211 1525=item Romania
4e860d0a 1526
5df44211
JH
1527 ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
1528 ftp://ftp.dntis.ro/pub/cpan/
1529 ftp://ftp.dnttm.ro/pub/CPAN/
1530 ftp://ftp.lasting.ro/pub/CPAN
1531 ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
4e860d0a 1532
5df44211 1533=item Russia
4e860d0a 1534
5df44211
JH
1535 ftp://ftp.chg.ru/pub/lang/perl/CPAN/
1536 http://cpan.rinet.ru/
1537 ftp://cpan.rinet.ru/pub/mirror/CPAN/
1538 ftp://ftp.aha.ru/pub/CPAN/
1539 http://cpan.sai.msu.ru/
1540 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
4e860d0a 1541
5df44211 1542=item Slovakia
4e860d0a 1543
5df44211
JH
1544 http://ftp.cvt.stuba.sk/pub/CPAN/
1545 ftp://ftp.cvt.stuba.sk/pub/CPAN/
4e860d0a 1546
5df44211 1547=item Slovenia
4e860d0a 1548
5df44211 1549 ftp://ftp.arnes.si/software/perl/CPAN/
4e860d0a 1550
5df44211 1551=item Spain
4e860d0a 1552
5df44211
JH
1553 http://cpan.imasd.elmundo.es/
1554 ftp://ftp.rediris.es/mirror/CPAN/
1555 ftp://ftp.etse.urv.es/pub/perl/
4e860d0a 1556
5df44211 1557=item Sweden
4e860d0a 1558
5df44211
JH
1559 http://ftp.du.se/CPAN/
1560 ftp://ftp.du.se/pub/CPAN/
1561 ftp://mirror.dataphone.se/pub/CPAN
1562 ftp://ftp.sunet.se/pub/lang/perl/CPAN/
4e860d0a 1563
5df44211 1564=item Switzerland
4e860d0a 1565
5df44211
JH
1566 ftp://ftp.danyk.ch/CPAN/
1567 ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
4e860d0a 1568
5df44211 1569=item Turkey
4e860d0a 1570
5df44211
JH
1571 http://ftp.ulak.net.tr/perl/CPAN/
1572 ftp://ftp.ulak.net.tr/perl/CPAN
1573 ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
37a78d01 1574
5df44211 1575=item Ukraine
37a78d01 1576
5df44211
JH
1577 http://cpan.org.ua/
1578 ftp://cpan.org.ua/
1579 ftp://ftp.perl.org.ua/pub/CPAN/
37a78d01 1580
5df44211 1581=item United Kingdom
556e28cf 1582
5df44211
JH
1583 http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
1584 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
1585 http://cpan.teleglobe.net/
1586 ftp://cpan.teleglobe.net/pub/CPAN
1587 http://cpan.crazygreek.co.uk
1588 ftp://ftp.demon.co.uk/pub/CPAN/
1589 http://cpan.m.flirble.org/
1590 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
1591 ftp://ftp.plig.org/pub/CPAN/
1592 http://mirror.uklinux.net/CPAN/
1593 ftp://mirror.uklinux.net/pub/CPAN/
1594 http://cpan.mirrors.clockerz.net/
1595 ftp://ftp.clockerz.net/pub/CPAN/
1596 ftp://usit.shef.ac.uk/pub/packages/CPAN/
556e28cf 1597
4e860d0a
JH
1598=back
1599
1600=head2 North America
1601
1602=over 4
1603
5df44211 1604=item Alberta
4e860d0a 1605
5df44211
JH
1606 http://sunsite.ualberta.ca/pub/Mirror/CPAN/
1607 ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
4e860d0a 1608
5df44211 1609=item Manitoba
4e860d0a 1610
5df44211
JH
1611 http://theoryx5.uwinnipeg.ca/pub/CPAN/
1612 ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
4e860d0a 1613
5df44211 1614=item Nova Scotia
4e860d0a 1615
5df44211 1616 ftp://cpan.chebucto.ns.ca/pub/CPAN/
4e860d0a 1617
5df44211 1618=item Ontario
4e860d0a 1619
5df44211 1620 ftp://ftp.crc.ca/pub/CPAN/
4e860d0a 1621
5df44211 1622=item Quebec
4e860d0a 1623
5df44211 1624 http://cpan.mirror.smartworker.org/
37a78d01 1625
5df44211 1626=item Mexico
37a78d01 1627
5df44211
JH
1628 http://cpan.azc.uam.mx
1629 ftp://cpan.azc.uam.mx/mirrors/CPAN
1630 http://cpan.unam.mx/
1631 ftp://cpan.unam.mx/pub/CPAN
1632 http://www.msg.com.mx/CPAN/
1633 ftp://ftp.msg.com.mx/pub/CPAN/
37a78d01
JH
1634
1635=back
4e860d0a 1636
5df44211 1637=head2 United States
556e28cf 1638
5df44211 1639=over 4
4e860d0a 1640
5df44211 1641=item Alabama
4e860d0a 1642
5df44211
JH
1643 http://mirror.hiwaay.net/CPAN/
1644 ftp://mirror.hiwaay.net/CPAN/
4e860d0a 1645
5df44211 1646=item California
4e860d0a 1647
5df44211
JH
1648 http://cpan.develooper.com/
1649 http://www.cpan.org/
1650 ftp://cpan.valueclick.com/pub/CPAN/
1651 http://mirrors.gossamer-threads.com/CPAN
1652 ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
1653 http://mirrors.kernel.org/cpan/
1654 ftp://mirrors.kernel.org/pub/CPAN
1655 http://cpan.digisle.net/
1656 ftp://cpan.digisle.net/pub/CPAN
1657 http://www.perl.com/CPAN/
1658 http://download.sourceforge.net/mirrors/CPAN/
4e860d0a 1659
5df44211 1660=item Colorado
4e860d0a 1661
5df44211 1662 ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
4e860d0a 1663
5df44211 1664=item Delaware
4e860d0a 1665
5df44211
JH
1666 http://ftp.lug.udel.edu/pub/CPAN
1667 ftp://ftp.lug.udel.edu/pub/CPAN
4e860d0a 1668
5df44211 1669=item District of Columbia
4e860d0a 1670
5df44211 1671 ftp://ftp.dc.aleron.net/pub/CPAN/
4e860d0a 1672
5df44211 1673=item Florida
37a78d01 1674
5df44211
JH
1675 ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
1676 http://mirror.csit.fsu.edu/pub/CPAN/
1677 ftp://mirror.csit.fsu.edu/pub/CPAN/
1678 http://cpan.mirrors.nks.net/
37a78d01 1679
5df44211 1680=item Illinois
4e860d0a 1681
5df44211
JH
1682 http://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
1683 ftp://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
4e860d0a 1684
5df44211 1685=item Indiana
4e860d0a 1686
5df44211
JH
1687 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
1688 http://cpan.netnitco.net/
1689 ftp://cpan.netnitco.net/pub/mirrors/CPAN/
1690 http://archive.progeny.com/CPAN/
1691 ftp://archive.progeny.com/CPAN/
1692 ftp://cpan.in-span.net/
1693 http://csociety-ftp.ecn.purdue.edu/pub/CPAN
1694 ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
4e860d0a 1695
5df44211 1696=item Kentucky
4e860d0a 1697
5df44211
JH
1698 http://cpan.uky.edu/
1699 ftp://cpan.uky.edu/pub/CPAN/
4e860d0a 1700
5df44211 1701=item Massachusetts
4e860d0a 1702
5df44211
JH
1703 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
1704 http://cpan.mirrors.netnumina.com/
1705 ftp://mirrors.netnumina.com/cpan/
4e860d0a 1706
5df44211 1707=item Michigan
4e860d0a 1708
5df44211 1709 ftp://cpan.cse.msu.edu/
4e860d0a 1710
5df44211 1711=item New Jersey
4e860d0a 1712
5df44211
JH
1713 ftp://ftp.cpanel.net/pub/CPAN/
1714 http://cpan.teleglobe.net/
1715 ftp://cpan.teleglobe.net/pub/CPAN
4e860d0a 1716
5df44211 1717=item New York
4e860d0a 1718
5df44211
JH
1719 ftp://ftp.exobit.org/pub/perl/CPAN
1720 http://cpan.belfry.net/
1721 http://cpan.thepirtgroup.com/
1722 ftp://cpan.thepirtgroup.com/
1723 ftp://ftp.stealth.net/pub/CPAN/
1724 http://www.rge.com/pub/languages/perl/
1725 ftp://ftp.rge.com/pub/languages/perl/
1726 ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
4e860d0a 1727
5df44211 1728=item North Carolina
4e860d0a 1729
5df44211 1730 ftp://ftp.duke.edu/pub/perl/
4e860d0a 1731
5df44211 1732=item Ohio
4e860d0a 1733
5df44211 1734 ftp://ftp.loaded.net/pub/CPAN/
4e860d0a 1735
5df44211 1736=item Oklahoma
4e860d0a 1737
5df44211 1738 ftp://ftp.ou.edu/mirrors/CPAN/
4e860d0a 1739
5df44211 1740=item Oregon
4e860d0a 1741
5df44211 1742 ftp://ftp.orst.edu/pub/CPAN
4e860d0a 1743
5df44211 1744=item Pennsylvania
4e860d0a 1745
5df44211
JH
1746 http://ftp.epix.net/CPAN/
1747 ftp://ftp.epix.net/pub/languages/perl/
1748 http://mirrors.phenominet.com/pub/CPAN/
1749 ftp://mirrors.phenominet.com/pub/CPAN/
1750 http://cpan.pair.com/
1751 ftp://cpan.pair.com/pub/CPAN/
1752 ftp://carroll.cac.psu.edu/pub/CPAN/
4e860d0a 1753
5df44211 1754=item Tennessee
4e860d0a 1755
5df44211 1756 ftp://ftp.sunsite.utk.edu/pub/CPAN/
4e860d0a 1757
5df44211 1758=item Texas
4e860d0a 1759
5df44211
JH
1760 http://ftp.sedl.org/pub/mirrors/CPAN/
1761 ftp://mirror.telentente.com/pub/CPAN
4e860d0a 1762
5df44211 1763=item Utah
4e860d0a 1764
5df44211 1765 ftp://mirror.xmission.com/CPAN/
4e860d0a 1766
5df44211 1767=item Virginia
4e860d0a 1768
5df44211
JH
1769 http://mirrors.rcn.net/pub/lang/CPAN/
1770 ftp://mirrors.rcn.net/pub/lang/CPAN/
1771 http://perl.secsup.org/
1772 ftp://perl.secsup.org/pub/perl/
1773 http://mirrors.phihost.com/CPAN/
1774 ftp://mirrors.phihost.com/CPAN/
1775 ftp://ruff.cs.jmu.edu/pub/CPAN/
1776 http://perl.Liquidation.com/CPAN/
4e860d0a 1777
5df44211 1778=item ashington
4e860d0a 1779
5df44211
JH
1780 http://cpan.llarian.net/
1781 ftp://cpan.llarian.net/pub/CPAN/
1782 http://cpan.mirrorcentral.com/
1783 ftp://ftp.mirrorcentral.com/pub/CPAN/
1784 ftp://ftp-mirror.internap.com/pub/CPAN/
556e28cf 1785
5df44211 1786=item Wisconsin
556e28cf 1787
5df44211
JH
1788 http://mirror.sit.wisc.edu/pub/CPAN/
1789 ftp://mirror.sit.wisc.edu/pub/CPAN/
4e860d0a
JH
1790
1791=back
1792
1793=head2 Oceania
1794
1795=over 4
1796
5df44211 1797=item Australia
4e860d0a 1798
5df44211
JH
1799 http://ftp.planetmirror.com/pub/CPAN/
1800 ftp://ftp.planetmirror.com/pub/CPAN/
1801 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
1802 ftp://cpan.topend.com.au/pub/CPAN/
4e860d0a 1803
5df44211 1804=item New Zealand
556e28cf 1805
5df44211
JH
1806 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
1807 http://cpan.soa.co.nz/CPAN/
4e860d0a
JH
1808
1809=back
1810
1811=head2 South America
1812
1813=over 4
1814
5df44211 1815=item Argentina
4e860d0a 1816
5df44211
JH
1817 ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
1818 http://ftp.fcaglp.unlp.edu.ar/pub/CPAN/
1819 ftp://ftp.fcaglp.unlp.edu.ar/pub/CPAN/
4e860d0a 1820
5df44211 1821=item Brazil
4e860d0a 1822
5df44211
JH
1823 ftp://cpan.pop-mg.com.br/pub/CPAN/
1824 ftp://ftp.matrix.com.br/pub/perl/CPAN/
4e860d0a 1825
5df44211 1826=item Chile
4e860d0a 1827
5df44211
JH
1828 http://cpan.netglobalis.net/
1829 ftp://cpan.netglobalis.net/pub/CPAN/
f102b883
TC
1830
1831=back
1832
5df44211
JH
1833=head2 RSYNC Mirrors
1834
1835 ftp.fcaglp.unlp.edu.ar::CPAN
1836 cpan.mirror.smartworker.org::CPAN
1837 theoryx5.uwinnipeg.ca::CPAN
1838 ftp.shellhung.org::CPAN
1839 ftp.funet.fi::CPAN
1840 ftp.u-paris10.fr::CPAN
1841 mir1.ovh.net::CPAN
1842 ftp.gwdg.de::FTP/languages/perl/CPAN/
1843 ftp.leo.org::CPAN
1844 CPAN.piksi.itb.ac.id::CPAN
1845 ftp.cbn.net.id::CPAN
1846 ftp.iglu.org.il::CPAN
1847 gusp.dyndns.org::cpan
1848 ftp.kddlabs.co.jp::cpan
1849 ftp.ayamura.org::pub/CPAN/
1850 mirror.averse.net::cpan
1851 cpan.teleglobe.net::CPAN
1852 ftp.sedl.org::cpan
1853 archive.progeny.com::CPAN
1854 cpan.teleglobe.net::CPAN
1855 ftp.lug.udel.edu::cpan
1856 mirrors.kernel.org::mirrors/CPAN
1857 mirrors.phenominet.com::CPAN
1858 mirror.csit.fsu.edu::CPAN
1859 csociety-ftp.ecn.purdue.edu::CPAN
1860
f102b883 1861For an up-to-date listing of CPAN sites,
4e860d0a 1862see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
f102b883
TC
1863
1864=head1 Modules: Creation, Use, and Abuse
1865
1866(The following section is borrowed directly from Tim Bunce's modules
1867file, available at your nearest CPAN site.)
1868
1869Perl implements a class using a package, but the presence of a
1870package doesn't imply the presence of a class. A package is just a
1871namespace. A class is a package that provides subroutines that can be
1872used as methods. A method is just a subroutine that expects, as its
1873first argument, either the name of a package (for "static" methods),
1874or a reference to something (for "virtual" methods).
1875
1876A module is a file that (by convention) provides a class of the same
1877name (sans the .pm), plus an import method in that class that can be
1878called to fetch exported symbols. This module may implement some of
1879its methods by loading dynamic C or C++ objects, but that should be
1880totally transparent to the user of the module. Likewise, the module
1881might set up an AUTOLOAD function to slurp in subroutine definitions on
1882demand, but this is also transparent. Only the F<.pm> file is required to
2e1d04bc 1883exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
f102b883
TC
1884the AUTOLOAD mechanism.
1885
1886=head2 Guidelines for Module Creation
1887
1888=over 4
1889
4e860d0a
JH
1890=item *
1891
1892Do similar modules already exist in some form?
f102b883
TC
1893
1894If so, please try to reuse the existing modules either in whole or
1895by inheriting useful features into a new class. If this is not
1896practical try to get together with the module authors to work on
1897extending or enhancing the functionality of the existing modules.
1898A perfect example is the plethora of packages in perl4 for dealing
1899with command line options.
1900
1901If you are writing a module to expand an already existing set of
1902modules, please coordinate with the author of the package. It
1903helps if you follow the same naming scheme and module interaction
1904scheme as the original author.
1905
4e860d0a
JH
1906=item *
1907
1908Try to design the new module to be easy to extend and reuse.
f102b883 1909
9f1b1f2d
GS
1910Try to C<use warnings;> (or C<use warnings qw(...);>).
1911Remember that you can add C<no warnings qw(...);> to individual blocks
2e1d04bc 1912of code that need less warnings.
19799a22 1913
f102b883
TC
1914Use blessed references. Use the two argument form of bless to bless
1915into the class name given as the first parameter of the constructor,
1916e.g.,:
1917
1918 sub new {
2e1d04bc
JH
1919 my $class = shift;
1920 return bless {}, $class;
f102b883
TC
1921 }
1922
1923or even this if you'd like it to be used as either a static
1924or a virtual method.
1925
1926 sub new {
2e1d04bc
JH
1927 my $self = shift;
1928 my $class = ref($self) || $self;
1929 return bless {}, $class;
f102b883
TC
1930 }
1931
1932Pass arrays as references so more parameters can be added later
1933(it's also faster). Convert functions into methods where
1934appropriate. Split large methods into smaller more flexible ones.
1935Inherit methods from other modules if appropriate.
1936
1937Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
19799a22 1938Generally you can delete the C<eq 'FOO'> part with no harm at all.
f102b883
TC
1939Let the objects look after themselves! Generally, avoid hard-wired
1940class names as far as possible.
1941
c47ff5f1
GS
1942Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1943C<< $r->func() >> would work (see L<perlbot> for more details).
f102b883
TC
1944
1945Use autosplit so little used or newly added functions won't be a
5a964f20 1946burden to programs that don't use them. Add test functions to
f102b883
TC
1947the module after __END__ either using AutoSplit or by saying:
1948
1949 eval join('',<main::DATA>) || die $@ unless caller();
1950
1951Does your module pass the 'empty subclass' test? If you say
19799a22 1952C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
f102b883
TC
1953to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1954does your application still work if you change: C<$obj = new YOURCLASS;>
1955into: C<$obj = new SUBCLASS;> ?
1956
1957Avoid keeping any state information in your packages. It makes it
1958difficult for multiple other packages to use yours. Keep state
1959information in objects.
1960
2e1d04bc 1961Always use B<-w>.
19799a22
GS
1962
1963Try to C<use strict;> (or C<use strict qw(...);>).
f102b883 1964Remember that you can add C<no strict qw(...);> to individual blocks
2e1d04bc 1965of code that need less strictness.
19799a22 1966
2e1d04bc 1967Always use B<-w>.
19799a22 1968
f102b883
TC
1969Follow the guidelines in the perlstyle(1) manual.
1970
19799a22
GS
1971Always use B<-w>.
1972
4e860d0a
JH
1973=item *
1974
1975Some simple style guidelines
f102b883 1976
5a964f20 1977The perlstyle manual supplied with Perl has many helpful points.
f102b883
TC
1978
1979Coding style is a matter of personal taste. Many people evolve their
1980style over several years as they learn what helps them write and
1981maintain good code. Here's one set of assorted suggestions that
1982seem to be widely used by experienced developers:
1983
1984Use underscores to separate words. It is generally easier to read
1985$var_names_like_this than $VarNamesLikeThis, especially for
1986non-native speakers of English. It's also a simple rule that works
1987consistently with VAR_NAMES_LIKE_THIS.
1988
1989Package/Module names are an exception to this rule. Perl informally
1990reserves lowercase module names for 'pragma' modules like integer
1991and strict. Other modules normally begin with a capital letter and
1992use mixed case with no underscores (need to be short and portable).
1993
1994You may find it helpful to use letter case to indicate the scope
1995or nature of a variable. For example:
1996
5a964f20 1997 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
f102b883
TC
1998 $Some_Caps_Here package-wide global/static
1999 $no_caps_here function scope my() or local() variables
2000
2001Function and method names seem to work best as all lowercase.
c47ff5f1 2002e.g., C<< $obj->as_string() >>.
f102b883
TC
2003
2004You can use a leading underscore to indicate that a variable or
2005function should not be used outside the package that defined it.
2006
4e860d0a
JH
2007=item *
2008
2009Select what to export.
f102b883
TC
2010
2011Do NOT export method names!
2012
2013Do NOT export anything else by default without a good reason!
2014
2015Exports pollute the namespace of the module user. If you must
2016export try to use @EXPORT_OK in preference to @EXPORT and avoid
2017short or common names to reduce the risk of name clashes.
2018
2019Generally anything not exported is still accessible from outside the
c47ff5f1 2020module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
f102b883
TC
2021syntax. By convention you can use a leading underscore on names to
2022indicate informally that they are 'internal' and not for public use.
2023
2024(It is actually possible to get private functions by saying:
2025C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
2026directly as a method, because a method must have a name in the symbol
2027table.)
2028
2029As a general rule, if the module is trying to be object oriented
2030then export nothing. If it's just a collection of functions then
2031@EXPORT_OK anything but use @EXPORT with caution.
2032
4e860d0a
JH
2033=item *
2034
2035Select a name for the module.
f102b883
TC
2036
2037This name should be as descriptive, accurate, and complete as
2038possible. Avoid any risk of ambiguity. Always try to use two or
2039more whole words. Generally the name should reflect what is special
2040about what the module does rather than how it does it. Please use
2041nested module names to group informally or categorize a module.
2042There should be a very good reason for a module not to have a nested name.
2043Module names should begin with a capital letter.
2044
2045Having 57 modules all called Sort will not make life easy for anyone
2046(though having 23 called Sort::Quick is only marginally better :-).
2047Imagine someone trying to install your module alongside many others.
2048If in any doubt ask for suggestions in comp.lang.perl.misc.
2049
2050If you are developing a suite of related modules/classes it's good
2051practice to use nested classes with a common prefix as this will
2052avoid namespace clashes. For example: Xyz::Control, Xyz::View,
2053Xyz::Model etc. Use the modules in this list as a naming guide.
2054
2055If adding a new module to a set, follow the original author's
2056standards for naming modules and the interface to methods in
2057those modules.
2058
165c0277
JH
2059If developing modules for private internal or project specific use,
2060that will never be released to the public, then you should ensure
2061that their names will not clash with any future public module. You
2062can do this either by using the reserved Local::* category or by
2063using a category name that includes an underscore like Foo_Corp::*.
2064
f102b883
TC
2065To be portable each component of a module name should be limited to
206611 characters. If it might be used on MS-DOS then try to ensure each is
2067unique in the first 8 characters. Nested modules make this easier.
2068
4e860d0a
JH
2069=item *
2070
2071Have you got it right?
f102b883
TC
2072
2073How do you know that you've made the right decisions? Have you
2074picked an interface design that will cause problems later? Have
2075you picked the most appropriate name? Do you have any questions?
2076
2077The best way to know for sure, and pick up many helpful suggestions,
2078is to ask someone who knows. Comp.lang.perl.misc is read by just about
2079all the people who develop modules and it's the best place to ask.
2080
2081All you need to do is post a short summary of the module, its
2082purpose and interfaces. A few lines on each of the main methods is
2083probably enough. (If you post the whole module it might be ignored
2084by busy people - generally the very people you want to read it!)
2085
2086Don't worry about posting if you can't say when the module will be
2087ready - just say so in the message. It might be worth inviting
2088others to help you, they may be able to complete it for you!
2089
4e860d0a
JH
2090=item *
2091
2092README and other Additional Files.
f102b883
TC
2093
2094It's well known that software developers usually fully document the
2095software they write. If, however, the world is in urgent need of
2096your software and there is not enough time to write the full
2097documentation please at least provide a README file containing:
2098
2099=over 10
2100
2101=item *
4e860d0a 2102
f102b883
TC
2103A description of the module/package/extension etc.
2104
2105=item *
4e860d0a 2106
f102b883
TC
2107A copyright notice - see below.
2108
2109=item *
4e860d0a 2110
f102b883
TC
2111Prerequisites - what else you may need to have.
2112
2113=item *
4e860d0a 2114
f102b883
TC
2115How to build it - possible changes to Makefile.PL etc.
2116
2117=item *
4e860d0a 2118
f102b883
TC
2119How to install it.
2120
2121=item *
4e860d0a 2122
f102b883
TC
2123Recent changes in this release, especially incompatibilities
2124
2125=item *
4e860d0a 2126
f102b883
TC
2127Changes / enhancements you plan to make in the future.
2128
2129=back
2130
2131If the README file seems to be getting too large you may wish to
2132split out some of the sections into separate files: INSTALL,
2133Copying, ToDo etc.
2134
2135=over 4
2136
37a78d01 2137=item *
f102b883 2138
37a78d01 2139Adding a Copyright Notice.
4e860d0a 2140
f102b883
TC
2141How you choose to license your work is a personal decision.
2142The general mechanism is to assert your Copyright and then make
2143a declaration of how others may copy/use/modify your work.
2144
2145Perl, for example, is supplied with two types of licence: The GNU
2146GPL and The Artistic Licence (see the files README, Copying, and
2147Artistic). Larry has good reasons for NOT just using the GNU GPL.
2148
2149My personal recommendation, out of respect for Larry, Perl, and the
5a964f20 2150Perl community at large is to state something simply like:
f102b883
TC
2151
2152 Copyright (c) 1995 Your Name. All rights reserved.
2153 This program is free software; you can redistribute it and/or
2154 modify it under the same terms as Perl itself.
2155
2156This statement should at least appear in the README file. You may
2157also wish to include it in a Copying file and your source files.
2158Remember to include the other words in addition to the Copyright.
2159
4e860d0a
JH
2160=item *
2161
2162Give the module a version/issue/release number.
f102b883
TC
2163
2164To be fully compatible with the Exporter and MakeMaker modules you
2165should store your module's version number in a non-my package
2166variable called $VERSION. This should be a floating point
2167number with at least two digits after the decimal (i.e., hundredths,
2168e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
19799a22 2169See L<Exporter> for details.
f102b883
TC
2170
2171It may be handy to add a function or method to retrieve the number.
2172Use the number in announcements and archive file names when
2173releasing the module (ModuleName-1.02.tar.Z).
2174See perldoc ExtUtils::MakeMaker.pm for details.
2175
4e860d0a
JH
2176=item *
2177
2178How to release and distribute a module.
f102b883
TC
2179
2180It's good idea to post an announcement of the availability of your
2181module (or the module itself if small) to the comp.lang.perl.announce
2182Usenet newsgroup. This will at least ensure very wide once-off
2183distribution.
2184
2e1d04bc 2185If possible, register the module with CPAN. You should
f102b883
TC
2186include details of its location in your announcement.
2187
2188Some notes about ftp archives: Please use a long descriptive file
5a964f20 2189name that includes the version number. Most incoming directories
f102b883
TC
2190will not be readable/listable, i.e., you won't be able to see your
2191file after uploading it. Remember to send your email notification
2192message as soon as possible after uploading else your file may get
2193deleted automatically. Allow time for the file to be processed
2194and/or check the file has been processed before announcing its
2195location.
2196
2197FTP Archives for Perl Modules:
2198
6cecdcac 2199Follow the instructions and links on:
f102b883 2200
4e860d0a
JH
2201 http://www.cpan.org/modules/00modlist.long.html
2202 http://www.cpan.org/modules/04pause.html
f102b883
TC
2203
2204or upload to one of these sites:
2205
6cecdcac
GS
2206 https://pause.kbx.de/pause/
2207 http://pause.perl.org/pause/
f102b883 2208
6cecdcac 2209and notify <modules@perl.org>.
f102b883
TC
2210
2211By using the WWW interface you can ask the Upload Server to mirror
2212your modules from your ftp or WWW site into your own directory on
2213CPAN!
2214
2215Please remember to send me an updated entry for the Module list!
2216
4e860d0a
JH
2217=item *
2218
2219Take care when changing a released module.
f102b883 2220
7b8d334a
GS
2221Always strive to remain compatible with previous released versions.
2222Otherwise try to add a mechanism to revert to the
19799a22 2223old behavior if people rely on it. Document incompatible changes.
f102b883
TC
2224
2225=back
2226
2227=back
2228
2229=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
2230
2231=over 4
2232
4e860d0a
JH
2233=item *
2234
2235There is no requirement to convert anything.
f102b883
TC
2236
2237If it ain't broke, don't fix it! Perl 4 library scripts should
2238continue to work with no problems. You may need to make some minor
2239changes (like escaping non-array @'s in double quoted strings) but
2240there is no need to convert a .pl file into a Module for just that.
2241
4e860d0a
JH
2242=item *
2243
2244Consider the implications.
f102b883 2245
5a964f20 2246All Perl applications that make use of the script will need to
f102b883
TC
2247be changed (slightly) if the script is converted into a module. Is
2248it worth it unless you plan to make other changes at the same time?
2249
4e860d0a
JH
2250=item *
2251
2252Make the most of the opportunity.
f102b883
TC
2253
2254If you are going to convert the script to a module you can use the
19799a22
GS
2255opportunity to redesign the interface. The guidelines for module
2256creation above include many of the issues you should consider.
f102b883 2257
4e860d0a
JH
2258=item *
2259
2260The pl2pm utility will get you started.
f102b883
TC
2261
2262This utility will read *.pl files (given as parameters) and write
2263corresponding *.pm files. The pl2pm utilities does the following:
2264
2265=over 10
2266
2267=item *
4e860d0a 2268
f102b883
TC
2269Adds the standard Module prologue lines
2270
2271=item *
4e860d0a 2272
f102b883
TC
2273Converts package specifiers from ' to ::
2274
2275=item *
4e860d0a 2276
f102b883
TC
2277Converts die(...) to croak(...)
2278
2279=item *
4e860d0a 2280
f102b883
TC
2281Several other minor changes
2282
2283=back
2284
2285Being a mechanical process pl2pm is not bullet proof. The converted
2286code will need careful checking, especially any package statements.
2287Don't delete the original .pl file till the new .pm one works!
2288
2289=back
2290
2291=head2 Guidelines for Reusing Application Code
2292
2293=over 4
2294
4e860d0a 2295=item *
551e1d92
RB
2296
2297Complete applications rarely belong in the Perl Module Library.
f102b883 2298
4e860d0a 2299=item *
551e1d92
RB
2300
2301Many applications contain some Perl code that could be reused.
f102b883
TC
2302
2303Help save the world! Share your code in a form that makes it easy
2304to reuse.
2305
4e860d0a 2306=item *
551e1d92
RB
2307
2308Break-out the reusable code into one or more separate module files.
f102b883 2309
4e860d0a 2310=item *
551e1d92
RB
2311
2312Take the opportunity to reconsider and redesign the interfaces.
2313
4e860d0a 2314=item *
f102b883 2315
551e1d92 2316In some cases the 'application' can then be reduced to a small
f102b883
TC
2317
2318fragment of code built on top of the reusable modules. In these cases
2319the application could invoked as:
2320
5a964f20 2321 % perl -e 'use Module::Name; method(@ARGV)' ...
f102b883 2322or
5a964f20 2323 % perl -mModule::Name ... (in perl5.002 or higher)
f102b883
TC
2324
2325=back
2326
2327=head1 NOTE
2328
2329Perl does not enforce private and public parts of its modules as you may
2330have been used to in other languages like C++, Ada, or Modula-17. Perl
2331doesn't have an infatuation with enforced privacy. It would prefer
2332that you stayed out of its living room because you weren't invited, not
2333because it has a shotgun.
2334
2335The module and its user have a contract, part of which is common law,
2336and part of which is "written". Part of the common law contract is
2337that a module doesn't pollute any namespace it wasn't asked to. The
2338written contract for the module (A.K.A. documentation) may make other
2339provisions. But then you know when you C<use RedefineTheWorld> that
2340you're redefining the world and willing to take the consequences.