Dream 52/Amiga_Dream_52.iso/RiscOS/APP/DEVS/PERL/RPC106.ZIP/Rpc106/Docs/perlmodlib

Text File | 1997-11-23 | 30KB | 877 lines

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

    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

    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 which 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 which 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 which 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 <[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.

  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 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 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 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:

         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.