2 Generated by perlmodlib.PL -- DO NOT EDIT!
6 perlmodlib - constructing new Perl modules and finding existing ones
8 =head1 THE PERL MODULE LIBRARY
10 Many modules are included in the Perl distribution. These are described
11 below, and all end in F<.pm>. You may discover compiled library
12 files (usually ending in F<.so>) or small pieces of modules to be
13 autoloaded (ending in F<.al>); these were automatically generated
14 by the installation process. You may also discover files in the
15 library directory that end in either F<.pl> or F<.ph>. These are
16 old libraries supplied so that old programs that use them still
17 run. The F<.pl> files will all eventually be converted into standard
18 modules, and the F<.ph> files made by B<h2ph> will probably end up
19 as extension modules made by B<h2xs>. (Some F<.ph> values may
20 already be available through the POSIX, Errno, or Fcntl modules.)
21 The B<pl2pm> file in the distribution may help in your conversion,
22 but it's just a mechanical process and therefore far from bulletproof.
24 =head2 Pragmatic Modules
26 They work somewhat like compiler directives (pragmata) in that they
27 tend to affect the compilation of your program, and thus will usually
28 work well only when used within a C<use>, or C<no>. Most of these
29 are lexically scoped, so an inner BLOCK may countermand them
36 which lasts until the end of that BLOCK.
38 Some pragmas are lexically scoped--typically those that affect the
39 C<$^H> hints variable. Others affect the current package instead,
40 like C<use vars> and C<use subs>, which allow you to predeclare a
41 variables or subroutines within a particular I<file> rather than
42 just a block. Such declarations are effective for the entire file
43 for which they were declared. You cannot rescind them with C<no
46 The following pragmas are defined (and have their own documentation).
52 Get/set subroutine or variable attributes
56 Set/get attributes of a subroutine (deprecated)
60 Postpone load of modules until a function is used
64 Establish IS-A relationship with base class at compile time
68 Transparent BigInteger support for Perl
72 Transparent BigNumber support for Perl
76 Transparent BigNumber/BigRationale support for Perl
80 Use MakeMaker's uninstalled version of a package
84 Force byte semantics rather than character semantics
88 Define character names for C<\N{named}> string literal escapes
96 Perl compiler pragma to force verbose warning diagnostics
100 Allows you to write your script in non-ascii or non-utf8
104 Compile-time class fields
108 Control the filetest permission operators
112 C<use> a Perl module if a condition holds
116 Use integer arithmetic instead of floating point
120 Request less of something from the compiler
124 Manipulate @INC at compile time
128 Use and avoid POSIX locales for built-in operations
132 Set default PerlIO layers for input and output
136 Restrict unsafe operations when compiling
140 Package for overloading perl operations
144 Alter regular expression behaviour
148 Enable simple signal handling
152 Control sort() behaviour
156 Restrict unsafe constructs
164 Perl extension allowing use of interpreter based threads from perl
166 =item threads::shared
168 Perl extension for sharing data structures between threads
172 Enable/disable UTF-8 (or UTF-EBCDIC) in source code
176 Predeclare global variable names (obsolete)
180 Perl extension for Version Objects
184 Control VMS-specific language features
188 Control optional warnings
190 =item warnings::register
192 Warnings import function
196 =head2 Standard Modules
198 Standard, bundled modules are all expected to behave in a well-defined
199 manner with respect to namespace pollution because they use the
200 Exporter module. See their own documentation for details.
202 It's possible that not all modules listed below are installed on your
203 system. For example, the GDBM_File module will not be installed if you
204 don't have the gdbm library.
210 Provide framework for multiple DBMs
212 =item Attribute::Handlers
214 Simpler definition of attribute handlers
218 Load subroutines only on demand
222 Split a package for autoloading
230 Autogenerated data about Perl ops, used to generate bytecode
234 Assemble Perl bytecode
242 Perl compiler's bytecode backend
246 Perl compiler's C backend
250 Perl compiler's optimized C translation backend
254 Walk Perl syntax tree, printing concise info about ops
258 Walk Perl syntax tree, printing debug info about ops
262 Perl compiler backend to produce perl code
264 =item B::Disassembler
266 Disassemble Perl bytecode
274 Show lexical variables used in functions or files
278 Helper module for CC backend
282 Show what stashes are loaded
286 Walk Perl syntax tree, printing terse info about ops
290 Generates cross reference reports for Perl programs
294 Benchmark running times of Perl code
298 Load byte compiled perl code
302 Simple Common Gateway Interface Class
306 Backward compatibility module for CGI.pm
310 CGI routines for writing to the HTTPD (or other) error log
314 Interface to Netscape Cookies
318 CGI Interface for Fast CGI
322 Module to produce nicely formatted HTML code
326 Simple Interface to Server Push
330 Backward compatibility module for defunct CGI::Switch
334 Internal utilities used by CGI module
338 Query, download and build perl modules from CPAN sites
340 =item CPAN::FirstTime
342 Utility for CPAN::Config file Initialization
346 Wrapper around CPAN.pm without using any XS module
350 Warn of errors (from perspective of caller)
354 No user serviceable parts inside
358 Report the search path for a class's ISA tree
362 Declare struct-like datatypes as Perl classes
366 Access Perl configuration information
370 Get pathname of current working directory
374 Programmatic interface to the Perl debugging API (draft, subject to
378 Perl5 access to Berkeley DB version 1.x
382 Stringified perl data structures, suitable for both printing and C<eval>
390 A data debugging tool for the XS programmer
392 =item Devel::SelfStubber
394 Generate stubs for a SelfLoading module
398 Modules that calculate message digests
402 Perl interface to the MD5 Algorithm
406 Supply object methods for directory handles
410 Provides screen dump of Perl data.
414 Dynamically load C libraries into Perl code
422 Alias definitions to encodings
426 Single Byte Encodings
428 =item Encode::CJKConstants
430 Internally used by Encode::??::ISO_2022_*
434 China-based Chinese Encodings
438 Internally used by Encode::CN
442 Internally used by Encode
448 =item Encode::Encoder
450 Object Oriented Encoder
452 =item Encode::Encoding
454 Encode Implementation Base Class
458 Guesses encoding from data
464 =item Encode::JP::H2Z
466 Internally used by Encode::JP::2022_JP*
468 =item Encode::JP::JIS7
470 Internally used by Encode::JP
476 =item Encode::KR::2022_KR
478 Internally used by Encode::KR
480 =item Encode::MIME::Header
482 MIME 'B' and 'Q' header encoding
486 A detailed document on Encode and PerlIO
488 =item Encode::Supported
490 Encodings supported by Encode
498 Taiwan-based Chinese Encodings
500 =item Encode::Unicode
502 Various Unicode Transformation Formats
506 Use nice English (or awk) names for ugly punctuation variables
510 Perl module that imports environment variables as scalars or arrays
514 System errno constants
518 Implements default import method for modules
520 =item Exporter::Heavy
524 =item ExtUtils::Command
526 Utilities to replace common UNIX commands in Makefiles etc.
528 =item ExtUtils::Command::MM
530 Commands for the MM's to use in Makefiles
532 =item ExtUtils::Constant
534 Generate XS code to import C header constants
536 =item ExtUtils::Embed
538 Utilities for embedding Perl in C/C++ applications
540 =item ExtUtils::Install
542 Install files from here to there
544 =item ExtUtils::Installed
546 Inventory management of installed modules
548 =item ExtUtils::Liblist
550 Determine libraries to use and how to use them
554 OS adjusted ExtUtils::MakeMaker subclass
556 =item ExtUtils::MM_Any
558 Platform agnostic MM methods
560 =item ExtUtils::MM_BeOS
562 Methods to override UN*X behaviour in ExtUtils::MakeMaker
564 =item ExtUtils::MM_Cygwin
566 Methods to override UN*X behaviour in ExtUtils::MakeMaker
568 =item ExtUtils::MM_DOS
570 DOS specific subclass of ExtUtils::MM_Unix
572 =item ExtUtils::MM_MacOS
574 Methods to override UN*X behaviour in ExtUtils::MakeMaker
576 =item ExtUtils::MM_NW5
578 Methods to override UN*X behaviour in ExtUtils::MakeMaker
580 =item ExtUtils::MM_OS2
582 Methods to override UN*X behaviour in ExtUtils::MakeMaker
584 =item ExtUtils::MM_UWIN
586 U/WIN specific subclass of ExtUtils::MM_Unix
588 =item ExtUtils::MM_Unix
590 Methods used by ExtUtils::MakeMaker
592 =item ExtUtils::MM_VMS
594 Methods to override UN*X behaviour in ExtUtils::MakeMaker
596 =item ExtUtils::MM_Win32
598 Methods to override UN*X behaviour in ExtUtils::MakeMaker
600 =item ExtUtils::MM_Win95
602 Method to customize MakeMaker for Win9X
606 ExtUtils::MakeMaker subclass for customization
608 =item ExtUtils::MakeMaker
610 Create an extension Makefile
612 =item ExtUtils::Manifest
614 Utilities to write and check a MANIFEST file
616 =item ExtUtils::Mkbootstrap
618 Make a bootstrap file for use by DynaLoader
620 =item ExtUtils::Mksymlists
622 Write linker options files for dynamic extension
624 =item ExtUtils::Packlist
626 Manage .packlist files
628 =item ExtUtils::testlib
630 Add blib/* directories to @INC
634 Replace functions with equivalents which succeed or die
638 Load the C Fcntl.h defines
642 Split a pathname into pieces
644 =item File::CheckTree
646 Run many filetest checks on a tree
650 Compare files or filehandles
654 Copy files or filehandles
658 DOS like globbing and then some
662 Traverse a directory tree.
666 Perl extension for BSD glob routine
670 Create or remove directory trees
674 Portably perform operations on file names
676 =item File::Spec::Cygwin
678 Methods for Cygwin file specs
680 =item File::Spec::Epoc
682 Methods for Epoc file specs
684 =item File::Spec::Functions
686 Portably perform operations on file names
688 =item File::Spec::Mac
690 File::Spec for Mac OS (Classic)
692 =item File::Spec::OS2
694 Methods for OS/2 file specs
696 =item File::Spec::Unix
698 File::Spec for Unix, base for other File::Spec modules
700 =item File::Spec::VMS
702 Methods for VMS file specs
704 =item File::Spec::Win32
706 Methods for Win32 file specs
710 Return name and handle of a temporary file safely
714 By-name interface to Perl's built-in stat() functions
718 Keep more files open than the system permits
722 Supply object methods for filehandles
726 Simplified source filtering
728 =item Filter::Util::Call
730 Perl Source Filter Utility Module
734 Locate directory of original perl script
738 Perl5 access to the gdbm library.
742 Extended processing of command line options
746 Process single-character switches with switch clustering
750 A selection of general-utility hash subroutines
754 Compare 8-bit scalar data according to the current locale
758 Functions for dealing with RFC3066-style language tags
760 =item I18N::LangTags::List
762 Tags and names for human languages
766 Query locale information
770 Load various IO modules
774 Supply object methods for directory handles
778 Supply object methods for filehandles
782 Supply object methods for I/O handles
786 Supply object methods for pipes
790 Object interface to system poll call
794 Supply seek based methods for I/O objects
798 OO interface to the select system call
802 Object interface to socket communications
804 =item IO::Socket::INET
806 Object interface for AF_INET domain sockets
808 =item IO::Socket::UNIX
810 Object interface for AF_UNIX domain sockets
814 Open a process for both reading and writing
818 Open a process for reading, writing, and error handling
826 SysV Msg IPC object class
828 =item IPC::SysV::Semaphore
830 SysV Semaphore IPC object class
834 A selection of general-utility list subroutines
836 =item Locale::Constants
838 Constants for Locale codes
840 =item Locale::Country
842 ISO codes for country identification (ISO 3166)
844 =item Locale::Currency
846 ISO three letter codes for currency identification (ISO 4217)
848 =item Locale::Language
850 ISO two letter codes for language identification (ISO 639)
852 =item Locale::Maketext
854 Framework for localization
856 =item Locale::Maketext::TPJ13
858 Article about software localization
862 ISO codes for script identification (ISO 15924)
866 Encoding and decoding of base64 strings
868 =item MIME::Base64::QuotedPrint
870 Encoding and decoding of quoted-printable strings
874 Arbitrary size floating point math package
878 Arbitrary size integer math package
880 =item Math::BigInt::Calc
882 Pure Perl module to support Math::BigInt
884 =item Math::BigInt::Scalar
886 Pure Perl module to test Math::BigInt with scalars
890 Arbitrarily big rationales
894 Complex numbers and associated mathematical functions
898 Trigonometric functions
902 Make functions faster by trading space for time
904 =item Memoize::AnyDBM_File
906 Glue to provide EXISTS for AnyDBM_File for Storable use
908 =item Memoize::Expire
910 Plug-in module for automatic expiration of memoized values
912 =item Memoize::ExpireFile
914 Test for Memoize expiration semantics
916 =item Memoize::ExpireTest
918 Test for Memoize expiration semantics
920 =item Memoize::NDBM_File
922 Glue to provide EXISTS for NDBM_File for Storable use
924 =item Memoize::SDBM_File
926 Glue to provide EXISTS for SDBM_File for Storable use
928 =item Memoize::Storable
930 Store Memoized data in Storable database
934 Tied access to ndbm files
938 Provide a pseudo-class NEXT that allows method redispatch
942 Network Command class (as used by FTP, SMTP etc)
946 Local configuration data for libnet
950 Attempt to evaluate the current host's internet name and domain
962 OO interface to users netrc file
966 Post Office Protocol 3 Client class (RFC1939)
970 Check a remote host for reachability
974 Simple Mail Transfer Protocol Client
978 Time and daytime network client interface
982 By-name interface to Perl's built-in gethost*() functions
986 Libnet Frequently Asked Questions
990 By-name interface to Perl's built-in getnet*() functions
994 By-name interface to Perl's built-in getproto*() functions
998 By-name interface to Perl's built-in getserv*() functions
1002 Generic interface to Perl Compiler backends
1006 Tied access to odbm files
1010 Disable named opcodes when compiling perl code
1014 Perl interface to IEEE Std 1003.1
1018 On demand loader for PerlIO layers and root of PerlIO::* name space
1020 =item PerlIO::encoding
1024 =item PerlIO::scalar
1026 Support module for in-memory IO.
1030 Helper class for PerlIO layers implemented in perl
1032 =item PerlIO::via::QuotedPrint
1034 PerlIO layer for quoted-printable strings
1038 Check pod documents for syntax errors
1042 Find POD documents in directory trees
1044 =item Pod::Functions
1046 Group Perl's functions a la perlfunc.pod
1050 Module to convert pod files to HTML
1052 =item Pod::InputObjects
1054 Objects representing POD input paragraphs, commands, etc.
1058 Convert Pod data to formatted Latex
1062 Convert POD data to formatted *roff input
1064 =item Pod::ParseLink
1066 Parse an LE<lt>E<gt> formatting code in POD text
1068 =item Pod::ParseUtils
1070 Helpers for POD parsing and conversion
1074 Base class for creating POD filters and translators
1078 Perl extension for converting Pod to old style Pod.
1082 Extract selected sections of POD from input
1086 Convert POD data to formatted ASCII text
1088 =item Pod::Text::Color
1090 Convert POD data to formatted color ASCII text
1092 =item Pod::Text::Overstrike
1094 Convert POD data to formatted overstrike text
1096 =item Pod::Text::Termcap
1098 Convert POD data to ASCII text with format escapes
1102 Print a usage message from embedded pod documentation
1106 Tied access to sdbm files
1110 Compile and execute code in restricted compartments
1114 A selection of general-utility scalar subroutines
1118 Search for key in dictionary file
1122 Save and restore selected file handle
1126 Load functions only on demand
1130 Run shell commands transparently within perl
1134 Load the C socket.h defines and structure manipulators
1138 Persistence for Perl data structures
1142 A switch statement for Perl
1146 Manipulate Perl symbols and their names
1150 Try every conceivable way to get hostname
1154 Perl interface to the UNIX syslog(3) calls
1156 =item Term::ANSIColor
1158 Color screen output using ANSI escape sequences
1162 Perl termcap interface
1164 =item Term::Complete
1166 Perl word completion module
1168 =item Term::ReadLine
1170 Perl interface to various C<readline> packages.
1174 Provides a simple framework for writing test scripts
1178 Backend for building test libraries
1182 Run perl standard test scripts with statistics
1184 =item Test::Harness::Assert
1188 =item Test::Harness::Iterator
1190 Internal Test::Harness Iterator
1192 =item Test::Harness::Straps
1194 Detailed analysis of test results
1198 Yet another framework for writing test scripts
1202 Basic utilities for writing tests.
1204 =item Test::Tutorial
1206 A tutorial about writing really basic tests
1210 Create an abbreviation table from a list
1212 =item Text::Balanced
1214 Extract delimited text sequences from strings.
1216 =item Text::ParseWords
1218 Parse text into an array of tokens or array of arrays
1222 Implementation of the Soundex Algorithm as Described by Knuth
1226 Expand and unexpand tabs per the unix expand(1) and unexpand(1)
1230 Line wrapping to form simple paragraphs
1234 Manipulate threads in Perl (for old code only)
1240 =item Thread::Semaphore
1242 Thread-safe semaphores
1244 =item Thread::Signal
1246 Start a thread which runs signal handlers reliably (for old code)
1248 =item Thread::Specific
1250 Thread-specific keys
1254 Base class for tied arrays
1258 Access the lines of a disk file via a Perl array
1262 Base class definitions for tied handles
1266 Base class definitions for tied hashes
1270 Add data to hash when needed
1274 Use references as hash keys
1278 Base class definitions for tied scalars
1280 =item Tie::SubstrHash
1282 Fixed-table-size, fixed-key-length hashing
1286 High resolution alarm, sleep, gettimeofday, interval timers
1290 Efficiently compute time from local and GMT time
1294 By-name interface to Perl's built-in gmtime() function
1296 =item Time::localtime
1298 By-name interface to Perl's built-in localtime() function
1302 Internal object used by Time::gmtime and Time::localtime
1306 Base class for ALL classes (blessed references)
1308 =item Unicode::Collate
1310 Unicode Collation Algorithm
1312 =item Unicode::Normalize
1314 Unicode Normalization Forms
1318 Unicode character database
1322 By-name interface to Perl's built-in getgr*() functions
1326 By-name interface to Perl's built-in getpw*() functions
1330 Interfaces to some Win32 API Functions
1338 Module to test the XS typemaps distributed with perl
1342 Dynamically load C libraries into Perl code
1346 To find out I<all> modules installed on your system, including
1347 those without documentation or outside the standard release,
1350 % find `perl -Te 'print "@INC"'` -name '*.pm' -print
1352 They should all have their own documentation installed and accessible
1353 via your system man(1) command. If you do not have a B<find>
1354 program, you can use the Perl B<find2perl> program instead, which
1355 generates Perl code as output you can run through perl. If you
1356 have a B<man> program but it doesn't find your modules, you'll have
1357 to fix your manpath. See L<perl> for details. If you have no
1358 system B<man> command, you might try the B<perldoc> program.
1360 =head2 Extension Modules
1362 Extension modules are written in C (or a mix of Perl and C). They
1363 are usually dynamically loaded into Perl if and when you need them,
1364 but may also be linked in statically. Supported extension modules
1365 include Socket, Fcntl, and POSIX.
1367 Many popular C extension modules do not come bundled (at least, not
1368 completely) due to their sizes, volatility, or simply lack of time
1369 for adequate testing and configuration across the multitude of
1370 platforms on which Perl was beta-tested. You are encouraged to
1371 look for them on CPAN (described below), or using web search engines
1372 like Alta Vista or Google.
1376 CPAN stands for Comprehensive Perl Archive Network; it's a globally
1377 replicated trove of Perl materials, including documentation, style
1378 guides, tricks and traps, alternate ports to non-Unix systems and
1379 occasional binary distributions for these. Search engines for
1380 CPAN can be found at http://www.cpan.org/
1382 Most importantly, CPAN includes around a thousand unbundled modules,
1383 some of which require a C compiler to build. Major categories of
1390 Language Extensions and Documentation Tools
1398 Operating System Interfaces
1402 Networking, Device Control (modems) and InterProcess Communication
1406 Data Types and Data Type Utilities
1418 Interfaces to / Emulations of Other Programming Languages
1422 File Names, File Systems and File Locking (see also File Handles)
1426 String Processing, Language Text Processing, Parsing, and Searching
1430 Option, Argument, Parameter, and Configuration File Processing
1434 Internationalization and Locale
1438 Authentication, Security, and Encryption
1442 World Wide Web, HTML, HTTP, CGI, MIME
1446 Server and Daemon Utilities
1450 Archiving and Compression
1454 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
1458 Mail and Usenet News
1462 Control Flow Utilities (callbacks and exceptions etc)
1466 File Handle and Input/Output Stream Utilities
1470 Miscellaneous Modules
1474 The list of the registered CPAN sites as of this writing follows.
1475 Please note that the sorting order is alphabetical on fields:
1481 |-->[state/province]
1487 and thus the North American servers happen to be listed between the
1488 European and the South American sites.
1490 You should try to choose one close to you.
1498 ftp://ftp.is.co.za/programming/perl/CPAN/
1499 ftp://ftp.mweb.co.za/pub/mirrors/cpan/
1500 ftp://ftp.saix.net/pub/CPAN/
1501 ftp://ftp.sun.ac.za/CPAN/CPAN/
1511 ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
1512 http://www2.linuxforum.net/mirror/CPAN/
1513 http://cpan.shellhung.org/
1514 ftp://ftp.shellhung.org/pub/CPAN
1518 http://cpan.in.freeos.com
1519 ftp://cpan.in.freeos.com/pub/CPAN/
1523 http://cpan.itb.web.id/
1524 ftp://mirrors.piksi.itb.ac.id/CPAN/
1525 http://cpan.cbn.net.id/
1526 ftp://ftp.cbn.net.id/mirror/CPAN
1527 http://CPAN.mweb.co.id/
1528 ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
1532 http://www.iglu.org.il:/pub/CPAN/
1533 ftp://ftp.iglu.org.il/pub/CPAN/
1534 http://cpan.lerner.co.il/
1535 http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1536 ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1540 ftp://ftp.u-aizu.ac.jp/pub/CPAN
1541 ftp://ftp.kddlabs.co.jp/CPAN/
1542 http://mirror.nucba.ac.jp/mirror/Perl/
1543 ftp://mirror.nucba.ac.jp/mirror/Perl/
1544 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
1545 ftp://ftp.ayamura.org/pub/CPAN/
1546 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
1547 ftp://ftp.dti.ad.jp/pub/lang/CPAN/
1548 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
1552 http://mirror.Mazic.org/pub/CPAN
1553 ftp://mirror.Mazic.org/pub/CPAN
1557 http://www.adzu.edu.ph/CPAN
1559 =item Russian Federation
1561 http://cpan.tomsk.ru
1562 ftp://cpan.tomsk.ru/pub/CPAN
1566 ftp://ftp.isu.net.sa/pub/CPAN/
1570 http://cpan.hjc.edu.sg
1571 http://mirror.averse.net/pub/CPAN
1572 ftp://mirror.averse.net/pub/CPAN
1576 http://CPAN.bora.net/
1577 ftp://ftp.bora.net/pub/CPAN/
1578 http://ftp.kornet.net/pub/CPAN/
1579 ftp://ftp.kornet.net/pub/CPAN/
1580 ftp://ftp.nuri.net/pub/CPAN/
1581 http://ftp.xgate.co.kr/cpan/
1582 ftp://ftp.xgate.co.kr/pub/mirror/CPAN
1586 ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN
1587 ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
1588 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
1589 http://ftp.tku.edu.tw/pub/CPAN/
1590 ftp://ftp.tku.edu.tw/pub/CPAN/
1594 ftp://ftp.loxinfo.co.th/pub/cpan/
1595 ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
1599 =head2 Central America
1605 ftp://ftp.linux.co.cr/mirrors/CPAN/
1606 http://ftp.ucr.ac.cr/Unix/CPAN/
1607 ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
1617 ftp://ftp.tuwien.ac.at/pub/CPAN/
1621 http://ftp.easynet.be/pub/CPAN/
1622 ftp://ftp.easynet.be/pub/CPAN/
1623 http://cpan.skynet.be
1624 ftp://ftp.skynet.be/pub/CPAN
1625 ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
1629 http://cpan.lirex.net/
1630 ftp://ftp.lirex.net/pub/mirrors/CPAN
1634 http://ftp.linux.hr/pub/CPAN/
1635 ftp://ftp.linux.hr/pub/CPAN/
1637 =item Czech Republic
1639 http://ftp.fi.muni.cz/pub/CPAN/
1640 ftp://ftp.fi.muni.cz/pub/CPAN/
1641 ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
1645 http://mirrors.sunsite.dk/cpan/
1646 ftp://sunsite.dk/mirrors/cpan/
1647 http://cpan.cybercity.dk
1648 http://www.cpan.dk/CPAN/
1649 ftp://www.cpan.dk/ftp.cpan.org/CPAN/
1653 ftp://ftp.ut.ee/pub/languages/perl/CPAN/
1657 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
1658 http://cpan.kpnqwest.fi/
1662 http://ftp.u-paris10.fr/perl/CPAN
1663 ftp://ftp.u-paris10.fr/perl/CPAN
1664 http://cpan.mirrors.easynet.fr/
1665 ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
1666 ftp://ftp.club-internet.fr/pub/perl/CPAN/
1668 ftp://ftp.lip6.fr/pub/perl/CPAN/
1669 ftp://ftp.oleane.net/pub/mirrors/CPAN/
1670 ftp://ftp.pasteur.fr/pub/computing/CPAN/
1671 http://mir2.ovh.net/ftp.cpan.org
1672 ftp://mir1.ovh.net/ftp.cpan.org
1673 http://ftp.u-strasbg.fr/CPAN
1674 ftp://ftp.u-strasbg.fr/CPAN
1675 http://cpan.cict.fr/
1676 ftp://cpan.cict.fr/pub/CPAN/
1677 ftp://ftp.uvsq.fr/pub/perl/CPAN/
1681 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
1682 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
1683 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
1684 ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
1685 http://pandemonium.tiscali.de/pub/CPAN/
1686 ftp://pandemonium.tiscali.de/pub/CPAN/
1687 http://ftp.gwdg.de/pub/languages/perl/CPAN/
1688 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
1689 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
1690 ftp://ftp.leo.org/pub/CPAN/
1691 http://cpan.noris.de/
1692 ftp://cpan.noris.de/pub/CPAN/
1693 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
1694 ftp://ftp.gmd.de/mirrors/CPAN/
1698 ftp://ftp.acn.gr/pub/lang/perl/CPAN
1699 ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
1700 ftp://ftp.ntua.gr/pub/lang/perl/
1704 http://cpan.artifact.hu/
1705 ftp://cpan.artifact.hu/CPAN/
1706 http://ftp.kfki.hu/packages/perl/CPAN/
1707 ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
1711 http://ftp.rhnet.is/pub/CPAN/
1712 ftp://ftp.rhnet.is/pub/CPAN/
1716 http://cpan.indigo.ie/
1717 ftp://cpan.indigo.ie/pub/CPAN/
1718 http://sunsite.compapp.dcu.ie/pub/perl/
1719 ftp://sunsite.compapp.dcu.ie/pub/perl/
1723 http://cpan.nettuno.it/
1724 http://gusp.dyndns.org/CPAN/
1725 ftp://gusp.dyndns.org/pub/CPAN
1726 http://softcity.iol.it/cpan
1727 ftp://softcity.iol.it/pub/cpan
1728 ftp://ftp.unina.it/pub/Other/CPAN/CPAN/
1729 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
1730 ftp://cis.uniRoma2.it/CPAN/
1731 ftp://ftp.edisontel.it/pub/CPAN_Mirror/
1732 ftp://ftp.flashnet.it/pub/CPAN/
1736 http://kvin.lv/pub/CPAN/
1740 ftp://ftp.unix.lt/pub/CPAN/
1744 ftp://download.xs4all.nl/pub/mirror/CPAN/
1745 ftp://ftp.nl.uu.net/pub/CPAN/
1746 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
1747 http://cpan.cybercomm.nl/
1748 ftp://mirror.cybercomm.nl/pub/CPAN
1749 ftp://ftp.cpan.nl/pub/CPAN/
1750 http://ftp.easynet.nl/mirror/CPAN
1751 ftp://ftp.easynet.nl/mirror/CPAN
1752 http://archive.cs.uu.nl/mirror/CPAN/
1753 ftp://ftp.cs.uu.nl/mirror/CPAN/
1757 ftp://ftp.uninett.no/pub/languages/perl/CPAN
1758 ftp://ftp.uit.no/pub/languages/perl/cpan/
1762 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
1763 ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
1764 ftp://ftp.man.torun.pl/pub/doc/CPAN/
1765 ftp://sunsite.icm.edu.pl/pub/CPAN/
1769 ftp://ftp.ua.pt/pub/CPAN/
1770 ftp://perl.di.uminho.pt/pub/CPAN/
1771 http://cpan.dei.uc.pt/
1772 ftp://ftp.dei.uc.pt/pub/CPAN
1773 ftp://ftp.ist.utl.pt/pub/CPAN/
1775 ftp://cpan.ip.pt/pub/cpan/
1776 ftp://ftp.netc.pt/pub/CPAN/
1777 ftp://ftp.up.pt/pub/CPAN
1781 ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
1782 ftp://ftp.dntis.ro/pub/cpan/
1783 ftp://ftp.dnttm.ro/pub/CPAN/
1784 ftp://ftp.lasting.ro/pub/CPAN
1785 ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
1789 ftp://ftp.chg.ru/pub/lang/perl/CPAN/
1790 http://cpan.rinet.ru/
1791 ftp://cpan.rinet.ru/pub/mirror/CPAN/
1792 ftp://ftp.aha.ru/pub/CPAN/
1793 http://cpan.sai.msu.ru/
1794 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
1798 http://ftp.cvt.stuba.sk/pub/CPAN/
1799 ftp://ftp.cvt.stuba.sk/pub/CPAN/
1803 ftp://ftp.arnes.si/software/perl/CPAN/
1807 http://cpan.imasd.elmundo.es/
1808 ftp://ftp.rediris.es/mirror/CPAN/
1809 ftp://ftp.etse.urv.es/pub/perl/
1813 http://ftp.du.se/CPAN/
1814 ftp://ftp.du.se/pub/CPAN/
1815 ftp://mirror.dataphone.se/pub/CPAN
1816 ftp://ftp.sunet.se/pub/lang/perl/CPAN/
1820 ftp://ftp.danyk.ch/CPAN/
1821 ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
1825 http://ftp.ulak.net.tr/perl/CPAN/
1826 ftp://ftp.ulak.net.tr/perl/CPAN
1827 ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
1833 ftp://ftp.perl.org.ua/pub/CPAN/
1835 =item United Kingdom
1837 http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
1838 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
1839 http://cpan.teleglobe.net/
1840 ftp://cpan.teleglobe.net/pub/CPAN
1841 http://cpan.crazygreek.co.uk
1842 ftp://ftp.demon.co.uk/pub/CPAN/
1843 http://cpan.m.flirble.org/
1844 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
1845 ftp://ftp.plig.org/pub/CPAN/
1846 http://mirror.uklinux.net/CPAN/
1847 ftp://mirror.uklinux.net/pub/CPAN/
1848 http://cpan.mirrors.clockerz.net/
1849 ftp://ftp.clockerz.net/pub/CPAN/
1850 ftp://usit.shef.ac.uk/pub/packages/CPAN/
1854 =head2 North America
1860 http://sunsite.ualberta.ca/pub/Mirror/CPAN/
1861 ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
1865 http://theoryx5.uwinnipeg.ca/pub/CPAN/
1866 ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
1870 ftp://cpan.chebucto.ns.ca/pub/CPAN/
1874 ftp://ftp.crc.ca/pub/CPAN/
1878 http://cpan.mirror.smartworker.org/
1882 http://cpan.azc.uam.mx
1883 ftp://cpan.azc.uam.mx/mirrors/CPAN
1884 http://cpan.unam.mx/
1885 ftp://cpan.unam.mx/pub/CPAN
1886 http://www.msg.com.mx/CPAN/
1887 ftp://ftp.msg.com.mx/pub/CPAN/
1891 =head2 United States
1897 http://mirror.hiwaay.net/CPAN/
1898 ftp://mirror.hiwaay.net/CPAN/
1902 http://cpan.develooper.com/
1903 http://www.cpan.org/
1904 ftp://cpan.valueclick.com/pub/CPAN/
1905 http://mirrors.gossamer-threads.com/CPAN
1906 ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
1907 http://mirrors.kernel.org/cpan/
1908 ftp://mirrors.kernel.org/pub/CPAN
1909 http://cpan.digisle.net/
1910 ftp://cpan.digisle.net/pub/CPAN
1911 http://www.perl.com/CPAN/
1912 http://download.sourceforge.net/mirrors/CPAN/
1916 ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
1920 http://ftp.lug.udel.edu/pub/CPAN
1921 ftp://ftp.lug.udel.edu/pub/CPAN
1923 =item District of Columbia
1925 ftp://ftp.dc.aleron.net/pub/CPAN/
1929 ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
1930 http://mirror.csit.fsu.edu/pub/CPAN/
1931 ftp://mirror.csit.fsu.edu/pub/CPAN/
1932 http://cpan.mirrors.nks.net/
1936 http://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
1937 ftp://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
1941 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
1942 http://cpan.netnitco.net/
1943 ftp://cpan.netnitco.net/pub/mirrors/CPAN/
1944 http://archive.progeny.com/CPAN/
1945 ftp://archive.progeny.com/CPAN/
1946 ftp://cpan.in-span.net/
1947 http://csociety-ftp.ecn.purdue.edu/pub/CPAN
1948 ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
1952 http://cpan.uky.edu/
1953 ftp://cpan.uky.edu/pub/CPAN/
1957 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
1958 http://cpan.mirrors.netnumina.com/
1959 ftp://mirrors.netnumina.com/cpan/
1963 ftp://cpan.cse.msu.edu/
1967 ftp://ftp.cpanel.net/pub/CPAN/
1968 http://cpan.teleglobe.net/
1969 ftp://cpan.teleglobe.net/pub/CPAN
1973 ftp://ftp.exobit.org/pub/perl/CPAN
1974 http://cpan.belfry.net/
1975 http://cpan.thepirtgroup.com/
1976 ftp://cpan.thepirtgroup.com/
1977 ftp://ftp.stealth.net/pub/CPAN/
1978 http://www.rge.com/pub/languages/perl/
1979 ftp://ftp.rge.com/pub/languages/perl/
1980 ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
1982 =item North Carolina
1984 ftp://ftp.duke.edu/pub/perl/
1988 ftp://ftp.loaded.net/pub/CPAN/
1992 ftp://ftp.ou.edu/mirrors/CPAN/
1996 ftp://ftp.orst.edu/pub/CPAN
2000 http://ftp.epix.net/CPAN/
2001 ftp://ftp.epix.net/pub/languages/perl/
2002 http://mirrors.phenominet.com/pub/CPAN/
2003 ftp://mirrors.phenominet.com/pub/CPAN/
2004 http://cpan.pair.com/
2005 ftp://cpan.pair.com/pub/CPAN/
2006 ftp://carroll.cac.psu.edu/pub/CPAN/
2010 ftp://ftp.sunsite.utk.edu/pub/CPAN/
2014 http://ftp.sedl.org/pub/mirrors/CPAN/
2015 ftp://mirror.telentente.com/pub/CPAN
2019 ftp://mirror.xmission.com/CPAN/
2023 http://mirrors.rcn.net/pub/lang/CPAN/
2024 ftp://mirrors.rcn.net/pub/lang/CPAN/
2025 http://perl.secsup.org/
2026 ftp://perl.secsup.org/pub/perl/
2027 http://mirrors.phihost.com/CPAN/
2028 ftp://mirrors.phihost.com/CPAN/
2029 ftp://ruff.cs.jmu.edu/pub/CPAN/
2030 http://perl.Liquidation.com/CPAN/
2034 http://cpan.llarian.net/
2035 ftp://cpan.llarian.net/pub/CPAN/
2036 http://cpan.mirrorcentral.com/
2037 ftp://ftp.mirrorcentral.com/pub/CPAN/
2038 ftp://ftp-mirror.internap.com/pub/CPAN/
2042 http://mirror.sit.wisc.edu/pub/CPAN/
2043 ftp://mirror.sit.wisc.edu/pub/CPAN/
2053 http://ftp.planetmirror.com/pub/CPAN/
2054 ftp://ftp.planetmirror.com/pub/CPAN/
2055 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
2056 ftp://cpan.topend.com.au/pub/CPAN/
2060 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
2061 http://cpan.soa.co.nz/CPAN/
2065 =head2 South America
2071 ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
2072 http://ftp.fcaglp.unlp.edu.ar/pub/CPAN/
2073 ftp://ftp.fcaglp.unlp.edu.ar/pub/CPAN/
2077 ftp://cpan.pop-mg.com.br/pub/CPAN/
2078 ftp://ftp.matrix.com.br/pub/perl/CPAN/
2082 http://cpan.netglobalis.net/
2083 ftp://cpan.netglobalis.net/pub/CPAN/
2087 =head2 RSYNC Mirrors
2089 ftp.fcaglp.unlp.edu.ar::CPAN
2090 cpan.mirror.smartworker.org::CPAN
2091 theoryx5.uwinnipeg.ca::CPAN
2092 ftp.shellhung.org::CPAN
2094 ftp.u-paris10.fr::CPAN
2096 ftp.gwdg.de::FTP/languages/perl/CPAN/
2098 CPAN.piksi.itb.ac.id::CPAN
2099 ftp.cbn.net.id::CPAN
2100 ftp.iglu.org.il::CPAN
2101 gusp.dyndns.org::cpan
2102 ftp.kddlabs.co.jp::cpan
2103 ftp.ayamura.org::pub/CPAN/
2104 mirror.averse.net::cpan
2105 cpan.teleglobe.net::CPAN
2107 archive.progeny.com::CPAN
2108 cpan.teleglobe.net::CPAN
2109 ftp.lug.udel.edu::cpan
2110 mirrors.kernel.org::mirrors/CPAN
2111 mirrors.phenominet.com::CPAN
2112 mirror.csit.fsu.edu::CPAN
2113 csociety-ftp.ecn.purdue.edu::CPAN
2115 For an up-to-date listing of CPAN sites,
2116 see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
2118 =head1 Modules: Creation, Use, and Abuse
2120 (The following section is borrowed directly from Tim Bunce's modules
2121 file, available at your nearest CPAN site.)
2123 Perl implements a class using a package, but the presence of a
2124 package doesn't imply the presence of a class. A package is just a
2125 namespace. A class is a package that provides subroutines that can be
2126 used as methods. A method is just a subroutine that expects, as its
2127 first argument, either the name of a package (for "static" methods),
2128 or a reference to something (for "virtual" methods).
2130 A module is a file that (by convention) provides a class of the same
2131 name (sans the .pm), plus an import method in that class that can be
2132 called to fetch exported symbols. This module may implement some of
2133 its methods by loading dynamic C or C++ objects, but that should be
2134 totally transparent to the user of the module. Likewise, the module
2135 might set up an AUTOLOAD function to slurp in subroutine definitions on
2136 demand, but this is also transparent. Only the F<.pm> file is required to
2137 exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
2138 the AUTOLOAD mechanism.
2140 =head2 Guidelines for Module Creation
2146 Do similar modules already exist in some form?
2148 If so, please try to reuse the existing modules either in whole or
2149 by inheriting useful features into a new class. If this is not
2150 practical try to get together with the module authors to work on
2151 extending or enhancing the functionality of the existing modules.
2152 A perfect example is the plethora of packages in perl4 for dealing
2153 with command line options.
2155 If you are writing a module to expand an already existing set of
2156 modules, please coordinate with the author of the package. It
2157 helps if you follow the same naming scheme and module interaction
2158 scheme as the original author.
2162 Try to design the new module to be easy to extend and reuse.
2164 Try to C<use warnings;> (or C<use warnings qw(...);>).
2165 Remember that you can add C<no warnings qw(...);> to individual blocks
2166 of code that need less warnings.
2168 Use blessed references. Use the two argument form of bless to bless
2169 into the class name given as the first parameter of the constructor,
2174 return bless {}, $class;
2177 or even this if you'd like it to be used as either a static
2178 or a virtual method.
2182 my $class = ref($self) || $self;
2183 return bless {}, $class;
2186 Pass arrays as references so more parameters can be added later
2187 (it's also faster). Convert functions into methods where
2188 appropriate. Split large methods into smaller more flexible ones.
2189 Inherit methods from other modules if appropriate.
2191 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
2192 Generally you can delete the C<eq 'FOO'> part with no harm at all.
2193 Let the objects look after themselves! Generally, avoid hard-wired
2194 class names as far as possible.
2196 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
2197 C<< $r->func() >> would work (see L<perlbot> for more details).
2199 Use autosplit so little used or newly added functions won't be a
2200 burden to programs that don't use them. Add test functions to
2201 the module after __END__ either using AutoSplit or by saying:
2203 eval join('',<main::DATA>) || die $@ unless caller();
2205 Does your module pass the 'empty subclass' test? If you say
2206 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
2207 to use SUBCLASS in exactly the same way as YOURCLASS. For example,
2208 does your application still work if you change: C<$obj = new YOURCLASS;>
2209 into: C<$obj = new SUBCLASS;> ?
2211 Avoid keeping any state information in your packages. It makes it
2212 difficult for multiple other packages to use yours. Keep state
2213 information in objects.
2217 Try to C<use strict;> (or C<use strict qw(...);>).
2218 Remember that you can add C<no strict qw(...);> to individual blocks
2219 of code that need less strictness.
2223 Follow the guidelines in the perlstyle(1) manual.
2229 Some simple style guidelines
2231 The perlstyle manual supplied with Perl has many helpful points.
2233 Coding style is a matter of personal taste. Many people evolve their
2234 style over several years as they learn what helps them write and
2235 maintain good code. Here's one set of assorted suggestions that
2236 seem to be widely used by experienced developers:
2238 Use underscores to separate words. It is generally easier to read
2239 $var_names_like_this than $VarNamesLikeThis, especially for
2240 non-native speakers of English. It's also a simple rule that works
2241 consistently with VAR_NAMES_LIKE_THIS.
2243 Package/Module names are an exception to this rule. Perl informally
2244 reserves lowercase module names for 'pragma' modules like integer
2245 and strict. Other modules normally begin with a capital letter and
2246 use mixed case with no underscores (need to be short and portable).
2248 You may find it helpful to use letter case to indicate the scope
2249 or nature of a variable. For example:
2251 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
2252 $Some_Caps_Here package-wide global/static
2253 $no_caps_here function scope my() or local() variables
2255 Function and method names seem to work best as all lowercase.
2256 e.g., C<< $obj->as_string() >>.
2258 You can use a leading underscore to indicate that a variable or
2259 function should not be used outside the package that defined it.
2263 Select what to export.
2265 Do NOT export method names!
2267 Do NOT export anything else by default without a good reason!
2269 Exports pollute the namespace of the module user. If you must
2270 export try to use @EXPORT_OK in preference to @EXPORT and avoid
2271 short or common names to reduce the risk of name clashes.
2273 Generally anything not exported is still accessible from outside the
2274 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
2275 syntax. By convention you can use a leading underscore on names to
2276 indicate informally that they are 'internal' and not for public use.
2278 (It is actually possible to get private functions by saying:
2279 C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
2280 directly as a method, because a method must have a name in the symbol
2283 As a general rule, if the module is trying to be object oriented
2284 then export nothing. If it's just a collection of functions then
2285 @EXPORT_OK anything but use @EXPORT with caution.
2289 Select a name for the module.
2291 This name should be as descriptive, accurate, and complete as
2292 possible. Avoid any risk of ambiguity. Always try to use two or
2293 more whole words. Generally the name should reflect what is special
2294 about what the module does rather than how it does it. Please use
2295 nested module names to group informally or categorize a module.
2296 There should be a very good reason for a module not to have a nested name.
2297 Module names should begin with a capital letter.
2299 Having 57 modules all called Sort will not make life easy for anyone
2300 (though having 23 called Sort::Quick is only marginally better :-).
2301 Imagine someone trying to install your module alongside many others.
2302 If in any doubt ask for suggestions in comp.lang.perl.misc.
2304 If you are developing a suite of related modules/classes it's good
2305 practice to use nested classes with a common prefix as this will
2306 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
2307 Xyz::Model etc. Use the modules in this list as a naming guide.
2309 If adding a new module to a set, follow the original author's
2310 standards for naming modules and the interface to methods in
2313 If developing modules for private internal or project specific use,
2314 that will never be released to the public, then you should ensure
2315 that their names will not clash with any future public module. You
2316 can do this either by using the reserved Local::* category or by
2317 using a category name that includes an underscore like Foo_Corp::*.
2319 To be portable each component of a module name should be limited to
2320 11 characters. If it might be used on MS-DOS then try to ensure each is
2321 unique in the first 8 characters. Nested modules make this easier.
2325 Have you got it right?
2327 How do you know that you've made the right decisions? Have you
2328 picked an interface design that will cause problems later? Have
2329 you picked the most appropriate name? Do you have any questions?
2331 The best way to know for sure, and pick up many helpful suggestions,
2332 is to ask someone who knows. Comp.lang.perl.misc is read by just about
2333 all the people who develop modules and it's the best place to ask.
2335 All you need to do is post a short summary of the module, its
2336 purpose and interfaces. A few lines on each of the main methods is
2337 probably enough. (If you post the whole module it might be ignored
2338 by busy people - generally the very people you want to read it!)
2340 Don't worry about posting if you can't say when the module will be
2341 ready - just say so in the message. It might be worth inviting
2342 others to help you, they may be able to complete it for you!
2346 README and other Additional Files.
2348 It's well known that software developers usually fully document the
2349 software they write. If, however, the world is in urgent need of
2350 your software and there is not enough time to write the full
2351 documentation please at least provide a README file containing:
2357 A description of the module/package/extension etc.
2361 A copyright notice - see below.
2365 Prerequisites - what else you may need to have.
2369 How to build it - possible changes to Makefile.PL etc.
2377 Recent changes in this release, especially incompatibilities
2381 Changes / enhancements you plan to make in the future.
2385 If the README file seems to be getting too large you may wish to
2386 split out some of the sections into separate files: INSTALL,
2393 Adding a Copyright Notice.
2395 How you choose to license your work is a personal decision.
2396 The general mechanism is to assert your Copyright and then make
2397 a declaration of how others may copy/use/modify your work.
2399 Perl, for example, is supplied with two types of licence: The GNU
2400 GPL and The Artistic Licence (see the files README, Copying, and
2401 Artistic). Larry has good reasons for NOT just using the GNU GPL.
2403 My personal recommendation, out of respect for Larry, Perl, and the
2404 Perl community at large is to state something simply like:
2406 Copyright (c) 1995 Your Name. All rights reserved.
2407 This program is free software; you can redistribute it and/or
2408 modify it under the same terms as Perl itself.
2410 This statement should at least appear in the README file. You may
2411 also wish to include it in a Copying file and your source files.
2412 Remember to include the other words in addition to the Copyright.
2416 Give the module a version/issue/release number.
2418 To be fully compatible with the Exporter and MakeMaker modules you
2419 should store your module's version number in a non-my package
2420 variable called $VERSION. This should be a floating point
2421 number with at least two digits after the decimal (i.e., hundredths,
2422 e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
2423 See L<Exporter> for details.
2425 It may be handy to add a function or method to retrieve the number.
2426 Use the number in announcements and archive file names when
2427 releasing the module (ModuleName-1.02.tar.Z).
2428 See perldoc ExtUtils::MakeMaker.pm for details.
2432 How to release and distribute a module.
2434 It's good idea to post an announcement of the availability of your
2435 module (or the module itself if small) to the comp.lang.perl.announce
2436 Usenet newsgroup. This will at least ensure very wide once-off
2439 If possible, register the module with CPAN. You should
2440 include details of its location in your announcement.
2442 Some notes about ftp archives: Please use a long descriptive file
2443 name that includes the version number. Most incoming directories
2444 will not be readable/listable, i.e., you won't be able to see your
2445 file after uploading it. Remember to send your email notification
2446 message as soon as possible after uploading else your file may get
2447 deleted automatically. Allow time for the file to be processed
2448 and/or check the file has been processed before announcing its
2451 FTP Archives for Perl Modules:
2453 Follow the instructions and links on:
2455 http://www.cpan.org/modules/00modlist.long.html
2456 http://www.cpan.org/modules/04pause.html
2458 or upload to one of these sites:
2460 https://pause.kbx.de/pause/
2461 http://pause.perl.org/pause/
2463 and notify <modules@perl.org>.
2465 By using the WWW interface you can ask the Upload Server to mirror
2466 your modules from your ftp or WWW site into your own directory on
2469 Please remember to send me an updated entry for the Module list!
2473 Take care when changing a released module.
2475 Always strive to remain compatible with previous released versions.
2476 Otherwise try to add a mechanism to revert to the
2477 old behavior if people rely on it. Document incompatible changes.
2483 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
2489 There is no requirement to convert anything.
2491 If it ain't broke, don't fix it! Perl 4 library scripts should
2492 continue to work with no problems. You may need to make some minor
2493 changes (like escaping non-array @'s in double quoted strings) but
2494 there is no need to convert a .pl file into a Module for just that.
2498 Consider the implications.
2500 All Perl applications that make use of the script will need to
2501 be changed (slightly) if the script is converted into a module. Is
2502 it worth it unless you plan to make other changes at the same time?
2506 Make the most of the opportunity.
2508 If you are going to convert the script to a module you can use the
2509 opportunity to redesign the interface. The guidelines for module
2510 creation above include many of the issues you should consider.
2514 The pl2pm utility will get you started.
2516 This utility will read *.pl files (given as parameters) and write
2517 corresponding *.pm files. The pl2pm utilities does the following:
2523 Adds the standard Module prologue lines
2527 Converts package specifiers from ' to ::
2531 Converts die(...) to croak(...)
2535 Several other minor changes
2539 Being a mechanical process pl2pm is not bullet proof. The converted
2540 code will need careful checking, especially any package statements.
2541 Don't delete the original .pl file till the new .pm one works!
2545 =head2 Guidelines for Reusing Application Code
2551 Complete applications rarely belong in the Perl Module Library.
2555 Many applications contain some Perl code that could be reused.
2557 Help save the world! Share your code in a form that makes it easy
2562 Break-out the reusable code into one or more separate module files.
2566 Take the opportunity to reconsider and redesign the interfaces.
2570 In some cases the 'application' can then be reduced to a small
2572 fragment of code built on top of the reusable modules. In these cases
2573 the application could invoked as:
2575 % perl -e 'use Module::Name; method(@ARGV)' ...
2577 % perl -mModule::Name ... (in perl5.002 or higher)
2583 Perl does not enforce private and public parts of its modules as you may
2584 have been used to in other languages like C++, Ada, or Modula-17. Perl
2585 doesn't have an infatuation with enforced privacy. It would prefer
2586 that you stayed out of its living room because you weren't invited, not
2587 because it has a shotgun.
2589 The module and its user have a contract, part of which is common law,
2590 and part of which is "written". Part of the common law contract is
2591 that a module doesn't pollute any namespace it wasn't asked to. The
2592 written contract for the module (A.K.A. documentation) may make other
2593 provisions. But then you know when you C<use RedefineTheWorld> that
2594 you're redefining the world and willing to take the consequences.