NAME
    perlmodlib - constructing new Perl modules and finding existing
    ones

DESCRIPTION
THE PERL MODULE LIBRARY
    A number of modules are included the Perl distribution. These
    are described below, and all end in .pm. You may also discover
    files in the library directory that end in either .pl or .ph.
    These are old libraries supplied so that old programs that use
    them still run. The .pl files will all eventually be converted
    into standard modules, and the .ph files made by h2ph will
    probably end up as extension modules made by h2xs. (Some .ph
    values may already be available through the POSIX module.) The
    pl2pm file in the distribution may help in your conversion, but
    it's just a mechanical process and therefore far from
    bulletproof.

  Pragmatic Modules

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

        no integer;
        no strict 'refs';


    which lasts until the end of that BLOCK.

    Unlike the pragmas that effect the `$^H' hints variable, the
    `use vars' and `use subs' declarations are not BLOCK-scoped.
    They allow you to predeclare a variables or subroutines within a
    particular *file* rather than just a block. Such declarations
    are effective for the entire file for which they were declared.
    You cannot rescind them with `no vars' or `no subs'.

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

    use autouse MODULE => qw(sub1 sub2 sub3)
                Defers `require MODULE' until someone calls one of
                the specified subroutines (which must be exported by
                MODULE). This pragma should be used with caution,
                and only when necessary.

    blib        manipulate @INC at compile time to use MakeMaker's
                uninstalled version of a package

    diagnostics force verbose warning diagnostics

    integer     compute arithmetic in integer instead of double

    less        request less of something from the compiler

    lib         manipulate @INC at compile time

    locale      use or ignore current locale for builtin operations (see
                the perllocale manpage)

    ops         restrict named opcodes when compiling or running Perl
                code

    overload    overload basic Perl operations

    re          alter behaviour of regular expressions

    sigtrap     enable simple signal handling

    strict      restrict unsafe constructs

    subs        predeclare sub names

    vmsish      adopt certain VMS-specific behaviors

    vars        predeclare global variable names


  Standard Modules

    Standard, bundled modules are all expected to behave in a well-
    defined manner with respect to namespace pollution because they
    use the Exporter module. See their own 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

    CPAN        interface to Comprehensive Perl Archive Network

    CPAN::FirstTime
                create a CPAN configuration file

    CPAN::Nox   run CPAN while avoiding compiled extensions

    Carp        warn of errors (from perspective of caller)

    Class::Struct
                declare struct-like datatypes

    Config      access Perl configuration information

    Cwd         get pathname of current working directory

    DB_File     access to Berkeley DB

    Devel::SelfStubber
                generate stubs for a SelfLoading module

    DirHandle   supply object methods for directory handles

    DynaLoader  dynamically load C libraries into Perl code

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

    Env         import environment variables

    Exporter    implements default import method for modules

    ExtUtils::Embed
                utilities for embedding Perl in C/C++ applications

    ExtUtils::Install
                install files from here to there

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

    ExtUtils::MM_OS2
                methods to override Unix behaviour in
                ExtUtils::MakeMaker

    ExtUtils::MM_Unix
                methods used by ExtUtils::MakeMaker

    ExtUtils::MM_VMS
                methods to override Unix behaviour in
                ExtUtils::MakeMaker

    ExtUtils::MakeMaker
                create an extension Makefile

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

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

    ExtUtils::Mksymlists
                write linker options files for dynamic extension

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

    Fatal       make errors in builtins or Perl functions fatal

    Fcntl       load the C Fcntl.h defines

    File::Basename
                split a pathname into pieces

    File::CheckTree
                run many filetest checks on a tree

    File::Compare
                compare files or filehandles

    File::Copy  copy files or filehandles

    File::Find  traverse a file tree

    File::Path  create or remove a series of directories

    File::stat  by-name interface to Perl's builtin stat() functions

    FileCache   keep more files open than the system permits

    FileHandle  supply object methods for filehandles

    FindBin     locate directory of original Perl script

    GDBM_File   access to the gdbm library

    Getopt::Long
                extended processing of command line options

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

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

    IO          load various IO modules

    IO::File    supply object methods for filehandles

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

    IO::Pipe    supply object methods for pipes

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

    IO::Select  OO interface to the select system call

    IO::Socket  object interface to socket communications

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

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

    Math::BigFloat
                arbitrary length float math package

    Math::BigInt
                arbitrary size integer math package

    Math::Complex
                complex numbers and associated mathematical
                functions

    Math::Trig  simple interface to parts of Math::Complex for those who
                need trigonometric functions only for real numbers

    NDBM_File   tied access to ndbm files

    Net::Ping   Hello, anybody home?

    Net::hostent
                by-name interface to Perl's builtin gethost*()
                functions

    Net::netent by-name interface to Perl's builtin getnet*() functions

    Net::protoent
                by-name interface to Perl's builtin getproto*()
                functions

    Net::servent
                by-name interface to Perl's builtin getserv*()
                functions

    Opcode      disable named opcodes when compiling or running Perl
                code

    Pod::Text   convert POD data to formatted ASCII text

    POSIX       interface to IEEE Standard 1003.1

    SDBM_File   tied access to sdbm files

    Safe        compile and execute code in restricted compartments

    Search::Dict
                search for key in dictionary file

    SelectSaver save and restore selected file handle

    SelfLoader  load functions only on demand

    Shell       run shell commands transparently within Perl

    Socket      load the C socket.h defines and structure manipulators

    Symbol      manipulate Perl symbols and their names

    Sys::Hostname
                try every conceivable way to get hostname

    Sys::Syslog interface to the Unix syslog(3) calls

    Term::Cap   termcap interface

    Term::Complete
                word completion module

    Term::ReadLine
                interface to various `readline' packages

    Test::Harness
                run Perl standard test scripts with statistics

    Text::Abbrev
                create an abbreviation table from a list

    Text::ParseWords
                parse text into an array of tokens

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

    Text::Tabs  expand and unexpand tabs per the Unix expand(1) and
                unexpand(1)

    Text::Wrap  line wrapping to form simple paragraphs

    Tie::Hash   base class definitions for tied hashes

    Tie::RefHash
                base class definitions for tied hashes with
                references as keys

    Tie::Scalar base class definitions for tied scalars

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

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

    Time::gmtime
                by-name interface to Perl's builtin gmtime()
                function

    Time::localtime
                by-name interface to Perl's builtin localtime()
                function

    Time::tm    internal object used by Time::gmtime and Time::localtime

    UNIVERSAL   base class for ALL classes (blessed references)

    User::grent by-name interface to Perl's builtin getgr*() functions

    User::pwent by-name interface to Perl's builtin getpw*() functions


    To find out *all* the modules installed on your system,
    including those without documentation or outside the standard
    release, do this:

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


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

  Extension Modules

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

    Many popular C extension modules do not come bundled (at least,
    not completely) due to their sizes, volatility, or simply lack
    of time for adequate testing and configuration across the
    multitude of platforms on which Perl was beta-tested. You are
    encouraged to look for them in archie(1L), the Perl FAQ or Meta-
    FAQ, the WWW page, and even with their authors before randomly
    posting asking for their present condition and disposition.

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

    *
    Language Extensions and Documentation Tools

    *
    Development Support

    *
    Operating System Interfaces

    *
    Networking, Device Control (modems) and InterProcess Communication

    *
    Data Types and Data Type Utilities

    *
    Database Interfaces

    *
    User Interfaces

    *
    Interfaces to / Emulations of Other Programming Languages

    *
    File Names, File Systems and File Locking (see also File Handles)

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

    *
    Option, Argument, Parameter, and Configuration File Processing

    *
    Internationalization and Locale

    *
    Authentication, Security, and Encryption

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

    *
    Server and Daemon Utilities

    *
    Archiving and Compression

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

    *
    Mail and Usenet News

    *
    Control Flow Utilities (callbacks and exceptions etc)

    *
    File Handle and Input/Output Stream Utilities

    *
    Miscellaneous Modules


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

    *
    Africa

            South Africa    ftp://ftp.is.co.za/programming/perl/CPAN/


    *
    Asia

            Hong Kong       ftp://ftp.hkstar.com/pub/CPAN/
            Japan           ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
                            ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
            South Korea     ftp://ftp.nuri.net/pub/CPAN/
            Taiwan          ftp://dongpo.math.ncu.edu.tw/perl/CPAN/
                            ftp://ftp.wownet.net/pub2/PERL/


    *
    Australasia

            Australia       ftp://ftp.netinfo.com.au/pub/perl/CPAN/
            New Zealand     ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/


    *
    Europe

            Austria         ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
            Belgium         ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
            Czech Republic  ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
            Denmark         ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
            Finland         ftp://ftp.funet.fi/pub/languages/perl/CPAN/
            France          ftp://ftp.ibp.fr/pub/perl/CPAN/
                            ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
            Germany         ftp://ftp.gmd.de/packages/CPAN/
                            ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/
                            ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
                            ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
                            ftp://ftp.uni-erlangen.de/pub/source/Perl/CPAN/
                            ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
            Greece          ftp://ftp.ntua.gr/pub/lang/perl/
            Hungary         ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
            Italy           ftp://cis.utovrm.it/CPAN/
            the Netherlands ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
                            ftp://ftp.EU.net/packages/cpan/
            Norway          ftp://ftp.uit.no/pub/languages/perl/cpan/
            Poland          ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
                            ftp://sunsite.icm.edu.pl/pub/CPAN/
            Portugal        ftp://ftp.ci.uminho.pt/pub/lang/perl/
                            ftp://ftp.telepac.pt/pub/CPAN/
            Russia          ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
            Slovenia        ftp://ftp.arnes.si/software/perl/CPAN/
            Spain           ftp://ftp.etse.urv.es/pub/mirror/perl/
                            ftp://ftp.rediris.es/mirror/CPAN/
            Sweden          ftp://ftp.sunet.se/pub/lang/perl/CPAN/
            UK              ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
                            ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
                            ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/


    *
    North America

            Ontario         ftp://ftp.utilis.com/public/CPAN/
                            ftp://enterprise.ic.gc.ca/pub/perl/CPAN/
            Manitoba        ftp://theory.uwinnipeg.ca/pub/CPAN/
            California      ftp://ftp.digital.com/pub/plan/perl/CPAN/
                            ftp://ftp.cdrom.com/pub/perl/CPAN/
            Colorado        ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
            Florida         ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
            Illinois        ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
            Massachusetts   ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
            New York        ftp://ftp.rge.com/pub/languages/perl/
            North Carolina  ftp://ftp.duke.edu/pub/perl/
            Oklahoma        ftp://ftp.ou.edu/mirrors/CPAN/
            Oregon          http://www.perl.org/CPAN/
                            ftp://ftp.orst.edu/pub/packages/CPAN/
            Pennsylvania    ftp://ftp.epix.net/pub/languages/perl/
            Texas           ftp://ftp.sedl.org/pub/mirrors/CPAN/
                            ftp://ftp.metronet.com/pub/perl/


    *
    South America

            Chile           ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/


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

Modules: Creation, Use, and Abuse
    (The following section is borrowed directly from Tim Bunce's
    modules file, available at your nearest CPAN site.)

    Perl implements a class using a package, but the presence of a
    package doesn't imply the presence of a class. A package is just
    a namespace. A class is a package that provides subroutines that
    can be used as methods. A method is just a subroutine that
    expects, as its first argument, either the name of a package
    (for "static" 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. See
    the perlsub manpage, the perltoot manpage, and the AutoLoader
    manpage for details about the AUTOLOAD mechanism.

  Guidelines for Module Creation

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

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

    Try to design the new module to be easy to extend and reuse.
        Use blessed references. Use the two argument form of bless
        to bless into the class name given as the first parameter of
        the constructor, e.g.,:

         sub new {
        	my $class = shift;
        	return bless {}, $class;
         }


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

         sub new {
        	my $self  = shift;
        	my $class = ref($self) || $self;
        	return bless {}, $class;
         }


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

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

        Avoid `$r->Class::func()' where using `@ISA=qw(... Class
        ...)' and `$r->func()' would work (see the perlbot manpage
        for more details).

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

         eval join('',<main::DATA>) || die $@ unless caller();


        Does your module pass the 'empty subclass' test? If you say
        "`@SUBCLASS::ISA = qw(YOURCLASS);'" your applications should
        be able to use SUBCLASS in exactly the same way as
        YOURCLASS. For example, does your application still work if
        you change: `$obj = new YOURCLASS;' into: `$obj = 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 -w. Try to `use strict;' (or `use strict
        qw(...);'). Remember that you can add `no strict qw(...);'
        to individual blocks of code that need less strictness.
        Always use -w. Always use -w! Follow the guidelines in the
        perlstyle(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 $var_names_like_this than $VarNamesLikeThis, 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:

         $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
         $Some_Caps_Here  package-wide global/static
         $no_caps_here    function scope my() or local() variables


        Function and method names seem to work best as all
        lowercase. e.g., `$obj->as_string()'.

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

    Select what to export.
        Do NOT export method names!

        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 @EXPORT_OK in preference to @EXPORT
        and avoid short or common names to reduce the risk of name
        clashes.

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

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

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

    Select a name for the module.
        This name should be as descriptive, accurate, and 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 group
        informally or categorize a module. There should be a very
        good reason for a module not to have a nested name. Module
        names should begin with a capital letter.

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

        If you are developing a suite of related 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 be
        limited to 11 characters. If it might be used on MS-DOS then
        try to ensure each is unique in the first 8 characters.
        Nested modules make this easier.

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

        The best way to know for sure, and pick up many 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:

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

    *
    A copyright notice - see below.

    *
    Prerequisites - what else you may need to have.

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

    *
    How to install it.

    *
    Recent changes in this release, especially incompatibilities

    *
    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.

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

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

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

             Copyright (c) 1995 Your Name. All rights reserved.
             This program is free software; you can redistribute it and/or
             modify it under the same terms as Perl itself.


            This statement should at least appear in the README
            file. You may also wish to include it in a Copying file
            and your source files. Remember to include the other
            words in addition to the 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 $VERSION. This should
            be a floating point number with at least two digits
            after the decimal (i.e., hundredths, e.g, `$VERSION =
            "0.01"'). Don't use a "1.3.2" style version. See
            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 its location in your
            announcement.

            Some notes about ftp archives: Please use a long
            descriptive file name that includes the version number.
            Most incoming directories will not be readable/listable,
            i.e., you won't be able to see your file after uploading
            it. Remember to send your email notification message as
            soon as 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

               http://franz.ww.tu-berlin.de/modulelist


            or upload to one of these sites:

               ftp://franz.ww.tu-berlin.de/incoming
               ftp://ftp.cis.ufl.edu/incoming


            and notify <upload@franz.ww.tu-berlin.de>.

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

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

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


  Guidelines for Converting Perl 4 Library Scripts into Modules

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

    Consider the implications.
        All Perl applications that make use of the script will need
        to be changed (slightly) if the script is 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 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:

    *
    Adds the standard Module prologue lines

    *
    Converts package specifiers from ' to ::

    *
    Converts die(...) to croak(...)

    *
    Several other minor changes


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


  Guidelines for Reusing Application Code

    Complete applications rarely belong in the Perl Module Library.

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

    Break-out the reusable code into one or more separate 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:

             % perl -e 'use Module::Name; method(@ARGV)' ...
        or
             % perl -mModule::Name ...    (in perl5.002 or higher)


NOTE
    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 (A.K.A.
    documentation) may make other provisions. But then you know when
    you `use RedefineTheWorld' that you're redefining the world and
    willing to take the consequences.

