1N/Aperlmodlib - constructing new Perl modules and finding existing ones
1N/A=head1 THE PERL MODULE LIBRARY
1N/AMany modules are included in the Perl distribution. These are described
1N/Abelow, and all end in F<.pm>. You may discover compiled library
1N/Afiles (usually ending in F<.so>) or small pieces of modules to be
1N/Aautoloaded (ending in F<.al>); these were automatically generated
1N/Aby the installation process. You may also discover files in the
1N/Alibrary directory that end in either F<.pl> or F<.ph>. These are
1N/Aold libraries supplied so that old programs that use them still
1N/Arun. The F<.pl> files will all eventually be converted into standard
1N/Amodules, and the F<.ph> files made by B<h2ph> will probably end up
1N/Aas extension modules made by B<h2xs>. (Some F<.ph> values may
1N/Aalready be available through the POSIX, Errno, or Fcntl modules.)
1N/AThe B<pl2pm> file in the distribution may help in your conversion,
1N/Abut it's just a mechanical process and therefore far from bulletproof.
1N/A=head2 Pragmatic Modules
1N/AThey work somewhat like compiler directives (pragmata) in that they
1N/Atend to affect the compilation of your program, and thus will usually
1N/Awork well only when used within a C<use>, or C<no>. Most of these
1N/Aare lexically scoped, so an inner BLOCK may countermand them
1N/Awhich lasts until the end of that BLOCK.
1N/ASome pragmas are lexically scoped--typically those that affect the
1N/AC<$^H> hints variable. Others affect the current package instead,
1N/Alike C<use vars> and C<use subs>, which allow you to predeclare a
1N/Avariables or subroutines within a particular I<file> rather than
1N/Ajust a block. Such declarations are effective for the entire file
1N/Afor which they were declared. You cannot rescind them with C<no
1N/AThe following pragmas are defined (and have their own documentation).
1N/APostpone load of modules until a function is used
1N/AEstablish IS-A relationship with base class at compile time
1N/ATransparent BigInteger support for Perl
1N/ATransparent BigNumber support for Perl
1N/AUse MakeMaker's uninstalled version of a package
1N/AForce byte semantics rather than character semantics
1N/ADefine character names for C<\N{named}> string literal escapes
1N/AProduce verbose warning diagnostics
1N/AAllows you to write your script in non-ascii or non-utf8
1N/ACompile-time class fields
1N/AControl the filetest permission operators
1N/AC<use> a Perl module if a condition holds
1N/AUse integer arithmetic instead of floating point
1N/ARequest less of something from the compiler
1N/AManipulate @INC at compile time
1N/AUse and avoid POSIX locales for built-in operations
1N/ASet default PerlIO layers for input and output
1N/ARestrict unsafe operations when compiling
1N/APackage for overloading perl operations
1N/AAlter regular expression behaviour
1N/AEnable simple signal handling
1N/AControl sort() behaviour
1N/ARestrict unsafe constructs
1N/APerl extension allowing use of interpreter based threads from perl
1N/A=item threads::shared
1N/APerl extension for sharing data structures between threads
1N/APredeclare global variable names (obsolete)
1N/AControl VMS-specific language features
1N/AControl optional warnings
1N/A=item warnings::register
1N/AWarnings import function
1N/A=head2 Standard Modules
1N/AStandard, bundled modules are all expected to behave in a well-defined
1N/Amanner with respect to namespace pollution because they use the
1N/AExporter module. See their own documentation for details.
1N/AIt's possible that not all modules listed below are installed on your
1N/Asystem. For example, the GDBM_File module will not be installed if you
1N/Adon't have the gdbm library.
1N/AProvide framework for multiple DBMs
1N/A=item Attribute::Handlers
1N/ASimpler definition of attribute handlers
1N/ALoad subroutines only on demand
1N/ASplit a package for autoloading
1N/AAutogenerated data about Perl ops, used to generate bytecode
1N/AAssemble Perl bytecode
1N/APerl compiler's bytecode backend
1N/APerl compiler's C backend
1N/APerl compiler's optimized C translation backend
1N/AWalk Perl syntax tree, printing concise info about ops
1N/AWalk Perl syntax tree, printing debug info about ops
1N/APerl compiler backend to produce perl code
1N/A=item B::Disassembler
1N/ADisassemble Perl bytecode
1N/AShow lexical variables used in functions or files
1N/AHelper module for CC backend
1N/AShow what stashes are loaded
1N/AWalk Perl syntax tree, printing terse info about ops
1N/AGenerates cross reference reports for Perl programs
1N/ABenchmark running times of Perl code
1N/ALoad byte compiled perl code
1N/ASimple Common Gateway Interface Class
1N/ACGI routines for writing to the HTTPD (or other) error log
1N/AInterface to Netscape Cookies
1N/ACGI Interface for Fast CGI
1N/AModule to produce nicely formatted HTML code
1N/ASimple Interface to Server Push
1N/ABackward compatibility module for defunct CGI::Switch
1N/AInternal utilities used by CGI module
1N/AQuery, download and build perl modules from CPAN sites
1N/A=item CPAN::FirstTime
1N/AUtility for CPAN::Config file Initialization
1N/AWarn of errors (from perspective of caller)
1N/ANo user serviceable parts inside
1N/AReport the search path for a class's ISA tree
1N/ADeclare struct-like datatypes as Perl classes
1N/AAccess Perl configuration information
1N/AGet pathname of current working directory
1N/AProgrammatic interface to the Perl debugging API (draft, subject to
1N/APerl5 access to Berkeley DB version
1.x 1N/AStringified perl data structures, suitable for both printing and C<eval>
1N/AA data debugging tool for the XS programmer
1N/A=item Devel::SelfStubber
1N/AGenerate stubs for a SelfLoading module
1N/AModules that calculate message digests
1N/APerl interface to the MD5 Algorithm
1N/ASupply object methods for directory handles
1N/AProvides screen dump of Perl data.
1N/ADynamically load C libraries into Perl code
1N/AAlias definitions to encodings
1N/ASingle Byte Encodings
1N/A=item Encode::CJKConstants
1N/AInternally used by Encode::??::ISO_2022_*
1N/AChina-based Chinese Encodings
1N/AInternally used by Encode::CN
1N/AInternally used by Encode
1N/A=item Encode::Encoder
1N/AObject Oriented Encoder
1N/A=item Encode::Encoding
1N/AEncode Implementation Base Class
1N/AGuesses encoding from data
1N/A=item Encode::JP::H2Z
1N/AInternally used by Encode::JP::2022_JP*
1N/A=item Encode::JP::JIS7
1N/AInternally used by Encode::JP
1N/A=item Encode::KR::2022_KR
1N/AInternally used by Encode::KR
1N/A=item Encode::MIME::Header
1N/AMIME 'B' and 'Q' header encoding
1N/AA detailed document on Encode and PerlIO
1N/A=item Encode::Supported
1N/AEncodings supported by Encode
1N/ATaiwan-based Chinese Encodings
1N/A=item Encode::Unicode
1N/AVarious Unicode Transformation Formats
1N/A=item Encode::Unicode::UTF7
1N/AUse nice English (or awk) names for ugly punctuation variables
1N/APerl module that imports environment variables as scalars or arrays
1N/ASystem errno constants
1N/AImplements default import method for modules
1N/A=item Exporter::Heavy
1N/A=item ExtUtils::Command
1N/AUtilities to replace common UNIX commands in Makefiles etc.
1N/A=item ExtUtils::Command::MM
1N/ACommands for the MM's to use in Makefiles
1N/A=item ExtUtils::Constant
1N/AGenerate XS code to import C header constants
1N/A=item ExtUtils::Embed
1N/AUtilities for embedding Perl in C/C++ applications
1N/A=item ExtUtils::Install
1N/AInstall files from here to there
1N/A=item ExtUtils::Installed
1N/AInventory management of installed modules
1N/A=item ExtUtils::Liblist
1N/ADetermine libraries to use and how to use them
1N/AOS adjusted ExtUtils::MakeMaker subclass
1N/A=item ExtUtils::MM_Any
1N/APlatform-agnostic MM methods
1N/A=item ExtUtils::MM_BeOS
1N/AMethods to override UN*X behaviour in ExtUtils::MakeMaker
1N/A=item ExtUtils::MM_Cygwin
1N/AMethods to override UN*X behaviour in ExtUtils::MakeMaker
1N/A=item ExtUtils::MM_DOS
1N/ADOS specific subclass of ExtUtils::MM_Unix
1N/A=item ExtUtils::MM_MacOS
1N/AMethods to override UN*X behaviour in ExtUtils::MakeMaker
1N/A=item ExtUtils::MM_NW5
1N/AMethods to override UN*X behaviour in ExtUtils::MakeMaker
1N/A=item ExtUtils::MM_OS2
1N/AMethods to override UN*X behaviour in ExtUtils::MakeMaker
1N/A=item ExtUtils::MM_UWIN
1N/AU/WIN specific subclass of ExtUtils::MM_Unix
1N/A=item ExtUtils::MM_Unix
1N/AMethods used by ExtUtils::MakeMaker
1N/A=item ExtUtils::MM_VMS
1N/AMethods to override UN*X behaviour in ExtUtils::MakeMaker
1N/A=item ExtUtils::MM_Win32
1N/AMethods to override UN*X behaviour in ExtUtils::MakeMaker
1N/A=item ExtUtils::MM_Win95
1N/AMethod to customize MakeMaker for Win9X
1N/AExtUtils::MakeMaker subclass for customization
1N/A=item ExtUtils::MakeMaker
1N/ACreate a module Makefile
1N/A=item ExtUtils::MakeMaker::FAQ
1N/AFrequently Asked Questions About MakeMaker
1N/A=item ExtUtils::MakeMaker::Tutorial
1N/AWriting a module with MakeMaker
1N/A=item ExtUtils::MakeMaker::bytes
1N/A=item ExtUtils::MakeMaker::vmsish
1N/A=item ExtUtils::Manifest
1N/AUtilities to write and check a MANIFEST file
1N/A=item ExtUtils::Mkbootstrap
1N/AMake a bootstrap file for use by DynaLoader
1N/A=item ExtUtils::Mksymlists
1N/AWrite linker options files for dynamic extension
1N/A=item ExtUtils::Packlist
1N/AManage .packlist files
1N/A=item ExtUtils::testlib
1N/AAdd blib/* directories to @INC
1N/AReplace functions with equivalents which succeed or die
1N/ASplit a pathname into pieces
1N/A=item File::CheckTree
1N/ARun many filetest checks on a tree
1N/ACompare files or filehandles
1N/ACopy files or filehandles
1N/ADOS like globbing and then some
1N/ATraverse a directory tree.
1N/APerl extension for BSD glob routine
1N/ACreate or remove directory trees
1N/APortably perform operations on file names
1N/A=item File::Spec::Cygwin
1N/AMethods for Cygwin file specs
1N/A=item File::Spec::Epoc
1N/AMethods for Epoc file specs
1N/A=item File::Spec::Functions
1N/APortably perform operations on file names
1N/A=item File::Spec::Mac
1N/AFile::Spec for Mac OS (Classic)
1N/A=item File::Spec::OS2
1N/AMethods for OS/2 file specs
1N/A=item File::Spec::Unix
1N/AFile::Spec for Unix, base for other File::Spec modules
1N/A=item File::Spec::VMS
1N/AMethods for VMS file specs
1N/A=item File::Spec::Win32
1N/AMethods for Win32 file specs
1N/AReturn name and handle of a temporary file safely
1N/ABy-name interface to Perl's built-in stat() functions
1N/AKeep more files open than the system permits
1N/ASupply object methods for filehandles
1N/ASimplified source filtering
1N/A=item Filter::Util::Call
1N/APerl Source Filter Utility Module
1N/ALocate directory of original perl script
1N/APerl5 access to the gdbm library.
1N/AExtended processing of command line options
1N/AProcess single-character switches with switch clustering
1N/AA selection of general-utility hash subroutines
1N/ACompare 8-bit scalar data according to the current locale
1N/AFunctions for dealing with RFC3066-style language tags
1N/A=item I18N::LangTags::List
1N/ATags and names for human languages
1N/AQuery locale information
1N/ALoad various IO modules
1N/ASupply object methods for directory handles
1N/ASupply object methods for filehandles
1N/ASupply object methods for I/O handles
1N/ASupply object methods for pipes
1N/AObject interface to system poll call
1N/ASupply seek based methods for I/O objects
1N/AOO interface to the select system call
1N/AObject interface to socket communications
1N/A=item IO::Socket::INET
1N/AObject interface for AF_INET domain sockets
1N/A=item IO::Socket::UNIX
1N/AObject interface for AF_UNIX domain sockets
1N/AOpen a process for both reading and writing
1N/AOpen a process for reading, writing, and error handling
1N/ASysV Msg IPC object class
1N/A=item IPC::SysV::Semaphore
1N/ASysV Semaphore IPC object class
1N/AA selection of general-utility list subroutines
1N/A=item Locale::Constants
1N/AConstants for Locale codes
1N/A=item Locale::Country
1N/AISO codes for country identification (ISO 3166)
1N/A=item Locale::Currency
1N/AISO three letter codes for currency identification (ISO 4217)
1N/A=item Locale::Language
1N/AISO two letter codes for language identification (ISO 639)
1N/A=item Locale::Maketext
1N/AFramework for localization
1N/A=item Locale::Maketext::TPJ13
1N/AArticle about software localization
1N/AISO codes for script identification (ISO 15924)
1N/AEncoding and decoding of base64 strings
1N/A=item MIME::Base64::QuotedPrint
1N/AEncoding and decoding of quoted-printable strings
1N/AArbitrary size floating point math package
1N/AArbitrary size integer math package
1N/A=item Math::BigInt::Calc
1N/APure Perl module to support Math::BigInt
1N/AArbitrarily big rationals
1N/AComplex numbers and associated mathematical functions
1N/ATrigonometric functions
1N/AMake functions faster by trading space for time
1N/A=item Memoize::AnyDBM_File
1N/AGlue to provide EXISTS for AnyDBM_File for Storable use
1N/A=item Memoize::Expire
1N/APlug-in module for automatic expiration of memoized values
1N/A=item Memoize::ExpireFile
1N/ATest for Memoize expiration semantics
1N/A=item Memoize::ExpireTest
1N/ATest for Memoize expiration semantics
1N/A=item Memoize::NDBM_File
1N/AGlue to provide EXISTS for NDBM_File for Storable use
1N/A=item Memoize::SDBM_File
1N/AGlue to provide EXISTS for SDBM_File for Storable use
1N/A=item Memoize::Storable
1N/AStore Memoized data in Storable database
1N/ATied access to ndbm files
1N/AProvide a pseudo-class NEXT (et al) that allows method redispatch
1N/ANetwork Command class (as used by FTP, SMTP etc)
1N/ALocal configuration data for libnet
1N/AAttempt to evaluate the current host's internet name and domain
1N/AOO interface to users netrc file
1N/APost Office Protocol 3 Client class (RFC1939)
1N/ACheck a remote host for reachability
1N/ASimple Mail Transfer Protocol Client
1N/ATime and daytime network client interface
1N/ABy-name interface to Perl's built-in gethost*() functions
1N/ALibnet Frequently Asked Questions
1N/ABy-name interface to Perl's built-in getnet*() functions
1N/ABy-name interface to Perl's built-in getproto*() functions
1N/ABy-name interface to Perl's built-in getserv*() functions
1N/AGeneric interface to Perl Compiler backends
1N/ATied access to odbm files
1N/ADisable named opcodes when compiling perl code
1N/APerl interface to IEEE Std 1003.1
1N/AOn demand loader for PerlIO layers and root of PerlIO::* name space
1N/A=item PerlIO::encoding
1N/AIn-memory IO, scalar IO
1N/AHelper class for PerlIO layers implemented in perl
1N/A=item PerlIO::via::QuotedPrint
1N/APerlIO layer for quoted-printable strings
1N/ACheck pod documents for syntax errors
1N/AFind POD documents in directory trees
1N/AModule to convert pod files to HTML
1N/A=item Pod::InputObjects
1N/AObjects representing POD input paragraphs, commands, etc.
1N/AConvert Pod data to formatted Latex
1N/AConvert POD data to formatted *roff input
1N/AParse an LE<lt>E<gt> formatting code in POD text
1N/A=item Pod::ParseUtils
1N/AHelpers for POD parsing and conversion
1N/ABase class for creating POD filters and translators
1N/A=item Pod::Perldoc::ToChecker
1N/ALet Perldoc check Pod for errors
1N/A=item Pod::Perldoc::ToMan
1N/ALet Perldoc render Pod as man pages
1N/A=item Pod::Perldoc::ToNroff
1N/ALet Perldoc convert Pod to nroff
1N/A=item Pod::Perldoc::ToPod
1N/ALet Perldoc render Pod as ... Pod!
1N/A=item Pod::Perldoc::ToRtf
1N/ALet Perldoc render Pod as RTF
1N/A=item Pod::Perldoc::ToText
1N/ALet Perldoc render Pod as plaintext
1N/A=item Pod::Perldoc::ToTk
1N/ALet Perldoc use Tk::Pod to render Pod
1N/A=item Pod::Perldoc::ToXml
1N/ALet Perldoc render Pod as XML
1N/AConvert POD data to formatted ASCII text
1N/APerl extension for converting Pod to old style Pod.
1N/AExtract selected sections of POD from input
1N/AConvert POD data to formatted ASCII text
1N/A=item Pod::Text::Color
1N/AConvert POD data to formatted color ASCII text
1N/A=item Pod::Text::Overstrike
1N/AConvert POD data to formatted overstrike text
1N/A=item Pod::Text::Termcap
1N/AConvert POD data to ASCII text with format escapes
1N/APrint a usage message from embedded pod documentation
1N/ATied access to sdbm files
1N/ACompile and execute code in restricted compartments
1N/AA selection of general-utility scalar subroutines
1N/ASearch for key in dictionary file
1N/ASave and restore selected file handle
1N/ALoad functions only on demand
1N/ARun shell commands transparently within perl
1N/APersistence for Perl data structures
1N/AA switch statement for Perl
1N/AManipulate Perl symbols and their names
1N/ATry every conceivable way to get hostname
1N/APerl interface to the UNIX syslog(3) calls
1N/A=item Term::ANSIColor
1N/AColor screen output using ANSI escape sequences
1N/APerl termcap interface
1N/APerl word completion module
1N/APerl interface to various C<readline> packages.
1N/AProvides a simple framework for writing test scripts
1N/ABackend for building test libraries
1N/ARun Perl standard test scripts with statistics
1N/A=item Test::Harness::Assert
1N/A=item Test::Harness::Iterator
1N/AInternal Test::Harness Iterator
1N/A=item Test::Harness::Straps
1N/ADetailed analysis of test results
1N/AYet another framework for writing test scripts
1N/ABasic utilities for writing tests.
1N/AA tutorial about writing really basic tests
1N/ACreate an abbreviation table from a list
1N/AExtract delimited text sequences from strings.
1N/A=item Text::ParseWords
1N/AParse text into an array of tokens or array of arrays
1N/AImplementation of the Soundex Algorithm as Described by Knuth
1N/AExpand and unexpand tabs per the unix expand(1) and unexpand(1)
1N/ALine wrapping to form simple paragraphs
1N/AManipulate threads in Perl (for old code only)
1N/A=item Thread::Semaphore
1N/AThread-safe semaphores
1N/AStart a thread which runs signal handlers reliably (for old code)
1N/A=item Thread::Specific
1N/ABase class for tied arrays
1N/AAccess the lines of a disk file via a Perl array
1N/ABase class definitions for tied handles
1N/ABase class definitions for tied hashes
1N/AAdd data to hash when needed
1N/AUse references as hash keys
1N/ABase class definitions for tied scalars
1N/A=item Tie::SubstrHash
1N/AFixed-table-size, fixed-key-length hashing
1N/AHigh resolution alarm, sleep, gettimeofday, interval timers
1N/AEfficiently compute time from local and GMT time
1N/ABy-name interface to Perl's built-in gmtime() function
1N/A=item Time::localtime
1N/ABy-name interface to Perl's built-in localtime() function
1N/AInternal object used by Time::gmtime and Time::localtime
1N/ABase class for ALL classes (blessed references)
1N/A=item Unicode::Collate
1N/AUnicode Collation Algorithm
1N/A=item Unicode::Normalize
1N/AUnicode Normalization Forms
1N/AUnicode character database
1N/ABy-name interface to Perl's built-in getgr*() functions
1N/ABy-name interface to Perl's built-in getpw*() functions
1N/AInterfaces to some Win32 API Functions
1N/AModule to test the XS typemaps distributed with perl
1N/ADynamically load C libraries into Perl code
1N/ATo find out I<all> modules installed on your system, including
1N/Athose without documentation or outside the standard release,
1N/Ajust use the following command (under the default win32 shell,
1N/Adouble quotes should be used instead of single quotes).
1N/A % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
1N/A 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
1N/A no_chdir => 1 }, @INC'
1N/A(The -T is here to prevent '.' from being listed in @INC.)
1N/AThey should all have their own documentation installed and accessible
1N/Avia your system man(1) command. If you do not have a B<find>
1N/Aprogram, you can use the Perl B<find2perl> program instead, which
1N/Agenerates Perl code as output you can run through perl. If you
1N/Ahave a B<man> program but it doesn't find your modules, you'll have
1N/Ato fix your manpath. See L<perl> for details. If you have no
1N/Asystem B<man> command, you might try the B<perldoc> program.
1N/ANote also that the command C<perldoc perllocal> gives you a (possibly
1N/Aincomplete) list of the modules that have been further installed on
1N/A=head2 Extension Modules
1N/AExtension modules are written in C (or a mix of Perl and C). They
1N/Aare usually dynamically loaded into Perl if and when you need them,
1N/Abut may also be linked in statically. Supported extension modules
1N/Ainclude Socket, Fcntl, and POSIX.
1N/AMany popular C extension modules do not come bundled (at least, not
1N/Acompletely) due to their sizes, volatility, or simply lack of time
1N/Afor adequate testing and configuration across the multitude of
1N/Aplatforms on which Perl was beta-tested. You are encouraged to
1N/Alook for them on CPAN (described below), or using web search engines
1N/Alike Alta Vista or Google.
1N/ACPAN stands for Comprehensive Perl Archive Network; it's a globally
1N/Areplicated trove of Perl materials, including documentation, style
1N/Aguides, tricks and traps, alternate ports to non-Unix systems and
1N/Aoccasional binary distributions for these. Search engines for
1N/AMost importantly, CPAN includes around a thousand unbundled modules,
1N/Asome of which require a C compiler to build. Major categories of
1N/ALanguage Extensions and Documentation Tools
1N/AOperating System Interfaces
1N/ANetworking, Device Control (modems) and InterProcess Communication
1N/AData Types and Data Type Utilities
1N/AInterfaces to / Emulations of Other Programming Languages
1N/AFile Names, File Systems and File Locking (see also File Handles)
1N/AString Processing, Language Text Processing, Parsing, and Searching
1N/AOption, Argument, Parameter, and Configuration File Processing
1N/AInternationalization and Locale
1N/AAuthentication, Security, and Encryption
1N/AWorld Wide Web, HTML, HTTP, CGI, MIME
1N/AServer and Daemon Utilities
1N/AArchiving and Compression
1N/AImages, Pixmap and Bitmap Manipulation, Drawing, and Graphing
1N/AControl Flow Utilities (callbacks and exceptions etc)
1N/AMiscellaneous Modules
1N/AThe list of the registered CPAN sites as of this writing follows.
1N/APlease note that the sorting order is alphabetical on fields:
1N/Aand thus the North American servers happen to be listed between the
1N/AEuropean and the South American sites.
1N/AYou should try to choose one close to you.
1N/A=item Russian Federation
1N/A=head2 Central America
1N/A=item Bosnia and Herzegovina
1N/A=item District of Columbia
1N/AFor an up-to-date listing of CPAN sites,
1N/A=head1 Modules: Creation, Use, and Abuse
1N/A(The following section is borrowed directly from Tim Bunce's modules
1N/Afile, available at your nearest CPAN site.)
1N/APerl implements a class using a package, but the presence of a
1N/Apackage doesn't imply the presence of a class. A package is just a
1N/Anamespace. A class is a package that provides subroutines that can be
1N/Aused as methods. A method is just a subroutine that expects, as its
1N/Afirst argument, either the name of a package (for "static" methods),
1N/Aor a reference to something (for "virtual" methods).
1N/AA module is a file that (by convention) provides a class of the same
1N/Aname (sans the .pm), plus an import method in that class that can be
1N/Acalled to fetch exported symbols. This module may implement some of
1N/Aits methods by loading dynamic C or C++ objects, but that should be
1N/Atotally transparent to the user of the module. Likewise, the module
1N/Amight set up an AUTOLOAD function to slurp in subroutine definitions on
1N/Ademand, but this is also transparent. Only the F<.pm> file is required to
1N/Aexist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1N/Athe AUTOLOAD mechanism.
1N/A=head2 Guidelines for Module Creation
1N/ADo similar modules already exist in some form?
1N/AIf so, please try to reuse the existing modules either in whole or
1N/Aby inheriting useful features into a new class. If this is not
1N/Apractical try to get together with the module authors to work on
1N/Aextending or enhancing the functionality of the existing modules.
1N/AA perfect example is the plethora of packages in perl4 for dealing
1N/Awith command line options.
1N/AIf you are writing a module to expand an already existing set of
1N/Amodules, please coordinate with the author of the package. It
1N/Ahelps if you follow the same naming scheme and module interaction
1N/Ascheme as the original author.
1N/ATry to design the new module to be easy to extend and reuse.
1N/ATry to C<use warnings;> (or C<use warnings qw(...);>).
1N/ARemember that you can add C<no warnings qw(...);> to individual blocks
1N/Aof code that need less warnings.
1N/AUse blessed references. Use the two argument form of bless to bless
1N/Ainto the class name given as the first parameter of the constructor,
1N/A return bless {}, $class;
1N/Aor even this if you'd like it to be used as either a static
1N/A my $class = ref($self) || $self;
1N/A return bless {}, $class;
1N/APass arrays as references so more parameters can be added later
1N/A(it's also faster). Convert functions into methods where
1N/Aappropriate. Split large methods into smaller more flexible ones.
1N/AInherit methods from other modules if appropriate.
1N/AAvoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1N/AGenerally you can delete the C<eq 'FOO'> part with no harm at all.
1N/ALet the objects look after themselves! Generally, avoid hard-wired
1N/Aclass names as far as possible.
1N/AAvoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1N/AC<< $r->func() >> would work (see L<perlbot> for more details).
1N/AUse autosplit so little used or newly added functions won't be a
1N/Aburden to programs that don't use them. Add test functions to
1N/Athe module after __END__ either using AutoSplit or by saying:
1N/A eval join('',<main::DATA>) || die $@ unless caller();
1N/ADoes your module pass the 'empty subclass' test? If you say
1N/AC<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1N/Ato use SUBCLASS in exactly the same way as YOURCLASS. For example,
1N/Adoes your application still work if you change: C<$obj = new YOURCLASS;>
1N/Ainto: C<$obj = new SUBCLASS;> ?
1N/AAvoid keeping any state information in your packages. It makes it
1N/Adifficult for multiple other packages to use yours. Keep state
1N/Ainformation in objects.
1N/ATry to C<use strict;> (or C<use strict qw(...);>).
1N/ARemember that you can add C<no strict qw(...);> to individual blocks
1N/Aof code that need less strictness.
1N/AFollow the guidelines in the perlstyle(1) manual.
1N/ASome simple style guidelines
1N/AThe perlstyle manual supplied with Perl has many helpful points.
1N/ACoding style is a matter of personal taste. Many people evolve their
1N/Astyle over several years as they learn what helps them write and
1N/Amaintain good code. Here's one set of assorted suggestions that
1N/Aseem to be widely used by experienced developers:
1N/AUse underscores to separate words. It is generally easier to read
1N/A$var_names_like_this than $VarNamesLikeThis, especially for
1N/Anon-native speakers of English. It's also a simple rule that works
1N/Aconsistently with VAR_NAMES_LIKE_THIS.
1N/Areserves lowercase module names for 'pragma' modules like integer
1N/Aand strict. Other modules normally begin with a capital letter and
1N/Ause mixed case with no underscores (need to be short and portable).
1N/AYou may find it helpful to use letter case to indicate the scope
1N/Aor nature of a variable. For example:
1N/A $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
1N/A $no_caps_here function scope my() or local() variables
1N/AFunction and method names seem to work best as all lowercase.
1N/AYou can use a leading underscore to indicate that a variable or
1N/Afunction should not be used outside the package that defined it.
1N/ASelect what to export.
1N/ADo NOT export method names!
1N/ADo NOT export anything else by default without a good reason!
1N/AExports pollute the namespace of the module user. If you must
1N/Aexport try to use @EXPORT_OK in preference to @EXPORT and avoid
1N/Ashort or common names to reduce the risk of name clashes.
1N/AGenerally anything not exported is still accessible from outside the
1N/Amodule using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1N/Asyntax. By convention you can use a leading underscore on names to
1N/Aindicate informally that they are 'internal' and not for public use.
1N/A(It is actually possible to get private functions by saying:
1N/AC<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1N/Adirectly as a method, because a method must have a name in the symbol
1N/AAs a general rule, if the module is trying to be object oriented
1N/Athen export nothing. If it's just a collection of functions then
1N/A@EXPORT_OK anything but use @EXPORT with caution.
1N/ASelect a name for the module.
1N/AThis name should be as descriptive, accurate, and complete as
1N/Apossible. Avoid any risk of ambiguity. Always try to use two or
1N/Amore whole words. Generally the name should reflect what is special
1N/Aabout what the module does rather than how it does it. Please use
1N/Anested module names to group informally or categorize a module.
1N/AThere should be a very good reason for a module not to have a nested name.
1N/AModule names should begin with a capital letter.
1N/AHaving 57 modules all called Sort will not make life easy for anyone
1N/A(though having 23 called Sort::Quick is only marginally better :-).
1N/AImagine someone trying to install your module alongside many others.
1N/Apractice to use nested classes with a common prefix as this will
1N/Aavoid namespace clashes. For example: Xyz::Control, Xyz::View,
1N/AXyz::Model etc. Use the modules in this list as a naming guide.
1N/AIf adding a new module to a set, follow the original author's
1N/Astandards for naming modules and the interface to methods in
1N/AIf developing modules for private internal or project specific use,
1N/Athat will never be released to the public, then you should ensure
1N/Athat their names will not clash with any future public module. You
1N/Acan do this either by using the reserved Local::* category or by
1N/Ausing a category name that includes an underscore like Foo_Corp::*.
1N/ATo be portable each component of a module name should be limited to
1N/A11 characters. If it might be used on MS-DOS then try to ensure each is
1N/Aunique in the first 8 characters. Nested modules make this easier.
1N/AHave you got it right?
1N/AHow do you know that you've made the right decisions? Have you
1N/Apicked an interface design that will cause problems later? Have
1N/Ayou picked the most appropriate name? Do you have any questions?
1N/AThe best way to know for sure, and pick up many helpful suggestions,
1N/Aall the people who develop modules and it's the best place to ask.
1N/AAll you need to do is post a short summary of the module, its
1N/Apurpose and interfaces. A few lines on each of the main methods is
1N/Aprobably enough. (If you post the whole module it might be ignored
1N/Aby busy people - generally the very people you want to read it!)
1N/ADon't worry about posting if you can't say when the module will be
1N/Aready - just say so in the message. It might be worth inviting
1N/Aothers to help you, they may be able to complete it for you!
1N/AREADME and other Additional Files.
1N/AIt's well known that software developers usually fully document the
1N/Asoftware they write. If, however, the world is in urgent need of
1N/Ayour software and there is not enough time to write the full
1N/Adocumentation please at least provide a README file containing:
1N/AA copyright notice - see below.
1N/APrerequisites - what else you may need to have.
1N/ARecent changes in this release, especially incompatibilities
1N/AChanges / enhancements you plan to make in the future.
1N/AIf the README file seems to be getting too large you may wish to
1N/Asplit out some of the sections into separate files: INSTALL,
1N/AAdding a Copyright Notice.
1N/AHow you choose to license your work is a personal decision.
1N/AThe general mechanism is to assert your Copyright and then make
1N/APerl, for example, is supplied with two types of licence: The GNU GPL
1N/Aand The Artistic Licence (see the files README, Copying, and Artistic,
1N/Aor L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
1N/Ajust using the GNU GPL.
1N/AMy personal recommendation, out of respect for Larry, Perl, and the
1N/APerl community at large is to state something simply like:
1N/A Copyright (c) 1995 Your Name. All rights reserved.
1N/A This program is free software; you can redistribute it
and/or 1N/A modify it under the same terms as Perl itself.
1N/AThis statement should at least appear in the README file. You may
1N/Aalso wish to include it in a Copying file and your source files.
1N/ARemember to include the other words in addition to the Copyright.
1N/ATo be fully compatible with the Exporter and MakeMaker modules you
1N/Ashould store your module's version number in a non-my package
1N/Avariable called $VERSION. This should be a floating point
1N/Anumber with at least two digits after the decimal (
i.e., hundredths,
1N/Ae.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1N/ASee L<Exporter> for details.
1N/AIt may be handy to add a function or method to retrieve the number.
1N/AUse the number in announcements and archive file names when
1N/AHow to release and distribute a module.
1N/AIt's good idea to post an announcement of the availability of your
1N/AUsenet newsgroup. This will at least ensure very wide once-off
1N/AIf possible, register the module with CPAN. You should
1N/Ainclude details of its location in your announcement.
1N/ASome notes about ftp archives: Please use a long descriptive file
1N/Aname that includes the version number. Most incoming directories
1N/Afile after uploading it. Remember to send your email notification
1N/Amessage as soon as possible after uploading else your file may get
1N/Adeleted automatically. Allow time for the file to be processed
1N/Aand/or check the file has been processed before announcing its
1N/AFTP Archives for Perl Modules:
1N/AFollow the instructions and links on:
1N/Aor upload to one of these sites:
1N/Aand notify <modules@perl.org>.
1N/ABy using the WWW interface you can ask the Upload Server to mirror
1N/Ayour modules from your ftp or WWW site into your own directory on
1N/APlease remember to send me an updated entry for the Module list!
1N/ATake care when changing a released module.
1N/AAlways strive to remain compatible with previous released versions.
1N/AOtherwise try to add a mechanism to revert to the
1N/Aold behavior if people rely on it. Document incompatible changes.
1N/A=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1N/AThere is no requirement to convert anything.
1N/AIf it ain't broke, don't fix it! Perl 4 library scripts should
1N/Acontinue to work with no problems. You may need to make some minor
1N/Achanges (like escaping non-array @'s in double quoted strings) but
1N/Athere is no need to convert a .pl file into a Module for just that.
1N/AConsider the implications.
1N/AAll Perl applications that make use of the script will need to
1N/Abe changed (slightly) if the script is converted into a module. Is
1N/Ait worth it unless you plan to make other changes at the same time?
1N/AMake the most of the opportunity.
1N/AIf you are going to convert the script to a module you can use the
1N/Aopportunity to redesign the interface. The guidelines for module
1N/Acreation above include many of the issues you should consider.
1N/AThe pl2pm utility will get you started.
1N/AThis utility will read *.pl files (given as parameters) and write
1N/Acorresponding *.pm files. The pl2pm utilities does the following:
1N/AAdds the standard Module prologue lines
1N/AConverts package specifiers from ' to ::
1N/AConverts die(...) to croak(...)
1N/ASeveral other minor changes
1N/ABeing a mechanical process pl2pm is not bullet proof. The converted
1N/Acode will need careful checking, especially any package statements.
1N/ADon't delete the original .pl file till the new .pm one works!
1N/A=head2 Guidelines for Reusing Application Code
1N/AComplete applications rarely belong in the Perl Module Library.
1N/AMany applications contain some Perl code that could be reused.
1N/AHelp save the world! Share your code in a form that makes it easy
1N/ABreak-out the reusable code into one or more separate module files.
1N/ATake the opportunity to reconsider and redesign the interfaces.
1N/AIn some cases the 'application' can then be reduced to a small
1N/Afragment of code built on top of the reusable modules. In these cases
1N/Athe application could invoked as:
1N/A % perl -e 'use Module::Name; method(@ARGV)' ...
1N/A % perl -mModule::Name ... (in perl5.002 or higher)
1N/APerl does not enforce private and public parts of its modules as you may
1N/Ahave been used to in other languages like C++, Ada, or Modula-17. Perl
1N/Adoesn't have an infatuation with enforced privacy. It would prefer
1N/Athat you stayed out of its living room because you weren't invited, not
1N/Abecause it has a shotgun.
1N/AThe module and its user have a contract, part of which is common law,
1N/Aand part of which is "written". Part of the common law contract is
1N/Athat a module doesn't pollute any namespace it wasn't asked to. The
1N/Awritten contract for the module (
A.K.A. documentation) may make other
1N/Aprovisions. But then you know when you C<use RedefineTheWorld> that
1N/Ayou're redefining the world and willing to take the consequences.