Amiga Magazin: Amiga-CD 1996 July/AMIGA_1996_7.BIN/ausgabe_7_96/pd-programmierung/perl5_002bin.lha/man/catp/perlmod.0

Text File | 1996-03-02 | 59KB | 1,255 lines

PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


NNNNAAAAMMMMEEEE
       perlmod - Perl modules (packages)

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
       PPPPaaaacccckkkkaaaaggggeeeessss

       Perl provides a mechanism for alternative namespaces to
       protect packages from stomping on each others variables.
       In fact, apart from certain magical variables, there's
       really no such thing as a global variable in Perl.  The
       package statement declares the compilation unit as being
       in the given namespace.  The scope of the package
       declaration is from the declaration itself through the end
       of the enclosing block (the same scope as the _l_o_c_a_l_(_)
       operator).  All further unqualified dynamic identifiers
       will be in this namespace.  A package statement only
       affects dynamic variables--including those you've used
       _l_o_c_a_l_(_) on--but _n_o_t lexical variables created with _m_y_(_).
       Typically it would be the first declaration in a file to
       be included by the rrrreeeeqqqquuuuiiiirrrreeee or uuuusssseeee operator.  You can
       switch into a package in more than one place; it merely
       influences which symbol table is used by the compiler for
       the rest of that block.  You can refer to variables and
       filehandles in other packages by prefixing the identifier
       with the package name and a double colon:
       $$$$PPPPaaaacccckkkkaaaaggggeeee::::::::VVVVaaaarrrriiiiaaaabbbblllleeee.  If the package name is null, the mmmmaaaaiiiinnnn
       package as assumed.  That is, $$$$::::::::ssssaaaaiiiillll is equivalent to
       $$$$mmmmaaaaiiiinnnn::::::::ssssaaaaiiiillll.

       (The old package delimiter was a single quote, but double
       colon is now the preferred delimiter, in part because it's
       more readable to humans, and in part because it's more
       readable to eeeemmmmaaaaccccssss macros.  It also makes C++ programmers
       feel like they know what's going on.)

       Packages may be nested inside other packages:
       $$$$OOOOUUUUTTTTEEEERRRR::::::::IIIINNNNNNNNEEEERRRR::::::::vvvvaaaarrrr.  This implies nothing about the order
       of name lookups, however.  All symbols are either local to
       the current package, or must be fully qualified from the
       outer package name down.  For instance, there is nowhere
       within package OOOOUUUUTTTTEEEERRRR that $$$$IIIINNNNNNNNEEEERRRR::::::::vvvvaaaarrrr refers to
       $$$$OOOOUUUUTTTTEEEERRRR::::::::IIIINNNNNNNNEEEERRRR::::::::vvvvaaaarrrr.  It would treat package IIIINNNNNNNNEEEERRRR as a
       totally separate global package.

       Only identifiers starting with letters (or underscore) are
       stored in a package's symbol table.  All other symbols are
       kept in package mmmmaaaaiiiinnnn, including all of the punctuation
       variables like $$$$____.  In addition, the identifiers STDIN,
       STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC and SIG are forced
       to be in package mmmmaaaaiiiinnnn, even when used for other purposes
       than their built-in one.  Note also that, if you have a
       package called mmmm, ssss or yyyy, then you can't use the qualified
       form of an identifier because it will be interpreted
       instead as a pattern match, a substitution, or a



2/Feb/96                 perl 5.002 with                        1





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


       translation.

       (Variables beginning with underscore used to be forced
       into package main, but we decided it was more useful for
       package writers to be able to use leading underscore to
       indicate private variables and method names.  $$$$____ is still
       global though.)

       _E_v_a_l_(_)ed strings are compiled in the package in which the
       _e_v_a_l_(_) was compiled.  (Assignments to $$$$SSSSIIIIGGGG{{{{}}}}, however,
       assume the signal handler specified is in the mmmmaaaaiiiinnnn
       package.  Qualify the signal handler name if you wish to
       have a signal handler in a package.)  For an example,
       examine _p_e_r_l_d_b_._p_l in the Perl library.  It initially
       switches to the DDDDBBBB package so that the debugger doesn't
       interfere with variables in the script you are trying to
       debug.  At various points, however, it temporarily
       switches back to the mmmmaaaaiiiinnnn package to evaluate various
       expressions in the context of the mmmmaaaaiiiinnnn package (or
       wherever you came from).  See the _p_e_r_l_d_e_b_u_g manpage.

       See the _p_e_r_l_s_u_b manpage for other scoping issues related
       to _m_y_(_) and _l_o_c_a_l_(_), or the _p_e_r_l_r_e_f manpage regarding
       closures.

       SSSSyyyymmmmbbbboooollll TTTTaaaabbbblllleeeessss

       The symbol table for a package happens to be stored in the
       associative array of that name appended with two colons.
       The main symbol table's name is thus %%%%mmmmaaaaiiiinnnn::::::::, or %%%%:::::::: for
       short.  Likewise the nested package mentioned earlier is
       named %%%%OOOOUUUUTTTTEEEERRRR::::::::IIIINNNNNNNNEEEERRRR::::::::.

       The value in each entry of the associative array is what
       you are referring to when you use the ****nnnnaaaammmmeeee typeglob
       notation.  In fact, the following have the same effect,
       though the first is more efficient because it does the
       symbol table lookups at compile time:

           llllooooccccaaaallll((((****mmmmaaaaiiiinnnn::::::::ffffoooooooo)))) ==== ****mmmmaaaaiiiinnnn::::::::bbbbaaaarrrr;;;; llllooooccccaaaallll(((($$$$mmmmaaaaiiiinnnn::::::::{{{{''''ffffoooooooo''''}}}})))) ====
           $$$$mmmmaaaaiiiinnnn::::::::{{{{''''bbbbaaaarrrr''''}}}};;;;

       You can use this to print out all the variables in a
       package, for instance.  Here is _d_u_m_p_v_a_r_._p_l from the Perl
       library:












2/Feb/96                 perl 5.002 with                        2





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


          ppppaaaacccckkkkaaaaggggeeee dddduuuummmmppppvvvvaaaarrrr;;;;
          ssssuuuubbbb mmmmaaaaiiiinnnn::::::::dddduuuummmmppppvvvvaaaarrrr {{{{
              (((($$$$ppppaaaacccckkkkaaaaggggeeee)))) ==== @@@@____;;;;
              llllooooccccaaaallll((((****ssssttttaaaabbbb)))) ==== eeeevvvvaaaallll((((""""****$$$${{{{ppppaaaacccckkkkaaaaggggeeee}}}}::::::::""""))));;;;
              wwwwhhhhiiiilllleeee (((((((($$$$kkkkeeeeyyyy,,,,$$$$vvvvaaaallll)))) ==== eeeeaaaacccchhhh((((%%%%ssssttttaaaabbbb)))))))) {{{{
                  llllooooccccaaaallll((((****eeeennnnttttrrrryyyy)))) ==== $$$$vvvvaaaallll;;;;
                  iiiiffff ((((ddddeeeeffffiiiinnnneeeedddd $$$$eeeennnnttttrrrryyyy)))) {{{{
                      pppprrrriiiinnnntttt """"\\\\$$$$$$$$kkkkeeeeyyyy ==== ''''$$$$eeeennnnttttrrrryyyy''''\\\\nnnn"""";;;;
                  }}}}

                  iiiiffff ((((ddddeeeeffffiiiinnnneeeedddd @@@@eeeennnnttttrrrryyyy)))) {{{{
                      pppprrrriiiinnnntttt """"\\\\@@@@$$$$kkkkeeeeyyyy ==== ((((\\\\nnnn"""";;;;
                      ffffoooorrrreeeeaaaacccchhhh $$$$nnnnuuuummmm (((($$$$[[[[ ........ $$$$####eeeennnnttttrrrryyyy)))) {{{{
                          pppprrrriiiinnnntttt """"  $$$$nnnnuuuummmm\\\\tttt''''"""",,,,$$$$eeeennnnttttrrrryyyy[[[[$$$$nnnnuuuummmm]]]],,,,""""''''\\\\nnnn"""";;;;
                      }}}}
                      pppprrrriiiinnnntttt """"))))\\\\nnnn"""";;;;
                  }}}}

                  iiiiffff (((($$$$kkkkeeeeyyyy nnnneeee """"$$$${{{{ppppaaaacccckkkkaaaaggggeeee}}}}::::::::"""" &&&&&&&& ddddeeeeffffiiiinnnneeeedddd %%%%eeeennnnttttrrrryyyy)))) {{{{
                      pppprrrriiiinnnntttt """"\\\\%%%%$$$$kkkkeeeeyyyy ==== ((((\\\\nnnn"""";;;;
                      ffffoooorrrreeeeaaaacccchhhh $$$$kkkkeeeeyyyy ((((ssssoooorrrrtttt kkkkeeeeyyyyssss((((%%%%eeeennnnttttrrrryyyy)))))))) {{{{
                          pppprrrriiiinnnntttt """"  $$$$kkkkeeeeyyyy\\\\tttt''''"""",,,,$$$$eeeennnnttttrrrryyyy{{{{$$$$kkkkeeeeyyyy}}}},,,,""""''''\\\\nnnn"""";;;;
                      }}}}
                      pppprrrriiiinnnntttt """"))))\\\\nnnn"""";;;;
                  }}}}
              }}}}
          }}}}

       Note that even though the subroutine is compiled in
       package dddduuuummmmppppvvvvaaaarrrr, the name of the subroutine is qualified
       so that its name is inserted into package mmmmaaaaiiiinnnn.

       Assignment to a typeglob performs an aliasing operation,
       i.e.,

           ****ddddiiiicccckkkk ==== ****rrrriiiicccchhhhaaaarrrrdddd;;;;

       causes variables, subroutines and file handles accessible
       via the identifier rrrriiiicccchhhhaaaarrrrdddd to also be accessible via the
       symbol ddddiiiicccckkkk.  If you only want to alias a particular
       variable or subroutine, you can assign a reference
       instead:

           ****ddddiiiicccckkkk ==== \\\\$$$$rrrriiiicccchhhhaaaarrrrdddd;;;;

       makes $$$$rrrriiiicccchhhhaaaarrrrdddd and $$$$ddddiiiicccckkkk the same variable, but leaves
       @@@@rrrriiiicccchhhhaaaarrrrdddd and @@@@ddddiiiicccckkkk as separate arrays.  Tricky, eh?

       This mechanism may be used to pass and return cheap
       references into or from subroutines if you won't want to
       copy the whole thing.






2/Feb/96                 perl 5.002 with                        3





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


           %%%%ssssoooommmmeeee____hhhhaaaasssshhhh ==== (((())));;;;
           ****ssssoooommmmeeee____hhhhaaaasssshhhh ==== ffffnnnn(((( \\\\%%%%aaaannnnooootttthhhheeeerrrr____hhhhaaaasssshhhh ))));;;;
           ssssuuuubbbb ffffnnnn {{{{
               llllooooccccaaaallll ****hhhhaaaasssshhhhssssyyyymmmm ==== sssshhhhiiiifffftttt;;;;
               #### nnnnoooowwww uuuusssseeee %%%%hhhhaaaasssshhhhssssyyyymmmm nnnnoooorrrrmmmmaaaallllllllyyyy,,,, aaaannnndddd yyyyoooouuuu
               #### wwwwiiiillllllll aaaaffffffffeeeecccctttt tttthhhheeee ccccaaaalllllllleeeerrrr''''ssss %%%%aaaannnnooootttthhhheeeerrrr____hhhhaaaasssshhhh
               mmmmyyyy %%%%nnnnhhhhaaaasssshhhh ==== (((())));;;; #### ddddoooo wwwwhhhhaaaatttt yyyyoooouuuu wwwwaaaannnntttt
               rrrreeeettttuuuurrrrnnnn \\\\%%%%nnnnhhhhaaaasssshhhh;;;;
           }}}}

       On return, the reference wil overwrite the hash slot in
       the symbol table specified by the *some_hash typeglob.
       This is a somewhat tricky way of passing around refernces
       cheaply when you won't want to have to remember to
       dereference variables explicitly.

       Another use of symbol tables is for making "constant"
       scalars.

           ****PPPPIIII ==== \\\\3333....11114444111155559999222266665555333355558888999977779999;;;;

       Now you cannot alter $$$$PPPPIIII, which is probably a good thing
       all in all.

       PPPPaaaacccckkkkaaaaggggeeee CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss aaaannnndddd DDDDeeeessssttttrrrruuuuccccttttoooorrrrssss

       There are two special subroutine definitions that function
       as package constructors and destructors.  These are the
       BBBBEEEEGGGGIIIINNNN and EEEENNNNDDDD routines.  The ssssuuuubbbb is optional for these
       routines.

       A BBBBEEEEGGGGIIIINNNN subroutine is executed as soon as possible, that
       is, the moment it is completely defined, even before the
       rest of the containing file is parsed.  You may have
       multiple BBBBEEEEGGGGIIIINNNN blocks within a file--they will execute in
       order of definition.  Because a BBBBEEEEGGGGIIIINNNN block executes
       immediately, it can pull in definitions of subroutines and
       such from other files in time to be visible to the rest of
       the file.

       An EEEENNNNDDDD subroutine is executed as late as possible, that
       is, when the interpreter is being exited, even if it is
       exiting as a result of a _d_i_e_(_) function.  (But not if it's
       is being blown out of the water by a signal--you have to
       trap that yourself (if you can).)  You may have multiple
       EEEENNNNDDDD blocks within a file--they will execute in reverse
       order of definition; that is: last in, first out (LIFO).

       Note that when you use the ----nnnn and ----pppp switches to Perl,
       BBBBEEEEGGGGIIIINNNN and EEEENNNNDDDD work just as they do in aaaawwwwkkkk, as a degenerate
       case.






2/Feb/96                 perl 5.002 with                        4





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


       PPPPeeeerrrrllll CCCCllllaaaasssssssseeeessss

       There is no special class syntax in Perl, but a package
       may function as a class if it provides subroutines that
       function as methods.  Such a package may also derive some
       of its methods from another class package by listing the
       other package name in its @@@@IIIISSSSAAAA array.

       For more on this, see the _p_e_r_l_o_b_j manpage.

       PPPPeeeerrrrllll MMMMoooodddduuuulllleeeessss

       A module is just a package that is defined in a library
       file of the same name, and is designed to be reusable.  It
       may do this by providing a mechanism for exporting some of
       its symbols into the symbol table of any package using it.
       Or it may function as a class definition and make its
       semantics available implicitly through method calls on the
       class and its objects, without explicit exportation of any
       symbols.  Or it can do a little of both.

       For example, to start a normal module called Fred, create
       a file called Fred.pm and put this at the start of it:

           ppppaaaacccckkkkaaaaggggeeee      FFFFrrrreeeedddd;;;;
           rrrreeeeqqqquuuuiiiirrrreeee      EEEExxxxppppoooorrrrtttteeeerrrr;;;;
           @@@@IIIISSSSAAAA       ==== qqqqwwww((((EEEExxxxppppoooorrrrtttteeeerrrr))));;;;
           @@@@EEEEXXXXPPPPOOOORRRRTTTT    ==== qqqqwwww((((ffffuuuunnnncccc1111 ffffuuuunnnncccc2222))));;;;
           @@@@EEEEXXXXPPPPOOOORRRRTTTT____OOOOKKKK ==== qqqqwwww(((($$$$ssssaaaallllllllyyyy @@@@lllliiiissssttttaaaabbbboooobbbb %%%%hhhhaaaarrrrrrrryyyy ffffuuuunnnncccc3333))));;;;

       Then go on to declare and use your variables in functions
       without any qualifications.  See the _E_x_p_o_r_t_e_r manpage and
       the _P_e_r_l _M_o_d_u_l_e_s _F_i_l_e for details on mechanics and style
       issues in module creation.

       Perl modules are included into your program by saying

           uuuusssseeee MMMMoooodddduuuulllleeee;;;;

       or

           uuuusssseeee MMMMoooodddduuuulllleeee LLLLIIIISSSSTTTT;;;;

       This is exactly equivalent to

           BBBBEEEEGGGGIIIINNNN {{{{ rrrreeeeqqqquuuuiiiirrrreeee """"MMMMoooodddduuuulllleeee....ppppmmmm"""";;;; iiiimmmmppppoooorrrrtttt MMMMoooodddduuuulllleeee;;;; }}}}

       or

           BBBBEEEEGGGGIIIINNNN {{{{ rrrreeeeqqqquuuuiiiirrrreeee """"MMMMoooodddduuuulllleeee....ppppmmmm"""";;;; iiiimmmmppppoooorrrrtttt MMMMoooodddduuuulllleeee LLLLIIIISSSSTTTT;;;; }}}}

       As a special case

           uuuusssseeee MMMMoooodddduuuulllleeee (((())));;;;



2/Feb/96                 perl 5.002 with                        5





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


       is exactly equivalent to

           BBBBEEEEGGGGIIIINNNN {{{{ rrrreeeeqqqquuuuiiiirrrreeee """"MMMMoooodddduuuulllleeee....ppppmmmm"""";;;; }}}}

       All Perl module files have the extension _._p_m.  uuuusssseeee assumes
       this so that you don't have to spell out "_M_o_d_u_l_e_._p_m" in
       quotes.  This also helps to differentiate new modules from
       old _._p_l and _._p_h files.  Module names are also capitalized
       unless they're functioning as pragmas, "Pragmas" are in
       effect compiler directives, and are sometimes called
       "pragmatic modules" (or even "pragmata" if you're a
       classicist).

       Because the uuuusssseeee statement implies a BBBBEEEEGGGGIIIINNNN block, the
       importation of semantics happens at the moment the uuuusssseeee
       statement is compiled, before the rest of the file is
       compiled.  This is how it is able to function as a pragma
       mechanism, and also how modules are able to declare
       subroutines that are then visible as list operators for
       the rest of the current file.  This will not work if you
       use rrrreeeeqqqquuuuiiiirrrreeee instead of uuuusssseeee.  With require you can get into
       this problem:

           rrrreeeeqqqquuuuiiiirrrreeee CCCCwwwwdddd;;;;                #### mmmmaaaakkkkeeee CCCCwwwwdddd:::::::: aaaacccccccceeeessssssssiiiibbbblllleeee
           $$$$hhhheeeerrrreeee ==== CCCCwwwwdddd::::::::ggggeeeettttccccwwwwdddd(((())));;;;

           uuuusssseeee CCCCwwwwdddd;;;;                    #### iiiimmmmppppoooorrrrtttt nnnnaaaammmmeeeessss ffffrrrroooommmm CCCCwwwwdddd::::::::
           $$$$hhhheeeerrrreeee ==== ggggeeeettttccccwwwwdddd(((())));;;;

           rrrreeeeqqqquuuuiiiirrrreeee CCCCwwwwdddd;;;;                #### mmmmaaaakkkkeeee CCCCwwwwdddd:::::::: aaaacccccccceeeessssssssiiiibbbblllleeee
           $$$$hhhheeeerrrreeee ==== ggggeeeettttccccwwwwdddd(((())));;;;           #### ooooooooppppssss!!!! nnnnoooo mmmmaaaaiiiinnnn::::::::ggggeeeettttccccwwwwdddd(((())))

       In general uuuusssseeee MMMMoooodddduuuulllleeee (((())));;;; is recommended over rrrreeeeqqqquuuuiiiirrrreeee
       MMMMoooodddduuuulllleeee;;;;.

       Perl packages may be nested inside other package names, so
       we can have package names containing ::::::::.  But if we used
       that package name directly as a filename it would makes
       for unwieldy or impossible filenames on some systems.
       Therefore, if a module's name is, say, TTTTeeeexxxxtttt::::::::SSSSoooouuuunnnnddddeeeexxxx, then
       its definition is actually found in the library file
       _T_e_x_t_/_S_o_u_n_d_e_x_._p_m.

       Perl modules always have a _._p_m file, but there may also be
       dynamically linked executables or autoloaded subroutine
       definitions associated with the module.  If so, these will
       be entirely transparent to the user of the module.  It is
       the responsibility of the _._p_m file to load (or arrange to
       autoload) any additional functionality.  The POSIX module
       happens to do both dynamic loading and autoloading, but
       the user can just say uuuusssseeee PPPPOOOOSSSSIIIIXXXX to get it all.

       For more information on writing extension modules, see the
       _p_e_r_l_x_s manpage and the _p_e_r_l_g_u_t_s manpage.



2/Feb/96                 perl 5.002 with                        6





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


NNNNOOOOTTTTEEEE
       Perl does not enforce private and public parts of its
       modules as you may have been used to in other languages
       like C++, Ada, or Modula-17.  Perl doesn't have an
       infatuation with enforced privacy.  It would prefer that
       you stayed out of its living room because you weren't
       invited, not because it has a shotgun.

       The module and its user have a contract, part of which is
       common law, and part of which is "written".  Part of the
       common law contract is that a module doesn't pollute any
       namespace it wasn't asked to.  The written contract for
       the module (AKA documentation) may make other provisions.
       But then you know when you uuuusssseeee RRRReeeeddddeeeeffffiiiinnnneeeeTTTThhhheeeeWWWWoooorrrrlllldddd that
       you're redefining the world and willing to take the
       consequences.

TTTTHHHHEEEE PPPPEEEERRRRLLLL MMMMOOOODDDDUUUULLLLEEEE LLLLIIIIBBBBRRRRAAAARRRRYYYY
       A number of modules are included the the Perl
       distribution.  These are described below, and all end in
       _._p_m.  You may also discover files in the library directory
       that end in either _._p_l or _._p_h.  These are old libraries
       supplied so that old programs that use them still run.
       The the _._p_h files made by hhhh2222pppphhhh will probably end up as
       extension modules made by hhhh2222xxxxssss.  (Some _._p_h values may
       already be available through the POSIX module.)  The ppppllll2222ppppmmmm
       file in the distribution may help in your conversion, but
       it's just a mechanical process, so is far from bullet
       proof.

       PPPPrrrraaaaggggmmmmaaaattttiiiicccc MMMMoooodddduuuulllleeeessss

       They work somewhat like pragmas in that they tend to
       affect the compilation of your program, and thus will
       usually only work well when used within a uuuusssseeee, or nnnnoooo.
       These are locally scoped, so an inner BLOCK may
       countermand any of these by saying

           nnnnoooo iiiinnnntttteeeeggggeeeerrrr;;;;
           nnnnoooo ssssttttrrrriiiicccctttt ''''rrrreeeeffffssss'''';;;;

       which lasts until the end of that BLOCK.

       The following programs are defined (and have their own
       documentation).

       diagnostics Pragma to produce enhanced diagnostics

       integer     Pragma to compute arithmetic in integer
                   instead of double

       less        Pragma to request less of something from the
                   compiler




2/Feb/96                 perl 5.002 with                        7





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


       overload    Pragma for overloading operators

       sigtrap     Pragma to enable stack backtrace on unexpected
                   signals

       strict      Pragma to restrict unsafe constructs

       subs        Pragma to predeclare sub names

       SSSSttttaaaannnnddddaaaarrrrdddd MMMMoooodddduuuulllleeeessss

       Standard, bundled modules are all expected to behave in a
       well-defined manner with respect to namespace pollution
       because they use the Exporter module.  See their own
       documentation for details.

       AnyDBM_File provide framework for multiple DBMs

       AutoLoader  load functions only on demand

       AutoSplit   split a package for autoloading

       Benchmark   benchmark running times of code

       Carp        warn of errors (from perspective of caller)

       Config      access Perl configuration option

       Cwd         get pathname of current working directory

       DB_File     Perl access to Berkeley DB

       Devel::SelfStubber
                   generate stubs for a SelfLoading module

       DynaLoader  Dynamically load C libraries into Perl code

       English     use nice English (or awk) names for ugly
                   punctuation variables

       Env         perl module that imports environment variables

       Exporter    provide inport/export controls for Perl
                   modules

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

       ExtUtils::MakeMaker
                   create an extension Makefile

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




2/Feb/96                 perl 5.002 with                        8





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


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

       ExtUtils::Miniperl
                   !!!GOOD QUESTION!!!

       Fcntl       load the C Fcntl.h defines

       File::Basename
                   parse file specifications

       File::CheckTree
                   run many filetest checks on a tree

       File::Find  traverse a file tree

       FileHandle  supply object methods for filehandles

       File::Path  create or remove a series of directories

       Getopt::Long
                   extended getopt processing

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

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

       IPC::Open2  a process for both reading and writing

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

       Net::Ping   check a host for upness

       POSIX       Perl interface to IEEE Std 1003.1

       SelfLoader  load functions only on demand

       Safe        Creation controlled compartments in which perl
                   code can be evaluated.

       Socket      load the C socket.h defines and structure
                   manipulators

       Test::Harness
                   run perl standard test scripts with statistics

       Text::Abbrev
                   rceate an abbreviation table from a list

       To find out _a_l_l the modules installed on your system,



2/Feb/96                 perl 5.002 with                        9





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


       including those without documentation or outside the
       standard release, do this:

           ffffiiiinnnndddd ````ppppeeeerrrrllll ----eeee ''''pppprrrriiiinnnntttt """"@@@@IIIINNNNCCCC""""''''```` ----nnnnaaaammmmeeee ''''****....ppppmmmm'''' ----pppprrrriiiinnnntttt

       They should all have their own documentation installed and
       accessible via your system _m_a_n(1) command.  If that fails,
       try the _p_e_r_l_d_o_c program.

       EEEExxxxtttteeeennnnssssiiiioooonnnn MMMMoooodddduuuulllleeeessss

       Extension modules are written in C (or a mix of Perl and
       C) and get dynamically loaded into Perl if and when you
       need them.  Supported extension modules include the
       Socket, Fcntl, and POSIX modules.

       Many popular C extension modules do not come bundled (at
       least, not completely) due to their size, 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
       _a_r_c_h_i_e(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.

CCCCPPPPAAAANNNN
       CPAN stands for the Comprehensive Perl Archive Network.
       This is a globally replicated collection of all known Perl
       materials, including hundreds of unbunded modules.  Here
       are the major categories of modules:

       +o Language Extensions and Documentation Tools

       +o Development Support

       +o Operating System Interfaces

       +o Networking, Device Control (modems) and InterProcess
            Communication

       +o Data Types and Data Type Utilities

       +o Database Interfaces

       +o User Interfaces

       +o Interfaces to / Emulations of Other Programming
            Languages

       +o File Names, File Systems and File Locking (see also File
            Handles)

       +o String Processing, Language Text Processing, Parsing and
            Searching



2/Feb/96                 perl 5.002 with                       10





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


       +o Option, Argument, Parameter and Configuration File
            Processing

       +o Internationalization and Locale

       +o Authentication, Security and Encryption

       +o World Wide Web, HTML, HTTP, CGI, MIME

       +o Server and Daemon Utilities

       +o Archiving and Compression

       +o Images, Pixmap and Bitmap Manipulation, Drawing and
            Graphing

       +o Mail and Usenet News

       +o Control Flow Utilities (callbacks and exceptions etc)

       +o File Handle and Input/Output Stream Utilities

       +o Miscellaneous Modules

       Some of the reguster CPAN sites as of this writing include
       the following.  You should try to choose one close to you:

       +o ftp://ftp.sterling.com/programming/languages/perl/

       +o ftp://ftp.sedl.org/pub/mirrors/CPAN/

       +o ftp://ftp.uoknor.edu/mirrors/CPAN/

       +o ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/

       +o ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/

       +o ftp://ftp.cis.ufl.edu/pub/perl/CPAN/

       +o ftp://ftp.switch.ch/mirror/CPAN/

       +o ftp://ftp.sunet.se/pub/lang/perl/CPAN/

       +o ftp://ftp.ci.uminho.pt/pub/lang/perl/

       +o ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/

       +o ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/

       +o ftp://ftp.rz.ruhr-uni-
            bochum.de/pub/programming/languages/perl/CPAN/

       +o
            ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/



2/Feb/96                 perl 5.002 with                       11





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


       +o ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/

       +o ftp://ftp.ibp.fr/pub/perl/CPAN/

       +o ftp://ftp.funet.fi/pub/languages/perl/CPAN/

       +o ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/

       +o ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/

       +o ftp://coombs.anu.edu.au/pub/perl/

       +o ftp://dongpo.math.ncu.edu.tw/perl/CPAN/

       +o ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/

       +o ftp://ftp.is.co.za/programming/perl/CPAN/

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

MMMMoooodddduuuulllleeeessss:::: CCCCrrrreeeeaaaattttiiiioooonnnn,,,, UUUUsssseeee aaaannnndddd AAAAbbbbuuuusssseeee
       (The following section is borrowed directly from Tim
       Bunce's modules file, available at your nearest CPAN
       site.)

       Perl 5 implements a class using a package, but the
       presence of a package doesn't imply the presence of a
       class.  A package is just a namespace.  A class is a
       package that provides subroutines that can be used as
       methods.  A method is just a subroutine that expects, as
       its first argument, either the name of a package (for
       "static" methods), or a reference to something (for
       "virtual" methods).

       A module is a file that (by convention) provides a class
       of the same name (sans the .pm), plus an import method in
       that class that can be called to fetch exported symbols.
       This module may implement some of its methods by loading
       dynamic C or C++ objects, but that should be totally
       transparent to the user of the module.  Likewise, the
       module might set up an AUTOLOAD function to slurp in
       subroutine definitions on demand, but this is also
       transparent.  Only the .pm file is required to exist.

       GGGGuuuuiiiiddddeeeelllliiiinnnneeeessss ffffoooorrrr MMMMoooodddduuuulllleeee CCCCrrrreeeeaaaattttiiiioooonnnn


       Do similar modules already exist in some form?
           If so, please try to reuse the existing modules either
           in whole or by inheriting useful features into a new
           class.  If this is not practical try to get together
           with the module authors to work on extending or
           enhancing the functionality of the existing modules.



2/Feb/96                 perl 5.002 with                       12





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


           A perfect example is the plethora of packages in perl4
           for dealing with command line options.

           If you are writing a module to expand an already
           existing set of modules, please coordinate with the
           author of the package.  It helps if you follow the
           same naming scheme and module interaction scheme as
           the original author.

       Try to design the new module to be easy to extend and
           reuse.
           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.:

            ssssuuuubbbb nnnneeeewwww {{{{
                   mmmmyyyy $$$$ccccllllaaaassssssss ==== sssshhhhiiiifffftttt;;;;
                   rrrreeeettttuuuurrrrnnnn bbbblllleeeessssssss {{{{}}}},,,, $$$$ccccllllaaaassssssss;;;;
            }}}}

           or even this if you'd like it to be used as either a
           static or a virtual method.

            ssssuuuubbbb nnnneeeewwww {{{{
                   mmmmyyyy $$$$sssseeeellllffff  ==== sssshhhhiiiifffftttt;;;;
                   mmmmyyyy $$$$ccccllllaaaassssssss ==== rrrreeeeffff(((($$$$sssseeeellllffff)))) |||||||| $$$$sssseeeellllffff;;;;
                   rrrreeeettttuuuurrrrnnnn bbbblllleeeessssssss {{{{}}}},,,, $$$$ccccllllaaaassssssss;;;;
            }}}}

           Pass arrays as references so more parameters can be
           added later (it's also faster).  Convert functions
           into methods where appropriate.  Split large methods
           into smaller more flexible ones.  Inherit methods from
           other modules if appropriate.

           Avoid class name tests like: die "Invalid" unless ref
           $$$$rrrreeeeffff eq 'FOO'.  Generally you can delete the "eq
           'FOO'" part with no harm at all.  Let the objects look
           after themselves! Generally, avoid hardwired class
           names as far as possible.

           Avoid $$$$rrrr->_C_l_a_s_s_:_:_f_u_n_c_(_) where using @@@@IIIISSSSAAAA=qw(... Class
           ...) and $$$$rrrr->_f_u_n_c_(_) would work (see perlbot man page
           for more details).

           Use autosplit so little used or newly added functions
           won't be a burden to programs which don't use them.
           Add test functions to the module after __END__ either
           using AutoSplit or by saying:

            eeeevvvvaaaallll jjjjooooiiiinnnn(((('''''''',,,,<<<<mmmmaaaaiiiinnnn::::::::DDDDAAAATTTTAAAA>>>>)))) |||||||| ddddiiiieeee $$$$@@@@ uuuunnnnlllleeeessssssss ccccaaaalllllllleeeerrrr(((())));;;;

           Does your module pass the 'empty sub-class' test? If
           you say "@SUBCLASS::ISA = _q_w(YOURCLASS);" your



2/Feb/96                 perl 5.002 with                       13





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


           applications should be able to use SUBCLASS in exactly
           the same way as YOURCLASS.  For example, does your
           application still work if you change:  $$$$oooobbbbjjjj = new
           YOURCLASS; into: $$$$oooobbbbjjjj = new SUBCLASS; ?

           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 ----wwww. Try to uuuusssseeee ssssttttrrrriiiicccctttt;;;; (or uuuusssseeee ssssttttrrrriiiicccctttt
           qqqqwwww((((............))));;;;).  Remember that you can add nnnnoooo ssssttttrrrriiiicccctttt
           qqqqwwww((((............))));;;; to individual blocks of code which need less
           strictness. Always use ----wwww. Always use ----wwww!  Follow the
           guidelines in the _p_e_r_l_s_t_y_l_e(1) manual.

       Some simple style guidelines
           The perlstyle manual supplied with perl has many
           helpful points.

           Coding style is a matter of personal taste. Many
           people evolve their style over several years as they
           learn what helps them write and maintain good code.
           Here's one set of assorted suggestions that seem to be
           widely used by experienced developers:

           Use underscores to separate words.  It is generally
           easier to read $$$$vvvvaaaarrrr____nnnnaaaammmmeeeessss____lllliiiikkkkeeee____tttthhhhiiiissss than
           $$$$VVVVaaaarrrrNNNNaaaammmmeeeessssLLLLiiiikkkkeeeeTTTThhhhiiiissss, especially for non-native speakers
           of English. It's also a simple rule that works
           consistently with VAR_NAMES_LIKE_THIS.

           Package/Module names are an exception to this rule.
           Perl informally reserves lowercase module names for
           'pragma' modules like integer and strict. Other
           modules normally begin with a capital letter and use
           mixed case with no underscores (need to be short and
           portable).

           You may find it helpful to use letter case to indicate
           the scope or nature of a variable. For example:

            $$$$AAAALLLLLLLL____CCCCAAAAPPPPSSSS____HHHHEEEERRRREEEE   ccccoooonnnnssssttttaaaannnnttttssss oooonnnnllllyyyy ((((bbbbeeeewwwwaaaarrrreeee ccccllllaaaasssshhhheeeessss wwwwiiiitttthhhh ppppeeeerrrrllll vvvvaaaarrrrssss))))
            $$$$SSSSoooommmmeeee____CCCCaaaappppssss____HHHHeeeerrrreeee  ppppaaaacccckkkkaaaaggggeeee----wwwwiiiiddddeeee gggglllloooobbbbaaaallll////ssssttttaaaattttiiiicccc
            $$$$nnnnoooo____ccccaaaappppssss____hhhheeeerrrreeee    ffffuuuunnnnccccttttiiiioooonnnn ssssccccooooppppeeee mmmmyyyy(((()))) oooorrrr llllooooccccaaaallll(((()))) vvvvaaaarrrriiiiaaaabbbblllleeeessss

           Function and method names seem to work best as all
           lowercase.  E.g., $$$$oooobbbbjjjj->_a_s___s_t_r_i_n_g_(_).

           You can use a leading underscore to indicate that a
           variable or function should not be used outside the
           package that defined it.

       Select what to export.
           Do NOT export method names!



2/Feb/96                 perl 5.002 with                       14





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


           Do NOT export anything else by default without a good
           reason!

           Exports pollute the namespace of the module user.  If
           you must export try to use @@@@EEEEXXXXPPPPOOOORRRRTTTT____OOOOKKKK in preference to
           @@@@EEEEXXXXPPPPOOOORRRRTTTT and avoid short or common names to reduce the
           risk of name clashes.

           Generally anything not exported is still accessible
           from outside the module using the
           ModuleName::item_name (or $$$$bbbblllleeeesssssssseeeedddd____rrrreeeeffff->method)
           syntax.  By convention you can use a leading
           underscore on names to informally indicate that they
           are 'internal' and not for public use.

           (It is actually possible to get private functions by
           saying: my $$$$ssssuuuubbbbrrrreeeeffff = sub { ... };  &$subref; But
           there's no way to call that directly as a method,
           since a method must have a name in the symbol table.)

           As a general rule, if the module is trying to be
           object oriented then export nothing. If it's just a
           collection of functions then @@@@EEEEXXXXPPPPOOOORRRRTTTT____OOOOKKKK anything but
           use @@@@EEEEXXXXPPPPOOOORRRRTTTT with caution.

       Select a name for the module.
           This name should be as descriptive, accurate and
           complete as possible.  Avoid any risk of ambiguity.
           Always try to use two or more whole words.  Generally
           the name should reflect what is special about what the
           module does rather than how it does it.  Please use
           nested module names to informally group or categorise
           a module.  A module should have a very good reason not
           to have a nested name.  Module names should begin with
           a capital letter.

           Having 57 modules all called Sort will not make life
           easy for anyone (though having 23 called Sort::Quick
           is only marginally better :-).  Imagine someone trying
           to install your module alongside many others.  If in
           any doubt ask for suggestions in comp.lang.perl.misc.

           If you are developing a suite of related
           modules/classes it's good practice to use nested
           classes with a common prefix as this will avoid
           namespace clashes. For example:  Xyz::Control,
           Xyz::View, Xyz::Model etc. Use the modules in this
           list as a naming guide.

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

           To be portable each component of a module name should



2/Feb/96                 perl 5.002 with                       15





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


           be limited to 11 characters. If it might be used on
           DOS then try to ensure each is unique in the first 8
           characters. Nested modules make this easier.

       Have you got it right?
           How do you know that you've made the right decisions?
           Have you picked an interface design that will cause
           problems later? Have you picked the most appropriate
           name? Do you have any questions?

           The best way to know for sure, and pick up many
           helpful suggestions, is to ask someone who knows.
           Comp.lang.perl.misc is read by just about all the
           people who develop modules and it's the best place to
           ask.

           All you need to do is post a short summary of the
           module, its purpose and interfaces. A few lines on
           each of the main methods is probably enough. (If you
           post the whole module it might be ignored by busy
           people - generally the very people you want to read
           it!)

           Don't worry about posting if you can't say when the
           module will be ready - just say so in the message. It
           might be worth inviting others to help you, they may
           be able to complete it for you!

       README and other Additional Files.
           It's well known that software developers usually fully
           document the software they write. If, however, the
           world is in urgent need of your software and there is
           not enough time to write the full documentation please
           at least provide a README file containing:

       +o A description of the module/package/extension etc.

       +o A copyright notice - see below.

       +o Prerequisites - what else you may need to have.

       +o How to build it - possible changes to Makefile.PL etc.

       +o How to install it.

       +o Recent changes in this release, especially
                     incompatibilities

       +o Changes / enhancements you plan to make in the future.

                     If the README file seems to be getting too
                     large you may wish to split out some of the
                     sections into separate files: INSTALL,
                     Copying, ToDo etc.



2/Feb/96                 perl 5.002 with                       16





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


       Adding a Copyright Notice.
           How you choose to licence your work is a personal
           decision.  The general mechanism is to assert your
           Copyright and then make a declaration of how others
           may copy/use/modify your work.

           Perl, for example, is supplied with two types of
           licence: The GNU GPL and The Artistic License (see the
           files README, Copying and Artistic).  Larry has good
           reasons for NOT just using the GNU GPL.

           My personal recommendation, out of respect for Larry,
           Perl and the perl community at large is to simply
           state something like:

            CCCCooooppppyyyyrrrriiiigggghhhhtttt ((((cccc)))) 1111999999995555 YYYYoooouuuurrrr NNNNaaaammmmeeee.... AAAAllllllll rrrriiiigggghhhhttttssss rrrreeeesssseeeerrrrvvvveeeedddd....
            TTTThhhhiiiissss pppprrrrooooggggrrrraaaammmm iiiissss ffffrrrreeeeeeee ssssooooffffttttwwwwaaaarrrreeee;;;; yyyyoooouuuu ccccaaaannnn rrrreeeeddddiiiissssttttrrrriiiibbbbuuuutttteeee iiiitttt aaaannnndddd////oooorrrr
            mmmmooooddddiiiiffffyyyy iiiitttt uuuunnnnddddeeeerrrr tttthhhheeee ssssaaaammmmeeee tttteeeerrrrmmmmssss aaaassss PPPPeeeerrrrllll iiiittttsssseeeellllffff....

           This statement should at least appear in the README
           file. You may also wish to include it in a Copying
           file and your source files.  Remember to include the
           other words in addition to the Copyright.

       Give the module a version/issue/release number.
           To be fully compatible with the Exporter and MakeMaker
           modules you should store your module's version number
           in a non-my package variable called $$$$VVVVEEEERRRRSSSSIIIIOOOONNNN.  This
           should be a valid floating point number with at least
           two digits after the decimal (ie hundredths, e.g,
           $$$$VVVVEEEERRRRSSSSIIIIOOOONNNN = "0.01").  Don't use a "1.3.2" style
           version.  See Exporter.pm in Perl5.001m or later for
           details.

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

       How to release and distribute a module.
           It's good idea to post an announcement of the
           availability of your module (or the module itself if
           small) to the comp.lang.perl.announce Usenet
           newsgroup.  This will at least ensure very wide once-
           off distribution.

           If possible you should place the module into a major
           ftp archive and include details of it's location in
           your announcement.

           Some notes about ftp archives: Please use a long
           descriptive file name which includes the version
           number. Most incoming directories will not be



2/Feb/96                 perl 5.002 with                       17





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


           readable/listable, i.e., you won't be able to see your
           file after uploading it. Remember to send your email
           notification message as soon as possible after
           uploading else your file may get deleted
           automatically. Allow time for the file to be processed
           and/or check the file has been processed before
           announcing its location.

           FTP Archives for Perl Modules:

           Follow the instructions and links on

              hhhhttttttttpppp::::////////ffffrrrraaaannnnzzzz....wwwwwwww....ttttuuuu----bbbbeeeerrrrlllliiiinnnn....ddddeeee////mmmmoooodddduuuulllleeeelllliiiisssstttt

           or upload to one of these sites:

              ffffttttpppp::::////////ffffrrrraaaannnnzzzz....wwwwwwww....ttttuuuu----bbbbeeeerrrrlllliiiinnnn....ddddeeee////iiiinnnnccccoooommmmiiiinnnngggg
              ffffttttpppp::::////////ffffttttpppp....cccciiiissss....uuuuffffllll....eeeedddduuuu////iiiinnnnccccoooommmmiiiinnnngggg

           and notify [e-mail].

           By using the WWW interface you can ask the Upload
           Server to mirror your modules from your ftp or WWW
           site into your own directory on CPAN!

           Please remember to send me an updated entry for the
           Module list!

       Take care when changing a released module.
           Always strive to remain compatible with previous
           released versions (see 2.2 above) Otherwise try to add
           a mechanism to revert to the old behaviour if people
           rely on it. Document incompatible changes.

       GGGGuuuuiiiiddddeeeelllliiiinnnneeeessss ffffoooorrrr CCCCoooonnnnvvvveeeerrrrttttiiiinnnngggg PPPPeeeerrrrllll 4444 LLLLiiiibbbbrrrraaaarrrryyyy SSSSccccrrrriiiippppttttssss iiiinnnnttttoooo
       MMMMoooodddduuuulllleeeessss


       There is no requirement to convert anything.
           If it ain't broke, don't fix it! Perl 4 library
           scripts should continue to work with no problems. You
           may need to make some minor changes (like escaping
           non-array @'s in double quoted strings) but there is
           no need to convert a .pl file into a Module for just
           that.

       Consider the implications.
           All the perl applications which make use of the script
           will need to be changed (slightly) if the script is
           converted into a module.  Is it worth it unless you
           plan to make other changes at the same time?

       Make the most of the opportunity.
           If you are going to convert the script to a module you



2/Feb/96                 perl 5.002 with                       18





PERLMOD(1)     User Contributed Perl Documentation     PERLMOD(1)


           can use the opportunity to redesign the interface. The
           'Guidelines for Module Creation' above include many of
           the issues you should consider.

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

       +o Adds the standard Module prologue lines

       +o Converts package specifiers from ' to ::

       +o Converts die(...) to croak(...)

       +o Several other minor changes

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

       GGGGuuuuiiiiddddeeeelllliiiinnnneeeessss ffffoooorrrr RRRReeeeuuuussssiiiinnnngggg AAAApppppppplllliiiiccccaaaattttiiiioooonnnn CCCCooooddddeeee


       Complete applications rarely belong in the Perl Module
           Library.

       Many applications contain some perl code which could be
           reused.
           Help save the world! Share your code in a form that
           makes it easy to reuse.

       Break-out the reusable code into one or more separate
           module files.

       Take the opportunity to reconsider and redesign the
           interfaces.

       In some cases the 'application' can then be reduced to a
           small
           fragment of code built on top of the reusable modules.
           In these cases the application could invoked as:

                ppppeeeerrrrllll ----eeee ''''uuuusssseeee MMMMoooodddduuuulllleeee::::::::NNNNaaaammmmeeee;;;; mmmmeeeetttthhhhoooodddd((((@@@@AAAARRRRGGGGVVVV))))'''' ............
           oooorrrr
                ppppeeeerrrrllll ----mmmmMMMMoooodddduuuulllleeee::::::::NNNNaaaammmmeeee ............    ((((iiiinnnn ppppeeeerrrrllll5555....000000002222????))))









2/Feb/96                 perl 5.002 with                       19