perlmodlib - constructing new Perl modules and finding
       existing ones


DESCRIPTION


THE PERL MODULE LIBRARY

       Many modules are included the Perl distribution.  These
       are described below, and all end in .pm.  You may discover
       compiled library file (usually ending in .so) or small
       pieces of modules to be autoloaded (ending in .al); these
       were automatically generated by the installation process.
       You may also discover files in the library directory that
       end in either .pl or .ph.  These are old libraries sup­
       plied so that old programs that use them still run.  The
       .pl files will all eventually be converted into standard
       modules, and the .ph files made by h2ph will probably end
       up as extension modules made by h2xs.  (Some .ph values
       may already be available through the POSIX, Errno, or
       Fcntl modules.)  The pl2pm file in the distribution may
       help in your conversion, but it's just a mechanical pro­
       cess and therefore far from bulletproof.

       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
       `use', or `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 `$^H' hints variable.  Others affect the cur­
       rent package instead, like `use vars' and `use subs',
       which allow you to predeclare a variables or subroutines
       within a particular file rather than just a block.  Such
       declarations are effective for the entire file for which
       they were declared.  You cannot rescind them with `no
       vars' or `no subs'.

       The following pragmas are defined (and have their own doc­
       umentation).

       attributes  Get/set subroutine or variable attributes

       attrs       Set/get attributes of a subroutine (depre­
                   cated)

                   used

       base        Establish IS-A relationship with base class at
                   compile time

       blib        Use MakeMaker's uninstalled version of a pack­
                   age

       caller      Inherit pragmatic attributes from caller's
                   context

       charnames   Define character names for `\N{named}' string
                   literal escape.

       constant    Declare constants

       diagnostics Force verbose warning diagnostics

       fields      Declare a class's attribute fields at compile-
                   time

       filetest    Control the filetest operators like `-r', `-w'
                   for AFS, etc.

       integer     Compute arithmetic in integer instead of dou­
                   ble

       less        Request less of something from the compiler
                   (unimplemented)

       lib         Manipulate @INC at compile time

       locale      Use or avoid POSIX locales for built-in opera­
                   tions

       ops         Restrict unsafe operations when compiling

       overload    Overload Perl operations

       re          Alter regular expression behavior

       sigtrap     Enable simple signal handling

       strict      Restrict unsafe constructs

       subs        Predeclare subroutine names

       utf8        Turn on UTF-8 and Unicode support

       vars        Predeclare global variable names (obsoleted by
                   our())


       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 docu­
       mentation for details.

       AnyDBM_File Provide framework for multiple DBM libraries

       AutoLoader  Load subroutines only on demand

       AutoSplit   Split a package for autoloading

       B           Guts of the Perl code generator (aka compiler)

       B::Asmdata  Autogenerated data about Perl ops, used to
                   generate bytecode

       B::Assembler
                   Assemble Perl bytecode

       B::Bblock   Walk basic blocks

       B::Bytecode Perl compiler's bytecode backend

       B::C        Perl compiler's C backend

       B::CC       Perl compiler's optimized C translation back­
                   end

       B::Debug    Walk Perl syntax tree, printing debug info
                   about ops

       B::Deparse  Perl compiler backend to produce Perl code

       B::Disassembler
                   Disassemble Perl bytecode

       B::Lint     Module to catch dubious constructs

       B::Showlex  Show lexical variables used in functions or
                   files

       B::Stackobj Helper module for CC backend

                   B::Stash -- XXX NFI XXX

       B::Terse    Walk Perl syntax tree, printing terse info
                   about ops

       B::Xref     Generates cross reference reports for Perl
                   programs


       ByteLoader  Load byte-compiled Perl code

       CGI         Simple Common Gateway Interface class

       CGI::Apache Make things work with CGI.pm against Perl-
                   Apache API

       CGI::Carp   CGI routines for writing to the HTTPD (or
                   other) error log

       CGI::Cookie Interface to Netscape Cookies

       CGI::Fast   CGI Interface for Fast CGI

       CGI::Pretty Module to produce nicely formatted HTML code

       CGI::Push   Simple Interface to Server Push

       CGI::Switch Try more than one constructors and return the
                   first object available

       CPAN        Query, download, and build Perl modules from
                   CPAN sites

       CPAN::FirstTime
                   Utility for CPAN::Config file initialization

       CPAN::Nox   Wrapper around CPAN.pm without using any XS
                   module

       Carp        Act like warn/die from perspective of caller

       Carp::Heavy Carp guts

       Class::Struct
                   Declare struct-like datatypes as Perl classes

       Config      Access Perl configuration information

       Cwd         Get pathname of current working directory

       DB          Programmatic interface to the Perl debugging
                   API (experimental)

       DB_File     Perl5 access to Berkeley DB version 1.x

       Data::Dumper
                   Serialize Perl data structures

       Devel::DProf
                   A Perl execution profiler


       Devel::SelfStubber
                   Generate stubs for a SelfLoading module

       DirHandle   Supply object methods for directory handles

       Dumpvalue   Provide screen dump of Perl data

       DynaLoader  Dynamically load C libraries into Perl code

       English     Use English (or awk) names for ugly punctua­
                   tion variables

       Env         Access environment variables as regular ones

       Errno       Load the libc errno.h defines

       Exporter    Implement default import method for modules

       Exporter::Heavy
                   Exporter guts

       ExtUtils::Command
                   Utilities to replace common Unix commands in
                   Makefiles etc.

       ExtUtils::Embed
                   Utilities for embedding Perl in C/C++ programs

       ExtUtils::Install
                   Install files from here to there

       ExtUtils::Installed
                   Inventory management of installed modules

       ExtUtils::Liblist
                   Determine libraries to use and how to use them

       ExtUtils::MM_Cygwin
                   Methods to override Unix behavior in ExtU­
                   tils::MakeMaker

       ExtUtils::MM_OS2
                   Methods to override Unix behavior in ExtU­
                   tils::MakeMaker

       ExtUtils::MM_Unix
                   Methods used by ExtUtils::MakeMaker

       ExtUtils::MM_VMS
                   Methods to override Unix behavior in ExtU­
                   tils::MakeMaker

                   Methods to override Unix behavior in ExtU­
                   tils::MakeMaker

       ExtUtils::MakeMaker
                   Create an extension Makefile

       ExtUtils::Manifest
                   Utilities to write and check a MANIFEST file

                   ExtUtils::Miniperl, writemain - Write the C
                   code for perlmain.c

       ExtUtils::Mkbootstrap
                   Make a bootstrap file for use by DynaLoader

       ExtUtils::Mksymlists
                   Write linker options files for dynamic exten­
                   sion

       ExtUtils::Packlist
                   Manage .packlist files

       ExtUtils::testlib
                   Add blib/* directories to @INC

       Fatal       Replace functions with equivalents which suc­
                   ceed or die

       Fcntl       Load the libc fcntl.h defines

       File::Basename
                   Split a pathname into pieces

       File::CheckTree
                   Run many filetest checks on a tree

       File::Compare
                   Compare files or filehandles

       File::Copy  Copy files or filehandles

       File::DosGlob
                   DOS-like globbing and then some

       File::Find  Traverse a file tree

       File::Glob  Perl extension for BSD filename globbing

       File::Path  Create or remove a series of directories

       File::Spec  Portably perform operations on file names

                   Portably perform operations on file names

       File::Spec::Mac
                   File::Spec for MacOS

       File::Spec::OS2
                   Methods for OS/2 file specs

       File::Spec::Unix
                   Methods used by File::Spec

       File::Spec::VMS
                   Methods for VMS file specs

       File::Spec::Win32
                   Methods for Win32 file specs

       File::stat  By-name interface to Perl's built-in stat()
                   functions

       FileCache   Keep more files open than the system permits

       FileHandle  Supply object methods for filehandles

       FindBin     Locate installation directory of running Perl
                   program

       GDBM_File   Access to the gdbm library

       Getopt::Long
                   Extended processing of command line options

       Getopt::Std Process single-character switches with switch
                   clustering

       I18N::Collate
                   Compare 8-bit scalar data according to current
                   locale

       IO          Front-end to load various IO modules

       IO::Dir     Supply object methods for directory handles

       IO::File    Supply object methods for filehandles

       IO::Handle  Supply object methods for I/O handles

       IO::Pipe    Supply object methods for pipes

       IO::Poll    Object interface to system poll call

       IO::Seekable
                   Supply seek based methods for I/O objects


       IO::Socket  Object interface to socket communications

       IO::Socket::INET
                   Object interface for AF_INET domain sockets

       IO::Socket::UNIX
                   Object interface for AF_UNIX domain sockets

       IPC::Msg    SysV Msg IPC object class

       IPC::Open2  Open a process for both reading and writing

       IPC::Open3  Open a process for reading, writing, and error
                   handling

       IPC::Semaphore
                   SysV Semaphore IPC object class

       IPC::SysV   SysV IPC constants

       Math::BigFloat
                   Arbitrary length float math package

       Math::BigInt
                   Arbitrary size integer math package

       Math::Complex
                   Complex numbers and associated mathematical
                   functions

       Math::Trig  Trigonometric functions

       Net::Ping   Check a remote host for reachability

       Net::hostent
                   By-name interface to Perl's built-in geth­
                   ost*() functions

       Net::netent By-name interface to Perl's built-in getnet*()
                   functions

       Net::protoent
                   By-name interface to Perl's built-in get­
                   proto*() functions

       Net::servent
                   By-name interface to Perl's built-in get­
                   serv*() functions

       O           Generic interface to Perl Compiler backends


       POSIX       Perl interface to IEEE Std 1003.1

       Pod::Checker
                   Check pod documents for syntax errors

       Pod::Html   Module to convert pod files to HTML

       Pod::InputObjects
                   Manage POD objects

       Pod::Man    Convert POD data to formatted *roff input

       Pod::Parser Base class for creating POD filters and trans­
                   lators

       Pod::Select Extract selected sections of POD from input

       Pod::Text   Convert POD data to formatted ASCII text

       Pod::Text::Color
                   Convert POD data to formatted color ASCII text

       Pod::Usage  Print a usage message from embedded pod docu­
                   mentation

       SDBM_File   Tied access to sdbm files

       Safe        Compile and execute code in restricted com­
                   partments

       Search::Dict
                   Search for key in dictionary file

       SelectSaver Save and restore selected file handle

       SelfLoader  Load functions only on demand

       Shell       Run shell commands transparently within Perl

       Socket      Load the libc socket.h defines and structure
                   manipulators

       Symbol      Manipulate Perl symbols and their names

       Sys::Hostname
                   Try every conceivable way to get hostname

       Sys::Syslog Interface to the libc syslog(3) calls

       Term::Cap   Termcap interface

                   Word completion module

       Term::ReadLine
                   Interface to various `readline' packages.

       Test        Provides a simple framework for writing test
                   scripts

       Test::Harness
                   Run Perl standard test scripts with statistics

       Text::Abbrev
                   Create an abbreviation table from a list

       Text::ParseWords
                   Parse text into a list of tokens or array of
                   arrays

       Text::Soundex
                   Implementation of the Soundex Algorithm as
                   described by Knuth

                   Text::Tabs -- expand and unexpand tabs per
                   expand(1) and unexpand(1)

       Text::Wrap  Line wrapping to form simple paragraphs

       Tie::Array  Base class for tied arrays

       Tie::Handle Base class definitions for tied handles

       Tie::Hash   Base class definitions for tied hashes

       Tie::RefHash
                   Use references as hash keys

       Tie::Scalar Base class definitions for tied scalars

       Tie::SubstrHash
                   Fixed-table-size, fixed-key-length hashing

       Time::Local Efficiently compute time from local and GMT
                   time

       Time::gmtime
                   By-name interface to Perl's built-in gmtime()
                   function

       Time::localtime
                   By-name interface to Perl's built-in local­
                   time() function

                   Time::localtime

       UNIVERSAL   Base class for ALL classes (blessed refer­
                   ences)

       User::grent By-name interface to Perl's built-in getgr*()
                   functions

       User::pwent By-name interface to Perl's built-in getpw*()
                   functions

       To find out all modules installed on your system, includ­
       ing those without documentation or outside the standard
       release, just do this:

           % find `perl -e 'print "@INC"'` -name '*.pm' -print

       To get a log of all module distributions which have been
       installed since perl was installed, just do:

           % perldoc perllocal

       Modules should all have their own documentation installed
       and accessible via your system man(1) command, or via the
       `perldoc' program.  If you do not have a find program, you
       can use the Perl find2perl program instead, which gener­
       ates Perl code as output you can run through perl.  If you
       have a man program but it doesn't find your modules,
       you'll have to fix your manpath.  See the perl manpage for
       details.

       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 be linked in stati­
       cally.  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 Deja News.


CPAN

       CPAN stands for Comprehensive Perl Archive Network; it's a
       globally replicated trove of Perl materials, including
       documentation, style guides, tricks and trap, alternate
       ports to non-Unix systems and occasional binary distribu­
       tions for these.   Search engines for CPAN can be found at

       nipeg.ca/mod_perl/cpan-search.pl .

       Most importantly, CPAN includes around a thousand unbun­
       dled modules, some of which require a C compiler to build.
       Major categories of modules are:

       · Language Extensions and Documentation Tools

       · Development Support

       · Operating System Interfaces

       · Networking, Device Control (modems) and InterProcess
           Communica­ tion

       · Data Types and Data Type Utilities

       · Database Interfaces

       · User Interfaces

       · Interfaces to / Emulations of Other Programming Lan­
           guages

       · File Names, File Systems and File Locking (see also File
           Han­ dles)

       · String Processing, Language Text Processing, Parsing,
           and Searching

       · Option, Argument, Parameter, and Configuration File Pro­
           cessing

       · Internationalization and Locale

       · Authentication, Security, and Encryption

       · World Wide Web, HTML, HTTP, CGI, MIME

       · Server and Daemon Utilities

       · Archiving and Compression

       · Images, Pixmap and Bitmap Manipulation, Drawing, and
           Graphing

       · Mail and Usenet News

       · Control Flow Utilities (callbacks and exceptions etc)

       · File Handle and Input/Output Stream Utilities


       Registered CPAN sites as of this writing include the fol­
       lowing.  You should try to choose one close to you:

       Africa
               South Africa   ftp://ftp.is.co.za/programming/perl/CPAN/
                              ftp://ftp.saix.net/pub/CPAN/
                              ftp://ftp.sun.ac.za/CPAN/
                              ftp://ftpza.co.za/pub/mirrors/cpan/

       Asia
               China          ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
               Hong Kong      ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
               Indonesia      ftp://malone.piksi.itb.ac.id/pub/CPAN/
               Israel         ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
               Japan          ftp://ftp.dti.ad.jp/pub/lang/CPAN/
                              ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
                              ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
                              ftp://ftp.meisei-u.ac.jp/pub/CPAN/
                              ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
                              ftp://mirror.nucba.ac.jp/mirror/Perl/
               Saudi-Arabia   ftp://ftp.isu.net.sa/pub/CPAN/
               Singapore      ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
               South Korea    ftp://ftp.bora.net/pub/CPAN/
                              ftp://ftp.kornet.net/pub/CPAN/
                              ftp://ftp.nuri.net/pub/CPAN/
               Taiwan         ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
                              ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/
                              ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
               Thailand       ftp://ftp.nectec.or.th/pub/mirrors/CPAN/

       Australasia
               Australia      ftp://cpan.topend.com.au/pub/CPAN/
                              ftp://ftp.labyrinth.net.au/pub/perl-CPAN/
                              ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
                              ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
               New Zealand    ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
                              ftp://sunsite.net.nz/pub/languages/perl/CPAN/

       Central America
               Costa Rica     ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/

       Europe

               Belgium        ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
               Bulgaria       ftp://ftp.ntrl.net/pub/mirrors/CPAN/
               Croatia        ftp://ftp.linux.hr/pub/CPAN/
               Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
                              ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
               Denmark        ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
               Estonia        ftp://ftp.ut.ee/pub/languages/perl/CPAN/
               Finland        ftp://ftp.funet.fi/pub/languages/perl/CPAN/
               France         ftp://ftp.grolier.fr/pub/perl/CPAN/
                              ftp://ftp.lip6.fr/pub/perl/CPAN/
                              ftp://ftp.oleane.net/pub/mirrors/CPAN/
                              ftp://ftp.pasteur.fr/pub/computing/CPAN/
                              ftp://ftp.uvsq.fr/pub/perl/CPAN/
               German         ftp://ftp.gigabell.net/pub/CPAN/
               Germany        ftp://ftp.archive.de.uu.net/pub/CPAN/
                              ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
                              ftp://ftp.gmd.de/packages/CPAN/
                              ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
                              ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
                              ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
                              ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
                              ftp://ftp.uni-erlangen.de/pub/source/CPAN/
                              ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
               Germany        ftp://ftp.archive.de.uu.net/pub/CPAN/
                              ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
                              ftp://ftp.gmd.de/packages/CPAN/
                              ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
                              ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
                              ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
                              ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
                              ftp://ftp.uni-erlangen.de/pub/source/CPAN/
                              ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
               Greece         ftp://ftp.ntua.gr/pub/lang/perl/
               Hungary        ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
               Iceland        ftp://ftp.gm.is/pub/CPAN/
               Ireland        ftp://cpan.indigo.ie/pub/CPAN/
                              ftp://sunsite.compapp.dcu.ie/pub/perl/
               Italy          ftp://cis.uniRoma2.it/CPAN/
                              ftp://ftp.flashnet.it/pub/CPAN/
                              ftp://ftp.unina.it/pub/Other/CPAN/
                              ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
               Netherlands    ftp://ftp.cs.uu.nl/mirror/CPAN/
                              ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
               Norway         ftp://ftp.uit.no/pub/languages/perl/cpan/
                              ftp://sunsite.uio.no/pub/languages/perl/CPAN/
               Poland         ftp://ftp.man.torun.pl/pub/CPAN/
                              ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
                              ftp://sunsite.icm.edu.pl/pub/CPAN/
               Portugal       ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
                              ftp://ftp.ist.utl.pt/pub/CPAN/
                              ftp://ftp.ua.pt/pub/CPAN/
               Romania        ftp://ftp.dnttm.ro/pub/CPAN/
               Russia         ftp://ftp.chg.ru/pub/lang/perl/CPAN/

               Slovakia       ftp://ftp.entry.sk/pub/languages/perl/CPAN/
               Slovenia       ftp://ftp.arnes.si/software/perl/CPAN/
               Spain          ftp://ftp.etse.urv.es/pub/perl/
                              ftp://ftp.rediris.es/mirror/CPAN/
               Sweden         ftp://ftp.sunet.se/pub/lang/perl/CPAN/
               Switzerland    ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
               Turkey         ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
               United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
                              ftp://ftp.flirble.org/pub/languages/perl/CPAN/
                              ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
                              ftp://ftp.plig.org/pub/CPAN/
                              ftp://sunsite.doc.ic.ac.uk/packages/CPAN/

       North America
               Alberta        ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
               California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
                              ftp://cpan.valueclick.com/CPAN/
                              ftp://ftp.cdrom.com/pub/perl/CPAN/
                              http://download.sourceforge.net/mirrors/CPAN/
               Colorado       ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
               Florida        ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
               Georgia        ftp://ftp.twoguys.org/CPAN/
               Illinois       ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
               Indiana        ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
                              ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
               Kentucky       ftp://ftp.uky.edu/CPAN/
               Manitoba       ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
               Massachusetts  ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
                              ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
               Mexico         ftp://ftp.msg.com.mx/pub/CPAN/
               New York       ftp://ftp.deao.net/pub/CPAN/
                              ftp://ftp.rge.com/pub/languages/perl/
               North Carolina ftp://ftp.duke.edu/pub/perl/
               Nova Scotia    ftp://cpan.chebucto.ns.ca/pub/CPAN/
               Oklahoma       ftp://ftp.ou.edu/mirrors/CPAN/
               Ontario        ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
               Oregon         ftp://ftp.orst.edu/pub/packages/CPAN/
               Pennsylvania   ftp://ftp.epix.net/pub/languages/perl/
               Tennessee      ftp://ftp.sunsite.utk.edu/pub/CPAN/
               Texas          ftp://ftp.sedl.org/pub/mirrors/CPAN/
                              ftp://jhcloos.com/pub/mirror/CPAN/
               Utah           ftp://mirror.xmission.com/CPAN/
               Virginia       ftp://ftp.perl.org/pub/perl/CPAN/
                              ftp://ruff.cs.jmu.edu/pub/CPAN/
               Washington     ftp://ftp-mirror.internap.com/pub/CPAN/
                              ftp://ftp.llarian.net/pub/CPAN/
                              ftp://ftp.spu.edu/pub/CPAN/

       South America

                              ftp://ftp.matrix.com.br/pub/perl/
               Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/

       For an up-to-date listing of CPAN sites, see
       http://www.perl.com/perl/CPAN/SITES or
       ftp://www.perl.com/CPAN/SITES .


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" meth­
       ods), 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 mod­
       ule might set up an AUTOLOAD function to slurp in subrou­
       tine definitions on demand, but this is also transparent.
       Only the .pm file is required to exist.  See the perlsub
       manpage, the perltoot manpage, and the AutoLoader manpage
       for details about the AUTOLOAD mechanism.

       Guidelines for Module Creation

       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.

       Try to design the new module to be easy to extend and
           reuse.

           Remember that you can add `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: `die "Invalid" unless ref
           $ref eq 'FOO''.  Generally you can delete the `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 `$r->Class::func()' where using `@ISA=qw(...
           Class ...)' and `$r->func()' would work (see the perl­
           bot manpage 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 `@SUBCLASS::ISA = qw(YOURCLASS);' your appli­
           cations should be able to use SUBCLASS in exactly the
           same way as YOURCLASS.  For example, does your appli­
           cation still work if you change:  `$obj = new YOUR­
           CLASS;' into: `$obj = new SUBCLASS;' ?

           Avoid keeping any state information in your packages.
           It makes it difficult for multiple other packages to


           Always use -w.

           Try to `use strict;' (or `use strict qw(...);').
           Remember that you can add `no strict qw(...);' to
           individual blocks of code that need less strictness.

           Always use -w.

           Follow the guidelines in the perlstyle(1) manual.

           Always use -w.

       Some simple style guidelines
           The perlstyle manual supplied with Perl has many help­
           ful points.

           Coding style is a matter of personal taste. Many peo­
           ple 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 $VarNames­
           LikeThis, especially for non-native speakers of
           English. It's also a simple rule that works consis­
           tently 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 mod­
           ules 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., `$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.

       Select what to export.
           Do NOT export method names!

           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 Module­
           Name::item_name (or `$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: `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.

       Select a name for the module.
           This name should be as descriptive, accurate, and com­
           plete 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 mod­
           ules/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 nam­
           ing guide.

           If adding a new module to a set, follow the original
           author's standards for naming modules and the inter­
           face to methods in those modules.

           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.

       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 help­
           ful suggestions, is to ask someone who knows.
           Comp.lang.perl.misc is read by just about all the peo­
           ple who develop modules and it's the best place to
           ask.

           All you need to do is post a short summary of the mod­
           ule, 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!

       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:

           · A description of the module/package/extension etc.

           · A copyright notice - see below.

           · Prerequisites - what else you may need to have.

           · How to build it - possible changes to Makefile.PL
                     etc.

           · How to install it.

           · Recent changes in this release, especially incompat­
                     ibilities

           · Changes / enhancements you plan to make in the
                     future.

           If the README file seems to be getting too large you
           may wish to split out some of the sections into


           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 oth­
               ers 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).  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 Copy­
               right.

           Give the module a version/issue/release number.
               To be fully compatible with the Exporter and Make­
               Maker modules you should store your module's ver­
               sion 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, `$VERSION = "0.01"').  Don't use
               a "1.3.2" style version.  See the Exporter manpage
               for details.

               It may be handy to add a function or method to
               retrieve the number.  Use the number in announce­
               ments and archive file names when releasing the
               module (ModuleName-1.02.tar.Z).  See perldoc ExtU­
               tils::MakeMaker.pm for details.

           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.

               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 possi­
               ble after uploading else your file may get deleted
               automatically. Allow time for the file to be pro­
               cessed 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.perl.com/CPAN/modules/00modlist.long.html
                  http://www.perl.com/CPAN/modules/04pause.html

               or upload to one of these sites:

                  https://pause.kbx.de/pause/
                  http://pause.perl.org/pause/

               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!

           Take care when changing a released module.
               Always strive to remain compatible with previous
               released versions.  Otherwise try to add a mecha­
               nism to revert to the old behavior if people rely
               on it.  Document incompatible changes.

       Guidelines for Converting Perl 4 Library Scripts into Mod­
       ules

       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.

       Consider the implications.
           All Perl applications that make use of the script will
           need to be changed (slightly) if the script is con­
           verted into a module.  Is it worth it unless you plan


       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.

       The pl2pm utility will get you started.
           This utility will read *.pl files (given as parame­
           ters) and write corresponding *.pm files. The pl2pm
           utilities does the following:

           · Adds the standard Module prologue lines

           · Converts package specifiers from ' to ::

           · Converts die(...) to croak(...)

           · Several other minor changes

           Being a mechanical process pl2pm is not bullet proof.
           The converted code will need careful checking, espe­
           cially any package statements.  Don't delete the orig­
           inal .pl file till the new .pm one works!

       Guidelines for Reusing Application Code

       Complete applications rarely belong in the Perl Module
           Library.

       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.

       Break-out the reusable code into one or more separate mod­
           ule files.

       Take the opportunity to reconsider and redesign the inter­
           faces.

       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)

       Perl does not enforce private and public parts of its mod­
       ules 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 provi­
       sions.  But then you know when you `use RedefineTheWorld'
       that you're redefining the world and willing to take the
       consequences.


Man(1) output converted with man2html