diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlmodlib.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlmodlib.pod | 3513 |
1 files changed, 3513 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod b/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod new file mode 100644 index 00000000000..05c2dd5c72b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perlmodlib.pod @@ -0,0 +1,3513 @@ +=for maintainers +Generated by perlmodlib.PL -- DO NOT EDIT! + +=head1 NAME + +perlmodlib - constructing new Perl modules and finding existing ones + +=head1 THE PERL MODULE LIBRARY + +Many modules are included in the Perl distribution. These are described +below, and all end in F<.pm>. You may discover compiled library +files (usually ending in F<.so>) or small pieces of modules to be +autoloaded (ending in F<.al>); these were automatically generated +by the installation process. You may also discover files in the +library directory that end in either F<.pl> or F<.ph>. These are +old libraries supplied so that old programs that use them still +run. The F<.pl> files will all eventually be converted into standard +modules, and the F<.ph> files made by B<h2ph> will probably end up +as extension modules made by B<h2xs>. (Some F<.ph> values may +already be available through the POSIX, Errno, or Fcntl modules.) +The B<pl2pm> file in the distribution may help in your conversion, +but it's just a mechanical process and therefore far from bulletproof. + +=head2 Pragmatic Modules + +They work somewhat like compiler directives (pragmata) in that they +tend to affect the compilation of your program, and thus will usually +work well only when used within a C<use>, or C<no>. Most of these +are lexically scoped, so an inner BLOCK may countermand them +by saying: + + no integer; + no strict 'refs'; + no warnings; + +which lasts until the end of that BLOCK. + +Some pragmas are lexically scoped--typically those that affect the +C<$^H> hints variable. Others affect the current package instead, +like C<use vars> and C<use subs>, which allow you to predeclare a +variables or subroutines within a particular I<file> rather than +just a block. Such declarations are effective for the entire file +for which they were declared. You cannot rescind them with C<no +vars> or C<no subs>. + +The following pragmas are defined (and have their own documentation). + +=over 12 + +=item attributes + +Get/set subroutine or variable attributes + +=item autodie + +Replace functions with ones that succeed or die with lexical scope + +=item autodie::exception + +Exceptions from autodying functions. + +=item autodie::exception::system + +Exceptions from autodying system(). + +=item autodie::hints + +Provide hints about user subroutines to autodie + +=item autouse + +Postpone load of modules until a function is used + +=item base + +Establish an ISA relationship with base classes at compile time + +=item bigint + +Transparent BigInteger support for Perl + +=item bignum + +Transparent BigNumber support for Perl + +=item bigrat + +Transparent BigNumber/BigRational support for Perl + +=item blib + +Use MakeMaker's uninstalled version of a package + +=item bytes + +Force byte semantics rather than character semantics + +=item charnames + +Define character names for C<\N{named}> string literal escapes + +=item constant + +Declare constants + +=item deprecate + +Perl pragma for deprecating the core version of a module + +=item diagnostics + +Produce verbose warning diagnostics + +=item encoding + +Allows you to write your script in non-ascii or non-utf8 + +=item encoding::warnings + +Warn on implicit encoding conversions + +=item feature + +Enable new features + +=item fields + +Compile-time class fields + +=item filetest + +Control the filetest permission operators + +=item if + +C<use> a Perl module if a condition holds + +=item inc::latest + +Use modules bundled in inc/ if they are newer than installed ones + +=item integer + +Use integer arithmetic instead of floating point + +=item less + +Request less of something + +=item lib + +Manipulate @INC at compile time + +=item locale + +Use and avoid POSIX locales for built-in operations + +=item mro + +Method Resolution Order + +=item open + +Set default PerlIO layers for input and output + +=item ops + +Restrict unsafe operations when compiling + +=item overload + +Package for overloading Perl operations + +=item overloading + +Lexically control overloading + +=item parent + +Establish an ISA relationship with base classes at compile time + +=item re + +Alter regular expression behaviour + +=item sigtrap + +Enable simple signal handling + +=item sort + +Control sort() behaviour + +=item strict + +Restrict unsafe constructs + +=item subs + +Predeclare sub names + +=item threads + +Perl interpreter-based threads + +=item threads::shared + +Perl extension for sharing data structures between threads + +=item utf8 + +Enable/disable UTF-8 (or UTF-EBCDIC) in source code + +=item vars + +Predeclare global variable names (obsolete) + +=item version + +Perl extension for Version Objects + +=item vmsish + +Control VMS-specific language features + +=item warnings + +Control optional warnings + +=item warnings::register + +Warnings import function + +=back + +=head2 Standard Modules + +Standard, bundled modules are all expected to behave in a well-defined +manner with respect to namespace pollution because they use the +Exporter module. See their own documentation for details. + +It's possible that not all modules listed below are installed on your +system. For example, the GDBM_File module will not be installed if you +don't have the gdbm library. + +=over 12 + +=item AnyDBM_File + +Provide framework for multiple DBMs + +=item App::Cpan + +Easily interact with CPAN from the command line + +=item App::Prove + +Implements the C<prove> command. + +=item App::Prove::State + +State storage for the C<prove> command. + +=item App::Prove::State::Result + +Individual test suite results. + +=item App::Prove::State::Result::Test + +Individual test results. + +=item Archive::Extract + +A generic archive extracting mechanism + +=item Archive::Tar + +Module for manipulations of tar archives + +=item Archive::Tar::File + +A subclass for in-memory extracted file from Archive::Tar + +=item Attribute::Handlers + +Simpler definition of attribute handlers + +=item AutoLoader + +Load subroutines only on demand + +=item AutoSplit + +Split a package for autoloading + +=item B + +The Perl Compiler Backend + +=item B::Concise + +Walk Perl syntax tree, printing concise info about ops + +=item B::Debug + +Walk Perl syntax tree, printing debug info about ops + +=item B::Deparse + +Perl compiler backend to produce perl code + +=item B::Lint + +Perl lint + +=item B::Lint::Debug + +Adds debugging stringification to B:: + +=item B::Showlex + +Show lexical variables used in functions or files + +=item B::Terse + +Walk Perl syntax tree, printing terse info about ops + +=item B::Xref + +Generates cross reference reports for Perl programs + +=item Benchmark + +Benchmark running times of Perl code + +=item CGI + +Handle Common Gateway Interface requests and responses + +=item CGI::Apache + +Backward compatibility module for CGI.pm + +=item CGI::Carp + +CGI routines for writing to the HTTPD (or other) error log + +=item CGI::Cookie + +Interface to Netscape Cookies + +=item CGI::Fast + +CGI Interface for Fast CGI + +=item CGI::Pretty + +Module to produce nicely formatted HTML code + +=item CGI::Push + +Simple Interface to Server Push + +=item CGI::Switch + +Backward compatibility module for defunct CGI::Switch + +=item CGI::Util + +Internal utilities used by CGI module + +=item CORE + +Pseudo-namespace for Perl's core routines + +=item CPAN + +Query, download and build perl modules from CPAN sites + +=item CPAN::API::HOWTO + +A recipe book for programming with CPAN.pm + +=item CPAN::Distroprefs + +Read and match distroprefs + +=item CPAN::FirstTime + +Utility for CPAN::Config file Initialization + +=item CPAN::Kwalify + +Interface between CPAN.pm and Kwalify.pm + +=item CPAN::Nox + +Wrapper around CPAN.pm without using any XS module + +=item CPAN::Version + +Utility functions to compare CPAN versions + +=item CPANPLUS + +API & CLI access to the CPAN mirrors + +=item CPANPLUS::Dist::Base + +Base class for custom distribution classes + +=item CPANPLUS::Dist::Build + +CPANPLUS plugin to install packages that use Build.PL + +=item CPANPLUS::Dist::Build::Constants + +Constants for CPANPLUS::Dist::Build + +=item CPANPLUS::Dist::Sample + +Sample code to create your own Dist::* plugin + +=item CPANPLUS::Internals::Source::Memory + +In memory implementation + +=item CPANPLUS::Internals::Source::SQLite + +SQLite implementation + +=item CPANPLUS::Shell::Classic + +CPAN.pm emulation for CPANPLUS + +=item CPANPLUS::Shell::Default::Plugins::HOWTO + +Documentation on how to write your own plugins + +=item Carp + +Warn of errors (from perspective of caller) + +=item Class::ISA + +Report the search path for a class's ISA tree + +=item Class::Struct + +Declare struct-like datatypes as Perl classes + +=item Compress::Raw::Bzip2 + +Low-Level Interface to bzip2 compression library + +=item Compress::Raw::Bzip2::FAQ + +Frequently Asked Questions about Compress::Raw::Bzip2 + +=item Compress::Raw::Zlib + +Low-Level Interface to zlib compression library + +=item Compress::Raw::Zlib::FAQ + +Frequently Asked Questions about Compress::Raw::Zlib + +=item Compress::Zlib + +Interface to zlib compression library + +=item Config + +Access Perl configuration information + +=item Cwd + +Get pathname of current working directory + +=item DB + +Programmatic interface to the Perl debugging API + +=item DBM_Filter + +Filter DBM keys/values + +=item DBM_Filter::compress + +Filter for DBM_Filter + +=item DBM_Filter::encode + +Filter for DBM_Filter + +=item DBM_Filter::int32 + +Filter for DBM_Filter + +=item DBM_Filter::null + +Filter for DBM_Filter + +=item DBM_Filter::utf8 + +Filter for DBM_Filter + +=item DB_File + +Perl5 access to Berkeley DB version 1.x + +=item Data::Dumper + +Stringified perl data structures, suitable for both printing and C<eval> + +=item Devel::DProf + +A Perl code profiler + +=item Devel::InnerPackage + +Find all the inner packages of a package + +=item Devel::PPPort + +Perl/Pollution/Portability + +=item Devel::Peek + +A data debugging tool for the XS programmer + +=item Devel::SelfStubber + +Generate stubs for a SelfLoading module + +=item Digest + +Modules that calculate message digests + +=item Digest::MD5 + +Perl interface to the MD5 Algorithm + +=item Digest::SHA + +Perl extension for SHA-1/224/256/384/512 + +=item Digest::base + +Digest base class + +=item Digest::file + +Calculate digests of files + +=item DirHandle + +Supply object methods for directory handles + +=item Dumpvalue + +Provides screen dump of Perl data. + +=item DynaLoader + +Dynamically load C libraries into Perl code + +=item Encode + +Character encodings + +=item Encode::Alias + +Alias definitions to encodings + +=item Encode::Byte + +Single Byte Encodings + +=item Encode::CJKConstants + +Internally used by Encode::??::ISO_2022_* + +=item Encode::CN + +China-based Chinese Encodings + +=item Encode::CN::HZ + +Internally used by Encode::CN + +=item Encode::Config + +Internally used by Encode + +=item Encode::EBCDIC + +EBCDIC Encodings + +=item Encode::Encoder + +Object Oriented Encoder + +=item Encode::Encoding + +Encode Implementation Base Class + +=item Encode::GSM0338 + +ESTI GSM 03.38 Encoding + +=item Encode::Guess + +Guesses encoding from data + +=item Encode::JP + +Japanese Encodings + +=item Encode::JP::H2Z + +Internally used by Encode::JP::2022_JP* + +=item Encode::JP::JIS7 + +Internally used by Encode::JP + +=item Encode::KR + +Korean Encodings + +=item Encode::KR::2022_KR + +Internally used by Encode::KR + +=item Encode::MIME::Header + +MIME 'B' and 'Q' header encoding + +=item Encode::MIME::Name + +Internally used by Encode + +=item Encode::PerlIO + +A detailed document on Encode and PerlIO + +=item Encode::Supported + +Encodings supported by Encode + +=item Encode::Symbol + +Symbol Encodings + +=item Encode::TW + +Taiwan-based Chinese Encodings + +=item Encode::Unicode + +Various Unicode Transformation Formats + +=item Encode::Unicode::UTF7 + +UTF-7 encoding + +=item English + +Use nice English (or awk) names for ugly punctuation variables + +=item Env + +Perl module that imports environment variables as scalars or arrays + +=item Errno + +System errno constants + +=item Exporter + +Implements default import method for modules + +=item Exporter::Heavy + +Exporter guts + +=item ExtUtils::CBuilder + +Compile and link C code for Perl modules + +=item ExtUtils::CBuilder::Platform::Windows + +Builder class for Windows platforms + +=item ExtUtils::Command + +Utilities to replace common UNIX commands in Makefiles etc. + +=item ExtUtils::Command::MM + +Commands for the MM's to use in Makefiles + +=item ExtUtils::Constant + +Generate XS code to import C header constants + +=item ExtUtils::Constant::Base + +Base class for ExtUtils::Constant objects + +=item ExtUtils::Constant::Utils + +Helper functions for ExtUtils::Constant + +=item ExtUtils::Constant::XS + +Generate C code for XS modules' constants. + +=item ExtUtils::Embed + +Utilities for embedding Perl in C/C++ applications + +=item ExtUtils::Install + +Install files from here to there + +=item ExtUtils::Installed + +Inventory management of installed modules + +=item ExtUtils::Liblist + +Determine libraries to use and how to use them + +=item ExtUtils::MM + +OS adjusted ExtUtils::MakeMaker subclass + +=item ExtUtils::MM_AIX + +AIX specific subclass of ExtUtils::MM_Unix + +=item ExtUtils::MM_Any + +Platform-agnostic MM methods + +=item ExtUtils::MM_BeOS + +Methods to override UN*X behaviour in ExtUtils::MakeMaker + +=item ExtUtils::MM_Cygwin + +Methods to override UN*X behaviour in ExtUtils::MakeMaker + +=item ExtUtils::MM_DOS + +DOS specific subclass of ExtUtils::MM_Unix + +=item ExtUtils::MM_Darwin + +Special behaviors for OS X + +=item ExtUtils::MM_MacOS + +Once produced Makefiles for MacOS Classic + +=item ExtUtils::MM_NW5 + +Methods to override UN*X behaviour in ExtUtils::MakeMaker + +=item ExtUtils::MM_OS2 + +Methods to override UN*X behaviour in ExtUtils::MakeMaker + +=item ExtUtils::MM_QNX + +QNX specific subclass of ExtUtils::MM_Unix + +=item ExtUtils::MM_UWIN + +U/WIN specific subclass of ExtUtils::MM_Unix + +=item ExtUtils::MM_Unix + +Methods used by ExtUtils::MakeMaker + +=item ExtUtils::MM_VMS + +Methods to override UN*X behaviour in ExtUtils::MakeMaker + +=item ExtUtils::MM_VOS + +VOS specific subclass of ExtUtils::MM_Unix + +=item ExtUtils::MM_Win32 + +Methods to override UN*X behaviour in ExtUtils::MakeMaker + +=item ExtUtils::MM_Win95 + +Method to customize MakeMaker for Win9X + +=item ExtUtils::MY + +ExtUtils::MakeMaker subclass for customization + +=item ExtUtils::MakeMaker + +Create a module Makefile + +=item ExtUtils::MakeMaker::Config + +Wrapper around Config.pm + +=item ExtUtils::MakeMaker::FAQ + +Frequently Asked Questions About MakeMaker + +=item ExtUtils::MakeMaker::Tutorial + +Writing a module with MakeMaker + +=item ExtUtils::Manifest + +Utilities to write and check a MANIFEST file + +=item ExtUtils::Mkbootstrap + +Make a bootstrap file for use by DynaLoader + +=item ExtUtils::Mksymlists + +Write linker options files for dynamic extension + +=item ExtUtils::Packlist + +Manage .packlist files + +=item ExtUtils::ParseXS + +Converts Perl XS code into C code + +=item ExtUtils::XSSymSet + +Keep sets of symbol names palatable to the VMS linker + +=item ExtUtils::testlib + +Add blib/* directories to @INC + +=item Fatal + +Replace functions with equivalents which succeed or die + +=item Fcntl + +Load the C Fcntl.h defines + +=item File::Basename + +Parse file paths into directory, filename and suffix. + +=item File::CheckTree + +Run many filetest checks on a tree + +=item File::Compare + +Compare files or filehandles + +=item File::Copy + +Copy files or filehandles + +=item File::DosGlob + +DOS like globbing and then some + +=item File::Fetch + +A generic file fetching mechanism + +=item File::Find + +Traverse a directory tree. + +=item File::Glob + +Perl extension for BSD glob routine + +=item File::GlobMapper + +Extend File Glob to Allow Input and Output Files + +=item File::Path + +Create or remove directory trees + +=item File::Spec + +Portably perform operations on file names + +=item File::Spec::Cygwin + +Methods for Cygwin file specs + +=item File::Spec::Epoc + +Methods for Epoc file specs + +=item File::Spec::Functions + +Portably perform operations on file names + +=item File::Spec::Mac + +File::Spec for Mac OS (Classic) + +=item File::Spec::OS2 + +Methods for OS/2 file specs + +=item File::Spec::Unix + +File::Spec for Unix, base for other File::Spec modules + +=item File::Spec::VMS + +Methods for VMS file specs + +=item File::Spec::Win32 + +Methods for Win32 file specs + +=item File::Temp + +Return name and handle of a temporary file safely + +=item File::stat + +By-name interface to Perl's built-in stat() functions + +=item FileCache + +Keep more files open than the system permits + +=item FileHandle + +Supply object methods for filehandles + +=item Filter::Simple + +Simplified source filtering + +=item Filter::Util::Call + +Perl Source Filter Utility Module + +=item FindBin + +Locate directory of original perl script + +=item GDBM_File + +Perl5 access to the gdbm library. + +=item Getopt::Long + +Extended processing of command line options + +=item Getopt::Std + +Process single-character switches with switch clustering + +=item Hash::Util + +A selection of general-utility hash subroutines + +=item Hash::Util::FieldHash + +Support for Inside-Out Classes + +=item I18N::Collate + +Compare 8-bit scalar data according to the current locale + +=item I18N::LangTags + +Functions for dealing with RFC3066-style language tags + +=item I18N::LangTags::Detect + +Detect the user's language preferences + +=item I18N::LangTags::List + +Tags and names for human languages + +=item I18N::Langinfo + +Query locale information + +=item IO + +Load various IO modules + +=item IO::Compress::Base + +Base Class for IO::Compress modules + +=item IO::Compress::Bzip2 + +Write bzip2 files/buffers + +=item IO::Compress::Deflate + +Write RFC 1950 files/buffers + +=item IO::Compress::FAQ + +Frequently Asked Questions about IO::Compress + +=item IO::Compress::Gzip + +Write RFC 1952 files/buffers + +=item IO::Compress::RawDeflate + +Write RFC 1951 files/buffers + +=item IO::Compress::Zip + +Write zip files/buffers + +=item IO::Dir + +Supply object methods for directory handles + +=item IO::File + +Supply object methods for filehandles + +=item IO::Handle + +Supply object methods for I/O handles + +=item IO::Pipe + +Supply object methods for pipes + +=item IO::Poll + +Object interface to system poll call + +=item IO::Seekable + +Supply seek based methods for I/O objects + +=item IO::Select + +OO interface to the select system call + +=item IO::Socket + +Object interface to socket communications + +=item IO::Socket::INET + +Object interface for AF_INET domain sockets + +=item IO::Socket::UNIX + +Object interface for AF_UNIX domain sockets + +=item IO::Uncompress::AnyInflate + +Uncompress zlib-based (zip, gzip) file/buffer + +=item IO::Uncompress::AnyUncompress + +Uncompress gzip, zip, bzip2 or lzop file/buffer + +=item IO::Uncompress::Base + +Base Class for IO::Uncompress modules + +=item IO::Uncompress::Bunzip2 + +Read bzip2 files/buffers + +=item IO::Uncompress::Gunzip + +Read RFC 1952 files/buffers + +=item IO::Uncompress::Inflate + +Read RFC 1950 files/buffers + +=item IO::Uncompress::RawInflate + +Read RFC 1951 files/buffers + +=item IO::Uncompress::Unzip + +Read zip files/buffers + +=item IO::Zlib + +IO:: style interface to L<Compress::Zlib> + +=item IPC::Cmd + +Finding and running system commands made easy + +=item IPC::Msg + +SysV Msg IPC object class + +=item IPC::Open2 + +Open a process for both reading and writing using open2() + +=item IPC::Open3 + +Open a process for reading, writing, and error handling using open3() + +=item IPC::Semaphore + +SysV Semaphore IPC object class + +=item IPC::SharedMem + +SysV Shared Memory IPC object class + +=item IPC::SysV + +System V IPC constants and system calls + +=item List::Util + +A selection of general-utility list subroutines + +=item List::Util::XS + +Indicate if List::Util was compiled with a C compiler + +=item Locale::Constants + +Constants for Locale codes + +=item Locale::Country + +ISO codes for country identification (ISO 3166) + +=item Locale::Currency + +ISO three letter codes for currency identification (ISO 4217) + +=item Locale::Language + +ISO two letter codes for language identification (ISO 639) + +=item Locale::Maketext + +Framework for localization + +=item Locale::Maketext::Simple + +Simple interface to Locale::Maketext::Lexicon + +=item Locale::Maketext::TPJ13 + +Article about software localization + +=item Locale::Script + +ISO codes for script identification (ISO 15924) + +=item Log::Message + +A generic message storing mechanism; + +=item Log::Message::Config + +Configuration options for Log::Message + +=item Log::Message::Handlers + +Message handlers for Log::Message + +=item Log::Message::Item + +Message objects for Log::Message + +=item Log::Message::Simple + +Simplified interface to Log::Message + +=item MIME::Base64 + +Encoding and decoding of base64 strings + +=item MIME::QuotedPrint + +Encoding and decoding of quoted-printable strings + +=item Math::BigFloat + +Arbitrary size floating point math package + +=item Math::BigInt + +Arbitrary size integer/float math package + +=item Math::BigInt::Calc + +Pure Perl module to support Math::BigInt + +=item Math::BigInt::CalcEmu + +Emulate low-level math with BigInt code + +=item Math::BigInt::FastCalc + +Math::BigInt::Calc with some XS for more speed + +=item Math::BigRat + +Arbitrary big rational numbers + +=item Math::Complex + +Complex numbers and associated mathematical functions + +=item Math::Trig + +Trigonometric functions + +=item Memoize + +Make functions faster by trading space for time + +=item Memoize::AnyDBM_File + +Glue to provide EXISTS for AnyDBM_File for Storable use + +=item Memoize::Expire + +Plug-in module for automatic expiration of memoized values + +=item Memoize::ExpireFile + +Test for Memoize expiration semantics + +=item Memoize::ExpireTest + +Test for Memoize expiration semantics + +=item Memoize::NDBM_File + +Glue to provide EXISTS for NDBM_File for Storable use + +=item Memoize::SDBM_File + +Glue to provide EXISTS for SDBM_File for Storable use + +=item Memoize::Storable + +Store Memoized data in Storable database + +=item Module::Build + +Build and install Perl modules + +=item Module::Build::API + +API Reference for Module Authors + +=item Module::Build::Authoring + +Authoring Module::Build modules + +=item Module::Build::Base + +Default methods for Module::Build + +=item Module::Build::Bundling + +How to bundle Module::Build with a distribution + +=item Module::Build::Compat + +Compatibility with ExtUtils::MakeMaker + +=item Module::Build::ConfigData + +Configuration for Module::Build + +=item Module::Build::Cookbook + +Examples of Module::Build Usage + +=item Module::Build::ModuleInfo + +Gather package and POD information from a perl module file + +=item Module::Build::Notes + +Create persistent distribution configuration modules + +=item Module::Build::PPMMaker + +Perl Package Manager file creation + +=item Module::Build::Platform::Amiga + +Builder class for Amiga platforms + +=item Module::Build::Platform::Default + +Stub class for unknown platforms + +=item Module::Build::Platform::EBCDIC + +Builder class for EBCDIC platforms + +=item Module::Build::Platform::MPEiX + +Builder class for MPEiX platforms + +=item Module::Build::Platform::MacOS + +Builder class for MacOS platforms + +=item Module::Build::Platform::RiscOS + +Builder class for RiscOS platforms + +=item Module::Build::Platform::Unix + +Builder class for Unix platforms + +=item Module::Build::Platform::VMS + +Builder class for VMS platforms + +=item Module::Build::Platform::VOS + +Builder class for VOS platforms + +=item Module::Build::Platform::Windows + +Builder class for Windows platforms + +=item Module::Build::Platform::aix + +Builder class for AIX platform + +=item Module::Build::Platform::cygwin + +Builder class for Cygwin platform + +=item Module::Build::Platform::darwin + +Builder class for Mac OS X platform + +=item Module::Build::Platform::os2 + +Builder class for OS/2 platform + +=item Module::CoreList + +What modules shipped with versions of perl + +=item Module::Load + +Runtime require of both modules and files + +=item Module::Load::Conditional + +Looking up module information / loading at runtime + +=item Module::Loaded + +Mark modules as loaded or unloaded + +=item Module::Pluggable + +Automatically give your module the ability to have plugins + +=item Module::Pluggable::Object + +Automatically give your module the ability to have plugins + +=item NDBM_File + +Tied access to ndbm files + +=item NEXT + +Provide a pseudo-class NEXT (et al) that allows method redispatch + +=item Net::Cmd + +Network Command class (as used by FTP, SMTP etc) + +=item Net::Config + +Local configuration data for libnet + +=item Net::Domain + +Attempt to evaluate the current host's internet name and domain + +=item Net::FTP + +FTP Client class + +=item Net::NNTP + +NNTP Client class + +=item Net::Netrc + +OO interface to users netrc file + +=item Net::POP3 + +Post Office Protocol 3 Client class (RFC1939) + +=item Net::Ping + +Check a remote host for reachability + +=item Net::SMTP + +Simple Mail Transfer Protocol Client + +=item Net::Time + +Time and daytime network client interface + +=item Net::hostent + +By-name interface to Perl's built-in gethost*() functions + +=item Net::libnetFAQ + +Libnet Frequently Asked Questions + +=item Net::netent + +By-name interface to Perl's built-in getnet*() functions + +=item Net::protoent + +By-name interface to Perl's built-in getproto*() functions + +=item Net::servent + +By-name interface to Perl's built-in getserv*() functions + +=item O + +Generic interface to Perl Compiler backends + +=item ODBM_File + +Tied access to odbm files + +=item Object::Accessor + +Interface to create per object accessors + +=item Opcode + +Disable named opcodes when compiling perl code + +=item POSIX + +Perl interface to IEEE Std 1003.1 + +=item Package::Constants + +List all constants declared in a package + +=item Params::Check + +A generic input parsing/checking mechanism. + +=item Parse::CPAN::Meta + +Parse META.yml and other similar CPAN metadata files + +=item PerlIO + +On demand loader for PerlIO layers and root of PerlIO::* name space + +=item PerlIO::encoding + +Encoding layer + +=item PerlIO::scalar + +In-memory IO, scalar IO + +=item PerlIO::via + +Helper class for PerlIO layers implemented in perl + +=item PerlIO::via::QuotedPrint + +PerlIO layer for quoted-printable strings + +=item Pod::Checker + +Check pod documents for syntax errors + +=item Pod::Escapes + +For resolving Pod EE<lt>...E<gt> sequences + +=item Pod::Find + +Find POD documents in directory trees + +=item Pod::Functions + +Group Perl's functions a la perlfunc.pod + +=item Pod::Html + +Module to convert pod files to HTML + +=item Pod::InputObjects + +Objects representing POD input paragraphs, commands, etc. + +=item Pod::LaTeX + +Convert Pod data to formatted Latex + +=item Pod::Man + +Convert POD data to formatted *roff input + +=item Pod::ParseLink + +Parse an LE<lt>E<gt> formatting code in POD text + +=item Pod::ParseUtils + +Helpers for POD parsing and conversion + +=item Pod::Parser + +Base class for creating POD filters and translators + +=item Pod::Perldoc + +Look up Perl documentation in Pod format. + +=item Pod::Perldoc::BaseTo + +Base for Pod::Perldoc formatters + +=item Pod::Perldoc::GetOptsOO + +Customized option parser for Pod::Perldoc + +=item Pod::Perldoc::ToChecker + +Let Perldoc check Pod for errors + +=item Pod::Perldoc::ToMan + +Let Perldoc render Pod as man pages + +=item Pod::Perldoc::ToNroff + +Let Perldoc convert Pod to nroff + +=item Pod::Perldoc::ToPod + +Let Perldoc render Pod as ... Pod! + +=item Pod::Perldoc::ToRtf + +Let Perldoc render Pod as RTF + +=item Pod::Perldoc::ToText + +Let Perldoc render Pod as plaintext + +=item Pod::Perldoc::ToTk + +Let Perldoc use Tk::Pod to render Pod + +=item Pod::Perldoc::ToXml + +Let Perldoc render Pod as XML + +=item Pod::PlainText + +Convert POD data to formatted ASCII text + +=item Pod::Plainer + +Perl extension for converting Pod to old-style Pod. + +=item Pod::Select + +Extract selected sections of POD from input + +=item Pod::Simple + +Framework for parsing Pod + +=item Pod::Simple::Checker + +Check the Pod syntax of a document + +=item Pod::Simple::Debug + +Put Pod::Simple into trace/debug mode + +=item Pod::Simple::DumpAsText + +Dump Pod-parsing events as text + +=item Pod::Simple::DumpAsXML + +Turn Pod into XML + +=item Pod::Simple::HTML + +Convert Pod to HTML + +=item Pod::Simple::HTMLBatch + +Convert several Pod files to several HTML files + +=item Pod::Simple::LinkSection + +Represent "section" attributes of L codes + +=item Pod::Simple::Methody + +Turn Pod::Simple events into method calls + +=item Pod::Simple::PullParser + +A pull-parser interface to parsing Pod + +=item Pod::Simple::PullParserEndToken + +End-tokens from Pod::Simple::PullParser + +=item Pod::Simple::PullParserStartToken + +Start-tokens from Pod::Simple::PullParser + +=item Pod::Simple::PullParserTextToken + +Text-tokens from Pod::Simple::PullParser + +=item Pod::Simple::PullParserToken + +Tokens from Pod::Simple::PullParser + +=item Pod::Simple::RTF + +Format Pod as RTF + +=item Pod::Simple::Search + +Find POD documents in directory trees + +=item Pod::Simple::SimpleTree + +Parse Pod into a simple parse tree + +=item Pod::Simple::Subclassing + +Write a formatter as a Pod::Simple subclass + +=item Pod::Simple::Text + +Format Pod as plaintext + +=item Pod::Simple::TextContent + +Get the text content of Pod + +=item Pod::Simple::XHTML + +Format Pod as validating XHTML + +=item Pod::Simple::XMLOutStream + +Turn Pod into XML + +=item Pod::Text + +Convert POD data to formatted ASCII text + +=item Pod::Text::Color + +Convert POD data to formatted color ASCII text + +=item Pod::Text::Termcap + +Convert POD data to ASCII text with format escapes + +=item Pod::Usage + +Print a usage message from embedded pod documentation + +=item SDBM_File + +Tied access to sdbm files + +=item Safe + +Compile and execute code in restricted compartments + +=item Scalar::Util + +A selection of general-utility scalar subroutines + +=item Search::Dict + +Search for key in dictionary file + +=item SelectSaver + +Save and restore selected file handle + +=item SelfLoader + +Load functions only on demand + +=item Shell + +Run shell commands transparently within perl + +=item Socket + +Load the C socket.h defines and structure manipulators + +=item Storable + +Persistence for Perl data structures + +=item Switch + +A switch statement for Perl + +=item Symbol + +Manipulate Perl symbols and their names + +=item Sys::Hostname + +Try every conceivable way to get hostname + +=item Sys::Syslog + +Perl interface to the UNIX syslog(3) calls + +=item Sys::Syslog::Win32 + +Win32 support for Sys::Syslog + +=item TAP::Base + +Base class that provides common functionality to L<TAP::Parser> + +=item TAP::Formatter::Color + +Run Perl test scripts with color + +=item TAP::Formatter::Console + +Harness output delegate for default console output + +=item TAP::Formatter::Console + +Harness output delegate for default console output + +=item TAP::Formatter::Console::ParallelSession + +Harness output delegate for parallel console output + +=item TAP::Formatter::Console::Session + +Harness output delegate for default console output + +=item TAP::Formatter::File + +Harness output delegate for file output + +=item TAP::Formatter::File::Session + +Harness output delegate for file output + +=item TAP::Formatter::Session + +Abstract base class for harness output delegate + +=item TAP::Harness + +Run test scripts with statistics + +=item TAP::Object + +Base class that provides common functionality to all C<TAP::*> modules + +=item TAP::Parser + +Parse L<TAP|Test::Harness::TAP> output + +=item TAP::Parser::Aggregator + +Aggregate TAP::Parser results + +=item TAP::Parser::Grammar + +A grammar for the Test Anything Protocol. + +=item TAP::Parser::Iterator + +Internal base class for TAP::Parser Iterators + +=item TAP::Parser::Iterator::Array + +Internal TAP::Parser array Iterator + +=item TAP::Parser::Iterator::Process + +Internal TAP::Parser Iterator + +=item TAP::Parser::Iterator::Stream + +Internal TAP::Parser Iterator + +=item TAP::Parser::IteratorFactory + +Internal TAP::Parser Iterator + +=item TAP::Parser::Multiplexer + +Multiplex multiple TAP::Parsers + +=item TAP::Parser::Result + +Base class for TAP::Parser output objects + +=item TAP::Parser::Result::Bailout + +Bailout result token. + +=item TAP::Parser::Result::Comment + +Comment result token. + +=item TAP::Parser::Result::Plan + +Plan result token. + +=item TAP::Parser::Result::Pragma + +TAP pragma token. + +=item TAP::Parser::Result::Test + +Test result token. + +=item TAP::Parser::Result::Unknown + +Unknown result token. + +=item TAP::Parser::Result::Version + +TAP syntax version token. + +=item TAP::Parser::Result::YAML + +YAML result token. + +=item TAP::Parser::ResultFactory + +Factory for creating TAP::Parser output objects + +=item TAP::Parser::Scheduler + +Schedule tests during parallel testing + +=item TAP::Parser::Scheduler::Job + +A single testing job. + +=item TAP::Parser::Scheduler::Spinner + +A no-op job. + +=item TAP::Parser::Source + +Stream output from some source + +=item TAP::Parser::Source::Perl + +Stream Perl output + +=item TAP::Parser::Utils + +Internal TAP::Parser utilities + +=item TAP::Parser::YAMLish::Reader + +Read YAMLish data from iterator + +=item TAP::Parser::YAMLish::Writer + +Write YAMLish data + +=item Term::ANSIColor + +Color screen output using ANSI escape sequences + +=item Term::Cap + +Perl termcap interface + +=item Term::Complete + +Perl word completion module + +=item Term::ReadLine + +Perl interface to various C<readline> packages. + +=item Term::UI + +Term::ReadLine UI made easy + +=item Test + +Provides a simple framework for writing test scripts + +=item Test::Builder + +Backend for building test libraries + +=item Test::Builder::Module + +Base class for test modules + +=item Test::Builder::Tester + +Test testsuites that have been built with + +=item Test::Builder::Tester::Color + +Turn on colour in Test::Builder::Tester + +=item Test::Harness + +Run Perl standard test scripts with statistics + +=item Test::More + +Yet another framework for writing test scripts + +=item Test::Simple + +Basic utilities for writing tests. + +=item Test::Tutorial + +A tutorial about writing really basic tests + +=item Text::Abbrev + +Create an abbreviation table from a list + +=item Text::Balanced + +Extract delimited text sequences from strings. + +=item Text::ParseWords + +Parse text into an array of tokens or array of arrays + +=item Text::Soundex + +Implementation of the soundex algorithm. + +=item Text::Tabs + +Expand and unexpand tabs per the unix expand(1) and unexpand(1) + +=item Text::Wrap + +Line wrapping to form simple paragraphs + +=item Thread + +Manipulate threads in Perl (for old code only) + +=item Thread::Queue + +Thread-safe queues + +=item Thread::Semaphore + +Thread-safe semaphores + +=item Tie::Array + +Base class for tied arrays + +=item Tie::File + +Access the lines of a disk file via a Perl array + +=item Tie::Handle + +Base class definitions for tied handles + +=item Tie::Hash + +Base class definitions for tied hashes + +=item Tie::Hash::NamedCapture + +Named regexp capture buffers + +=item Tie::Memoize + +Add data to hash when needed + +=item Tie::RefHash + +Use references as hash keys + +=item Tie::Scalar + +Base class definitions for tied scalars + +=item Tie::StdHandle + +Base class definitions for tied handles + +=item Tie::SubstrHash + +Fixed-table-size, fixed-key-length hashing + +=item Time::HiRes + +High resolution alarm, sleep, gettimeofday, interval timers + +=item Time::Local + +Efficiently compute time from local and GMT time + +=item Time::Piece + +Object Oriented time objects + +=item Time::Seconds + +A simple API to convert seconds to other date values + +=item Time::gmtime + +By-name interface to Perl's built-in gmtime() function + +=item Time::localtime + +By-name interface to Perl's built-in localtime() function + +=item Time::tm + +Internal object used by Time::gmtime and Time::localtime + +=item UNIVERSAL + +Base class for ALL classes (blessed references) + +=item Unicode::Collate + +Unicode Collation Algorithm + +=item Unicode::Normalize + +Unicode Normalization Forms + +=item Unicode::UCD + +Unicode character database + +=item User::grent + +By-name interface to Perl's built-in getgr*() functions + +=item User::pwent + +By-name interface to Perl's built-in getpw*() functions + +=item VMS::DCLsym + +Perl extension to manipulate DCL symbols + +=item VMS::Stdio + +Standard I/O functions via VMS extensions + +=item Win32 + +Interfaces to some Win32 API Functions + +=item Win32API::File + +Low-level access to Win32 system API calls for files/dirs. + +=item Win32CORE + +Win32 CORE function stubs + +=item XS::APItest + +Test the perl C API + +=item XS::APItest::KeywordRPN + +Write arithmetic expressions in RPN + +=item XS::Typemap + +Module to test the XS typemaps distributed with perl + +=item XSLoader + +Dynamically load C libraries into Perl code + +=item version::Internals + +Perl extension for Version Objects + +=back + +To find out I<all> modules installed on your system, including +those without documentation or outside the standard release, +just use the following command (under the default win32 shell, +double quotes should be used instead of single quotes). + + % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \ + 'find { wanted => sub { print canonpath $_ if /\.pm\z/ }, + no_chdir => 1 }, @INC' + +(The -T is here to prevent '.' from being listed in @INC.) +They should all have their own documentation installed and accessible +via your system man(1) command. If you do not have a B<find> +program, you can use the Perl B<find2perl> program instead, which +generates Perl code as output you can run through perl. If you +have a B<man> program but it doesn't find your modules, you'll have +to fix your manpath. See L<perl> for details. If you have no +system B<man> command, you might try the B<perldoc> program. + +Note also that the command C<perldoc perllocal> gives you a (possibly +incomplete) list of the modules that have been further installed on +your system. (The perllocal.pod file is updated by the standard MakeMaker +install process.) + +=head2 Extension Modules + +Extension modules are written in C (or a mix of Perl and C). They +are usually dynamically loaded into Perl if and when you need them, +but may also be linked in statically. Supported extension modules +include Socket, Fcntl, and POSIX. + +Many popular C extension modules do not come bundled (at least, not +completely) due to their sizes, volatility, or simply lack of time +for adequate testing and configuration across the multitude of +platforms on which Perl was beta-tested. You are encouraged to +look for them on CPAN (described below), or using web search engines +like Alta Vista or Google. + +=head1 CPAN + +CPAN stands for Comprehensive Perl Archive Network; it's a globally +replicated trove of Perl materials, including documentation, style +guides, tricks and traps, alternate ports to non-Unix systems and +occasional binary distributions for these. Search engines for +CPAN can be found at http://www.cpan.org/ + +Most importantly, CPAN includes around a thousand unbundled modules, +some of which require a C compiler to build. Major categories of +modules are: + +=over + +=item * + +Language Extensions and Documentation Tools + +=item * + +Development Support + +=item * + +Operating System Interfaces + +=item * + +Networking, Device Control (modems) and InterProcess Communication + +=item * + +Data Types and Data Type Utilities + +=item * + +Database Interfaces + +=item * + +User Interfaces + +=item * + +Interfaces to / Emulations of Other Programming Languages + +=item * + +File Names, File Systems and File Locking (see also File Handles) + +=item * + +String Processing, Language Text Processing, Parsing, and Searching + +=item * + +Option, Argument, Parameter, and Configuration File Processing + +=item * + +Internationalization and Locale + +=item * + +Authentication, Security, and Encryption + +=item * + +World Wide Web, HTML, HTTP, CGI, MIME + +=item * + +Server and Daemon Utilities + +=item * + +Archiving and Compression + +=item * + +Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing + +=item * + +Mail and Usenet News + +=item * + +Control Flow Utilities (callbacks and exceptions etc) + +=item * + +File Handle and Input/Output Stream Utilities + +=item * + +Miscellaneous Modules + +=back + +The list of the registered CPAN sites follows. +Please note that the sorting order is alphabetical on fields: + +Continent + | + |-->Country + | + |-->[state/province] + | + |-->ftp + | + |-->[http] + +and thus the North American servers happen to be listed between the +European and the South American sites. + +Registered CPAN sites + +=head2 Africa + +=over 4 + +=item South Africa + + http://cpan.mirror.ac.za/ + ftp://cpan.mirror.ac.za/ + http://mirror.is.co.za/pub/cpan/ + ftp://ftp.is.co.za/pub/cpan/ + ftp://ftp.saix.net/pub/CPAN/ + +=back + +=head2 Asia + +=over 4 + +=item Hong Kong + + http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/ + ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/ + http://mirrors.geoexpat.com/cpan/ + +=item India + + http://perlmirror.indialinks.com/ + +=item Indonesia + + http://cpan.biz.net.id/ + http://komo.vlsm.org/CPAN/ + ftp://komo.vlsm.org/CPAN/ + http://cpan.pesat.net.id/ + http://mirror.unej.ac.id/cpan/ + ftp://mirror.unej.ac.id/cpan/ + +=item Japan + + ftp://ftp.u-aizu.ac.jp/pub/CPAN + ftp://ftp.kddilabs.jp/CPAN/ + http://ftp.nara.wide.ad.jp/pub/CPAN/ + ftp://ftp.nara.wide.ad.jp/pub/CPAN/ + http://ftp.jaist.ac.jp/pub/CPAN/ + ftp://ftp.jaist.ac.jp/pub/CPAN/ + ftp://ftp.dti.ad.jp/pub/lang/CPAN/ + ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/ + http://ftp.riken.jp/lang/CPAN/ + ftp://ftp.riken.jp/lang/CPAN/ + http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/ + ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/ + +=item Kazakhstan + + http://mirror.linuxiso.kz/CPAN/ + +=item Republic of Korea + + http://ftp.kaist.ac.kr/pub/CPAN + ftp://ftp.kaist.ac.kr/pub/CPAN + http://cpan.mirror.cdnetworks.com/ + ftp://cpan.mirror.cdnetworks.com/CPAN/ + http://cpan.sarang.net/ + ftp://cpan.sarang.net/CPAN/ + +=item Russia + + http://cpan.tomsk.ru/ + ftp://cpan.tomsk.ru/ + +=item Singapore + + http://mirror.averse.net/pub/CPAN + ftp://mirror.averse.net/pub/CPAN + http://cpan.mirror.choon.net/ + http://cpan.oss.eznetsols.org + ftp://ftp.oss.eznetsols.org/cpan + +=item Taiwan + + http://ftp.cse.yzu.edu.tw/pub/CPAN/ + ftp://ftp.cse.yzu.edu.tw/pub/CPAN/ + http://cpan.nctu.edu.tw/ + ftp://cpan.nctu.edu.tw/ + ftp://ftp.ncu.edu.tw/CPAN/ + http://cpan.cdpa.nsysu.edu.tw/ + ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/ + http://cpan.stu.edu.tw + ftp://ftp.stu.edu.tw/CPAN + http://ftp.stu.edu.tw/CPAN + ftp://ftp.stu.edu.tw/pub/CPAN + http://cpan.cs.pu.edu.tw/ + ftp://cpan.cs.pu.edu.tw/pub/CPAN + +=item Thailand + + http://mirrors.issp.co.th/cpan/ + ftp://mirrors.issp.co.th/cpan/ + +=item Turkey + + http://cpan.gazi.edu.tr/ + http://cpan.ulak.net.tr + ftp://ftp.ulak.net.tr/pub/CPAN + +=item Viet Nam + + http://mirror-fpt-telecom.fpt.net/cpan/ + ftp://mirror-fpt-telecom.fpt.net/cpan/ + +=back + +=head2 Central America + +=over 4 + +=item Costa Rica + + http://mirrors.ucr.ac.cr/CPAN/ + ftp://mirrors.ucr.ac.cr/CPAN/ + +=back + +=head2 Europe + +=over 4 + +=item Austria + + http://cpan.inode.at/ + ftp://cpan.inode.at + http://gd.tuwien.ac.at/languages/perl/CPAN/ + ftp://gd.tuwien.ac.at/pub/CPAN/ + +=item Belgium + + http://ftp.belnet.be/mirror/ftp.cpan.org/ + ftp://ftp.belnet.be/mirror/ftp.cpan.org/ + http://ftp.easynet.be/pub/CPAN/ + http://cpan.weepee.org/ + http://cpan.fluoline.net/ + +=item Bosnia and Herzegovina + + http://cpan.blic.net/ + +=item Bulgaria + + http://cpan.cbox.biz/ + ftp://cpan.cbox.biz/cpan/ + http://cpan.digsys.bg/ + ftp://ftp.digsys.bg/pub/CPAN + +=item Croatia + + http://ftp.carnet.hr/pub/CPAN/ + ftp://ftp.carnet.hr/pub/CPAN/ + +=item Czech Republic + + ftp://ftp.fi.muni.cz/pub/CPAN/ + http://archive.cpan.cz/ + +=item Denmark + + http://mirrors.dotsrc.org/cpan + ftp://mirrors.dotsrc.org/cpan/ + http://www.cpan.dk/ + http://mirror.uni-c.dk/pub/CPAN/ + +=item Finland + + ftp://ftp.funet.fi/pub/languages/perl/CPAN/ + http://mirror.eunet.fi/CPAN + +=item France + + http://cpan.enstimac.fr/ + ftp://ftp.inria.fr/pub/CPAN/ + http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ + ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ + ftp://ftp.lip6.fr/pub/perl/CPAN/ + http://mir2.ovh.net/ftp.cpan.org + ftp://mir1.ovh.net/ftp.cpan.org + http://cpan.miroir-francais.fr/ + ftp://miroir-francais.fr/pub/cpan/ + ftp://ftp.oleane.net/pub/CPAN/ + http://ftp.crihan.fr/mirrors/ftp.cpan.org/ + ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/ + http://ftp.u-strasbg.fr/CPAN + ftp://ftp.u-strasbg.fr/CPAN + http://cpan.cict.fr/ + ftp://cpan.cict.fr/pub/CPAN/ + +=item Germany + + ftp://ftp.fu-berlin.de/unix/languages/perl/ + http://mirrors.softliste.de/cpan/ + ftp://ftp.rub.de/pub/CPAN/ + http://www.planet-elektronik.de/CPAN/ + http://ftp.hosteurope.de/pub/CPAN/ + ftp://ftp.hosteurope.de/pub/CPAN/ + http://www.mirrorspace.org/cpan/ + http://mirror.netcologne.de/cpan/ + ftp://mirror.netcologne.de/cpan/ + ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/ + http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/ + ftp://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/ + http://mirrors.zerg.biz/cpan/ + http://ftp.gwdg.de/pub/languages/perl/CPAN/ + ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ + http://dl.ambiweb.de/mirrors/ftp.cpan.org/ + http://cpan.mirror.clusters.kg/ + http://cpan.mirror.iphh.net/ + ftp://cpan.mirror.iphh.net/pub/CPAN/ + http://cpan.mirroring.de/ + http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/ + ftp://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/ + http://ftp.cw.net/pub/CPAN/ + ftp://ftp.cw.net/pub/CPAN/ + http://cpan.cpantesters.org/ + ftp://cpan.cpantesters.org/CPAN/ + http://cpan.mirrored.de/ + ftp://mirror.petamem.com/CPAN/ + http://cpan.noris.de/ + ftp://cpan.noris.de/pub/CPAN/ + ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ + ftp://ftp.gmd.de/mirrors/CPAN/ + +=item Greece + + ftp://ftp.forthnet.gr/pub/languages/perl/CPAN + ftp://ftp.ntua.gr/pub/lang/perl/ + http://cpan.cc.uoc.gr/ + ftp://ftp.cc.uoc.gr/mirrors/CPAN/ + +=item Hungary + + http://cpan.mirrors.enexis.hu/ + ftp://cpan.mirrors.enexis.hu/mirrors/cpan/ + http://cpan.hu/ + +=item Iceland + + http://ftp.rhnet.is/pub/CPAN/ + ftp://ftp.rhnet.is/pub/CPAN/ + +=item Ireland + + http://ftp.esat.net/pub/languages/perl/CPAN/ + ftp://ftp.esat.net/pub/languages/perl/CPAN/ + http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN + ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN + +=item Italy + + http://bo.mirror.garr.it/mirrors/CPAN/ + http://cpan.panu.it/ + ftp://ftp.panu.it/pub/mirrors/perl/CPAN/ + http://cpan.fastbull.org/ + +=item Latvia + + http://kvin.lv/pub/CPAN/ + +=item Lithuania + + http://ftp.litnet.lt/pub/CPAN/ + ftp://ftp.litnet.lt/pub/CPAN/ + +=item Malta + + http://cpan.waldonet.net.mt/ + +=item Netherlands + + ftp://ftp.quicknet.nl/pub/CPAN/ + http://mirror.hostfuss.com/CPAN/ + ftp://mirror.hostfuss.com/CPAN/ + http://mirrors3.kernel.org/cpan/ + ftp://mirrors3.kernel.org/pub/CPAN/ + http://cpan.osmirror.nl/ + ftp://ftp.osmirror.nl/pub/cpan/ + http://cpan.mirror.versatel.nl/ + ftp://ftp.mirror.versatel.nl/cpan/ + ftp://download.xs4all.nl/pub/mirror/CPAN/ + http://mirror.leaseweb.com/CPAN/ + ftp://mirror.leaseweb.com/CPAN/ + ftp://ftp.cpan.nl/pub/CPAN/ + http://archive.cs.uu.nl/mirror/CPAN/ + ftp://ftp.cs.uu.nl/mirror/CPAN/ + http://https://luxitude.net/cpan/ + +=item Norway + + ftp://ftp.uninett.no/pub/languages/perl/CPAN + ftp://ftp.uit.no/pub/languages/perl/cpan/ + +=item Poland + + http://mirror.icis.pcz.pl/CPAN/ + ftp://mirror.icis.pcz.pl/CPAN/ + http://piotrkosoft.net/pub/mirrors/CPAN/ + ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/ + http://ftp.man.poznan.pl/pub/CPAN + ftp://ftp.man.poznan.pl/pub/CPAN + ftp://sunsite.icm.edu.pl/pub/CPAN/ + ftp://ftp.tpnet.pl/d4/CPAN/ + +=item Portugal + + http://cpan.dei.uc.pt/ + ftp://ftp.dei.uc.pt/pub/CPAN + ftp://ftp.ist.utl.pt/pub/CPAN/ + http://cpan.perl.pt/ + http://cpan.ip.pt/ + ftp://cpan.ip.pt/pub/cpan/ + http://mirrors.nfsi.pt/CPAN/ + ftp://mirrors.nfsi.pt/pub/CPAN/ + http://cpan.dcc.fc.up.pt/ + +=item Romania + + http://ftp.astral.ro/pub/CPAN/ + ftp://ftp.astral.ro/pub/CPAN/ + ftp://ftp.lug.ro/CPAN + http://mirrors.xservers.ro/CPAN/ + http://mirrors.hostingromania.ro/ftp.cpan.org/ + ftp://ftp.hostingromania.ro/mirrors/ftp.cpan.org/ + ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/ + ftp://ftp.ambra.ro/pub/CPAN + +=item Russia + + ftp://ftp.aha.ru/CPAN/ + http://cpan.rinet.ru/ + ftp://cpan.rinet.ru/pub/mirror/CPAN/ + ftp://ftp.SpringDaemons.com/pub/CPAN/ + http://cpan.nx1.ru/ + ftp://cpan.nx1.ru/ + http://mirror.rol.ru/CPAN/ + http://ftp.silvernet.ru/CPAN/ + http://ftp.spbu.ru/CPAN/ + ftp://ftp.spbu.ru/CPAN/ + +=item Slovakia + + http://cpan.fyxm.net/ + +=item Slovenia + + http://www.klevze.si/cpan + +=item Spain + + http://osl.ugr.es/CPAN/ + ftp://ftp.rediris.es/mirror/CPAN/ + http://ftp.gui.uva.es/sites/cpan.org/ + ftp://ftp.gui.uva.es/sites/cpan.org/ + +=item Sweden + + http://mirrors4.kernel.org/cpan/ + ftp://mirrors4.kernel.org/pub/CPAN/ + +=item Switzerland + + http://cpan.mirror.solnet.ch/ + ftp://ftp.solnet.ch/mirror/CPAN/ + http://mirror.switch.ch/ftp/mirror/CPAN/ + ftp://mirror.switch.ch/mirror/CPAN/ + +=item Ukraine + + http://cpan.makeperl.org/ + ftp://cpan.makeperl.org/pub/CPAN + http://cpan.org.ua/ + http://no-more.kiev.ua/CPAN/ + ftp://no-more.kiev.ua/pub/CPAN/ + http://cpan.gafol.net/ + ftp://ftp.gafol.net/pub/cpan/ + +=item United Kingdom + + http://www.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/ + ftp://ftp.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/ + http://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/ + ftp://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/ + http://www.mirror.8086.net/sites/CPAN/ + ftp://ftp.mirror.8086.net/sites/CPAN/ + http://cpan.mirror.anlx.net/ + ftp://ftp.mirror.anlx.net/CPAN/ + http://mirror.bytemark.co.uk/CPAN/ + ftp://mirror.bytemark.co.uk/CPAN/ + http://cpan.etla.org/ + ftp://cpan.etla.org/pub/CPAN + ftp://ftp.demon.co.uk/pub/CPAN/ + http://mirror.sov.uk.goscomb.net/CPAN/ + ftp://mirror.sov.uk.goscomb.net/pub/CPAN/ + http://ftp.plig.net/pub/CPAN/ + ftp://ftp.plig.net/pub/CPAN/ + http://ftp.ticklers.org/pub/CPAN/ + ftp://ftp.ticklers.org/pub/CPAN/ + http://cpan.mirrors.uk2.net/ + ftp://mirrors.uk2.net/pub/CPAN/ + http://mirror.ox.ac.uk/sites/www.cpan.org/ + ftp://mirror.ox.ac.uk/sites/www.cpan.org/ + +=back + +=head2 North America + +=over 4 + +=item Bahamas + + http://www.securehost.com/mirror/CPAN/ + +=item Canada + + http://cpan.justanotherperlhacker.com/pub/CPAN/ + ftp://cpan.justanotherperlhacker.com/pub/CPAN/ + http://cpan.arcticnetwork.ca + ftp://mirror.arcticnetwork.ca/pub/CPAN + http://cpan.sunsite.ualberta.ca/ + ftp://cpan.sunsite.ualberta.ca/pub/CPAN/ + http://theoryx5.uwinnipeg.ca/pub/CPAN/ + ftp://theoryx5.uwinnipeg.ca/pub/CPAN/ + http://arwen.cs.dal.ca/mirror/CPAN/ + ftp://arwen.cs.dal.ca/pub/mirror/CPAN/ + http://CPAN.mirror.rafal.ca/ + ftp://CPAN.mirror.rafal.ca/pub/CPAN/ + ftp://ftp.nrc.ca/pub/CPAN/ + http://mirror.csclub.uwaterloo.ca/pub/CPAN/ + ftp://mirror.csclub.uwaterloo.ca/pub/CPAN/ + +=item Mexico + + http://www.msg.com.mx/CPAN/ + ftp://ftp.msg.com.mx/pub/CPAN/ + +=item United States + +=over 8 + +=item Alabama + + http://mirror.hiwaay.net/CPAN/ + ftp://mirror.hiwaay.net/CPAN/ + +=item California + + http://cpan.knowledgematters.net/ + http://cpan.binkerton.com/ + http://cpan.develooper.com/ + http://mirrors.gossamer-threads.com/CPAN + http://cpan.schatt.com/ + http://mirrors.kernel.org/cpan/ + ftp://mirrors.kernel.org/pub/CPAN + http://mirrors2.kernel.org/cpan/ + ftp://mirrors2.kernel.org/pub/CPAN/ + http://cpan.mirrors.redwire.net/ + http://cpan.mirror.facebook.net/ + http://mirrors1.kernel.org/cpan/ + ftp://mirrors1.kernel.org/pub/CPAN/ + http://cpan-sj.viaverio.com/ + ftp://cpan-sj.viaverio.com/pub/CPAN/ + http://www.perl.com/CPAN/ + http://cpan.yahoo.com/ + +=item Florida + + ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/ + http://mirror.atlantic.net/pub/CPAN/ + ftp://mirror.atlantic.net/pub/CPAN/ + http://mirror.candidhosting.com/pub/CPAN + ftp://mirror.candidhosting.com/pub/CPAN + +=item Idaho + + http://mirror.its.uidaho.edu/pub/cpan/ + ftp://mirror.its.uidaho.edu/cpan/ + +=item Illinois + + http://cpan.mirrors.hoobly.com/ + http://cpan.uchicago.edu/pub/CPAN/ + ftp://cpan.uchicago.edu/pub/CPAN/ + http://mirrors.servercentral.net/CPAN/ + http://www.stathy.com/CPAN/ + ftp://www.stathy.com/CPAN/ + +=item Indiana + + ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/ + http://cpan.netnitco.net/ + ftp://cpan.netnitco.net/pub/mirrors/CPAN/ + http://ftp.ndlug.nd.edu/pub/perl/ + ftp://ftp.ndlug.nd.edu/pub/perl/ + http://fx.saintjoe.edu/pub/CPAN + +=item Massachusetts + + ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ + +=item Michigan + + http://ftp.wayne.edu/cpan/ + ftp://ftp.wayne.edu/cpan/ + +=item Minnesota + + http://cpan.msi.umn.edu/ + +=item New Jersey + + http://mirror.datapipe.net/CPAN/ + ftp://mirror.datapipe.net/pub/CPAN/ + +=item New York + + http://mirrors.24-7-solutions.net/pub/CPAN/ + ftp://mirrors.24-7-solutions.net/pub/CPAN/ + http://mirror.cc.columbia.edu/pub/software/cpan/ + ftp://mirror.cc.columbia.edu/pub/software/cpan/ + http://cpan.belfry.net/ + http://cpan.erlbaum.net/ + ftp://cpan.erlbaum.net/CPAN/ + http://cpan.hexten.net/ + ftp://cpan.hexten.net/ + http://ftp.fxcorporate.com/CPAN/ + ftp://ftp.fxcorporate.com/pub/CPAN/ + ftp://mirror.nyi.net/CPAN/ + http://mirror.rit.edu/CPAN/ + ftp://mirror.rit.edu/CPAN/ + +=item North Carolina + + http://www.ibiblio.org/pub/mirrors/CPAN + ftp://ftp.ncsu.edu/pub/mirror/CPAN/ + +=item Oregon + + http://ftp.osuosl.org/pub/CPAN/ + ftp://ftp.osuosl.org/pub/CPAN/ + +=item Pennsylvania + + http://ftp.epix.net/CPAN/ + ftp://ftp.epix.net/pub/languages/perl/ + http://cpan.pair.com/ + ftp://cpan.pair.com/pub/CPAN/ + +=item South Carolina + + http://cpan.mirror.clemson.edu/ + +=item Tennessee + + http://mira.sunsite.utk.edu/CPAN/ + +=item Texas + + http://mirror.uta.edu/CPAN + +=item Utah + + http://cpan.cs.utah.edu + ftp://cpan.cs.utah.edu/pub/CPAN/ + ftp://mirror.xmission.com/CPAN/ + +=item Virginia + + http://cpan-du.viaverio.com/ + ftp://cpan-du.viaverio.com/pub/CPAN/ + http://perl.secsup.org/ + ftp://perl.secsup.org/pub/perl/ + ftp://mirror.cogentco.com/pub/CPAN/ + +=item Washington + + http://cpan.llarian.net/ + ftp://cpan.llarian.net/pub/CPAN/ + ftp://ftp-mirror.internap.com/pub/CPAN/ + +=item Wisconsin + + http://cpan.mirrors.tds.net + ftp://cpan.mirrors.tds.net/pub/CPAN + http://mirror.sit.wisc.edu/pub/CPAN/ + ftp://mirror.sit.wisc.edu/pub/CPAN/ + +=back + +=back + +=head2 Oceania + +=over 4 + +=item Australia + + http://mirror.internode.on.net/pub/cpan/ + ftp://mirror.internode.on.net/pub/cpan/ + http://cpan.mirror.aussiehq.net.au/ + http://mirror.as24220.net/cpan/ + ftp://mirror.as24220.net/cpan/ + +=item New Zealand + + ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ + http://cpan.inspire.net.nz + ftp://cpan.inspire.net.nz/cpan + http://cpan.catalyst.net.nz/CPAN/ + ftp://cpan.catalyst.net.nz/pub/CPAN/ + +=back + +=head2 South America + +=over 4 + +=item Argentina + + http://cpan.patan.com.ar/ + http://cpan.localhost.net.ar + ftp://mirrors.localhost.net.ar/pub/mirrors/CPAN + +=item Brazil + + ftp://cpan.pop-mg.com.br/pub/CPAN/ + http://ftp.pucpr.br/CPAN + ftp://ftp.pucpr.br/CPAN + http://cpan.kinghost.net/ + ftp://ftp.linorg.usp.br/CPAN + +=item Chile + + http://cpan.dcc.uchile.cl/ + ftp://cpan.dcc.uchile.cl/pub/lang/cpan/ + +=item Colombia + + http://www.laqee.unal.edu.co/CPAN/ + +=back + +=head2 RSYNC Mirrors + + mirror.as24220.net::cpan + cpan.inode.at::CPAN + gd.tuwien.ac.at::CPAN + ftp.belnet.be::packages/cpan + rsync.linorg.usp.br::CPAN + rsync.arcticnetwork.ca::CPAN + CPAN.mirror.rafal.ca::CPAN + mirror.csclub.uwaterloo.ca::CPAN + theoryx5.uwinnipeg.ca::CPAN + www.laqee.unal.edu.co::CPAN + mirror.uni-c.dk::CPAN + rsync.nic.funet.fi::CPAN + rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ + mir1.ovh.net::CPAN + miroir-francais.fr::cpan + ftp.crihan.fr::CPAN + rsync://mirror.cict.fr/cpan/ + rsync://mirror.netcologne.de/cpan/ + ftp-stud.hs-esslingen.de::CPAN/ + ftp.gwdg.de::FTP/languages/perl/CPAN/ + cpan.mirror.iphh.net::CPAN + cpan.cpantesters.org::cpan + cpan.hu::CPAN + komo.vlsm.org::CPAN + mirror.unej.ac.id::cpan + ftp.esat.net::/pub/languages/perl/CPAN + ftp.heanet.ie::mirrors/ftp.perl.org/pub/CPAN + rsync.panu.it::CPAN + cpan.fastbull.org::CPAN + ftp.kddilabs.jp::cpan + ftp.nara.wide.ad.jp::cpan/ + rsync://ftp.jaist.ac.jp/pub/CPAN/ + rsync://ftp.riken.jp/cpan/ + mirror.linuxiso.kz::CPAN + rsync://mirrors3.kernel.org/mirrors/CPAN/ + rsync://rsync.osmirror.nl/cpan/ + mirror.leaseweb.com::CPAN + cpan.nautile.nc::CPAN + mirror.icis.pcz.pl::CPAN + piotrkosoft.net::mirrors/CPAN + rsync://cpan.perl.pt/ + ftp.kaist.ac.kr::cpan + cpan.sarang.net::CPAN + mirror.averse.net::cpan + rsync.oss.eznetsols.org + mirror.ac.za::cpan + ftp.is.co.za::IS-Mirror/ftp.cpan.org/ + rsync://ftp.gui.uva.es/cpan/ + rsync://mirrors4.kernel.org/mirrors/CPAN/ + ftp.solnet.ch::CPAN + ftp.ulak.net.tr::CPAN + gafol.net::cpan + rsync.mirrorservice.org::ftp.funet.fi/pub/ + rsync://rsync.mirror.8086.net/CPAN/ + rsync.mirror.anlx.net::CPAN + mirror.bytemark.co.uk::CPAN + ftp.plig.net::CPAN + rsync://ftp.ticklers.org:CPAN/ + mirrors.ibiblio.org::CPAN + cpan-du.viaverio.com::CPAN + mirror.hiwaay.net::CPAN + rsync://mira.sunsite.utk.edu/CPAN/ + cpan.mirrors.tds.net::CPAN + mirror.its.uidaho.edu::cpan + rsync://mirror.cc.columbia.edu::cpan/ + ftp.fxcorporate.com::CPAN + rsync.atlantic.net::CPAN + mirrors.kernel.org::mirrors/CPAN + rsync://mirrors2.kernel.org/mirrors/CPAN/ + cpan.pair.com::CPAN + rsync://mirror.rit.edu/CPAN/ + rsync://mirror.facebook.net/cpan/ + rsync://mirrors1.kernel.org/mirrors/CPAN/ + cpan-sj.viaverio.com::CPAN + +For an up-to-date listing of CPAN sites, +see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES . + +=head1 Modules: Creation, Use, and Abuse + +(The following section is borrowed directly from Tim Bunce's modules +file, available at your nearest CPAN site.) + +Perl implements a class using a package, but the presence of a +package doesn't imply the presence of a class. A package is just a +namespace. A class is a package that provides subroutines that can be +used as methods. A method is just a subroutine that expects, as its +first argument, either the name of a package (for "static" methods), +or a reference to something (for "virtual" methods). + +A module is a file that (by convention) provides a class of the same +name (sans the .pm), plus an import method in that class that can be +called to fetch exported symbols. This module may implement some of +its methods by loading dynamic C or C++ objects, but that should be +totally transparent to the user of the module. Likewise, the module +might set up an AUTOLOAD function to slurp in subroutine definitions on +demand, but this is also transparent. Only the F<.pm> file is required to +exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about +the AUTOLOAD mechanism. + +=head2 Guidelines for Module Creation + +=over 4 + +=item * + +Do similar modules already exist in some form? + +If so, please try to reuse the existing modules either in whole or +by inheriting useful features into a new class. If this is not +practical try to get together with the module authors to work on +extending or enhancing the functionality of the existing modules. +A perfect example is the plethora of packages in perl4 for dealing +with command line options. + +If you are writing a module to expand an already existing set of +modules, please coordinate with the author of the package. It +helps if you follow the same naming scheme and module interaction +scheme as the original author. + +=item * + +Try to design the new module to be easy to extend and reuse. + +Try to C<use warnings;> (or C<use warnings qw(...);>). +Remember that you can add C<no warnings qw(...);> to individual blocks +of code that need less warnings. + +Use blessed references. Use the two argument form of bless to bless +into the class name given as the first parameter of the constructor, +e.g.,: + + sub new { + my $class = shift; + return bless {}, $class; + } + +or even this if you'd like it to be used as either a static +or a virtual method. + + sub new { + my $self = shift; + my $class = ref($self) || $self; + return bless {}, $class; + } + +Pass arrays as references so more parameters can be added later +(it's also faster). Convert functions into methods where +appropriate. Split large methods into smaller more flexible ones. +Inherit methods from other modules if appropriate. + +Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>. +Generally you can delete the C<eq 'FOO'> part with no harm at all. +Let the objects look after themselves! Generally, avoid hard-wired +class names as far as possible. + +Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and +C<< $r->func() >> would work (see L<perlbot> for more details). + +Use autosplit so little used or newly added functions won't be a +burden to programs that don't use them. Add test functions to +the module after __END__ either using AutoSplit or by saying: + + eval join('',<main::DATA>) || die $@ unless caller(); + +Does your module pass the 'empty subclass' test? If you say +C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able +to use SUBCLASS in exactly the same way as YOURCLASS. For example, +does your application still work if you change: C<< $obj = YOURCLASS->new(); >> +into: C<< $obj = SUBCLASS->new(); >> ? + +Avoid keeping any state information in your packages. It makes it +difficult for multiple other packages to use yours. Keep state +information in objects. + +Always use B<-w>. + +Try to C<use strict;> (or C<use strict qw(...);>). +Remember that you can add C<no strict qw(...);> to individual blocks +of code that need less strictness. + +Always use B<-w>. + +Follow the guidelines in L<perlstyle>. + +Always use B<-w>. + +=item * + +Some simple style guidelines + +The perlstyle manual supplied with Perl has many helpful points. + +Coding style is a matter of personal taste. Many people evolve their +style over several years as they learn what helps them write and +maintain good code. Here's one set of assorted suggestions that +seem to be widely used by experienced developers: + +Use underscores to separate words. It is generally easier to read +$var_names_like_this than $VarNamesLikeThis, especially for +non-native speakers of English. It's also a simple rule that works +consistently with VAR_NAMES_LIKE_THIS. + +Package/Module names are an exception to this rule. Perl informally +reserves lowercase module names for 'pragma' modules like integer +and strict. Other modules normally begin with a capital letter and +use mixed case with no underscores (need to be short and portable). + +You may find it helpful to use letter case to indicate the scope +or nature of a variable. For example: + + $ALL_CAPS_HERE constants only (beware clashes with Perl vars) + $Some_Caps_Here package-wide global/static + $no_caps_here function scope my() or local() variables + +Function and method names seem to work best as all lowercase. +e.g., C<< $obj->as_string() >>. + +You can use a leading underscore to indicate that a variable or +function should not be used outside the package that defined it. + +=item * + +Select what to export. + +Do NOT export method names! + +Do NOT export anything else by default without a good reason! + +Exports pollute the namespace of the module user. If you must +export try to use @EXPORT_OK in preference to @EXPORT and avoid +short or common names to reduce the risk of name clashes. + +Generally anything not exported is still accessible from outside the +module using the ModuleName::item_name (or C<< $blessed_ref->method >>) +syntax. By convention you can use a leading underscore on names to +indicate informally that they are 'internal' and not for public use. + +(It is actually possible to get private functions by saying: +C<my $subref = sub { ... }; &$subref;>. But there's no way to call that +directly as a method, because a method must have a name in the symbol +table.) + +As a general rule, if the module is trying to be object oriented +then export nothing. If it's just a collection of functions then +@EXPORT_OK anything but use @EXPORT with caution. + +=item * + +Select a name for the module. + +This name should be as descriptive, accurate, and complete as +possible. Avoid any risk of ambiguity. Always try to use two or +more whole words. Generally the name should reflect what is special +about what the module does rather than how it does it. Please use +nested module names to group informally or categorize a module. +There should be a very good reason for a module not to have a nested name. +Module names should begin with a capital letter. + +Having 57 modules all called Sort will not make life easy for anyone +(though having 23 called Sort::Quick is only marginally better :-). +Imagine someone trying to install your module alongside many others. +If in any doubt ask for suggestions in comp.lang.perl.misc. + +If you are developing a suite of related modules/classes it's good +practice to use nested classes with a common prefix as this will +avoid namespace clashes. For example: Xyz::Control, Xyz::View, +Xyz::Model etc. Use the modules in this list as a naming guide. + +If adding a new module to a set, follow the original author's +standards for naming modules and the interface to methods in +those modules. + +If developing modules for private internal or project specific use, +that will never be released to the public, then you should ensure +that their names will not clash with any future public module. You +can do this either by using the reserved Local::* category or by +using a category name that includes an underscore like Foo_Corp::*. + +To be portable each component of a module name should be limited to +11 characters. If it might be used on MS-DOS then try to ensure each is +unique in the first 8 characters. Nested modules make this easier. + +=item * + +Have you got it right? + +How do you know that you've made the right decisions? Have you +picked an interface design that will cause problems later? Have +you picked the most appropriate name? Do you have any questions? + +The best way to know for sure, and pick up many helpful suggestions, +is to ask someone who knows. Comp.lang.perl.misc is read by just about +all the people who develop modules and it's the best place to ask. + +All you need to do is post a short summary of the module, its +purpose and interfaces. A few lines on each of the main methods is +probably enough. (If you post the whole module it might be ignored +by busy people - generally the very people you want to read it!) + +Don't worry about posting if you can't say when the module will be +ready - just say so in the message. It might be worth inviting +others to help you, they may be able to complete it for you! + +=item * + +README and other Additional Files. + +It's well known that software developers usually fully document the +software they write. If, however, the world is in urgent need of +your software and there is not enough time to write the full +documentation please at least provide a README file containing: + +=over 10 + +=item * + +A description of the module/package/extension etc. + +=item * + +A copyright notice - see below. + +=item * + +Prerequisites - what else you may need to have. + +=item * + +How to build it - possible changes to Makefile.PL etc. + +=item * + +How to install it. + +=item * + +Recent changes in this release, especially incompatibilities + +=item * + +Changes / enhancements you plan to make in the future. + +=back + +If the README file seems to be getting too large you may wish to +split out some of the sections into separate files: INSTALL, +Copying, ToDo etc. + +=over 4 + +=item * + +Adding a Copyright Notice. + +How you choose to license your work is a personal decision. +The general mechanism is to assert your Copyright and then make +a declaration of how others may copy/use/modify your work. + +Perl, for example, is supplied with two types of licence: The GNU GPL +and The Artistic Licence (see the files README, Copying, and Artistic, +or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT +just using the GNU GPL. + +My personal recommendation, out of respect for Larry, Perl, and the +Perl community at large is to state something simply like: + + Copyright (c) 1995 Your Name. All rights reserved. + This program is free software; you can redistribute it and/or + modify it under the same terms as Perl itself. + +This statement should at least appear in the README file. You may +also wish to include it in a Copying file and your source files. +Remember to include the other words in addition to the Copyright. + +=item * + +Give the module a version/issue/release number. + +To be fully compatible with the Exporter and MakeMaker modules you +should store your module's version number in a non-my package +variable called $VERSION. This should be a floating point +number with at least two digits after the decimal (i.e., hundredths, +e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version. +See L<Exporter> for details. + +It may be handy to add a function or method to retrieve the number. +Use the number in announcements and archive file names when +releasing the module (ModuleName-1.02.tar.Z). +See perldoc ExtUtils::MakeMaker.pm for details. + +=item * + +How to release and distribute a module. + +It's good idea to post an announcement of the availability of your +module (or the module itself if small) to the comp.lang.perl.announce +Usenet newsgroup. This will at least ensure very wide once-off +distribution. + +If possible, register the module with CPAN. You should +include details of its location in your announcement. + +Some notes about ftp archives: Please use a long descriptive file +name that includes the version number. Most incoming directories +will not be readable/listable, i.e., you won't be able to see your +file after uploading it. Remember to send your email notification +message as soon as possible after uploading else your file may get +deleted automatically. Allow time for the file to be processed +and/or check the file has been processed before announcing its +location. + +FTP Archives for Perl Modules: + +Follow the instructions and links on: + + http://www.cpan.org/modules/00modlist.long.html + http://www.cpan.org/modules/04pause.html + +or upload to one of these sites: + + https://pause.kbx.de/pause/ + http://pause.perl.org/ + +and notify <modules@perl.org>. + +By using the WWW interface you can ask the Upload Server to mirror +your modules from your ftp or WWW site into your own directory on +CPAN! + +Please remember to send me an updated entry for the Module list! + +=item * + +Take care when changing a released module. + +Always strive to remain compatible with previous released versions. +Otherwise try to add a mechanism to revert to the +old behavior if people rely on it. Document incompatible changes. + +=back + +=head2 Guidelines for Converting Perl 4 Library Scripts into Modules + +=over 4 + +=item * + +There is no requirement to convert anything. + +If it ain't broke, don't fix it! Perl 4 library scripts should +continue to work with no problems. You may need to make some minor +changes (like escaping non-array @'s in double quoted strings) but +there is no need to convert a .pl file into a Module for just that. + +=item * + +Consider the implications. + +All Perl applications that make use of the script will need to +be changed (slightly) if the script is converted into a module. Is +it worth it unless you plan to make other changes at the same time? + +=item * + +Make the most of the opportunity. + +If you are going to convert the script to a module you can use the +opportunity to redesign the interface. The guidelines for module +creation above include many of the issues you should consider. + +=item * + +The pl2pm utility will get you started. + +This utility will read *.pl files (given as parameters) and write +corresponding *.pm files. The pl2pm utilities does the following: + +=over 10 + +=item * + +Adds the standard Module prologue lines + +=item * + +Converts package specifiers from ' to :: + +=item * + +Converts die(...) to croak(...) + +=item * + +Several other minor changes + +=back + +Being a mechanical process pl2pm is not bullet proof. The converted +code will need careful checking, especially any package statements. +Don't delete the original .pl file till the new .pm one works! + +=back + +=head2 Guidelines for Reusing Application Code + +=over 4 + +=item * + +Complete applications rarely belong in the Perl Module Library. + +=item * + +Many applications contain some Perl code that could be reused. + +Help save the world! Share your code in a form that makes it easy +to reuse. + +=item * + +Break-out the reusable code into one or more separate module files. + +=item * + +Take the opportunity to reconsider and redesign the interfaces. + +=item * + +In some cases the 'application' can then be reduced to a small + +fragment of code built on top of the reusable modules. In these cases +the application could invoked as: + + % perl -e 'use Module::Name; method(@ARGV)' ... +or + % perl -mModule::Name ... (in perl5.002 or higher) + +=back + +=back + +=head1 NOTE + +Perl does not enforce private and public parts of its modules as you may +have been used to in other languages like C++, Ada, or Modula-17. Perl +doesn't have an infatuation with enforced privacy. It would prefer +that you stayed out of its living room because you weren't invited, not +because it has a shotgun. + +The module and its user have a contract, part of which is common law, +and part of which is "written". Part of the common law contract is +that a module doesn't pollute any namespace it wasn't asked to. The +written contract for the module (A.K.A. documentation) may make other +provisions. But then you know when you C<use RedefineTheWorld> that +you're redefining the world and willing to take the consequences. |