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