3 perlmodlib - constructing new Perl modules and finding existing ones
7 =head1 THE PERL MODULE LIBRARY
9 Many modules are included the Perl distribution. These are described
10 below, and all end in F<.pm>. You may discover compiled library
11 file (usually ending in F<.so>) or small pieces of modules to be
12 autoloaded (ending in F<.al>); these were automatically generated
13 by the installation process. You may also discover files in the
14 library directory that end in either F<.pl> or F<.ph>. These are
15 old libraries supplied so that old programs that use them still
16 run. The F<.pl> files will all eventually be converted into standard
17 modules, and the F<.ph> files made by B<h2ph> will probably end up
18 as extension modules made by B<h2xs>. (Some F<.ph> values may
19 already be available through the POSIX, Errno, or Fcntl modules.)
20 The B<pl2pm> file in the distribution may help in your conversion,
21 but it's just a mechanical process and therefore far from bulletproof.
23 =head2 Pragmatic Modules
25 They work somewhat like compiler directives (pragmata) in that they
26 tend to affect the compilation of your program, and thus will usually
27 work well only when used within a C<use>, or C<no>. Most of these
28 are lexically scoped, so an inner BLOCK may countermand them
35 which lasts until the end of that BLOCK.
37 Some pragmas are lexically scoped--typically those that affect the
38 C<$^H> hints variable. Others affect the current package instead,
39 like C<use vars> and C<use subs>, whic allow you to predeclare a
40 variables or subroutines within a particular I<file> rather than
41 just a block. Such declarations are effective for the entire file
42 for which they were declared. You cannot rescind them with C<no
45 The following pragmas are defined (and have their own documentation).
51 set/get the attributes of a subroutine or variable
55 set/get attributes of a subroutine (obsolescent)
59 postpone load of modules until a function is used
63 Establish IS-A relationship with base class at compile time
67 Use MakeMaker's uninstalled version of a package
75 Perl compiler pragma to force verbose warning diagnostics
79 compile-time class fields
83 control the filetest permission operators
87 compute arithmetic in integer instead of double
91 perl pragma to request less of something from the compiler
95 manipulate @INC at compile time
99 use and avoid POSIX locales for built-in operations
103 restrict unsafe operations when compiling
107 Package for overloading perl operations
111 alter regular expression behavior
115 enable simple signal handling
119 restrict unsafe constructs
127 turn on UTF-8 and Unicode support
131 predeclare global variable names
135 control optional warnings
139 control VMS-specific language features
143 =head2 Standard Modules
145 Standard, bundled modules are all expected to behave in a well-defined
146 manner with respect to namespace pollution because they use the
147 Exporter module. See their own documentation for details.
153 provide framework for multiple DBMs
157 load subroutines only on demand
161 split a package for autoloading
165 The Perl Compiler; See also L<perlcc>.
169 Autogenerated data about Perl ops, used to generate bytecode
173 Assemble Perl bytecode
181 Perl compiler's bytecode backend
185 Perl compiler's C backend
189 Perl compiler's optimized C translation backend
193 Walk Perl syntax tree, printing debug info about ops
197 Perl compiler backend to produce perl code
199 =item B::Disassembler
201 Disassemble Perl bytecode
209 Show lexical variables used in functions or files
213 Helper module for CC backend
217 Walk Perl syntax tree, printing terse info about ops
221 Generates cross reference reports for Perl programs
225 benchmark running times of code
229 Simple Common Gateway Interface Class
233 Make things work with CGI.pm against Perl-Apache API
237 CGI routines for writing to the HTTPD (or other) error log
241 Interface to Netscape Cookies
245 CGI Interface for Fast CGI
249 Simple Interface to Server Push
253 Try more than one constructors and return the first object available
257 query, download and build perl modules from CPAN sites
259 =item CPAN::FirstTime
261 Utility for CPAN::Config file Initialization
265 Wrapper around CPAN.pm without using any XS module
269 warn of errors (from perspective of caller)
273 declare struct-like datatypes as Perl classes
277 access Perl configuration information
281 get pathname of current working directory
285 programmatic interface to the Perl debugging API
289 Perl5 access to Berkeley DB version 1.x
293 stringified perl data structures, suitable for both printing and C<eval>
297 A data debugging tool for the XS programmer
299 =item Devel::SelfStubber
301 generate stubs for a SelfLoading module
305 supply object methods for directory handles
309 provides screen dump of Perl data.
313 Dynamically load C libraries into Perl code
317 use nice English (or awk) names for ugly punctuation variables
321 perl module that imports environment variables
325 System errno constants
329 Implements default import method for modules
331 =item ExtUtils::Command
333 utilities to replace common UNIX commands in Makefiles etc.
335 =item ExtUtils::Embed
337 Utilities for embedding Perl in C/C++ applications
339 =item ExtUtils::Install
341 install files from here to there
343 =item ExtUtils::Installed
345 Inventory management of installed modules
347 =item ExtUtils::Liblist
349 determine libraries to use and how to use them
351 =item ExtUtils::MM_OS2
353 methods to override UN*X behavior in ExtUtils::MakeMaker
355 =item ExtUtils::MM_Unix
357 methods used by ExtUtils::MakeMaker
359 =item ExtUtils::MM_VMS
361 methods to override UN*X behavior in ExtUtils::MakeMaker
363 =item ExtUtils::MM_Win32
365 methods to override UN*X behavior in ExtUtils::MakeMaker
367 =item ExtUtils::MakeMaker
369 create an extension Makefile
371 =item ExtUtils::Manifest
373 utilities to write and check a MANIFEST file
375 =item ExtUtils::Miniperl
377 write the C code for perlmain.c
379 =item ExtUtils::Mkbootstrap
381 make a bootstrap file for use by DynaLoader
383 =item ExtUtils::Mksymlists
385 write linker options files for dynamic extension
387 =item ExtUtils::Packlist
389 manage .packlist files
391 =item ExtUtils::testlib
393 add blib/* directories to @INC
397 replace functions with equivalents which succeed or die
401 load the C Fcntl.h defines
405 split a pathname into pieces
409 Compare files or filehandles
413 Copy files or filehandles
417 DOS like globbing and then some
425 create or remove a series of directories
429 portably perform operations on file names
431 =item File::Spec::Functions
433 portably perform operations on file names
435 =item File::Spec::Mac
439 =item File::Spec::OS2
441 methods for OS/2 file specs
443 =item File::Spec::Unix
445 methods used by File::Spec
447 =item File::Spec::VMS
449 methods for VMS file specs
451 =item File::Spec::Win32
453 methods for Win32 file specs
457 by-name interface to Perl's built-in stat() functions
461 keep more files open than the system permits
465 supply object methods for filehandles
469 Locate directory of original perl script
473 Perl5 access to the gdbm library.
477 extended processing of command line options
481 Process single-character switches with switch clustering
485 compare 8-bit scalar data according to the current locale
489 load various IO modules
493 supply object methods for directory handles
497 supply object methods for filehandles
501 supply object methods for I/O handles
505 supply object methods for pipes
509 Object interface to system poll call
513 supply seek based methods for I/O objects
517 OO interface to the select system call
521 Object interface to socket communications
523 =item IO::Socket::INET
525 Object interface for AF_INET domain sockets
527 =item IO::Socket::UNIX
529 Object interface for AF_UNIX domain sockets
533 SysV Msg IPC object class
537 open a process for both reading and writing
541 open a process for reading, writing, and error handling
545 SysV Semaphore IPC object class
553 Arbitrary length float math package
557 Arbitrary size integer math package
561 complex numbers and associated mathematical functions
565 trigonometric functions
569 Tied access to ndbm files
573 check a remote host for reachability
577 by-name interface to Perl's built-in gethost*() functions
581 by-name interface to Perl's built-in getnet*() functions
585 by-name interface to Perl's built-in getproto*() functions
589 by-name interface to Perl's built-in getserv*() functions
593 Generic interface to Perl Compiler backends
597 Disable named opcodes when compiling perl code
601 Perl interface to IEEE Std 1003.1
605 module to convert pod files to HTML
609 convert POD data to formatted ASCII text
613 Tied access to sdbm files
617 Compile and execute code in restricted compartments
621 search for key in dictionary file
625 save and restore selected file handle
629 load functions only on demand
633 run shell commands transparently within perl
637 load the C socket.h defines and structure manipulators
641 manipulate Perl symbols and their names
645 Try every conceivable way to get hostname
649 Perl interface to the UNIX syslog(3) calls
653 Perl termcap interface
657 Perl word completion module
661 Perl interface to various C<readline> packages.
665 provides a simple framework for writing test scripts
669 run perl standard test scripts with statistics
673 create an abbreviation table from a list
675 =item Text::ParseWords
677 parse text into an array of tokens or array of arrays
681 Implementation of the Soundex Algorithm as Described by Knuth
683 =item Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1)
687 line wrapping to form simple paragraphs
697 =item Thread::Semaphore
699 thread-safe semaphores
703 Start a thread which runs signal handlers reliably
705 =item Thread::Specific
711 base class for tied arrays
715 base class definitions for tied handles
717 =item Tie::Hash, Tie::StdHash
719 base class definitions for tied hashes
723 use references as hash keys
725 =item Tie::Scalar, Tie::StdScalar
727 base class definitions for tied scalars
729 =item Tie::SubstrHash
731 Fixed-table-size, fixed-key-length hashing
735 efficiently compute time from local and GMT time
739 by-name interface to Perl's built-in gmtime() function
741 =item Time::localtime
743 by-name interface to Perl's built-in localtime() function
747 internal object used by Time::gmtime and Time::localtime
751 base class for ALL classes (blessed references)
755 by-name interface to Perl's built-in getgr*() functions
759 by-name interface to Perl's built-in getpw*() functions
763 To find out I<all> modules installed on your system, including
764 those without documentation or outside the standard release,
767 % find `perl -e 'print "@INC"'` -name '*.pm' -print
769 They should all have their own documentation installed and accessible
770 via your system man(1) command. If you do not have a B<find>
771 program, you can use the Perl B<find2perl> program instead, which
772 generates Perl code as output you can run through perl. If you
773 have a B<man> program but it doesn't find your modules, you'll have
774 to fix your manpath. See L<perl> for details. If you have no
775 system B<man> command, you might try the B<perldoc> program.
777 =head2 Extension Modules
779 Extension modules are written in C (or a mix of Perl and C). They
780 are usually dynamically loaded into Perl if and when you need them,
781 but may also be be linked in statically. Supported extension modules
782 include Socket, Fcntl, and POSIX.
784 Many popular C extension modules do not come bundled (at least, not
785 completely) due to their sizes, volatility, or simply lack of time
786 for adequate testing and configuration across the multitude of
787 platforms on which Perl was beta-tested. You are encouraged to
788 look for them on CPAN (described below), or using web search engines
789 like Alta Vista or Deja News.
793 CPAN stands for Comprehensive Perl Archive Network; it's a globally
794 replicated trove of Perl materials, including documentation, style
795 guides, tricks and trap, alternate ports to non-Unix systems and
796 occasional binary distributions for these. Search engines for
797 CPAN can be found at http://cpan.perl.com/ and at
798 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
800 Most importantly, CPAN includes around a thousand unbundled modules,
801 some of which require a C compiler to build. Major categories of
807 Language Extensions and Documentation Tools
813 Operating System Interfaces
816 Networking, Device Control (modems) and InterProcess Communication
819 Data Types and Data Type Utilities
828 Interfaces to / Emulations of Other Programming Languages
831 File Names, File Systems and File Locking (see also File Handles)
834 String Processing, Language Text Processing, Parsing, and Searching
837 Option, Argument, Parameter, and Configuration File Processing
840 Internationalization and Locale
843 Authentication, Security, and Encryption
846 World Wide Web, HTML, HTTP, CGI, MIME
849 Server and Daemon Utilities
852 Archiving and Compression
855 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
861 Control Flow Utilities (callbacks and exceptions etc)
864 File Handle and Input/Output Stream Utilities
867 Miscellaneous Modules
871 Registered CPAN sites as of this writing include the following.
872 You should try to choose one close to you:
878 South Africa ftp://ftp.is.co.za/programming/perl/CPAN/
879 ftp://ftpza.co.za/pub/mirrors/cpan/
883 China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
884 Hong Kong ftp://ftp.hkstar.com/pub/CPAN/
885 Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
886 Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/
887 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
888 ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
889 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
890 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
891 ftp://mirror.nucba.ac.jp/mirror/Perl/
892 Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
893 South Korea ftp://ftp.bora.net/pub/CPAN/
894 ftp://ftp.nuri.net/pub/CPAN/
895 Taiwan ftp://ftp.wownet.net/pub2/PERL/
896 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
897 Thailand ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
898 ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
902 Australia ftp://cpan.topend.com.au/pub/CPAN/
903 ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
904 ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
905 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
906 New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
907 ftp://sunsite.net.nz/pub/languages/perl/CPAN/
911 Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
915 Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
916 Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
917 Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/
918 Croatia ftp://ftp.linux.hr/pub/CPAN/
919 Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
920 ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
921 Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
922 Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/
923 Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/
924 France ftp://ftp.lip6.fr/pub/perl/CPAN/
925 ftp://ftp.oleane.net/pub/mirrors/CPAN/
926 ftp://ftp.pasteur.fr/pub/computing/CPAN/
927 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
928 ftp://ftp.gmd.de/packages/CPAN/
929 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
930 ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/
931 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
932 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
933 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
934 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
935 Greece ftp://ftp.ntua.gr/pub/lang/perl/
936 Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
937 Ireland ftp://sunsite.compapp.dcu.ie/pub/perl/
938 Italy ftp://cis.uniRoma2.it/CPAN/
939 ftp://ftp.flashnet.it/pub/CPAN/
940 ftp://ftp.unina.it/pub/Other/CPAN/
941 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
942 Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/
943 ftp://ftp.EU.net/packages/cpan/
944 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
945 Norway ftp://ftp.uit.no/pub/languages/perl/cpan/
946 ftp://sunsite.uio.no/pub/languages/perl/CPAN/
947 Poland ftp://ftp.man.szczecin.pl/pub/perl/CPAN/
948 ftp://ftp.man.torun.pl/pub/doc/CPAN/
949 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
950 ftp://sunsite.icm.edu.pl/pub/CPAN/
951 Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
952 ftp://ftp.ist.utl.pt/pub/CPAN/
953 ftp://ftp.ua.pt/pub/CPAN/
954 Romania ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
955 ftp://ftp.dnttm.ro/pub/CPAN/
956 Russia ftp://ftp.chg.ru/pub/lang/perl/CPAN/
957 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
958 Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/
959 Slovenia ftp://ftp.arnes.si/software/perl/CPAN/
960 Spain ftp://ftp.etse.urv.es/pub/perl/
961 ftp://ftp.rediris.es/mirror/CPAN/
962 Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/
963 Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
964 Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
965 United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
966 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
967 ftp://ftp.plig.org/pub/CPAN/
968 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
969 ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
973 Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
974 California ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
975 ftp://ftp.cdrom.com/pub/perl/CPAN/
976 ftp://ftp.digital.com/pub/plan/perl/CPAN/
977 Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
978 Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
979 Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
980 Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
981 ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
982 Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/
983 Massachusetts ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
984 ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
985 Mexico ftp://ftp.msg.com.mx/pub/CPAN/
986 Minnesota ftp://ftp.midearthbbs.com/CPAN/
987 New York ftp://ftp.rge.com/pub/languages/perl/
988 North Carolina ftp://ftp.duke.edu/pub/perl/
989 Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/
990 Ontario ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
991 Oregon ftp://ftp.orst.edu/pub/packages/CPAN/
992 Pennsylvania ftp://ftp.epix.net/pub/languages/perl/
993 Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/
994 Utah ftp://mirror.xmission.com/CPAN/
995 Virginia ftp://ftp.perl.org/pub/perl/CPAN/
996 ftp://ruff.cs.jmu.edu/pub/CPAN/
997 Washington ftp://ftp-mirror.internap.com/pub/CPAN/
998 ftp://ftp.spu.edu/pub/CPAN/
1002 Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/
1003 Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
1007 For an up-to-date listing of CPAN sites,
1008 see http://www.perl.com/perl/CPAN or ftp://www.perl.com/perl/ .
1010 =head1 Modules: Creation, Use, and Abuse
1012 (The following section is borrowed directly from Tim Bunce's modules
1013 file, available at your nearest CPAN site.)
1015 Perl implements a class using a package, but the presence of a
1016 package doesn't imply the presence of a class. A package is just a
1017 namespace. A class is a package that provides subroutines that can be
1018 used as methods. A method is just a subroutine that expects, as its
1019 first argument, either the name of a package (for "static" methods),
1020 or a reference to something (for "virtual" methods).
1022 A module is a file that (by convention) provides a class of the same
1023 name (sans the .pm), plus an import method in that class that can be
1024 called to fetch exported symbols. This module may implement some of
1025 its methods by loading dynamic C or C++ objects, but that should be
1026 totally transparent to the user of the module. Likewise, the module
1027 might set up an AUTOLOAD function to slurp in subroutine definitions on
1028 demand, but this is also transparent. Only the F<.pm> file is required to
1029 exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1030 the AUTOLOAD mechanism.
1032 =head2 Guidelines for Module Creation
1036 =item Do similar modules already exist in some form?
1038 If so, please try to reuse the existing modules either in whole or
1039 by inheriting useful features into a new class. If this is not
1040 practical try to get together with the module authors to work on
1041 extending or enhancing the functionality of the existing modules.
1042 A perfect example is the plethora of packages in perl4 for dealing
1043 with command line options.
1045 If you are writing a module to expand an already existing set of
1046 modules, please coordinate with the author of the package. It
1047 helps if you follow the same naming scheme and module interaction
1048 scheme as the original author.
1050 =item Try to design the new module to be easy to extend and reuse.
1054 Use blessed references. Use the two argument form of bless to bless
1055 into the class name given as the first parameter of the constructor,
1060 return bless {}, $class;
1063 or even this if you'd like it to be used as either a static
1064 or a virtual method.
1068 my $class = ref($self) || $self;
1069 return bless {}, $class;
1072 Pass arrays as references so more parameters can be added later
1073 (it's also faster). Convert functions into methods where
1074 appropriate. Split large methods into smaller more flexible ones.
1075 Inherit methods from other modules if appropriate.
1077 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1078 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1079 Let the objects look after themselves! Generally, avoid hard-wired
1080 class names as far as possible.
1082 Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
1083 C<$r-E<gt>func()> would work (see L<perlbot> for more details).
1085 Use autosplit so little used or newly added functions won't be a
1086 burden to programs that don't use them. Add test functions to
1087 the module after __END__ either using AutoSplit or by saying:
1089 eval join('',<main::DATA>) || die $@ unless caller();
1091 Does your module pass the 'empty subclass' test? If you say
1092 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1093 to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1094 does your application still work if you change: C<$obj = new YOURCLASS;>
1095 into: C<$obj = new SUBCLASS;> ?
1097 Avoid keeping any state information in your packages. It makes it
1098 difficult for multiple other packages to use yours. Keep state
1099 information in objects.
1103 Try to C<use strict;> (or C<use strict qw(...);>).
1104 Remember that you can add C<no strict qw(...);> to individual blocks
1105 of code that need less strictness.
1109 Follow the guidelines in the perlstyle(1) manual.
1113 =item Some simple style guidelines
1115 The perlstyle manual supplied with Perl has many helpful points.
1117 Coding style is a matter of personal taste. Many people evolve their
1118 style over several years as they learn what helps them write and
1119 maintain good code. Here's one set of assorted suggestions that
1120 seem to be widely used by experienced developers:
1122 Use underscores to separate words. It is generally easier to read
1123 $var_names_like_this than $VarNamesLikeThis, especially for
1124 non-native speakers of English. It's also a simple rule that works
1125 consistently with VAR_NAMES_LIKE_THIS.
1127 Package/Module names are an exception to this rule. Perl informally
1128 reserves lowercase module names for 'pragma' modules like integer
1129 and strict. Other modules normally begin with a capital letter and
1130 use mixed case with no underscores (need to be short and portable).
1132 You may find it helpful to use letter case to indicate the scope
1133 or nature of a variable. For example:
1135 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
1136 $Some_Caps_Here package-wide global/static
1137 $no_caps_here function scope my() or local() variables
1139 Function and method names seem to work best as all lowercase.
1140 e.g., C<$obj-E<gt>as_string()>.
1142 You can use a leading underscore to indicate that a variable or
1143 function should not be used outside the package that defined it.
1145 =item Select what to export.
1147 Do NOT export method names!
1149 Do NOT export anything else by default without a good reason!
1151 Exports pollute the namespace of the module user. If you must
1152 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1153 short or common names to reduce the risk of name clashes.
1155 Generally anything not exported is still accessible from outside the
1156 module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
1157 syntax. By convention you can use a leading underscore on names to
1158 indicate informally that they are 'internal' and not for public use.
1160 (It is actually possible to get private functions by saying:
1161 C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1162 directly as a method, because a method must have a name in the symbol
1165 As a general rule, if the module is trying to be object oriented
1166 then export nothing. If it's just a collection of functions then
1167 @EXPORT_OK anything but use @EXPORT with caution.
1169 =item Select a name for the module.
1171 This name should be as descriptive, accurate, and complete as
1172 possible. Avoid any risk of ambiguity. Always try to use two or
1173 more whole words. Generally the name should reflect what is special
1174 about what the module does rather than how it does it. Please use
1175 nested module names to group informally or categorize a module.
1176 There should be a very good reason for a module not to have a nested name.
1177 Module names should begin with a capital letter.
1179 Having 57 modules all called Sort will not make life easy for anyone
1180 (though having 23 called Sort::Quick is only marginally better :-).
1181 Imagine someone trying to install your module alongside many others.
1182 If in any doubt ask for suggestions in comp.lang.perl.misc.
1184 If you are developing a suite of related modules/classes it's good
1185 practice to use nested classes with a common prefix as this will
1186 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1187 Xyz::Model etc. Use the modules in this list as a naming guide.
1189 If adding a new module to a set, follow the original author's
1190 standards for naming modules and the interface to methods in
1193 To be portable each component of a module name should be limited to
1194 11 characters. If it might be used on MS-DOS then try to ensure each is
1195 unique in the first 8 characters. Nested modules make this easier.
1197 =item Have you got it right?
1199 How do you know that you've made the right decisions? Have you
1200 picked an interface design that will cause problems later? Have
1201 you picked the most appropriate name? Do you have any questions?
1203 The best way to know for sure, and pick up many helpful suggestions,
1204 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1205 all the people who develop modules and it's the best place to ask.
1207 All you need to do is post a short summary of the module, its
1208 purpose and interfaces. A few lines on each of the main methods is
1209 probably enough. (If you post the whole module it might be ignored
1210 by busy people - generally the very people you want to read it!)
1212 Don't worry about posting if you can't say when the module will be
1213 ready - just say so in the message. It might be worth inviting
1214 others to help you, they may be able to complete it for you!
1216 =item README and other Additional Files.
1218 It's well known that software developers usually fully document the
1219 software they write. If, however, the world is in urgent need of
1220 your software and there is not enough time to write the full
1221 documentation please at least provide a README file containing:
1226 A description of the module/package/extension etc.
1229 A copyright notice - see below.
1232 Prerequisites - what else you may need to have.
1235 How to build it - possible changes to Makefile.PL etc.
1241 Recent changes in this release, especially incompatibilities
1244 Changes / enhancements you plan to make in the future.
1248 If the README file seems to be getting too large you may wish to
1249 split out some of the sections into separate files: INSTALL,
1254 =item Adding a Copyright Notice.
1256 How you choose to license your work is a personal decision.
1257 The general mechanism is to assert your Copyright and then make
1258 a declaration of how others may copy/use/modify your work.
1260 Perl, for example, is supplied with two types of licence: The GNU
1261 GPL and The Artistic Licence (see the files README, Copying, and
1262 Artistic). Larry has good reasons for NOT just using the GNU GPL.
1264 My personal recommendation, out of respect for Larry, Perl, and the
1265 Perl community at large is to state something simply like:
1267 Copyright (c) 1995 Your Name. All rights reserved.
1268 This program is free software; you can redistribute it and/or
1269 modify it under the same terms as Perl itself.
1271 This statement should at least appear in the README file. You may
1272 also wish to include it in a Copying file and your source files.
1273 Remember to include the other words in addition to the Copyright.
1275 =item Give the module a version/issue/release number.
1277 To be fully compatible with the Exporter and MakeMaker modules you
1278 should store your module's version number in a non-my package
1279 variable called $VERSION. This should be a floating point
1280 number with at least two digits after the decimal (i.e., hundredths,
1281 e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1282 See L<Exporter> for details.
1284 It may be handy to add a function or method to retrieve the number.
1285 Use the number in announcements and archive file names when
1286 releasing the module (ModuleName-1.02.tar.Z).
1287 See perldoc ExtUtils::MakeMaker.pm for details.
1289 =item How to release and distribute a module.
1291 It's good idea to post an announcement of the availability of your
1292 module (or the module itself if small) to the comp.lang.perl.announce
1293 Usenet newsgroup. This will at least ensure very wide once-off
1296 If possible, register the module with CPAN. You should
1297 include details of its location in your announcement.
1299 Some notes about ftp archives: Please use a long descriptive file
1300 name that includes the version number. Most incoming directories
1301 will not be readable/listable, i.e., you won't be able to see your
1302 file after uploading it. Remember to send your email notification
1303 message as soon as possible after uploading else your file may get
1304 deleted automatically. Allow time for the file to be processed
1305 and/or check the file has been processed before announcing its
1308 FTP Archives for Perl Modules:
1310 Follow the instructions and links on
1312 http://franz.ww.tu-berlin.de/modulelist
1314 or upload to one of these sites:
1316 ftp://franz.ww.tu-berlin.de/incoming
1317 ftp://ftp.cis.ufl.edu/incoming
1319 and notify <F<upload@franz.ww.tu-berlin.de>>.
1321 By using the WWW interface you can ask the Upload Server to mirror
1322 your modules from your ftp or WWW site into your own directory on
1325 Please remember to send me an updated entry for the Module list!
1327 =item Take care when changing a released module.
1329 Always strive to remain compatible with previous released versions.
1330 Otherwise try to add a mechanism to revert to the
1331 old behavior if people rely on it. Document incompatible changes.
1337 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1341 =item There is no requirement to convert anything.
1343 If it ain't broke, don't fix it! Perl 4 library scripts should
1344 continue to work with no problems. You may need to make some minor
1345 changes (like escaping non-array @'s in double quoted strings) but
1346 there is no need to convert a .pl file into a Module for just that.
1348 =item Consider the implications.
1350 All Perl applications that make use of the script will need to
1351 be changed (slightly) if the script is converted into a module. Is
1352 it worth it unless you plan to make other changes at the same time?
1354 =item Make the most of the opportunity.
1356 If you are going to convert the script to a module you can use the
1357 opportunity to redesign the interface. The guidelines for module
1358 creation above include many of the issues you should consider.
1360 =item The pl2pm utility will get you started.
1362 This utility will read *.pl files (given as parameters) and write
1363 corresponding *.pm files. The pl2pm utilities does the following:
1368 Adds the standard Module prologue lines
1371 Converts package specifiers from ' to ::
1374 Converts die(...) to croak(...)
1377 Several other minor changes
1381 Being a mechanical process pl2pm is not bullet proof. The converted
1382 code will need careful checking, especially any package statements.
1383 Don't delete the original .pl file till the new .pm one works!
1387 =head2 Guidelines for Reusing Application Code
1391 =item Complete applications rarely belong in the Perl Module Library.
1393 =item Many applications contain some Perl code that could be reused.
1395 Help save the world! Share your code in a form that makes it easy
1398 =item Break-out the reusable code into one or more separate module files.
1400 =item Take the opportunity to reconsider and redesign the interfaces.
1402 =item In some cases the 'application' can then be reduced to a small
1404 fragment of code built on top of the reusable modules. In these cases
1405 the application could invoked as:
1407 % perl -e 'use Module::Name; method(@ARGV)' ...
1409 % perl -mModule::Name ... (in perl5.002 or higher)
1415 Perl does not enforce private and public parts of its modules as you may
1416 have been used to in other languages like C++, Ada, or Modula-17. Perl
1417 doesn't have an infatuation with enforced privacy. It would prefer
1418 that you stayed out of its living room because you weren't invited, not
1419 because it has a shotgun.
1421 The module and its user have a contract, part of which is common law,
1422 and part of which is "written". Part of the common law contract is
1423 that a module doesn't pollute any namespace it wasn't asked to. The
1424 written contract for the module (A.K.A. documentation) may make other
1425 provisions. But then you know when you C<use RedefineTheWorld> that
1426 you're redefining the world and willing to take the consequences.