X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlmodlib.pod;h=99d31bd6e1ba9aae3e52ffe9ea4c0579ed4bdfbf;hb=b363f7ed458679f785ff5f459a6ae701688eb6f5;hp=9511f55df4782ab3869380d8b1d8f18ccac4e902;hpb=5a964f204835a8014f4ba86fc91884cff958ac67;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod index 9511f55..99d31bd 100644 --- a/pod/perlmodlib.pod +++ b/pod/perlmodlib.pod @@ -6,54 +6,81 @@ perlmodlib - constructing new Perl modules and finding existing ones =head1 THE PERL MODULE LIBRARY -A number of modules are included the Perl distribution. These are -described below, and all end in F<.pm>. 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 will probably end up as extension modules -made by B. (Some F<.ph> values may already be available through the -POSIX module.) The B file in the distribution may help in your -conversion, but it's just a mechanical process and therefore far from -bulletproof. +Many modules are included the Perl distribution. These are described +below, and all end in F<.pm>. You may discover compiled library +file (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 will probably end up +as extension modules made by B. (Some F<.ph> values may +already be available through the POSIX, Errno, or Fcntl modules.) +The B 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 pragmas in that they tend to affect the compilation of -your program, and thus will usually work well only when used within a -C, or C. Most of these are locally scoped, so an inner BLOCK -may countermand any of these by saying: +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, or C. 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. -Unlike the pragmas that effect the C<$^H> hints variable, the C and C declarations are not BLOCK-scoped. They allow -you to predeclare a variables or subroutines within a particular -I rather than just a block. Such declarations are effective -for the entire file for which they were declared. You cannot rescind -them with C or C. +Some pragmas are lexically scoped--typically those that affect the +C<$^H> hints variable. Others affect the current package instead, +like C and C, which allow you to predeclare a +variables or subroutines within a particular I rather than +just a block. Such declarations are effective for the entire file +for which they were declared. You cannot rescind them with C or C. The following pragmas are defined (and have their own documentation). =over 12 -=item use autouse MODULE => qw(sub1 sub2 sub3) +=item attributes -Defers C until someone calls one of the specified -subroutines (which must be exported by MODULE). This pragma should be -used with caution, and only when necessary. +set/get the attributes of a subroutine or variable + +=item attrs + +set/get attributes of a subroutine (obsolescent) + +=item autouse + +postpone load of modules until a function is used + +=item base + +Establish IS-A relationship with base class at compile time =item blib -manipulate @INC at compile time to use MakeMaker's uninstalled version -of a package +Use MakeMaker's uninstalled version of a package + +=item constant + +declare constants =item diagnostics -force verbose warning diagnostics +Perl compiler pragma to force verbose warning diagnostics + +=item fields + +compile-time class fields + +=item filetest + +control the filetest permission operators =item integer @@ -61,7 +88,7 @@ compute arithmetic in integer instead of double =item less -request less of something from the compiler +perl pragma to request less of something from the compiler =item lib @@ -69,15 +96,19 @@ manipulate @INC at compile time =item locale -use or ignore current locale for builtin operations (see L) +use and avoid POSIX locales for built-in operations =item ops -restrict named opcodes when compiling or running Perl code +restrict unsafe operations when compiling =item overload -overload basic Perl operations +Package for overloading perl operations + +=item re + +alter regular expression behavior =item sigtrap @@ -91,14 +122,22 @@ restrict unsafe constructs predeclare sub names -=item vmsish +=item utf8 -adopt certain VMS-specific behaviors +turn on UTF-8 and Unicode support =item vars predeclare global variable names +=item warnings + +control optional warnings + +=item vmsish + +control VMS-specific language features + =back =head2 Standard Modules @@ -115,27 +154,115 @@ provide framework for multiple DBMs =item AutoLoader -load functions only on demand +load subroutines only on demand =item AutoSplit split a package for autoloading +=item B + +The Perl Compiler; See also L. + +=item B::Asmdata + +Autogenerated data about Perl ops, used to generate bytecode + +=item B::Assembler + +Assemble Perl bytecode + +=item B::Bblock + +Walk basic blocks + +=item B::Bytecode + +Perl compiler's bytecode backend + +=item B::C + +Perl compiler's C backend + +=item B::CC + +Perl compiler's optimized C translation backend + +=item B::Debug + +Walk Perl syntax tree, printing debug info about ops + +=item B::Deparse + +Perl compiler backend to produce perl code + +=item B::Disassembler + +Disassemble Perl bytecode + +=item B::Lint + +Perl lint + +=item B::Showlex + +Show lexical variables used in functions or files + +=item B::Stackobj + +Helper module for CC backend + +=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 code +=item CGI + +Simple Common Gateway Interface Class + +=item CGI::Apache + +Make things work with CGI.pm against Perl-Apache API + +=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::Push + +Simple Interface to Server Push + +=item CGI::Switch + +Try more than one constructors and return the first object available + =item CPAN -interface to Comprehensive Perl Archive Network +query, download and build perl modules from CPAN sites =item CPAN::FirstTime -create a CPAN configuration file +Utility for CPAN::Config file Initialization =item CPAN::Nox -run CPAN while avoiding compiled extensions +Wrapper around CPAN.pm without using any XS module =item Carp @@ -143,7 +270,7 @@ warn of errors (from perspective of caller) =item Class::Struct -declare struct-like datatypes +declare struct-like datatypes as Perl classes =item Config @@ -153,9 +280,21 @@ access Perl configuration information get pathname of current working directory +=item DB + +programmatic interface to the Perl debugging API + =item DB_File -access to Berkeley DB +Perl5 access to Berkeley DB version 1.x + +=item Data::Dumper + +stringified perl data structures, suitable for both printing and C + +=item Devel::Peek + +A data debugging tool for the XS programmer =item Devel::SelfStubber @@ -165,9 +304,13 @@ generate stubs for a SelfLoading module supply object methods for directory handles +=item Dumpvalue + +provides screen dump of Perl data. + =item DynaLoader -dynamically load C libraries into Perl code +Dynamically load C libraries into Perl code =item English @@ -175,27 +318,39 @@ use nice English (or awk) names for ugly punctuation variables =item Env -import environment variables +perl module that imports environment variables + +=item Errno + +System errno constants =item Exporter -implements default import method for modules +Implements default import method for modules + +=item ExtUtils::Command + +utilities to replace common UNIX commands in Makefiles etc. =item ExtUtils::Embed -utilities for embedding Perl in C/C++ applications +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_OS2 -methods to override Unix behaviour in ExtUtils::MakeMaker +methods to override UN*X behavior in ExtUtils::MakeMaker =item ExtUtils::MM_Unix @@ -203,7 +358,11 @@ methods used by ExtUtils::MakeMaker =item ExtUtils::MM_VMS -methods to override Unix behaviour in ExtUtils::MakeMaker +methods to override UN*X behavior in ExtUtils::MakeMaker + +=item ExtUtils::MM_Win32 + +methods to override UN*X behavior in ExtUtils::MakeMaker =item ExtUtils::MakeMaker @@ -213,6 +372,10 @@ create an extension Makefile utilities to write and check a MANIFEST file +=item ExtUtils::Miniperl + +write the C code for perlmain.c + =item ExtUtils::Mkbootstrap make a bootstrap file for use by DynaLoader @@ -221,13 +384,17 @@ make a bootstrap file for use by DynaLoader write linker options files for dynamic extension +=item ExtUtils::Packlist + +manage .packlist files + =item ExtUtils::testlib add blib/* directories to @INC =item Fatal -make errors in builtins or Perl functions fatal +replace functions with equivalents which succeed or die =item Fcntl @@ -237,17 +404,17 @@ load the C Fcntl.h defines split a pathname into pieces -=item File::CheckTree - -run many filetest checks on a tree - =item File::Compare -compare files or filehandles +Compare files or filehandles =item File::Copy -copy files or filehandles +Copy files or filehandles + +=item File::DosGlob + +DOS like globbing and then some =item File::Find @@ -257,9 +424,37 @@ traverse a file tree create or remove a series of directories +=item File::Spec + +portably perform operations on file names + +=item File::Spec::Functions + +portably perform operations on file names + +=item File::Spec::Mac + +File::Spec for MacOS + +=item File::Spec::OS2 + +methods for OS/2 file specs + +=item File::Spec::Unix + +methods used by File::Spec + +=item File::Spec::VMS + +methods for VMS file specs + +=item File::Spec::Win32 + +methods for Win32 file specs + =item File::stat -by-name interface to Perl's builtin stat() functions +by-name interface to Perl's built-in stat() functions =item FileCache @@ -271,11 +466,11 @@ supply object methods for filehandles =item FindBin -locate directory of original Perl script +Locate directory of original perl script =item GDBM_File -access to the gdbm library +Perl5 access to the gdbm library. =item Getopt::Long @@ -283,7 +478,7 @@ extended processing of command line options =item Getopt::Std -process single-character switches with switch clustering +Process single-character switches with switch clustering =item I18N::Collate @@ -293,6 +488,10 @@ compare 8-bit scalar data according to the current locale load various IO modules +=item IO::Dir + +supply object methods for directory handles + =item IO::File supply object methods for filehandles @@ -305,6 +504,10 @@ supply object methods for I/O handles 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 @@ -315,7 +518,19 @@ OO interface to the select system call =item IO::Socket -object interface to socket communications +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 IPC::Msg + +SysV Msg IPC object class =item IPC::Open2 @@ -325,13 +540,21 @@ open a process for both reading and writing open a process for reading, writing, and error handling +=item IPC::Semaphore + +SysV Semaphore IPC object class + +=item IPC::SysV + +SysV IPC constants + =item Math::BigFloat -arbitrary length float math package +Arbitrary length float math package =item Math::BigInt -arbitrary size integer math package +Arbitrary size integer math package =item Math::Complex @@ -339,52 +562,59 @@ complex numbers and associated mathematical functions =item Math::Trig -simple interface to parts of Math::Complex for those who -need trigonometric functions only for real numbers +trigonometric functions =item NDBM_File -tied access to ndbm files +Tied access to ndbm files =item Net::Ping -Hello, anybody home? +check a remote host for reachability =item Net::hostent -by-name interface to Perl's builtin gethost*() functions +by-name interface to Perl's built-in gethost*() functions =item Net::netent -by-name interface to Perl's builtin getnet*() functions +by-name interface to Perl's built-in getnet*() functions =item Net::protoent -by-name interface to Perl's builtin getproto*() functions +by-name interface to Perl's built-in getproto*() functions =item Net::servent -by-name interface to Perl's builtin getserv*() functions +by-name interface to Perl's built-in getserv*() functions -=item Opcode +=item O -disable named opcodes when compiling or running Perl code +Generic interface to Perl Compiler backends -=item Pod::Text +=item Opcode -convert POD data to formatted ASCII text +Disable named opcodes when compiling perl code =item POSIX -interface to IEEE Standard 1003.1 +Perl interface to IEEE Std 1003.1 + +=item Pod::Html + +module to convert pod files to HTML + +=item Pod::Text + +convert POD data to formatted ASCII text =item SDBM_File -tied access to sdbm files +Tied access to sdbm files =item Safe -compile and execute code in restricted compartments +Compile and execute code in restricted compartments =item Search::Dict @@ -400,7 +630,7 @@ load functions only on demand =item Shell -run shell commands transparently within Perl +run shell commands transparently within perl =item Socket @@ -412,27 +642,31 @@ manipulate Perl symbols and their names =item Sys::Hostname -try every conceivable way to get hostname +Try every conceivable way to get hostname =item Sys::Syslog -interface to the Unix syslog(3) calls +Perl interface to the UNIX syslog(3) calls =item Term::Cap -termcap interface +Perl termcap interface =item Term::Complete -word completion module +Perl word completion module =item Term::ReadLine -interface to various C packages +Perl interface to various C packages. + +=item Test + +provides a simple framework for writing test scripts =item Test::Harness -run Perl standard test scripts with statistics +run perl standard test scripts with statistics =item Text::Abbrev @@ -440,35 +674,61 @@ create an abbreviation table from a list =item Text::ParseWords -parse text into an array of tokens +parse text into an array of tokens or array of arrays =item Text::Soundex -implementation of the Soundex Algorithm as described by Knuth - -=item Text::Tabs +Implementation of the Soundex Algorithm as Described by Knuth -expand and unexpand tabs per the Unix expand(1) and unexpand(1) +=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 Tie::Hash +=item Thread + +multithreading + +=item Thread::Queue + +thread-safe queues + +=item Thread::Semaphore + +thread-safe semaphores + +=item Thread::Signal + +Start a thread which runs signal handlers reliably + +=item Thread::Specific + +thread-specific keys + +=item Tie::Array + +base class for tied arrays + +=item Tie::Handle + +base class definitions for tied handles + +=item Tie::Hash, Tie::StdHash base class definitions for tied hashes =item Tie::RefHash -base class definitions for tied hashes with references as keys +use references as hash keys -=item Tie::Scalar +=item Tie::Scalar, Tie::StdScalar base class definitions for tied scalars =item Tie::SubstrHash -fixed-table-size, fixed-key-length hashing +Fixed-table-size, fixed-key-length hashing =item Time::Local @@ -476,11 +736,11 @@ efficiently compute time from local and GMT time =item Time::gmtime -by-name interface to Perl's builtin gmtime() function +by-name interface to Perl's built-in gmtime() function =item Time::localtime -by-name interface to Perl's builtin localtime() function +by-name interface to Perl's built-in localtime() function =item Time::tm @@ -492,42 +752,54 @@ base class for ALL classes (blessed references) =item User::grent -by-name interface to Perl's builtin getgr*() functions +by-name interface to Perl's built-in getgr*() functions =item User::pwent -by-name interface to Perl's builtin getpw*() functions +by-name interface to Perl's built-in getpw*() functions =back -To find out I the modules installed on your system, including -those without documentation or outside the standard release, do this: +To find out I modules installed on your system, including +those without documentation or outside the standard release, +jus tdo this: % find `perl -e 'print "@INC"'` -name '*.pm' -print -They should all have their own documentation installed and accessible via -your system man(1) command. If that fails, try the I program. +They should all have their own documentation installed and accessible +via your system man(1) command. If you do not have a B +program, you can use the Perl B program instead, which +generates Perl code as output you can run through perl. If you +have a B program but it doesn't find your modules, you'll have +to fix your manpath. See L for details. If you have no +system B command, you might try the B program. =head2 Extension Modules -Extension modules are written in C (or a mix of Perl and C) and may be -statically linked or in general are -dynamically loaded into Perl if and when you need them. Supported -extension modules include the Socket, Fcntl, and POSIX 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 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 in -archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their -authors before randomly posting asking for their present condition and -disposition. +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. =head1 CPAN -CPAN stands for the Comprehensive Perl Archive Network. This is a globally -replicated collection of all known Perl materials, including hundreds -of unbundled modules. Here are the major categories of modules: +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 distributions for these. Search engines for +CPAN can be found at http://cpan.perl.com/ and at +http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl . + +Most importantly, CPAN includes around a thousand unbundled modules, +some of which require a C compiler to build. Major categories of +modules are: =over @@ -596,97 +868,144 @@ Miscellaneous Modules =back -The registered CPAN sites as of this writing include the following. +Registered CPAN sites as of this writing include the following. You should try to choose one close to you: =over -=item * -Africa - - South Africa ftp://ftp.is.co.za/programming/perl/CPAN/ - -=item * -Asia - - Hong Kong ftp://ftp.hkstar.com/pub/CPAN/ - Japan ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ - ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/ - South Korea ftp://ftp.nuri.net/pub/CPAN/ - Taiwan ftp://dongpo.math.ncu.edu.tw/perl/CPAN/ - ftp://ftp.wownet.net/pub2/PERL/ - -=item * -Australasia - - Australia ftp://ftp.netinfo.com.au/pub/perl/CPAN/ - New Zealand ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/ - -=item * -Europe - - Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ - Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ - Czech Republic ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/ - Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ - Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/ - France ftp://ftp.ibp.fr/pub/perl/CPAN/ - ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/ - Germany ftp://ftp.gmd.de/packages/CPAN/ - ftp://ftp.leo.org/pub/comp/programming/languages/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/Perl/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/ - Italy ftp://cis.utovrm.it/CPAN/ - the Netherlands ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/ - ftp://ftp.EU.net/packages/cpan/ - Norway ftp://ftp.uit.no/pub/languages/perl/cpan/ - Poland ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ - ftp://sunsite.icm.edu.pl/pub/CPAN/ - Portugal ftp://ftp.ci.uminho.pt/pub/lang/perl/ - ftp://ftp.telepac.pt/pub/CPAN/ - Russia ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ - Slovenia ftp://ftp.arnes.si/software/perl/CPAN/ - Spain ftp://ftp.etse.urv.es/pub/mirror/perl/ - ftp://ftp.rediris.es/mirror/CPAN/ - Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/ - UK ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ - ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ - ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/ - -=item * -North America - - Ontario ftp://ftp.utilis.com/public/CPAN/ - ftp://enterprise.ic.gc.ca/pub/perl/CPAN/ - Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/ - California ftp://ftp.digital.com/pub/plan/perl/CPAN/ - ftp://ftp.cdrom.com/pub/perl/CPAN/ - Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ - Florida ftp://ftp.cis.ufl.edu/pub/perl/CPAN/ - Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/ - Massachusetts ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ - New York ftp://ftp.rge.com/pub/languages/perl/ - North Carolina ftp://ftp.duke.edu/pub/perl/ - Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/ - Oregon http://www.perl.org/CPAN/ - ftp://ftp.orst.edu/pub/packages/CPAN/ - Pennsylvania ftp://ftp.epix.net/pub/languages/perl/ - Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/ - ftp://ftp.metronet.com/pub/perl/ - -=item * -South America - - Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/ +=item Africa + + South Africa ftp://ftp.is.co.za/programming/perl/CPAN/ + ftp://ftpza.co.za/pub/mirrors/cpan/ + +=item Asia + + China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/ + Hong Kong ftp://ftp.hkstar.com/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/ + Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/ + South Korea ftp://ftp.bora.net/pub/CPAN/ + ftp://ftp.nuri.net/pub/CPAN/ + Taiwan ftp://ftp.wownet.net/pub2/PERL/ + ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/ + Thailand ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/ + ftp://ftp.nectec.or.th/pub/mirrors/CPAN/ + +=item 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/ + +=item Europe + + Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ + 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.lip6.fr/pub/perl/CPAN/ + ftp://ftp.oleane.net/pub/mirrors/CPAN/ + ftp://ftp.pasteur.fr/pub/computing/CPAN/ + Germany ftp://ftp.archive.de.uu.net/pub/CPAN/ + ftp://ftp.gmd.de/packages/CPAN/ + ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ + ftp://ftp.leo.org/pub/comp/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/ + Ireland 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.EU.net/packages/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.szczecin.pl/pub/perl/CPAN/ + ftp://ftp.man.torun.pl/pub/doc/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.dntis.ro/pub/mirrors/perl-cpan/ + ftp://ftp.dnttm.ro/pub/CPAN/ + Russia ftp://ftp.chg.ru/pub/lang/perl/CPAN/ + ftp://ftp.sai.msu.su/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.plig.org/pub/CPAN/ + ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ + ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/ + +=item North America + + Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/ + California ftp://cpan.nas.nasa.gov/pub/perl/CPAN/ + ftp://ftp.cdrom.com/pub/perl/CPAN/ + ftp://ftp.digital.com/pub/plan/perl/CPAN/ + Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ + Florida ftp://ftp.cise.ufl.edu/pub/perl/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/ + Manitoba ftp://theory.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/ + Minnesota ftp://ftp.midearthbbs.com/CPAN/ + New York ftp://ftp.rge.com/pub/languages/perl/ + North Carolina ftp://ftp.duke.edu/pub/perl/ + 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/ + Texas ftp://ftp.sedl.org/pub/mirrors/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.spu.edu/pub/CPAN/ + +=item South America + + Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/ + Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/ =back For an up-to-date listing of CPAN sites, -see F or F. +see http://www.perl.com/perl/CPAN or ftp://www.perl.com/perl/ . =head1 Modules: Creation, Use, and Abuse @@ -730,6 +1049,8 @@ scheme as the original author. =item Try to design the new module to be easy to extend and reuse. +Always use B<-w>. + 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.,: @@ -754,7 +1075,7 @@ appropriate. Split large methods into smaller more flexible ones. Inherit methods from other modules if appropriate. Avoid class name tests like: C. -Generally you can delete the "C" part with no harm at all. +Generally you can delete the C part with no harm at all. Let the objects look after themselves! Generally, avoid hard-wired class names as far as possible. @@ -768,7 +1089,7 @@ the module after __END__ either using AutoSplit or by saying: eval join('',) || die $@ unless caller(); Does your module pass the 'empty subclass' test? If you say -"C<@SUBCLASS::ISA = qw(YOURCLASS);>" your applications should be able +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 = new YOURCLASS;> into: C<$obj = new SUBCLASS;> ? @@ -777,11 +1098,18 @@ 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 (or C). +Always use B<-w>. + +Try to C (or C). Remember that you can add C to individual blocks -of code that need less strictness. Always use B<-w>. Always use B<-w>! +of code that need less strictness. + +Always use B<-w>. + Follow the guidelines in the perlstyle(1) manual. +Always use B<-w>. + =item Some simple style guidelines The perlstyle manual supplied with Perl has many helpful points. @@ -951,7 +1279,7 @@ 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 Exporter.pm in Perl5.001m or later for details. +See L 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 @@ -965,7 +1293,7 @@ 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 you should place the module into a major ftp archive and +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 @@ -1000,7 +1328,7 @@ Please remember to send me an updated entry for the Module list! Always strive to remain compatible with previous released versions. Otherwise try to add a mechanism to revert to the -old behaviour if people rely on it. Document incompatible changes. +old behavior if people rely on it. Document incompatible changes. =back @@ -1026,8 +1354,8 @@ 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. +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.