This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
doubled words in pods (from Simon Cozens
[perl5.git] / pod / perlmodlib.pod
CommitLineData
f102b883
TC
1=head1 NAME
2
3perlmodlib - constructing new Perl modules and finding existing ones
4
5=head1 DESCRIPTION
6
7=head1 THE PERL MODULE LIBRARY
8
19799a22
GS
9Many modules are included the Perl distribution. These are described
10below, and all end in F<.pm>. You may discover compiled library
11file (usually ending in F<.so>) or small pieces of modules to be
12autoloaded (ending in F<.al>); these were automatically generated
13by the installation process. You may also discover files in the
14library directory that end in either F<.pl> or F<.ph>. These are
15old libraries supplied so that old programs that use them still
16run. The F<.pl> files will all eventually be converted into standard
17modules, and the F<.ph> files made by B<h2ph> will probably end up
18as extension modules made by B<h2xs>. (Some F<.ph> values may
19already be available through the POSIX, Errno, or Fcntl modules.)
20The B<pl2pm> file in the distribution may help in your conversion,
21but it's just a mechanical process and therefore far from bulletproof.
f102b883
TC
22
23=head2 Pragmatic Modules
24
19799a22
GS
25They work somewhat like compiler directives (pragmata) in that they
26tend to affect the compilation of your program, and thus will usually
27work well only when used within a C<use>, or C<no>. Most of these
28are lexically scoped, so an inner BLOCK may countermand them
29by saying:
f102b883
TC
30
31 no integer;
32 no strict 'refs';
4438c4b7 33 no warnings;
f102b883
TC
34
35which lasts until the end of that BLOCK.
36
19799a22
GS
37Some pragmas are lexically scoped--typically those that affect the
38C<$^H> hints variable. Others affect the current package instead,
77ca0c92 39like C<use vars> and C<use subs>, which allow you to predeclare a
19799a22
GS
40variables or subroutines within a particular I<file> rather than
41just a block. Such declarations are effective for the entire file
42for which they were declared. You cannot rescind them with C<no
43vars> or C<no subs>.
f102b883
TC
44
45The following pragmas are defined (and have their own documentation).
46
47=over 12
48
09bef843
SB
49=item attributes
50
9e107c59 51Get/set subroutine or variable attributes
09bef843 52
19799a22 53=item attrs
f102b883 54
9e107c59 55Set/get attributes of a subroutine (deprecated)
19799a22
GS
56
57=item autouse
58
9e107c59 59Postpone load of modules until a function is used
19799a22
GS
60
61=item base
62
63Establish IS-A relationship with base class at compile time
f102b883
TC
64
65=item blib
66
19799a22
GS
67Use MakeMaker's uninstalled version of a package
68
9e107c59
GS
69=item caller
70
71Inherit pragmatic attributes from caller's context
72
73=item charnames
74
75Define character names for C<\N{named}> string literal escape.
76
19799a22
GS
77=item constant
78
9e107c59 79Declare constants
f102b883
TC
80
81=item diagnostics
82
9e107c59 83Force verbose warning diagnostics
19799a22
GS
84
85=item fields
86
9e107c59 87Declare a class's attribute fields at compile-time
19799a22
GS
88
89=item filetest
90
9e107c59 91Control the filetest operators like C<-r>, C<-w> for AFS, etc.
f102b883
TC
92
93=item integer
94
9e107c59 95Compute arithmetic in integer instead of double
f102b883
TC
96
97=item less
98
9e107c59 99Request less of something from the compiler (unimplemented)
f102b883
TC
100
101=item lib
102
9e107c59 103Manipulate @INC at compile time
f102b883
TC
104
105=item locale
106
9e107c59 107Use or avoid POSIX locales for built-in operations
f102b883
TC
108
109=item ops
110
9e107c59 111Restrict unsafe operations when compiling
f102b883
TC
112
113=item overload
114
9e107c59 115Overload Perl operations
f102b883 116
b3eb6a9b
GS
117=item re
118
9e107c59 119Alter regular expression behavior
b3eb6a9b 120
f102b883
TC
121=item sigtrap
122
9e107c59 123Enable simple signal handling
f102b883
TC
124
125=item strict
126
9e107c59 127Restrict unsafe constructs
f102b883
TC
128
129=item subs
130
9e107c59 131Predeclare subroutine names
f102b883 132
19799a22 133=item utf8
f102b883 134
9e107c59 135Turn on UTF-8 and Unicode support
f102b883
TC
136
137=item vars
138
9e107c59 139Predeclare global variable names (obsoleted by our())
f102b883 140
4438c4b7 141=item warnings
0453d815 142
9e107c59 143Control optional warnings
19799a22 144
f102b883
TC
145=back
146
147=head2 Standard Modules
148
149Standard, bundled modules are all expected to behave in a well-defined
150manner with respect to namespace pollution because they use the
151Exporter module. See their own documentation for details.
152
153=over 12
154
155=item AnyDBM_File
156
9e107c59 157Provide framework for multiple DBM libraries
f102b883
TC
158
159=item AutoLoader
160
9e107c59 161Load subroutines only on demand
f102b883
TC
162
163=item AutoSplit
164
9e107c59 165Split a package for autoloading
f102b883 166
19799a22
GS
167=item B
168
9e107c59 169Guts of the Perl code generator (aka compiler)
19799a22
GS
170
171=item B::Asmdata
172
173Autogenerated data about Perl ops, used to generate bytecode
174
175=item B::Assembler
176
177Assemble Perl bytecode
178
179=item B::Bblock
180
181Walk basic blocks
182
183=item B::Bytecode
184
185Perl compiler's bytecode backend
186
187=item B::C
188
189Perl compiler's C backend
190
191=item B::CC
192
193Perl compiler's optimized C translation backend
194
195=item B::Debug
196
197Walk Perl syntax tree, printing debug info about ops
198
199=item B::Deparse
200
9e107c59 201Perl compiler backend to produce Perl code
19799a22
GS
202
203=item B::Disassembler
204
205Disassemble Perl bytecode
206
207=item B::Lint
208
9e107c59 209Module to catch dubious constructs
19799a22
GS
210
211=item B::Showlex
212
213Show lexical variables used in functions or files
214
215=item B::Stackobj
216
217Helper module for CC backend
218
9e107c59
GS
219B::Stash -- XXX NFI XXX
220
19799a22
GS
221=item B::Terse
222
223Walk Perl syntax tree, printing terse info about ops
224
225=item B::Xref
226
227Generates cross reference reports for Perl programs
228
f102b883
TC
229=item Benchmark
230
9e107c59
GS
231Benchmark running times of code
232
233=item ByteLoader
234
235Load byte-compiled Perl code
f102b883 236
19799a22
GS
237=item CGI
238
9e107c59 239Simple Common Gateway Interface class
19799a22
GS
240
241=item CGI::Apache
242
243Make things work with CGI.pm against Perl-Apache API
244
245=item CGI::Carp
246
247CGI routines for writing to the HTTPD (or other) error log
248
249=item CGI::Cookie
250
251Interface to Netscape Cookies
252
253=item CGI::Fast
254
255CGI Interface for Fast CGI
256
9e107c59
GS
257=item CGI::Pretty
258
259Module to produce nicely formatted HTML code
260
19799a22
GS
261=item CGI::Push
262
263Simple Interface to Server Push
264
265=item CGI::Switch
266
267Try more than one constructors and return the first object available
268
f102b883
TC
269=item CPAN
270
9e107c59 271Query, download, and build Perl modules from CPAN sites
f102b883
TC
272
273=item CPAN::FirstTime
274
9e107c59 275Utility for CPAN::Config file initialization
f102b883
TC
276
277=item CPAN::Nox
278
19799a22 279Wrapper around CPAN.pm without using any XS module
f102b883
TC
280
281=item Carp
282
9e107c59
GS
283Act like warn/die from perspective of caller
284
285=item Carp::Heavy
286
287Carp guts
f102b883
TC
288
289=item Class::Struct
290
9e107c59 291Declare struct-like datatypes as Perl classes
f102b883
TC
292
293=item Config
294
9e107c59 295Access Perl configuration information
f102b883
TC
296
297=item Cwd
298
9e107c59 299Get pathname of current working directory
f102b883 300
19799a22
GS
301=item DB
302
9e107c59 303Programmatic interface to the Perl debugging API (experimental)
19799a22 304
f102b883
TC
305=item DB_File
306
19799a22
GS
307Perl5 access to Berkeley DB version 1.x
308
309=item Data::Dumper
310
9e107c59
GS
311Serialize Perl data structures
312
313=item Devel::DProf
314
315A Perl execution profiler
f102b883 316
f505c983
GS
317=item Devel::Peek
318
19799a22 319A data debugging tool for the XS programmer
f505c983 320
f102b883
TC
321=item Devel::SelfStubber
322
9e107c59 323Generate stubs for a SelfLoading module
f102b883
TC
324
325=item DirHandle
326
9e107c59 327Supply object methods for directory handles
f102b883 328
19799a22
GS
329=item Dumpvalue
330
9e107c59 331Provide screen dump of Perl data
19799a22 332
f102b883
TC
333=item DynaLoader
334
19799a22 335Dynamically load C libraries into Perl code
f102b883
TC
336
337=item English
338
9e107c59 339Use English (or awk) names for ugly punctuation variables
f102b883
TC
340
341=item Env
342
9e107c59 343Access environment variables as regular ones
19799a22
GS
344
345=item Errno
346
9e107c59 347Load the libc errno.h defines
f102b883
TC
348
349=item Exporter
350
9e107c59
GS
351Implement default import method for modules
352
353=item Exporter::Heavy
354
355Exporter guts
19799a22
GS
356
357=item ExtUtils::Command
358
9e107c59 359Utilities to replace common Unix commands in Makefiles etc.
f102b883
TC
360
361=item ExtUtils::Embed
362
9e107c59 363Utilities for embedding Perl in C/C++ programs
f102b883
TC
364
365=item ExtUtils::Install
366
9e107c59 367Install files from here to there
f102b883 368
19799a22
GS
369=item ExtUtils::Installed
370
371Inventory management of installed modules
372
f102b883
TC
373=item ExtUtils::Liblist
374
9e107c59
GS
375Determine libraries to use and how to use them
376
377=item ExtUtils::MM_Cygwin
378
379Methods to override Unix behavior in ExtUtils::MakeMaker
f102b883
TC
380
381=item ExtUtils::MM_OS2
382
9e107c59 383Methods to override Unix behavior in ExtUtils::MakeMaker
f102b883
TC
384
385=item ExtUtils::MM_Unix
386
9e107c59 387Methods used by ExtUtils::MakeMaker
f102b883
TC
388
389=item ExtUtils::MM_VMS
390
9e107c59 391Methods to override Unix behavior in ExtUtils::MakeMaker
19799a22
GS
392
393=item ExtUtils::MM_Win32
394
9e107c59 395Methods to override Unix behavior in ExtUtils::MakeMaker
f102b883
TC
396
397=item ExtUtils::MakeMaker
398
9e107c59 399Create an extension Makefile
f102b883
TC
400
401=item ExtUtils::Manifest
402
9e107c59 403Utilities to write and check a MANIFEST file
f102b883 404
9e107c59 405ExtUtils::Miniperl, writemain - Write the C code for perlmain.c
19799a22 406
f102b883
TC
407=item ExtUtils::Mkbootstrap
408
9e107c59 409Make a bootstrap file for use by DynaLoader
f102b883
TC
410
411=item ExtUtils::Mksymlists
412
9e107c59 413Write linker options files for dynamic extension
f102b883 414
19799a22
GS
415=item ExtUtils::Packlist
416
9e107c59 417Manage .packlist files
19799a22 418
f102b883
TC
419=item ExtUtils::testlib
420
9e107c59 421Add blib/* directories to @INC
f102b883 422
b6c543e3
IZ
423=item Fatal
424
9e107c59 425Replace functions with equivalents which succeed or die
b6c543e3 426
f102b883
TC
427=item Fcntl
428
9e107c59 429Load the libc fcntl.h defines
f102b883
TC
430
431=item File::Basename
432
9e107c59
GS
433Split a pathname into pieces
434
435=item File::CheckTree
436
437Run many filetest checks on a tree
f102b883 438
f102b883
TC
439=item File::Compare
440
19799a22 441Compare files or filehandles
f102b883
TC
442
443=item File::Copy
444
19799a22
GS
445Copy files or filehandles
446
447=item File::DosGlob
448
9e107c59 449DOS-like globbing and then some
f102b883
TC
450
451=item File::Find
452
9e107c59
GS
453Traverse a file tree
454
455=item File::Glob
456
457Perl extension for BSD filename globbing
f102b883
TC
458
459=item File::Path
460
9e107c59 461Create or remove a series of directories
f102b883 462
f505c983
GS
463=item File::Spec
464
9e107c59 465Portably perform operations on file names
f505c983
GS
466
467=item File::Spec::Functions
468
9e107c59 469Portably perform operations on file names
19799a22
GS
470
471=item File::Spec::Mac
472
473File::Spec for MacOS
474
475=item File::Spec::OS2
476
9e107c59 477Methods for OS/2 file specs
19799a22
GS
478
479=item File::Spec::Unix
480
9e107c59 481Methods used by File::Spec
19799a22
GS
482
483=item File::Spec::VMS
484
9e107c59 485Methods for VMS file specs
19799a22
GS
486
487=item File::Spec::Win32
488
9e107c59 489Methods for Win32 file specs
f505c983 490
f102b883
TC
491=item File::stat
492
9e107c59 493By-name interface to Perl's built-in stat() functions
f102b883
TC
494
495=item FileCache
496
9e107c59 497Keep more files open than the system permits
f102b883
TC
498
499=item FileHandle
500
9e107c59 501Supply object methods for filehandles
f102b883
TC
502
503=item FindBin
504
9e107c59 505Locate installation directory of running Perl program
f102b883
TC
506
507=item GDBM_File
508
9e107c59 509Access to the gdbm library
f102b883
TC
510
511=item Getopt::Long
512
9e107c59 513Extended processing of command line options
f102b883
TC
514
515=item Getopt::Std
516
19799a22 517Process single-character switches with switch clustering
f102b883
TC
518
519=item I18N::Collate
520
9e107c59 521Compare 8-bit scalar data according to current locale
f102b883
TC
522
523=item IO
524
9e107c59 525Front-end to load various IO modules
f102b883 526
19799a22
GS
527=item IO::Dir
528
9e107c59 529Supply object methods for directory handles
19799a22 530
f102b883
TC
531=item IO::File
532
9e107c59 533Supply object methods for filehandles
f102b883
TC
534
535=item IO::Handle
536
9e107c59 537Supply object methods for I/O handles
f102b883
TC
538
539=item IO::Pipe
540
9e107c59 541Supply object methods for pipes
f102b883 542
19799a22
GS
543=item IO::Poll
544
545Object interface to system poll call
546
f102b883
TC
547=item IO::Seekable
548
9e107c59 549Supply seek based methods for I/O objects
f102b883
TC
550
551=item IO::Select
552
553OO interface to the select system call
554
555=item IO::Socket
556
19799a22
GS
557Object interface to socket communications
558
559=item IO::Socket::INET
560
561Object interface for AF_INET domain sockets
562
563=item IO::Socket::UNIX
564
565Object interface for AF_UNIX domain sockets
566
567=item IPC::Msg
568
569SysV Msg IPC object class
f102b883
TC
570
571=item IPC::Open2
572
9e107c59 573Open a process for both reading and writing
f102b883
TC
574
575=item IPC::Open3
576
9e107c59 577Open a process for reading, writing, and error handling
f102b883 578
19799a22
GS
579=item IPC::Semaphore
580
581SysV Semaphore IPC object class
582
583=item IPC::SysV
584
585SysV IPC constants
586
f102b883
TC
587=item Math::BigFloat
588
19799a22 589Arbitrary length float math package
f102b883
TC
590
591=item Math::BigInt
592
19799a22 593Arbitrary size integer math package
f102b883
TC
594
595=item Math::Complex
596
9e107c59 597Complex numbers and associated mathematical functions
f102b883 598
404b15a1
CS
599=item Math::Trig
600
9e107c59 601Trigonometric functions
f102b883
TC
602
603=item Net::Ping
604
9e107c59 605Check a remote host for reachability
f102b883
TC
606
607=item Net::hostent
608
9e107c59 609By-name interface to Perl's built-in gethost*() functions
f102b883
TC
610
611=item Net::netent
612
9e107c59 613By-name interface to Perl's built-in getnet*() functions
f102b883
TC
614
615=item Net::protoent
616
9e107c59 617By-name interface to Perl's built-in getproto*() functions
f102b883
TC
618
619=item Net::servent
620
9e107c59 621By-name interface to Perl's built-in getserv*() functions
f102b883 622
19799a22 623=item O
f102b883 624
19799a22 625Generic interface to Perl Compiler backends
f102b883 626
19799a22 627=item Opcode
f102b883 628
9e107c59 629Disable named opcodes when compiling Perl code
f102b883
TC
630
631=item POSIX
632
19799a22
GS
633Perl interface to IEEE Std 1003.1
634
9e107c59
GS
635=item Pod::Checker
636
637Check pod documents for syntax errors
638
19799a22
GS
639=item Pod::Html
640
9e107c59
GS
641Module to convert pod files to HTML
642
643=item Pod::InputObjects
644
645Manage POD objects
646
647=item Pod::Man
648
649Convert POD data to formatted *roff input
650
651=item Pod::Parser
652
653Base class for creating POD filters and translators
654
655=item Pod::Select
656
657Extract selected sections of POD from input
19799a22
GS
658
659=item Pod::Text
660
9e107c59
GS
661Convert POD data to formatted ASCII text
662
663=item Pod::Text::Color
664
665Convert POD data to formatted color ASCII text
666
667=item Pod::Usage
668
669Print a usage message from embedded pod documentation
f102b883
TC
670
671=item SDBM_File
672
19799a22 673Tied access to sdbm files
f102b883
TC
674
675=item Safe
676
19799a22 677Compile and execute code in restricted compartments
f102b883
TC
678
679=item Search::Dict
680
9e107c59 681Search for key in dictionary file
f102b883
TC
682
683=item SelectSaver
684
9e107c59 685Save and restore selected file handle
f102b883
TC
686
687=item SelfLoader
688
9e107c59 689Load functions only on demand
f102b883
TC
690
691=item Shell
692
9e107c59 693Run shell commands transparently within Perl
f102b883
TC
694
695=item Socket
696
9e107c59 697Load the libc socket.h defines and structure manipulators
f102b883
TC
698
699=item Symbol
700
9e107c59 701Manipulate Perl symbols and their names
f102b883
TC
702
703=item Sys::Hostname
704
19799a22 705Try every conceivable way to get hostname
f102b883
TC
706
707=item Sys::Syslog
708
9e107c59 709Interface to the libc syslog(3) calls
f102b883
TC
710
711=item Term::Cap
712
9e107c59 713Termcap interface
f102b883
TC
714
715=item Term::Complete
716
9e107c59 717Word completion module
f102b883
TC
718
719=item Term::ReadLine
720
9e107c59 721Interface to various `readline' packages.
19799a22
GS
722
723=item Test
724
9e107c59 725Provides a simple framework for writing test scripts
f102b883
TC
726
727=item Test::Harness
728
9e107c59 729Run Perl standard test scripts with statistics
f102b883
TC
730
731=item Text::Abbrev
732
9e107c59 733Create an abbreviation table from a list
f102b883
TC
734
735=item Text::ParseWords
736
9e107c59 737Parse text into a list of tokens or array of arrays
f102b883
TC
738
739=item Text::Soundex
740
9e107c59 741Implementation of the Soundex Algorithm as described by Knuth
f102b883 742
9e107c59 743Text::Tabs -- expand and unexpand tabs per expand(1) and unexpand(1)
f102b883
TC
744
745=item Text::Wrap
746
9e107c59 747Line wrapping to form simple paragraphs
19799a22
GS
748
749=item Tie::Array
750
9e107c59 751Base class for tied arrays
19799a22
GS
752
753=item Tie::Handle
754
9e107c59 755Base class definitions for tied handles
19799a22 756
9e107c59 757=item Tie::Hash
f102b883 758
9e107c59 759Base class definitions for tied hashes
f102b883
TC
760
761=item Tie::RefHash
762
9e107c59 763Use references as hash keys
f102b883 764
9e107c59 765=item Tie::Scalar
f102b883 766
9e107c59 767Base class definitions for tied scalars
f102b883
TC
768
769=item Tie::SubstrHash
770
19799a22 771Fixed-table-size, fixed-key-length hashing
f102b883
TC
772
773=item Time::Local
774
9e107c59 775Efficiently compute time from local and GMT time
f102b883
TC
776
777=item Time::gmtime
778
9e107c59 779By-name interface to Perl's built-in gmtime() function
f102b883
TC
780
781=item Time::localtime
782
9e107c59 783By-name interface to Perl's built-in localtime() function
f102b883
TC
784
785=item Time::tm
786
9e107c59 787Internal object used by Time::gmtime and Time::localtime
f102b883
TC
788
789=item UNIVERSAL
790
9e107c59 791Base class for ALL classes (blessed references)
f102b883
TC
792
793=item User::grent
794
9e107c59 795By-name interface to Perl's built-in getgr*() functions
f102b883
TC
796
797=item User::pwent
798
9e107c59 799By-name interface to Perl's built-in getpw*() functions
f102b883
TC
800
801=back
802
19799a22
GS
803To find out I<all> modules installed on your system, including
804those without documentation or outside the standard release,
6175e926 805just do this:
f102b883 806
5a964f20 807 % find `perl -e 'print "@INC"'` -name '*.pm' -print
f102b883 808
6175e926
GS
809To get a log of all module distributions which have been installed
810since perl was installed, just do:
811
812 % perldoc perllocal
813
814Modules should all have their own documentation installed and accessible
815via your system man(1) command, or via the C<perldoc> program. If you do
816not have a B<find>
19799a22
GS
817program, you can use the Perl B<find2perl> program instead, which
818generates Perl code as output you can run through perl. If you
819have a B<man> program but it doesn't find your modules, you'll have
6175e926 820to fix your manpath. See L<perl> for details.
f102b883
TC
821
822=head2 Extension Modules
823
19799a22
GS
824Extension modules are written in C (or a mix of Perl and C). They
825are usually dynamically loaded into Perl if and when you need them,
106325ad 826but may also be linked in statically. Supported extension modules
19799a22 827include Socket, Fcntl, and POSIX.
f102b883
TC
828
829Many popular C extension modules do not come bundled (at least, not
19799a22
GS
830completely) due to their sizes, volatility, or simply lack of time
831for adequate testing and configuration across the multitude of
832platforms on which Perl was beta-tested. You are encouraged to
833look for them on CPAN (described below), or using web search engines
834like Alta Vista or Deja News.
f102b883
TC
835
836=head1 CPAN
837
19799a22
GS
838CPAN stands for Comprehensive Perl Archive Network; it's a globally
839replicated trove of Perl materials, including documentation, style
840guides, tricks and trap, alternate ports to non-Unix systems and
841occasional binary distributions for these. Search engines for
842CPAN can be found at http://cpan.perl.com/ and at
843http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
844
845Most importantly, CPAN includes around a thousand unbundled modules,
846some of which require a C compiler to build. Major categories of
847modules are:
f102b883
TC
848
849=over
850
851=item *
852Language Extensions and Documentation Tools
853
854=item *
855Development Support
856
857=item *
858Operating System Interfaces
859
860=item *
861Networking, Device Control (modems) and InterProcess Communication
862
863=item *
864Data Types and Data Type Utilities
865
866=item *
867Database Interfaces
868
869=item *
870User Interfaces
871
872=item *
873Interfaces to / Emulations of Other Programming Languages
874
875=item *
876File Names, File Systems and File Locking (see also File Handles)
877
878=item *
879String Processing, Language Text Processing, Parsing, and Searching
880
881=item *
882Option, Argument, Parameter, and Configuration File Processing
883
884=item *
885Internationalization and Locale
886
887=item *
888Authentication, Security, and Encryption
889
890=item *
891World Wide Web, HTML, HTTP, CGI, MIME
892
893=item *
894Server and Daemon Utilities
895
896=item *
897Archiving and Compression
898
899=item *
900Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
901
902=item *
903Mail and Usenet News
904
905=item *
906Control Flow Utilities (callbacks and exceptions etc)
907
908=item *
909File Handle and Input/Output Stream Utilities
910
911=item *
912Miscellaneous Modules
913
914=back
915
19799a22 916Registered CPAN sites as of this writing include the following.
f102b883
TC
917You should try to choose one close to you:
918
919=over
920
19799a22 921=item Africa
f102b883 922
0974df93
JH
923 South Africa ftp://ftp.is.co.za/programming/perl/CPAN/
924 ftp://ftp.saix.net/pub/CPAN/
925 ftp://ftp.sun.ac.za/CPAN/
be94a901 926 ftp://ftpza.co.za/pub/mirrors/cpan/
f102b883 927
6cecdcac 928
19799a22 929=item Asia
f102b883 930
0974df93 931 China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
6cecdcac 932 Hong Kong ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
0974df93
JH
933 Indonesia ftp://malone.piksi.itb.ac.id/pub/CPAN/
934 Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
935 Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/
be94a901
GS
936 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
937 ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
938 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
19799a22 939 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
be94a901 940 ftp://mirror.nucba.ac.jp/mirror/Perl/
6cecdcac 941 Saudi-Arabia ftp://ftp.isu.net.sa/pub/CPAN/
0974df93
JH
942 Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
943 South Korea ftp://ftp.bora.net/pub/CPAN/
944 ftp://ftp.kornet.net/pub/CPAN/
be94a901 945 ftp://ftp.nuri.net/pub/CPAN/
0974df93
JH
946 Taiwan ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
947 ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/
be94a901 948 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
6cecdcac
GS
949 Thailand ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
950
f102b883 951
19799a22 952=item Australasia
f102b883 953
0974df93 954 Australia ftp://cpan.topend.com.au/pub/CPAN/
6cecdcac 955 ftp://ftp.labyrinth.net.au/pub/perl-CPAN/
be94a901
GS
956 ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
957 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
0974df93 958 New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
be94a901
GS
959 ftp://sunsite.net.nz/pub/languages/perl/CPAN/
960
6cecdcac 961
0974df93 962=item Central America
be94a901 963
0974df93 964 Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
f102b883 965
6cecdcac 966
19799a22 967=item Europe
f102b883 968
0974df93
JH
969 Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
970 Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
971 Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/
972 Croatia ftp://ftp.linux.hr/pub/CPAN/
973 Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
be94a901 974 ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
0974df93
JH
975 Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
976 Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/
977 Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/
6cecdcac
GS
978 France ftp://ftp.grolier.fr/pub/perl/CPAN/
979 ftp://ftp.lip6.fr/pub/perl/CPAN/
be94a901
GS
980 ftp://ftp.oleane.net/pub/mirrors/CPAN/
981 ftp://ftp.pasteur.fr/pub/computing/CPAN/
0974df93 982 ftp://ftp.uvsq.fr/pub/perl/CPAN/
6cecdcac
GS
983 German ftp://ftp.gigabell.net/pub/CPAN/
984 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
985 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
986 ftp://ftp.gmd.de/packages/CPAN/
987 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
988 ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
989 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
990 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
991 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
992 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
0974df93 993 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
6cecdcac 994 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
be94a901
GS
995 ftp://ftp.gmd.de/packages/CPAN/
996 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
6cecdcac 997 ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
be94a901
GS
998 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
999 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
1000 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
1001 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
0974df93
JH
1002 Greece ftp://ftp.ntua.gr/pub/lang/perl/
1003 Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
1004 Iceland ftp://ftp.gm.is/pub/CPAN/
1005 Ireland ftp://cpan.indigo.ie/pub/CPAN/
1006 ftp://sunsite.compapp.dcu.ie/pub/perl/
1007 Italy ftp://cis.uniRoma2.it/CPAN/
be94a901 1008 ftp://ftp.flashnet.it/pub/CPAN/
19799a22 1009 ftp://ftp.unina.it/pub/Other/CPAN/
be94a901 1010 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
0974df93 1011 Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/
be94a901 1012 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
0974df93 1013 Norway ftp://ftp.uit.no/pub/languages/perl/cpan/
be94a901 1014 ftp://sunsite.uio.no/pub/languages/perl/CPAN/
6cecdcac 1015 Poland ftp://ftp.man.torun.pl/pub/CPAN/
be94a901
GS
1016 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
1017 ftp://sunsite.icm.edu.pl/pub/CPAN/
0974df93 1018 Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
19799a22 1019 ftp://ftp.ist.utl.pt/pub/CPAN/
be94a901 1020 ftp://ftp.ua.pt/pub/CPAN/
6cecdcac 1021 Romania ftp://ftp.dnttm.ro/pub/CPAN/
19799a22 1022 Russia ftp://ftp.chg.ru/pub/lang/perl/CPAN/
be94a901 1023 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
0974df93
JH
1024 Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/
1025 Slovenia ftp://ftp.arnes.si/software/perl/CPAN/
1026 Spain ftp://ftp.etse.urv.es/pub/perl/
be94a901 1027 ftp://ftp.rediris.es/mirror/CPAN/
0974df93
JH
1028 Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/
1029 Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
1030 Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
1031 United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
be94a901 1032 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
0974df93 1033 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
be94a901
GS
1034 ftp://ftp.plig.org/pub/CPAN/
1035 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
f102b883 1036
6cecdcac 1037
19799a22 1038=item North America
f102b883 1039
0974df93 1040 Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
19799a22 1041 California ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
0974df93 1042 ftp://cpan.valueclick.com/CPAN/
19799a22 1043 ftp://ftp.cdrom.com/pub/perl/CPAN/
6cecdcac 1044 http://download.sourceforge.net/mirrors/CPAN/
0974df93
JH
1045 Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
1046 Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
6cecdcac 1047 Georgia ftp://ftp.twoguys.org/CPAN/
0974df93
JH
1048 Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
1049 Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
be94a901 1050 ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
0974df93
JH
1051 Kentucky ftp://ftp.uky.edu/CPAN/
1052 Manitoba ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
1053 Massachusetts ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
be94a901 1054 ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
19799a22 1055 Mexico ftp://ftp.msg.com.mx/pub/CPAN/
0974df93
JH
1056 New York ftp://ftp.deao.net/pub/CPAN/
1057 ftp://ftp.rge.com/pub/languages/perl/
0974df93 1058 North Carolina ftp://ftp.duke.edu/pub/perl/
6cecdcac 1059 Nova Scotia ftp://cpan.chebucto.ns.ca/pub/CPAN/
0974df93 1060 Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/
19799a22 1061 Ontario ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
0974df93
JH
1062 Oregon ftp://ftp.orst.edu/pub/packages/CPAN/
1063 Pennsylvania ftp://ftp.epix.net/pub/languages/perl/
1064 Tennessee ftp://ftp.sunsite.utk.edu/pub/CPAN/
1065 Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/
6cecdcac 1066 ftp://jhcloos.com/pub/mirror/CPAN/
0974df93
JH
1067 Utah ftp://mirror.xmission.com/CPAN/
1068 Virginia ftp://ftp.perl.org/pub/perl/CPAN/
be94a901 1069 ftp://ruff.cs.jmu.edu/pub/CPAN/
19799a22 1070 Washington ftp://ftp-mirror.internap.com/pub/CPAN/
6cecdcac 1071 ftp://ftp.llarian.net/pub/CPAN/
19799a22 1072 ftp://ftp.spu.edu/pub/CPAN/
f102b883 1073
6cecdcac 1074
19799a22 1075=item South America
f102b883 1076
0974df93
JH
1077 Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/
1078 ftp://ftp.matrix.com.br/pub/perl/
6cecdcac 1079 Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/
f102b883
TC
1080
1081=back
1082
1083For an up-to-date listing of CPAN sites,
6cecdcac 1084see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
f102b883
TC
1085
1086=head1 Modules: Creation, Use, and Abuse
1087
1088(The following section is borrowed directly from Tim Bunce's modules
1089file, available at your nearest CPAN site.)
1090
1091Perl implements a class using a package, but the presence of a
1092package doesn't imply the presence of a class. A package is just a
1093namespace. A class is a package that provides subroutines that can be
1094used as methods. A method is just a subroutine that expects, as its
1095first argument, either the name of a package (for "static" methods),
1096or a reference to something (for "virtual" methods).
1097
1098A module is a file that (by convention) provides a class of the same
1099name (sans the .pm), plus an import method in that class that can be
1100called to fetch exported symbols. This module may implement some of
1101its methods by loading dynamic C or C++ objects, but that should be
1102totally transparent to the user of the module. Likewise, the module
1103might set up an AUTOLOAD function to slurp in subroutine definitions on
1104demand, but this is also transparent. Only the F<.pm> file is required to
1105exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1106the AUTOLOAD mechanism.
1107
1108=head2 Guidelines for Module Creation
1109
1110=over 4
1111
1112=item Do similar modules already exist in some form?
1113
1114If so, please try to reuse the existing modules either in whole or
1115by inheriting useful features into a new class. If this is not
1116practical try to get together with the module authors to work on
1117extending or enhancing the functionality of the existing modules.
1118A perfect example is the plethora of packages in perl4 for dealing
1119with command line options.
1120
1121If you are writing a module to expand an already existing set of
1122modules, please coordinate with the author of the package. It
1123helps if you follow the same naming scheme and module interaction
1124scheme as the original author.
1125
1126=item Try to design the new module to be easy to extend and reuse.
1127
9f1b1f2d
GS
1128Try to C<use warnings;> (or C<use warnings qw(...);>).
1129Remember that you can add C<no warnings qw(...);> to individual blocks
1130of code that need less warnings.
19799a22 1131
f102b883
TC
1132Use blessed references. Use the two argument form of bless to bless
1133into the class name given as the first parameter of the constructor,
1134e.g.,:
1135
1136 sub new {
1137 my $class = shift;
1138 return bless {}, $class;
1139 }
1140
1141or even this if you'd like it to be used as either a static
1142or a virtual method.
1143
1144 sub new {
1145 my $self = shift;
1146 my $class = ref($self) || $self;
1147 return bless {}, $class;
1148 }
1149
1150Pass arrays as references so more parameters can be added later
1151(it's also faster). Convert functions into methods where
1152appropriate. Split large methods into smaller more flexible ones.
1153Inherit methods from other modules if appropriate.
1154
1155Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
19799a22 1156Generally you can delete the C<eq 'FOO'> part with no harm at all.
f102b883
TC
1157Let the objects look after themselves! Generally, avoid hard-wired
1158class names as far as possible.
1159
c47ff5f1
GS
1160Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1161C<< $r->func() >> would work (see L<perlbot> for more details).
f102b883
TC
1162
1163Use autosplit so little used or newly added functions won't be a
5a964f20 1164burden to programs that don't use them. Add test functions to
f102b883
TC
1165the module after __END__ either using AutoSplit or by saying:
1166
1167 eval join('',<main::DATA>) || die $@ unless caller();
1168
1169Does your module pass the 'empty subclass' test? If you say
19799a22 1170C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
f102b883
TC
1171to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1172does your application still work if you change: C<$obj = new YOURCLASS;>
1173into: C<$obj = new SUBCLASS;> ?
1174
1175Avoid keeping any state information in your packages. It makes it
1176difficult for multiple other packages to use yours. Keep state
1177information in objects.
1178
19799a22
GS
1179Always use B<-w>.
1180
1181Try to C<use strict;> (or C<use strict qw(...);>).
f102b883 1182Remember that you can add C<no strict qw(...);> to individual blocks
19799a22
GS
1183of code that need less strictness.
1184
1185Always use B<-w>.
1186
f102b883
TC
1187Follow the guidelines in the perlstyle(1) manual.
1188
19799a22
GS
1189Always use B<-w>.
1190
f102b883
TC
1191=item Some simple style guidelines
1192
5a964f20 1193The perlstyle manual supplied with Perl has many helpful points.
f102b883
TC
1194
1195Coding style is a matter of personal taste. Many people evolve their
1196style over several years as they learn what helps them write and
1197maintain good code. Here's one set of assorted suggestions that
1198seem to be widely used by experienced developers:
1199
1200Use underscores to separate words. It is generally easier to read
1201$var_names_like_this than $VarNamesLikeThis, especially for
1202non-native speakers of English. It's also a simple rule that works
1203consistently with VAR_NAMES_LIKE_THIS.
1204
1205Package/Module names are an exception to this rule. Perl informally
1206reserves lowercase module names for 'pragma' modules like integer
1207and strict. Other modules normally begin with a capital letter and
1208use mixed case with no underscores (need to be short and portable).
1209
1210You may find it helpful to use letter case to indicate the scope
1211or nature of a variable. For example:
1212
5a964f20 1213 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
f102b883
TC
1214 $Some_Caps_Here package-wide global/static
1215 $no_caps_here function scope my() or local() variables
1216
1217Function and method names seem to work best as all lowercase.
c47ff5f1 1218e.g., C<< $obj->as_string() >>.
f102b883
TC
1219
1220You can use a leading underscore to indicate that a variable or
1221function should not be used outside the package that defined it.
1222
1223=item Select what to export.
1224
1225Do NOT export method names!
1226
1227Do NOT export anything else by default without a good reason!
1228
1229Exports pollute the namespace of the module user. If you must
1230export try to use @EXPORT_OK in preference to @EXPORT and avoid
1231short or common names to reduce the risk of name clashes.
1232
1233Generally anything not exported is still accessible from outside the
c47ff5f1 1234module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
f102b883
TC
1235syntax. By convention you can use a leading underscore on names to
1236indicate informally that they are 'internal' and not for public use.
1237
1238(It is actually possible to get private functions by saying:
1239C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1240directly as a method, because a method must have a name in the symbol
1241table.)
1242
1243As a general rule, if the module is trying to be object oriented
1244then export nothing. If it's just a collection of functions then
1245@EXPORT_OK anything but use @EXPORT with caution.
1246
1247=item Select a name for the module.
1248
1249This name should be as descriptive, accurate, and complete as
1250possible. Avoid any risk of ambiguity. Always try to use two or
1251more whole words. Generally the name should reflect what is special
1252about what the module does rather than how it does it. Please use
1253nested module names to group informally or categorize a module.
1254There should be a very good reason for a module not to have a nested name.
1255Module names should begin with a capital letter.
1256
1257Having 57 modules all called Sort will not make life easy for anyone
1258(though having 23 called Sort::Quick is only marginally better :-).
1259Imagine someone trying to install your module alongside many others.
1260If in any doubt ask for suggestions in comp.lang.perl.misc.
1261
1262If you are developing a suite of related modules/classes it's good
1263practice to use nested classes with a common prefix as this will
1264avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1265Xyz::Model etc. Use the modules in this list as a naming guide.
1266
1267If adding a new module to a set, follow the original author's
1268standards for naming modules and the interface to methods in
1269those modules.
1270
1271To be portable each component of a module name should be limited to
127211 characters. If it might be used on MS-DOS then try to ensure each is
1273unique in the first 8 characters. Nested modules make this easier.
1274
1275=item Have you got it right?
1276
1277How do you know that you've made the right decisions? Have you
1278picked an interface design that will cause problems later? Have
1279you picked the most appropriate name? Do you have any questions?
1280
1281The best way to know for sure, and pick up many helpful suggestions,
1282is to ask someone who knows. Comp.lang.perl.misc is read by just about
1283all the people who develop modules and it's the best place to ask.
1284
1285All you need to do is post a short summary of the module, its
1286purpose and interfaces. A few lines on each of the main methods is
1287probably enough. (If you post the whole module it might be ignored
1288by busy people - generally the very people you want to read it!)
1289
1290Don't worry about posting if you can't say when the module will be
1291ready - just say so in the message. It might be worth inviting
1292others to help you, they may be able to complete it for you!
1293
1294=item README and other Additional Files.
1295
1296It's well known that software developers usually fully document the
1297software they write. If, however, the world is in urgent need of
1298your software and there is not enough time to write the full
1299documentation please at least provide a README file containing:
1300
1301=over 10
1302
1303=item *
1304A description of the module/package/extension etc.
1305
1306=item *
1307A copyright notice - see below.
1308
1309=item *
1310Prerequisites - what else you may need to have.
1311
1312=item *
1313How to build it - possible changes to Makefile.PL etc.
1314
1315=item *
1316How to install it.
1317
1318=item *
1319Recent changes in this release, especially incompatibilities
1320
1321=item *
1322Changes / enhancements you plan to make in the future.
1323
1324=back
1325
1326If the README file seems to be getting too large you may wish to
1327split out some of the sections into separate files: INSTALL,
1328Copying, ToDo etc.
1329
1330=over 4
1331
1332=item Adding a Copyright Notice.
1333
1334How you choose to license your work is a personal decision.
1335The general mechanism is to assert your Copyright and then make
1336a declaration of how others may copy/use/modify your work.
1337
1338Perl, for example, is supplied with two types of licence: The GNU
1339GPL and The Artistic Licence (see the files README, Copying, and
1340Artistic). Larry has good reasons for NOT just using the GNU GPL.
1341
1342My personal recommendation, out of respect for Larry, Perl, and the
5a964f20 1343Perl community at large is to state something simply like:
f102b883
TC
1344
1345 Copyright (c) 1995 Your Name. All rights reserved.
1346 This program is free software; you can redistribute it and/or
1347 modify it under the same terms as Perl itself.
1348
1349This statement should at least appear in the README file. You may
1350also wish to include it in a Copying file and your source files.
1351Remember to include the other words in addition to the Copyright.
1352
1353=item Give the module a version/issue/release number.
1354
1355To be fully compatible with the Exporter and MakeMaker modules you
1356should store your module's version number in a non-my package
1357variable called $VERSION. This should be a floating point
1358number with at least two digits after the decimal (i.e., hundredths,
1359e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
19799a22 1360See L<Exporter> for details.
f102b883
TC
1361
1362It may be handy to add a function or method to retrieve the number.
1363Use the number in announcements and archive file names when
1364releasing the module (ModuleName-1.02.tar.Z).
1365See perldoc ExtUtils::MakeMaker.pm for details.
1366
1367=item How to release and distribute a module.
1368
1369It's good idea to post an announcement of the availability of your
1370module (or the module itself if small) to the comp.lang.perl.announce
1371Usenet newsgroup. This will at least ensure very wide once-off
1372distribution.
1373
19799a22 1374If possible, register the module with CPAN. You should
f102b883
TC
1375include details of its location in your announcement.
1376
1377Some notes about ftp archives: Please use a long descriptive file
5a964f20 1378name that includes the version number. Most incoming directories
f102b883
TC
1379will not be readable/listable, i.e., you won't be able to see your
1380file after uploading it. Remember to send your email notification
1381message as soon as possible after uploading else your file may get
1382deleted automatically. Allow time for the file to be processed
1383and/or check the file has been processed before announcing its
1384location.
1385
1386FTP Archives for Perl Modules:
1387
6cecdcac 1388Follow the instructions and links on:
f102b883 1389
6cecdcac
GS
1390 http://www.perl.com/CPAN/modules/00modlist.long.html
1391 http://www.perl.com/CPAN/modules/04pause.html
f102b883
TC
1392
1393or upload to one of these sites:
1394
6cecdcac
GS
1395 https://pause.kbx.de/pause/
1396 http://pause.perl.org/pause/
f102b883 1397
6cecdcac 1398and notify <modules@perl.org>.
f102b883
TC
1399
1400By using the WWW interface you can ask the Upload Server to mirror
1401your modules from your ftp or WWW site into your own directory on
1402CPAN!
1403
1404Please remember to send me an updated entry for the Module list!
1405
1406=item Take care when changing a released module.
1407
7b8d334a
GS
1408Always strive to remain compatible with previous released versions.
1409Otherwise try to add a mechanism to revert to the
19799a22 1410old behavior if people rely on it. Document incompatible changes.
f102b883
TC
1411
1412=back
1413
1414=back
1415
1416=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1417
1418=over 4
1419
1420=item There is no requirement to convert anything.
1421
1422If it ain't broke, don't fix it! Perl 4 library scripts should
1423continue to work with no problems. You may need to make some minor
1424changes (like escaping non-array @'s in double quoted strings) but
1425there is no need to convert a .pl file into a Module for just that.
1426
1427=item Consider the implications.
1428
5a964f20 1429All Perl applications that make use of the script will need to
f102b883
TC
1430be changed (slightly) if the script is converted into a module. Is
1431it worth it unless you plan to make other changes at the same time?
1432
1433=item Make the most of the opportunity.
1434
1435If you are going to convert the script to a module you can use the
19799a22
GS
1436opportunity to redesign the interface. The guidelines for module
1437creation above include many of the issues you should consider.
f102b883
TC
1438
1439=item The pl2pm utility will get you started.
1440
1441This utility will read *.pl files (given as parameters) and write
1442corresponding *.pm files. The pl2pm utilities does the following:
1443
1444=over 10
1445
1446=item *
1447Adds the standard Module prologue lines
1448
1449=item *
1450Converts package specifiers from ' to ::
1451
1452=item *
1453Converts die(...) to croak(...)
1454
1455=item *
1456Several other minor changes
1457
1458=back
1459
1460Being a mechanical process pl2pm is not bullet proof. The converted
1461code will need careful checking, especially any package statements.
1462Don't delete the original .pl file till the new .pm one works!
1463
1464=back
1465
1466=head2 Guidelines for Reusing Application Code
1467
1468=over 4
1469
1470=item Complete applications rarely belong in the Perl Module Library.
1471
5a964f20 1472=item Many applications contain some Perl code that could be reused.
f102b883
TC
1473
1474Help save the world! Share your code in a form that makes it easy
1475to reuse.
1476
1477=item Break-out the reusable code into one or more separate module files.
1478
1479=item Take the opportunity to reconsider and redesign the interfaces.
1480
1481=item In some cases the 'application' can then be reduced to a small
1482
1483fragment of code built on top of the reusable modules. In these cases
1484the application could invoked as:
1485
5a964f20 1486 % perl -e 'use Module::Name; method(@ARGV)' ...
f102b883 1487or
5a964f20 1488 % perl -mModule::Name ... (in perl5.002 or higher)
f102b883
TC
1489
1490=back
1491
1492=head1 NOTE
1493
1494Perl does not enforce private and public parts of its modules as you may
1495have been used to in other languages like C++, Ada, or Modula-17. Perl
1496doesn't have an infatuation with enforced privacy. It would prefer
1497that you stayed out of its living room because you weren't invited, not
1498because it has a shotgun.
1499
1500The module and its user have a contract, part of which is common law,
1501and part of which is "written". Part of the common law contract is
1502that a module doesn't pollute any namespace it wasn't asked to. The
1503written contract for the module (A.K.A. documentation) may make other
1504provisions. But then you know when you C<use RedefineTheWorld> that
1505you're redefining the world and willing to take the consequences.