home *** CD-ROM | disk | FTP | other *** search
/ Chip: Windows 2000 Professional Resource Kit / W2KPRK.iso / apps / perl / ActivePerl.exe / data.z / perlmodlib.pod < prev    next >
Encoding:
Text File  |  1999-10-14  |  33.5 KB  |  1,160 lines
  1. =head1 NAME
  2.  
  3. perlmodlib - constructing new Perl modules and finding existing ones
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. =head1 THE PERL MODULE LIBRARY
  8.  
  9. A number of modules are included the Perl distribution.  These are
  10. described below, and all end in F<.pm>.  You may also discover files in
  11. the library directory that end in either F<.pl> or F<.ph>.  These are old
  12. libraries supplied so that old programs that use them still run.  The
  13. F<.pl> files will all eventually be converted into standard modules, and
  14. the F<.ph> files made by B<h2ph> will probably end up as extension modules
  15. made by B<h2xs>.  (Some F<.ph> values may already be available through the
  16. POSIX module.)  The B<pl2pm> file in the distribution may help in your
  17. conversion, but it's just a mechanical process and therefore far from
  18. bulletproof.
  19.  
  20. =head2 Pragmatic Modules
  21.  
  22. They work somewhat like pragmas in that they tend to affect the compilation of
  23. your program, and thus will usually work well only when used within a
  24. C<use>, or C<no>.  Most of these are lexically scoped, so an inner BLOCK
  25. may countermand any of these by saying:
  26.  
  27.     no integer;
  28.     no strict 'refs';
  29.  
  30. which lasts until the end of that BLOCK.
  31.  
  32. Unlike the pragmas that effect the C<$^H> hints variable, the C<use
  33. vars> and C<use subs> declarations are not BLOCK-scoped.  They allow
  34. you to predeclare a variables or subroutines within a particular
  35. I<file> rather than just a block.  Such declarations are effective
  36. for the entire file for which they were declared.  You cannot rescind
  37. them with C<no vars> or C<no subs>.
  38.  
  39. The following pragmas are defined (and have their own documentation).
  40.  
  41. =over 12
  42.  
  43. =item use autouse MODULE => qw(sub1 sub2 sub3)
  44.  
  45. Defers C<require MODULE> until someone calls one of the specified
  46. subroutines (which must be exported by MODULE).  This pragma should be
  47. used with caution, and only when necessary.
  48.  
  49. =item blib
  50.  
  51. manipulate @INC at compile time to use MakeMaker's uninstalled version
  52. of a package
  53.  
  54. =item diagnostics
  55.  
  56. force verbose warning diagnostics
  57.  
  58. =item integer
  59.  
  60. compute arithmetic in integer instead of double
  61.  
  62. =item less
  63.  
  64. request less of something from the compiler
  65.  
  66. =item lib
  67.  
  68. manipulate @INC at compile time
  69.  
  70. =item locale
  71.  
  72. use or ignore current locale for builtin operations (see L<perllocale>)
  73.  
  74. =item ops
  75.  
  76. restrict named opcodes when compiling or running Perl code
  77.  
  78. =item overload
  79.  
  80. overload basic Perl operations
  81.  
  82. =item re
  83.  
  84. alter behaviour of regular expressions
  85.  
  86. =item sigtrap
  87.  
  88. enable simple signal handling
  89.  
  90. =item strict
  91.  
  92. restrict unsafe constructs
  93.  
  94. =item subs
  95.  
  96. predeclare sub names
  97.  
  98. =item vmsish
  99.  
  100. adopt certain VMS-specific behaviors
  101.  
  102. =item vars
  103.  
  104. predeclare global variable names
  105.  
  106. =back
  107.  
  108. =head2 Standard Modules
  109.  
  110. Standard, bundled modules are all expected to behave in a well-defined
  111. manner with respect to namespace pollution because they use the
  112. Exporter module.  See their own documentation for details.
  113.  
  114. =over 12
  115.  
  116. =item AnyDBM_File
  117.  
  118. provide framework for multiple DBMs
  119.  
  120. =item AutoLoader
  121.  
  122. load functions only on demand
  123.  
  124. =item AutoSplit
  125.  
  126. split a package for autoloading
  127.  
  128. =item Benchmark
  129.  
  130. benchmark running times of code
  131.  
  132. =item CPAN
  133.  
  134. interface to Comprehensive Perl Archive Network
  135.  
  136. =item CPAN::FirstTime
  137.  
  138. create a CPAN configuration file
  139.  
  140. =item CPAN::Nox
  141.  
  142. run CPAN while avoiding compiled extensions
  143.  
  144. =item Carp
  145.  
  146. warn of errors (from perspective of caller)
  147.  
  148. =item Class::Struct
  149.  
  150. declare struct-like datatypes
  151.  
  152. =item Config
  153.  
  154. access Perl configuration information
  155.  
  156. =item Cwd
  157.  
  158. get pathname of current working directory
  159.  
  160. =item DB_File
  161.  
  162. access to Berkeley DB
  163.  
  164. =item Devel::SelfStubber
  165.  
  166. generate stubs for a SelfLoading module
  167.  
  168. =item DirHandle
  169.  
  170. supply object methods for directory handles
  171.  
  172. =item DynaLoader
  173.  
  174. dynamically load C libraries into Perl code
  175.  
  176. =item English
  177.  
  178. use nice English (or awk) names for ugly punctuation variables
  179.  
  180. =item Env
  181.  
  182. import environment variables
  183.  
  184. =item Exporter
  185.  
  186. implements default import method for modules
  187.  
  188. =item ExtUtils::Embed
  189.  
  190. utilities for embedding Perl in C/C++ applications
  191.  
  192. =item ExtUtils::Install
  193.  
  194. install files from here to there
  195.  
  196. =item ExtUtils::Liblist
  197.  
  198. determine libraries to use and how to use them
  199.  
  200. =item ExtUtils::MM_OS2
  201.  
  202. methods to override Unix behaviour in ExtUtils::MakeMaker
  203.  
  204. =item ExtUtils::MM_Unix
  205.  
  206. methods used by ExtUtils::MakeMaker
  207.  
  208. =item ExtUtils::MM_VMS
  209.  
  210. methods to override Unix behaviour in ExtUtils::MakeMaker
  211.  
  212. =item ExtUtils::MakeMaker
  213.  
  214. create an extension Makefile
  215.  
  216. =item ExtUtils::Manifest
  217.  
  218. utilities to write and check a MANIFEST file
  219.  
  220. =item ExtUtils::Mkbootstrap
  221.  
  222. make a bootstrap file for use by DynaLoader
  223.  
  224. =item ExtUtils::Mksymlists
  225.  
  226. write linker options files for dynamic extension
  227.  
  228. =item ExtUtils::testlib
  229.  
  230. add blib/* directories to @INC
  231.  
  232. =item Fatal
  233.  
  234. make errors in builtins or Perl functions fatal
  235.  
  236. =item Fcntl
  237.  
  238. load the C Fcntl.h defines
  239.  
  240. =item File::Basename
  241.  
  242. split a pathname into pieces
  243.  
  244. =item File::CheckTree
  245.  
  246. run many filetest checks on a tree
  247.  
  248. =item File::Compare
  249.  
  250. compare files or filehandles
  251.  
  252. =item File::Copy
  253.  
  254. copy files or filehandles
  255.  
  256. =item File::Find
  257.  
  258. traverse a file tree
  259.  
  260. =item File::Path
  261.  
  262. create or remove a series of directories
  263.  
  264. =item File::Spec
  265.  
  266. portably perform operations on file names
  267.  
  268. =item File::Spec::Functions
  269.  
  270. function call interface to File::Spec module
  271.  
  272. =item File::stat
  273.  
  274. by-name interface to Perl's builtin stat() functions
  275.  
  276. =item FileCache
  277.  
  278. keep more files open than the system permits
  279.  
  280. =item FileHandle
  281.  
  282. supply object methods for filehandles
  283.  
  284. =item FindBin
  285.  
  286. locate directory of original Perl script
  287.  
  288. =item GDBM_File
  289.  
  290. access to the gdbm library
  291.  
  292. =item Getopt::Long
  293.  
  294. extended processing of command line options
  295.  
  296. =item Getopt::Std
  297.  
  298. process single-character switches with switch clustering
  299.  
  300. =item I18N::Collate
  301.  
  302. compare 8-bit scalar data according to the current locale
  303.  
  304. =item IO
  305.  
  306. load various IO modules
  307.  
  308. =item IO::File
  309.  
  310. supply object methods for filehandles
  311.  
  312. =item IO::Handle
  313.  
  314. supply object methods for I/O handles
  315.  
  316. =item IO::Pipe
  317.  
  318. supply object methods for pipes
  319.  
  320. =item IO::Seekable
  321.  
  322. supply seek based methods for I/O objects
  323.  
  324. =item IO::Select
  325.  
  326. OO interface to the select system call
  327.  
  328. =item IO::Socket
  329.  
  330. object interface to socket communications
  331.  
  332. =item IPC::Open2
  333.  
  334. open a process for both reading and writing
  335.  
  336. =item IPC::Open3
  337.  
  338. open a process for reading, writing, and error handling
  339.  
  340. =item Math::BigFloat
  341.  
  342. arbitrary length float math package
  343.  
  344. =item Math::BigInt
  345.  
  346. arbitrary size integer math package
  347.  
  348. =item Math::Complex
  349.  
  350. complex numbers and associated mathematical functions
  351.  
  352. =item Math::Trig
  353.  
  354. simple interface to parts of Math::Complex for those who
  355. need trigonometric functions only for real numbers
  356.  
  357. =item NDBM_File
  358.  
  359. tied access to ndbm files
  360.  
  361. =item Net::Ping
  362.  
  363. Hello, anybody home?
  364.  
  365. =item Net::hostent
  366.  
  367. by-name interface to Perl's builtin gethost*() functions
  368.  
  369. =item Net::netent
  370.  
  371. by-name interface to Perl's builtin getnet*() functions
  372.  
  373. =item Net::protoent
  374.  
  375. by-name interface to Perl's builtin getproto*() functions
  376.  
  377. =item Net::servent
  378.  
  379. by-name interface to Perl's builtin getserv*() functions
  380.  
  381. =item Opcode
  382.  
  383. disable named opcodes when compiling or running Perl code
  384.  
  385. =item Pod::Text
  386.  
  387. convert POD data to formatted ASCII text
  388.  
  389. =item POSIX
  390.  
  391. interface to IEEE Standard 1003.1
  392.  
  393. =item SDBM_File
  394.  
  395. tied access to sdbm files
  396.  
  397. =item Safe
  398.  
  399. compile and execute code in restricted compartments
  400.  
  401. =item Search::Dict
  402.  
  403. search for key in dictionary file
  404.  
  405. =item SelectSaver
  406.  
  407. save and restore selected file handle
  408.  
  409. =item SelfLoader
  410.  
  411. load functions only on demand
  412.  
  413. =item Shell
  414.  
  415. run shell commands transparently within Perl
  416.  
  417. =item Socket
  418.  
  419. load the C socket.h defines and structure manipulators
  420.  
  421. =item Symbol
  422.  
  423. manipulate Perl symbols and their names
  424.  
  425. =item Sys::Hostname
  426.  
  427. try every conceivable way to get hostname
  428.  
  429. =item Sys::Syslog
  430.  
  431. interface to the Unix syslog(3) calls
  432.  
  433. =item Term::Cap
  434.  
  435. termcap interface
  436.  
  437. =item Term::Complete
  438.  
  439. word completion module
  440.  
  441. =item Term::ReadLine
  442.  
  443. interface to various C<readline> packages
  444.  
  445. =item Test::Harness
  446.  
  447. run Perl standard test scripts with statistics
  448.  
  449. =item Text::Abbrev
  450.  
  451. create an abbreviation table from a list
  452.  
  453. =item Text::ParseWords
  454.  
  455. parse text into an array of tokens
  456.  
  457. =item Text::Soundex
  458.  
  459. implementation of the Soundex Algorithm as described by Knuth
  460.  
  461. =item Text::Tabs
  462.  
  463. expand and unexpand tabs per the Unix expand(1) and unexpand(1)
  464.  
  465. =item Text::Wrap
  466.  
  467. line wrapping to form simple paragraphs
  468.  
  469. =item Tie::Hash
  470.  
  471. base class definitions for tied hashes
  472.  
  473. =item Tie::RefHash
  474.  
  475. base class definitions for tied hashes with references as keys
  476.  
  477. =item Tie::Scalar
  478.  
  479. base class definitions for tied scalars
  480.  
  481. =item Tie::SubstrHash
  482.  
  483. fixed-table-size, fixed-key-length hashing
  484.  
  485. =item Time::Local
  486.  
  487. efficiently compute time from local and GMT time
  488.  
  489. =item Time::gmtime
  490.  
  491. by-name interface to Perl's builtin gmtime() function
  492.  
  493. =item Time::localtime
  494.  
  495. by-name interface to Perl's builtin localtime() function
  496.  
  497. =item Time::tm
  498.  
  499. internal object used by Time::gmtime and Time::localtime
  500.  
  501. =item UNIVERSAL
  502.  
  503. base class for ALL classes (blessed references)
  504.  
  505. =item User::grent
  506.  
  507. by-name interface to Perl's builtin getgr*() functions
  508.  
  509. =item User::pwent
  510.  
  511. by-name interface to Perl's builtin getpw*() functions
  512.  
  513. =back
  514.  
  515. To find out I<all> the modules installed on your system, including
  516. those without documentation or outside the standard release, do this:
  517.  
  518.     % find `perl -e 'print "@INC"'` -name '*.pm' -print
  519.  
  520. They should all have their own documentation installed and accessible via
  521. your system man(1) command.  If that fails, try the I<perldoc> program.
  522.  
  523. =head2 Extension Modules
  524.  
  525. Extension modules are written in C (or a mix of Perl and C) and may be
  526. statically linked or in general are
  527. dynamically loaded into Perl if and when you need them.  Supported
  528. extension modules include the Socket, Fcntl, and POSIX modules.
  529.  
  530. Many popular C extension modules do not come bundled (at least, not
  531. completely) due to their sizes, volatility, or simply lack of time for
  532. adequate testing and configuration across the multitude of platforms on
  533. which Perl was beta-tested.  You are encouraged to look for them in
  534. archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
  535. authors before randomly posting asking for their present condition and
  536. disposition.
  537.  
  538. =head1 CPAN
  539.  
  540. CPAN stands for the Comprehensive Perl Archive Network.  This is a globally
  541. replicated collection of all known Perl materials, including hundreds
  542. of unbundled modules.  Here are the major categories of modules:
  543.  
  544. =over
  545.  
  546. =item *
  547. Language Extensions and Documentation Tools
  548.  
  549. =item *
  550. Development Support
  551.  
  552. =item *
  553. Operating System Interfaces
  554.  
  555. =item *
  556. Networking, Device Control (modems) and InterProcess Communication
  557.  
  558. =item *
  559. Data Types and Data Type Utilities
  560.  
  561. =item *
  562. Database Interfaces
  563.  
  564. =item *
  565. User Interfaces
  566.  
  567. =item *
  568. Interfaces to / Emulations of Other Programming Languages
  569.  
  570. =item *
  571. File Names, File Systems and File Locking (see also File Handles)
  572.  
  573. =item *
  574. String Processing, Language Text Processing, Parsing, and Searching
  575.  
  576. =item *
  577. Option, Argument, Parameter, and Configuration File Processing
  578.  
  579. =item *
  580. Internationalization and Locale
  581.  
  582. =item *
  583. Authentication, Security, and Encryption
  584.  
  585. =item *
  586. World Wide Web, HTML, HTTP, CGI, MIME
  587.  
  588. =item *
  589. Server and Daemon Utilities
  590.  
  591. =item *
  592. Archiving and Compression
  593.  
  594. =item *
  595. Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
  596.  
  597. =item *
  598. Mail and Usenet News
  599.  
  600. =item *
  601. Control Flow Utilities (callbacks and exceptions etc)
  602.  
  603. =item *
  604. File Handle and Input/Output Stream Utilities
  605.  
  606. =item *
  607. Miscellaneous Modules
  608.  
  609. =back
  610.  
  611. The registered CPAN sites as of this writing include the following.
  612. You should try to choose one close to you:
  613.  
  614. =over
  615.  
  616. =item *
  617. Africa
  618.  
  619.    South Africa    ftp://ftp.is.co.za/programming/perl/CPAN/
  620.                    ftp://ftpza.co.za/pub/mirrors/cpan/
  621.  
  622. =item *
  623. Asia
  624.  
  625.    Armenia         ftp://sunsite.aua.am/pub/CPAN/
  626.    China           ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
  627.    Hong Kong       ftp://ftp.hkstar.com/pub/CPAN/
  628.    Israel          ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
  629.    Japan           ftp://ftp.dti.ad.jp/pub/lang/CPAN/
  630.                    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
  631.                    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
  632.                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
  633.                    ftp://mirror.nucba.ac.jp/mirror/Perl/
  634.    Singapore       ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
  635.    South Korea     ftp://ftp.bora.net/pub/CPAN/
  636.                    ftp://ftp.nuri.net/pub/CPAN/
  637.    Taiwan          ftp://ftp.wownet.net/pub2/PERL/
  638.                    ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
  639.    Thailand        ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
  640.                    ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
  641.  
  642. =item *
  643. Australasia
  644.  
  645.    Australia       ftp://cpan.topend.com.au/pub/CPAN/
  646.                    ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
  647.                    ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
  648.                    ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
  649.    New Zealand     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
  650.                    ftp://sunsite.net.nz/pub/languages/perl/CPAN/
  651.  
  652. =item *
  653. Central America
  654.  
  655.    Costa Rica      ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
  656.  
  657. =item *
  658. Europe
  659.  
  660.    Austria         ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
  661.    Belgium         ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
  662.    Bulgaria        ftp://ftp.ntrl.net/pub/mirrors/CPAN/
  663.    Croatia         ftp://ftp.linux.hr/pub/CPAN/
  664.    Czech Republic  ftp://ftp.fi.muni.cz/pub/perl/
  665.                    ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
  666.    Denmark         ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
  667.    Estonia         ftp://ftp.ut.ee/pub/languages/perl/CPAN/
  668.    Finland         ftp://ftp.funet.fi/pub/languages/perl/CPAN/
  669.    France          ftp://ftp.lip6.fr/pub/perl/CPAN/
  670.                    ftp://ftp.oleane.net/pub/mirrors/CPAN/
  671.                    ftp://ftp.pasteur.fr/pub/computing/CPAN/
  672.    Germany         ftp://ftp.archive.de.uu.net/pub/CPAN/
  673.                    ftp://ftp.gmd.de/packages/CPAN/
  674.                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
  675.                    ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/
  676.                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
  677.                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
  678.                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
  679.                    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
  680.    Greece          ftp://ftp.ntua.gr/pub/lang/perl/
  681.    Hungary         ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
  682.    Ireland         ftp://sunsite.compapp.dcu.ie/pub/perl/
  683.    Italy           ftp://cis.uniRoma2.it/CPAN/
  684.                    ftp://ftp.flashnet.it/pub/CPAN/
  685.                    ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
  686.    Netherlands     ftp://ftp.cs.uu.nl/mirror/CPAN/
  687.                    ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
  688.    Norway          ftp://ftp.uit.no/pub/languages/perl/cpan/
  689.                    ftp://sunsite.uio.no/pub/languages/perl/CPAN/
  690.    Poland          ftp://ftp.man.szczecin.pl/pub/perl/CPAN/
  691.                    ftp://ftp.man.torun.pl/pub/doc/CPAN/
  692.                    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
  693.                    ftp://sunsite.icm.edu.pl/pub/CPAN/
  694.    Portugal        ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
  695.                    ftp://ftp.ua.pt/pub/CPAN/
  696.    Romania         ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
  697.                    ftp://ftp.dnttm.ro/pub/CPAN/
  698.    Russia          ftp://cpan.npi.msu.su/CPAN/
  699.                    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
  700.    Slovakia        ftp://ftp.entry.sk/pub/languages/perl/CPAN/
  701.    Slovenia        ftp://ftp.arnes.si/software/perl/CPAN/
  702.    Spain           ftp://ftp.etse.urv.es/pub/perl/
  703.                    ftp://ftp.rediris.es/mirror/CPAN/
  704.    Sweden          ftp://ftp.sunet.se/pub/lang/perl/CPAN/
  705.    Switzerland     ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
  706.    Turkey          ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
  707.    United Kingdom  ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
  708.                    ftp://ftp.flirble.org/pub/languages/perl/CPAN/
  709.                    ftp://ftp.plig.org/pub/CPAN/
  710.                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
  711.                    ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
  712.  
  713. =item *
  714. North America
  715.  
  716.    Alberta         ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
  717.    California      ftp://ftp.cdrom.com/pub/perl/CPAN/
  718.                    ftp://ftp.digital.com/pub/plan/perl/CPAN/
  719.    Colorado        ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
  720.    Florida         ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
  721.    Illinois        ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
  722.    Indiana         ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
  723.                    ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
  724.    Manitoba        ftp://theory.uwinnipeg.ca/pub/CPAN/
  725.    Massachusetts   ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
  726.                    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
  727.    Mexico D.F.     ftp://ftp.msg.com.mx/pub/CPAN/
  728.    New York        ftp://ftp.rge.com/pub/languages/perl/
  729.    North Carolina  ftp://ftp.duke.edu/pub/perl/
  730.    Oklahoma        ftp://ftp.ou.edu/mirrors/CPAN/
  731.    Ontario         ftp://ftp.crc.ca/pub/packages/perl/CPAN/
  732.    Oregon          ftp://ftp.orst.edu/pub/packages/CPAN/
  733.    Pennsylvania    ftp://ftp.epix.net/pub/languages/perl/
  734.    Texas           ftp://ftp.sedl.org/pub/mirrors/CPAN/
  735.    Utah            ftp://mirror.xmission.com/CPAN/
  736.    Virginia        ftp://ftp.perl.org/pub/perl/CPAN/
  737.                    ftp://ruff.cs.jmu.edu/pub/CPAN/
  738.    Washington      ftp://ftp.spu.edu/pub/CPAN/
  739.  
  740. =item *
  741. South America
  742.  
  743.    Brazil          ftp://cpan.if.usp.br/pub/mirror/CPAN/
  744.    Chile           ftp://ftp.ing.puc.cl/pub/unix/perl/CPAN/
  745.                    ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
  746.  
  747. =back
  748.  
  749. For an up-to-date listing of CPAN sites,
  750. see F<http://www.perl.com/perl/CPAN> or F<ftp://ftp.perl.com/perl/>.
  751.  
  752. =head1 Modules: Creation, Use, and Abuse
  753.  
  754. (The following section is borrowed directly from Tim Bunce's modules
  755. file, available at your nearest CPAN site.)
  756.  
  757. Perl implements a class using a package, but the presence of a
  758. package doesn't imply the presence of a class.  A package is just a
  759. namespace.  A class is a package that provides subroutines that can be
  760. used as methods.  A method is just a subroutine that expects, as its
  761. first argument, either the name of a package (for "static" methods),
  762. or a reference to something (for "virtual" methods).
  763.  
  764. A module is a file that (by convention) provides a class of the same
  765. name (sans the .pm), plus an import method in that class that can be
  766. called to fetch exported symbols.  This module may implement some of
  767. its methods by loading dynamic C or C++ objects, but that should be
  768. totally transparent to the user of the module.  Likewise, the module
  769. might set up an AUTOLOAD function to slurp in subroutine definitions on
  770. demand, but this is also transparent.  Only the F<.pm> file is required to
  771. exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about 
  772. the AUTOLOAD mechanism.
  773.  
  774. =head2 Guidelines for Module Creation
  775.  
  776. =over 4
  777.  
  778. =item Do similar modules already exist in some form?
  779.  
  780. If so, please try to reuse the existing modules either in whole or
  781. by inheriting useful features into a new class.  If this is not
  782. practical try to get together with the module authors to work on
  783. extending or enhancing the functionality of the existing modules.
  784. A perfect example is the plethora of packages in perl4 for dealing
  785. with command line options.
  786.  
  787. If you are writing a module to expand an already existing set of
  788. modules, please coordinate with the author of the package.  It
  789. helps if you follow the same naming scheme and module interaction
  790. scheme as the original author.
  791.  
  792. =item Try to design the new module to be easy to extend and reuse.
  793.  
  794. Use blessed references.  Use the two argument form of bless to bless
  795. into the class name given as the first parameter of the constructor,
  796. e.g.,:
  797.  
  798.  sub new {
  799.     my $class = shift;
  800.     return bless {}, $class;
  801.  }
  802.  
  803. or even this if you'd like it to be used as either a static
  804. or a virtual method.
  805.  
  806.  sub new {
  807.     my $self  = shift;
  808.     my $class = ref($self) || $self;
  809.     return bless {}, $class;
  810.  }
  811.  
  812. Pass arrays as references so more parameters can be added later
  813. (it's also faster).  Convert functions into methods where
  814. appropriate.  Split large methods into smaller more flexible ones.
  815. Inherit methods from other modules if appropriate.
  816.  
  817. Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
  818. Generally you can delete the "C<eq 'FOO'>" part with no harm at all.
  819. Let the objects look after themselves! Generally, avoid hard-wired
  820. class names as far as possible.
  821.  
  822. Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
  823. C<$r-E<gt>func()> would work (see L<perlbot> for more details).
  824.  
  825. Use autosplit so little used or newly added functions won't be a
  826. burden to programs that don't use them. Add test functions to
  827. the module after __END__ either using AutoSplit or by saying:
  828.  
  829.  eval join('',<main::DATA>) || die $@ unless caller();
  830.  
  831. Does your module pass the 'empty subclass' test? If you say
  832. "C<@SUBCLASS::ISA = qw(YOURCLASS);>" your applications should be able
  833. to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
  834. does your application still work if you change:  C<$obj = new YOURCLASS;>
  835. into: C<$obj = new SUBCLASS;> ?
  836.  
  837. Avoid keeping any state information in your packages. It makes it
  838. difficult for multiple other packages to use yours. Keep state
  839. information in objects.
  840.  
  841. Always use B<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
  842. Remember that you can add C<no strict qw(...);> to individual blocks
  843. of code that need less strictness. Always use B<-w>. Always use B<-w>!
  844. Follow the guidelines in the perlstyle(1) manual.
  845.  
  846. =item Some simple style guidelines
  847.  
  848. The perlstyle manual supplied with Perl has many helpful points.
  849.  
  850. Coding style is a matter of personal taste. Many people evolve their
  851. style over several years as they learn what helps them write and
  852. maintain good code.  Here's one set of assorted suggestions that
  853. seem to be widely used by experienced developers:
  854.  
  855. Use underscores to separate words.  It is generally easier to read
  856. $var_names_like_this than $VarNamesLikeThis, especially for
  857. non-native speakers of English. It's also a simple rule that works
  858. consistently with VAR_NAMES_LIKE_THIS.
  859.  
  860. Package/Module names are an exception to this rule. Perl informally
  861. reserves lowercase module names for 'pragma' modules like integer
  862. and strict. Other modules normally begin with a capital letter and
  863. use mixed case with no underscores (need to be short and portable).
  864.  
  865. You may find it helpful to use letter case to indicate the scope
  866. or nature of a variable. For example:
  867.  
  868.  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
  869.  $Some_Caps_Here  package-wide global/static
  870.  $no_caps_here    function scope my() or local() variables
  871.  
  872. Function and method names seem to work best as all lowercase.
  873. e.g., C<$obj-E<gt>as_string()>.
  874.  
  875. You can use a leading underscore to indicate that a variable or
  876. function should not be used outside the package that defined it.
  877.  
  878. =item Select what to export.
  879.  
  880. Do NOT export method names!
  881.  
  882. Do NOT export anything else by default without a good reason!
  883.  
  884. Exports pollute the namespace of the module user.  If you must
  885. export try to use @EXPORT_OK in preference to @EXPORT and avoid
  886. short or common names to reduce the risk of name clashes.
  887.  
  888. Generally anything not exported is still accessible from outside the
  889. module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
  890. syntax.  By convention you can use a leading underscore on names to
  891. indicate informally that they are 'internal' and not for public use.
  892.  
  893. (It is actually possible to get private functions by saying:
  894. C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
  895. directly as a method, because a method must have a name in the symbol
  896. table.)
  897.  
  898. As a general rule, if the module is trying to be object oriented
  899. then export nothing. If it's just a collection of functions then
  900. @EXPORT_OK anything but use @EXPORT with caution.
  901.  
  902. =item Select a name for the module.
  903.  
  904. This name should be as descriptive, accurate, and complete as
  905. possible.  Avoid any risk of ambiguity. Always try to use two or
  906. more whole words.  Generally the name should reflect what is special
  907. about what the module does rather than how it does it.  Please use
  908. nested module names to group informally or categorize a module.
  909. There should be a very good reason for a module not to have a nested name.
  910. Module names should begin with a capital letter.
  911.  
  912. Having 57 modules all called Sort will not make life easy for anyone
  913. (though having 23 called Sort::Quick is only marginally better :-).
  914. Imagine someone trying to install your module alongside many others.
  915. If in any doubt ask for suggestions in comp.lang.perl.misc.
  916.  
  917. If you are developing a suite of related modules/classes it's good
  918. practice to use nested classes with a common prefix as this will
  919. avoid namespace clashes. For example: Xyz::Control, Xyz::View,
  920. Xyz::Model etc. Use the modules in this list as a naming guide.
  921.  
  922. If adding a new module to a set, follow the original author's
  923. standards for naming modules and the interface to methods in
  924. those modules.
  925.  
  926. To be portable each component of a module name should be limited to
  927. 11 characters. If it might be used on MS-DOS then try to ensure each is
  928. unique in the first 8 characters. Nested modules make this easier.
  929.  
  930. =item Have you got it right?
  931.  
  932. How do you know that you've made the right decisions? Have you
  933. picked an interface design that will cause problems later? Have
  934. you picked the most appropriate name? Do you have any questions?
  935.  
  936. The best way to know for sure, and pick up many helpful suggestions,
  937. is to ask someone who knows. Comp.lang.perl.misc is read by just about
  938. all the people who develop modules and it's the best place to ask.
  939.  
  940. All you need to do is post a short summary of the module, its
  941. purpose and interfaces. A few lines on each of the main methods is
  942. probably enough. (If you post the whole module it might be ignored
  943. by busy people - generally the very people you want to read it!)
  944.  
  945. Don't worry about posting if you can't say when the module will be
  946. ready - just say so in the message. It might be worth inviting
  947. others to help you, they may be able to complete it for you!
  948.  
  949. =item README and other Additional Files.
  950.  
  951. It's well known that software developers usually fully document the
  952. software they write. If, however, the world is in urgent need of
  953. your software and there is not enough time to write the full
  954. documentation please at least provide a README file containing:
  955.  
  956. =over 10
  957.  
  958. =item *
  959. A description of the module/package/extension etc.
  960.  
  961. =item *
  962. A copyright notice - see below.
  963.  
  964. =item *
  965. Prerequisites - what else you may need to have.
  966.  
  967. =item *
  968. How to build it - possible changes to Makefile.PL etc.
  969.  
  970. =item *
  971. How to install it.
  972.  
  973. =item *
  974. Recent changes in this release, especially incompatibilities
  975.  
  976. =item *
  977. Changes / enhancements you plan to make in the future.
  978.  
  979. =back
  980.  
  981. If the README file seems to be getting too large you may wish to
  982. split out some of the sections into separate files: INSTALL,
  983. Copying, ToDo etc.
  984.  
  985. =over 4
  986.  
  987. =item Adding a Copyright Notice.
  988.  
  989. How you choose to license your work is a personal decision.
  990. The general mechanism is to assert your Copyright and then make
  991. a declaration of how others may copy/use/modify your work.
  992.  
  993. Perl, for example, is supplied with two types of licence: The GNU
  994. GPL and The Artistic Licence (see the files README, Copying, and
  995. Artistic).  Larry has good reasons for NOT just using the GNU GPL.
  996.  
  997. My personal recommendation, out of respect for Larry, Perl, and the
  998. Perl community at large is to state something simply like:
  999.  
  1000.  Copyright (c) 1995 Your Name. All rights reserved.
  1001.  This program is free software; you can redistribute it and/or
  1002.  modify it under the same terms as Perl itself.
  1003.  
  1004. This statement should at least appear in the README file. You may
  1005. also wish to include it in a Copying file and your source files.
  1006. Remember to include the other words in addition to the Copyright.
  1007.  
  1008. =item Give the module a version/issue/release number.
  1009.  
  1010. To be fully compatible with the Exporter and MakeMaker modules you
  1011. should store your module's version number in a non-my package
  1012. variable called $VERSION.  This should be a floating point
  1013. number with at least two digits after the decimal (i.e., hundredths,
  1014. e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
  1015. See Exporter.pm in Perl5.001m or later for details.
  1016.  
  1017. It may be handy to add a function or method to retrieve the number.
  1018. Use the number in announcements and archive file names when
  1019. releasing the module (ModuleName-1.02.tar.Z).
  1020. See perldoc ExtUtils::MakeMaker.pm for details.
  1021.  
  1022. =item How to release and distribute a module.
  1023.  
  1024. It's good idea to post an announcement of the availability of your
  1025. module (or the module itself if small) to the comp.lang.perl.announce
  1026. Usenet newsgroup.  This will at least ensure very wide once-off
  1027. distribution.
  1028.  
  1029. If possible you should place the module into a major ftp archive and
  1030. include details of its location in your announcement.
  1031.  
  1032. Some notes about ftp archives: Please use a long descriptive file
  1033. name that includes the version number. Most incoming directories
  1034. will not be readable/listable, i.e., you won't be able to see your
  1035. file after uploading it. Remember to send your email notification
  1036. message as soon as possible after uploading else your file may get
  1037. deleted automatically. Allow time for the file to be processed
  1038. and/or check the file has been processed before announcing its
  1039. location.
  1040.  
  1041. FTP Archives for Perl Modules:
  1042.  
  1043. Follow the instructions and links on
  1044.  
  1045.    http://franz.ww.tu-berlin.de/modulelist
  1046.  
  1047. or upload to one of these sites:
  1048.  
  1049.    ftp://franz.ww.tu-berlin.de/incoming
  1050.    ftp://ftp.cis.ufl.edu/incoming
  1051.  
  1052. and notify <F<upload@franz.ww.tu-berlin.de>>.
  1053.  
  1054. By using the WWW interface you can ask the Upload Server to mirror
  1055. your modules from your ftp or WWW site into your own directory on
  1056. CPAN!
  1057.  
  1058. Please remember to send me an updated entry for the Module list!
  1059.  
  1060. =item Take care when changing a released module.
  1061.  
  1062. Always strive to remain compatible with previous released versions.
  1063. Otherwise try to add a mechanism to revert to the
  1064. old behaviour if people rely on it. Document incompatible changes.
  1065.  
  1066. =back
  1067.  
  1068. =back
  1069.  
  1070. =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
  1071.  
  1072. =over 4
  1073.  
  1074. =item There is no requirement to convert anything.
  1075.  
  1076. If it ain't broke, don't fix it! Perl 4 library scripts should
  1077. continue to work with no problems. You may need to make some minor
  1078. changes (like escaping non-array @'s in double quoted strings) but
  1079. there is no need to convert a .pl file into a Module for just that.
  1080.  
  1081. =item Consider the implications.
  1082.  
  1083. All Perl applications that make use of the script will need to
  1084. be changed (slightly) if the script is converted into a module.  Is
  1085. it worth it unless you plan to make other changes at the same time?
  1086.  
  1087. =item Make the most of the opportunity.
  1088.  
  1089. If you are going to convert the script to a module you can use the
  1090. opportunity to redesign the interface. The 'Guidelines for Module
  1091. Creation' above include many of the issues you should consider.
  1092.  
  1093. =item The pl2pm utility will get you started.
  1094.  
  1095. This utility will read *.pl files (given as parameters) and write
  1096. corresponding *.pm files. The pl2pm utilities does the following:
  1097.  
  1098. =over 10
  1099.  
  1100. =item *
  1101. Adds the standard Module prologue lines
  1102.  
  1103. =item *
  1104. Converts package specifiers from ' to ::
  1105.  
  1106. =item *
  1107. Converts die(...) to croak(...)
  1108.  
  1109. =item *
  1110. Several other minor changes
  1111.  
  1112. =back
  1113.  
  1114. Being a mechanical process pl2pm is not bullet proof. The converted
  1115. code will need careful checking, especially any package statements.
  1116. Don't delete the original .pl file till the new .pm one works!
  1117.  
  1118. =back
  1119.  
  1120. =head2 Guidelines for Reusing Application Code
  1121.  
  1122. =over 4
  1123.  
  1124. =item Complete applications rarely belong in the Perl Module Library.
  1125.  
  1126. =item Many applications contain some Perl code that could be reused.
  1127.  
  1128. Help save the world! Share your code in a form that makes it easy
  1129. to reuse.
  1130.  
  1131. =item Break-out the reusable code into one or more separate module files.
  1132.  
  1133. =item Take the opportunity to reconsider and redesign the interfaces.
  1134.  
  1135. =item In some cases the 'application' can then be reduced to a small
  1136.  
  1137. fragment of code built on top of the reusable modules. In these cases
  1138. the application could invoked as:
  1139.  
  1140.      % perl -e 'use Module::Name; method(@ARGV)' ...
  1141. or
  1142.      % perl -mModule::Name ...    (in perl5.002 or higher)
  1143.  
  1144. =back
  1145.  
  1146. =head1 NOTE
  1147.  
  1148. Perl does not enforce private and public parts of its modules as you may
  1149. have been used to in other languages like C++, Ada, or Modula-17.  Perl
  1150. doesn't have an infatuation with enforced privacy.  It would prefer
  1151. that you stayed out of its living room because you weren't invited, not
  1152. because it has a shotgun.
  1153.  
  1154. The module and its user have a contract, part of which is common law,
  1155. and part of which is "written".  Part of the common law contract is
  1156. that a module doesn't pollute any namespace it wasn't asked to.  The
  1157. written contract for the module (A.K.A. documentation) may make other
  1158. provisions.  But then you know when you C<use RedefineTheWorld> that
  1159. you're redefining the world and willing to take the consequences.
  1160.