This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlfaq update from Tom Christiansen
[perl5.git] / pod / perlmodlib.pod
CommitLineData
f102b883
TC
1=head1 NAME
2
3perlmodlib - constructing new Perl modules and finding existing ones
4
5=head1 DESCRIPTION
6
7=head1 THE PERL MODULE LIBRARY
8
9A number of modules are included the Perl distribution. These are
10described below, and all end in F<.pm>. You may also discover files in
11the library directory that end in either F<.pl> or F<.ph>. These are old
12libraries supplied so that old programs that use them still run. The
13F<.pl> files will all eventually be converted into standard modules, and
14the F<.ph> files made by B<h2ph> will probably end up as extension modules
15made by B<h2xs>. (Some F<.ph> values may already be available through the
16POSIX module.) The B<pl2pm> file in the distribution may help in your
17conversion, but it's just a mechanical process and therefore far from
18bulletproof.
19
20=head2 Pragmatic Modules
21
22They work somewhat like pragmas in that they tend to affect the compilation of
23your program, and thus will usually work well only when used within a
f70b4f9c 24C<use>, or C<no>. Most of these are lexically scoped, so an inner BLOCK
f102b883
TC
25may countermand any of these by saying:
26
27 no integer;
28 no strict 'refs';
29
30which lasts until the end of that BLOCK.
31
32Unlike the pragmas that effect the C<$^H> hints variable, the C<use
33vars> and C<use subs> declarations are not BLOCK-scoped. They allow
34you to predeclare a variables or subroutines within a particular
35I<file> rather than just a block. Such declarations are effective
36for the entire file for which they were declared. You cannot rescind
37them with C<no vars> or C<no subs>.
38
39The following pragmas are defined (and have their own documentation).
40
41=over 12
42
43=item use autouse MODULE => qw(sub1 sub2 sub3)
44
45Defers C<require MODULE> until someone calls one of the specified
46subroutines (which must be exported by MODULE). This pragma should be
47used with caution, and only when necessary.
48
49=item blib
50
51manipulate @INC at compile time to use MakeMaker's uninstalled version
52of a package
53
54=item diagnostics
55
56force verbose warning diagnostics
57
58=item integer
59
60compute arithmetic in integer instead of double
61
62=item less
63
64request less of something from the compiler
65
66=item lib
67
68manipulate @INC at compile time
69
70=item locale
71
72use or ignore current locale for builtin operations (see L<perllocale>)
73
74=item ops
75
76restrict named opcodes when compiling or running Perl code
77
78=item overload
79
80overload basic Perl operations
81
b3eb6a9b
GS
82=item re
83
84alter behaviour of regular expressions
85
f102b883
TC
86=item sigtrap
87
88enable simple signal handling
89
90=item strict
91
92restrict unsafe constructs
93
94=item subs
95
96predeclare sub names
97
98=item vmsish
99
100adopt certain VMS-specific behaviors
101
102=item vars
103
104predeclare global variable names
105
106=back
107
108=head2 Standard Modules
109
110Standard, bundled modules are all expected to behave in a well-defined
111manner with respect to namespace pollution because they use the
112Exporter module. See their own documentation for details.
113
114=over 12
115
116=item AnyDBM_File
117
118provide framework for multiple DBMs
119
120=item AutoLoader
121
122load functions only on demand
123
124=item AutoSplit
125
126split a package for autoloading
127
128=item Benchmark
129
130benchmark running times of code
131
132=item CPAN
133
134interface to Comprehensive Perl Archive Network
135
136=item CPAN::FirstTime
137
138create a CPAN configuration file
139
140=item CPAN::Nox
141
142run CPAN while avoiding compiled extensions
143
144=item Carp
145
146warn of errors (from perspective of caller)
147
148=item Class::Struct
149
150declare struct-like datatypes
151
152=item Config
153
154access Perl configuration information
155
156=item Cwd
157
158get pathname of current working directory
159
160=item DB_File
161
162access to Berkeley DB
163
f505c983
GS
164=item Devel::Peek
165
166data debugging tool for the XS programmer
167
f102b883
TC
168=item Devel::SelfStubber
169
170generate stubs for a SelfLoading module
171
172=item DirHandle
173
174supply object methods for directory handles
175
176=item DynaLoader
177
178dynamically load C libraries into Perl code
179
180=item English
181
182use nice English (or awk) names for ugly punctuation variables
183
184=item Env
185
186import environment variables
187
188=item Exporter
189
190implements default import method for modules
191
192=item ExtUtils::Embed
193
194utilities for embedding Perl in C/C++ applications
195
196=item ExtUtils::Install
197
198install files from here to there
199
200=item ExtUtils::Liblist
201
202determine libraries to use and how to use them
203
204=item ExtUtils::MM_OS2
205
206methods to override Unix behaviour in ExtUtils::MakeMaker
207
208=item ExtUtils::MM_Unix
209
210methods used by ExtUtils::MakeMaker
211
212=item ExtUtils::MM_VMS
213
214methods to override Unix behaviour in ExtUtils::MakeMaker
215
216=item ExtUtils::MakeMaker
217
218create an extension Makefile
219
220=item ExtUtils::Manifest
221
222utilities to write and check a MANIFEST file
223
224=item ExtUtils::Mkbootstrap
225
226make a bootstrap file for use by DynaLoader
227
228=item ExtUtils::Mksymlists
229
230write linker options files for dynamic extension
231
232=item ExtUtils::testlib
233
234add blib/* directories to @INC
235
b6c543e3
IZ
236=item Fatal
237
238make errors in builtins or Perl functions fatal
239
f102b883
TC
240=item Fcntl
241
242load the C Fcntl.h defines
243
244=item File::Basename
245
246split a pathname into pieces
247
248=item File::CheckTree
249
250run many filetest checks on a tree
251
252=item File::Compare
253
254compare files or filehandles
255
256=item File::Copy
257
258copy files or filehandles
259
260=item File::Find
261
262traverse a file tree
263
264=item File::Path
265
266create or remove a series of directories
267
f505c983
GS
268=item File::Spec
269
270portably perform operations on file names
271
272=item File::Spec::Functions
273
274function call interface to File::Spec module
275
f102b883
TC
276=item File::stat
277
278by-name interface to Perl's builtin stat() functions
279
280=item FileCache
281
282keep more files open than the system permits
283
284=item FileHandle
285
286supply object methods for filehandles
287
288=item FindBin
289
5a964f20 290locate directory of original Perl script
f102b883
TC
291
292=item GDBM_File
293
294access to the gdbm library
295
296=item Getopt::Long
297
298extended processing of command line options
299
300=item Getopt::Std
301
302process single-character switches with switch clustering
303
304=item I18N::Collate
305
306compare 8-bit scalar data according to the current locale
307
308=item IO
309
310load various IO modules
311
312=item IO::File
313
314supply object methods for filehandles
315
316=item IO::Handle
317
318supply object methods for I/O handles
319
320=item IO::Pipe
321
322supply object methods for pipes
323
324=item IO::Seekable
325
326supply seek based methods for I/O objects
327
328=item IO::Select
329
330OO interface to the select system call
331
332=item IO::Socket
333
334object interface to socket communications
335
336=item IPC::Open2
337
338open a process for both reading and writing
339
340=item IPC::Open3
341
342open a process for reading, writing, and error handling
343
344=item Math::BigFloat
345
346arbitrary length float math package
347
348=item Math::BigInt
349
350arbitrary size integer math package
351
352=item Math::Complex
353
354complex numbers and associated mathematical functions
355
404b15a1
CS
356=item Math::Trig
357
358simple interface to parts of Math::Complex for those who
359need trigonometric functions only for real numbers
360
f102b883
TC
361=item NDBM_File
362
363tied access to ndbm files
364
365=item Net::Ping
366
367Hello, anybody home?
368
369=item Net::hostent
370
371by-name interface to Perl's builtin gethost*() functions
372
373=item Net::netent
374
375by-name interface to Perl's builtin getnet*() functions
376
377=item Net::protoent
378
379by-name interface to Perl's builtin getproto*() functions
380
381=item Net::servent
382
383by-name interface to Perl's builtin getserv*() functions
384
385=item Opcode
386
5a964f20 387disable named opcodes when compiling or running Perl code
f102b883
TC
388
389=item Pod::Text
390
391convert POD data to formatted ASCII text
392
393=item POSIX
394
395interface to IEEE Standard 1003.1
396
397=item SDBM_File
398
399tied access to sdbm files
400
401=item Safe
402
403compile and execute code in restricted compartments
404
405=item Search::Dict
406
407search for key in dictionary file
408
409=item SelectSaver
410
411save and restore selected file handle
412
413=item SelfLoader
414
415load functions only on demand
416
417=item Shell
418
5a964f20 419run shell commands transparently within Perl
f102b883
TC
420
421=item Socket
422
423load the C socket.h defines and structure manipulators
424
425=item Symbol
426
427manipulate Perl symbols and their names
428
429=item Sys::Hostname
430
431try every conceivable way to get hostname
432
433=item Sys::Syslog
434
435interface to the Unix syslog(3) calls
436
437=item Term::Cap
438
439termcap interface
440
441=item Term::Complete
442
443word completion module
444
445=item Term::ReadLine
446
447interface to various C<readline> packages
448
449=item Test::Harness
450
5a964f20 451run Perl standard test scripts with statistics
f102b883
TC
452
453=item Text::Abbrev
454
455create an abbreviation table from a list
456
457=item Text::ParseWords
458
459parse text into an array of tokens
460
461=item Text::Soundex
462
463implementation of the Soundex Algorithm as described by Knuth
464
465=item Text::Tabs
466
467expand and unexpand tabs per the Unix expand(1) and unexpand(1)
468
469=item Text::Wrap
470
471line wrapping to form simple paragraphs
472
473=item Tie::Hash
474
475base class definitions for tied hashes
476
477=item Tie::RefHash
478
479base class definitions for tied hashes with references as keys
480
481=item Tie::Scalar
482
483base class definitions for tied scalars
484
485=item Tie::SubstrHash
486
487fixed-table-size, fixed-key-length hashing
488
489=item Time::Local
490
491efficiently compute time from local and GMT time
492
493=item Time::gmtime
494
495by-name interface to Perl's builtin gmtime() function
496
497=item Time::localtime
498
499by-name interface to Perl's builtin localtime() function
500
501=item Time::tm
502
503internal object used by Time::gmtime and Time::localtime
504
505=item UNIVERSAL
506
507base class for ALL classes (blessed references)
508
509=item User::grent
510
511by-name interface to Perl's builtin getgr*() functions
512
513=item User::pwent
514
515by-name interface to Perl's builtin getpw*() functions
516
517=back
518
519To find out I<all> the modules installed on your system, including
520those without documentation or outside the standard release, do this:
521
5a964f20 522 % find `perl -e 'print "@INC"'` -name '*.pm' -print
f102b883
TC
523
524They should all have their own documentation installed and accessible via
525your system man(1) command. If that fails, try the I<perldoc> program.
526
527=head2 Extension Modules
528
529Extension modules are written in C (or a mix of Perl and C) and may be
530statically linked or in general are
531dynamically loaded into Perl if and when you need them. Supported
532extension modules include the Socket, Fcntl, and POSIX modules.
533
534Many popular C extension modules do not come bundled (at least, not
535completely) due to their sizes, volatility, or simply lack of time for
536adequate testing and configuration across the multitude of platforms on
537which Perl was beta-tested. You are encouraged to look for them in
538archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
539authors before randomly posting asking for their present condition and
540disposition.
541
542=head1 CPAN
543
544CPAN stands for the Comprehensive Perl Archive Network. This is a globally
545replicated collection of all known Perl materials, including hundreds
546of unbundled modules. Here are the major categories of modules:
547
548=over
549
550=item *
551Language Extensions and Documentation Tools
552
553=item *
554Development Support
555
556=item *
557Operating System Interfaces
558
559=item *
560Networking, Device Control (modems) and InterProcess Communication
561
562=item *
563Data Types and Data Type Utilities
564
565=item *
566Database Interfaces
567
568=item *
569User Interfaces
570
571=item *
572Interfaces to / Emulations of Other Programming Languages
573
574=item *
575File Names, File Systems and File Locking (see also File Handles)
576
577=item *
578String Processing, Language Text Processing, Parsing, and Searching
579
580=item *
581Option, Argument, Parameter, and Configuration File Processing
582
583=item *
584Internationalization and Locale
585
586=item *
587Authentication, Security, and Encryption
588
589=item *
590World Wide Web, HTML, HTTP, CGI, MIME
591
592=item *
593Server and Daemon Utilities
594
595=item *
596Archiving and Compression
597
598=item *
599Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
600
601=item *
602Mail and Usenet News
603
604=item *
605Control Flow Utilities (callbacks and exceptions etc)
606
607=item *
608File Handle and Input/Output Stream Utilities
609
610=item *
611Miscellaneous Modules
612
613=back
614
615The registered CPAN sites as of this writing include the following.
616You should try to choose one close to you:
617
618=over
619
620=item *
621Africa
622
be94a901
GS
623 South Africa ftp://ftp.is.co.za/programming/perl/CPAN/
624 ftp://ftpza.co.za/pub/mirrors/cpan/
f102b883
TC
625
626=item *
627Asia
628
be94a901
GS
629 Armenia ftp://sunsite.aua.am/pub/CPAN/
630 China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
631 Hong Kong ftp://ftp.hkstar.com/pub/CPAN/
632 Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
633 Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/
634 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
635 ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
636 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
637 ftp://mirror.nucba.ac.jp/mirror/Perl/
638 Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
639 South Korea ftp://ftp.bora.net/pub/CPAN/
640 ftp://ftp.nuri.net/pub/CPAN/
641 Taiwan ftp://ftp.wownet.net/pub2/PERL/
642 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
643 Thailand ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
644 ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
f102b883
TC
645
646=item *
647Australasia
648
be94a901
GS
649 Australia ftp://cpan.topend.com.au/pub/CPAN/
650 ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
651 ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
652 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
653 New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
654 ftp://sunsite.net.nz/pub/languages/perl/CPAN/
655
656=item *
657Central America
658
659 Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
f102b883
TC
660
661=item *
662Europe
663
be94a901
GS
664 Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
665 Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
666 Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/
667 Croatia ftp://ftp.linux.hr/pub/CPAN/
668 Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
669 ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
670 Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
671 Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/
672 Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/
673 France ftp://ftp.lip6.fr/pub/perl/CPAN/
674 ftp://ftp.oleane.net/pub/mirrors/CPAN/
675 ftp://ftp.pasteur.fr/pub/computing/CPAN/
676 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
677 ftp://ftp.gmd.de/packages/CPAN/
678 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
679 ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/
680 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
681 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
682 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
683 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
684 Greece ftp://ftp.ntua.gr/pub/lang/perl/
685 Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
686 Ireland ftp://sunsite.compapp.dcu.ie/pub/perl/
687 Italy ftp://cis.uniRoma2.it/CPAN/
688 ftp://ftp.flashnet.it/pub/CPAN/
689 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
690 Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/
691 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
692 Norway ftp://ftp.uit.no/pub/languages/perl/cpan/
693 ftp://sunsite.uio.no/pub/languages/perl/CPAN/
694 Poland ftp://ftp.man.szczecin.pl/pub/perl/CPAN/
695 ftp://ftp.man.torun.pl/pub/doc/CPAN/
696 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
697 ftp://sunsite.icm.edu.pl/pub/CPAN/
698 Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
699 ftp://ftp.ua.pt/pub/CPAN/
700 Romania ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
701 ftp://ftp.dnttm.ro/pub/CPAN/
702 Russia ftp://cpan.npi.msu.su/CPAN/
703 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
704 Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/
705 Slovenia ftp://ftp.arnes.si/software/perl/CPAN/
706 Spain ftp://ftp.etse.urv.es/pub/perl/
707 ftp://ftp.rediris.es/mirror/CPAN/
708 Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/
709 Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
710 Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
711 United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
712 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
713 ftp://ftp.plig.org/pub/CPAN/
714 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
715 ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
f102b883
TC
716
717=item *
718North America
719
be94a901
GS
720 Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
721 California ftp://ftp.cdrom.com/pub/perl/CPAN/
722 ftp://ftp.digital.com/pub/plan/perl/CPAN/
723 Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
724 Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
725 Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
726 Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
727 ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
728 Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/
729 Massachusetts ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
730 ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
731 Mexico D.F. ftp://ftp.msg.com.mx/pub/CPAN/
732 New York ftp://ftp.rge.com/pub/languages/perl/
733 North Carolina ftp://ftp.duke.edu/pub/perl/
734 Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/
735 Ontario ftp://ftp.crc.ca/pub/packages/perl/CPAN/
736 Oregon ftp://ftp.orst.edu/pub/packages/CPAN/
737 Pennsylvania ftp://ftp.epix.net/pub/languages/perl/
738 Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/
739 Utah ftp://mirror.xmission.com/CPAN/
740 Virginia ftp://ftp.perl.org/pub/perl/CPAN/
741 ftp://ruff.cs.jmu.edu/pub/CPAN/
742 Washington ftp://ftp.spu.edu/pub/CPAN/
f102b883
TC
743
744=item *
745South America
746
be94a901
GS
747 Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/
748 Chile ftp://ftp.ing.puc.cl/pub/unix/perl/CPAN/
749 ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
f102b883
TC
750
751=back
752
753For an up-to-date listing of CPAN sites,
754see F<http://www.perl.com/perl/CPAN> or F<ftp://ftp.perl.com/perl/>.
755
756=head1 Modules: Creation, Use, and Abuse
757
758(The following section is borrowed directly from Tim Bunce's modules
759file, available at your nearest CPAN site.)
760
761Perl implements a class using a package, but the presence of a
762package doesn't imply the presence of a class. A package is just a
763namespace. A class is a package that provides subroutines that can be
764used as methods. A method is just a subroutine that expects, as its
765first argument, either the name of a package (for "static" methods),
766or a reference to something (for "virtual" methods).
767
768A module is a file that (by convention) provides a class of the same
769name (sans the .pm), plus an import method in that class that can be
770called to fetch exported symbols. This module may implement some of
771its methods by loading dynamic C or C++ objects, but that should be
772totally transparent to the user of the module. Likewise, the module
773might set up an AUTOLOAD function to slurp in subroutine definitions on
774demand, but this is also transparent. Only the F<.pm> file is required to
775exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
776the AUTOLOAD mechanism.
777
778=head2 Guidelines for Module Creation
779
780=over 4
781
782=item Do similar modules already exist in some form?
783
784If so, please try to reuse the existing modules either in whole or
785by inheriting useful features into a new class. If this is not
786practical try to get together with the module authors to work on
787extending or enhancing the functionality of the existing modules.
788A perfect example is the plethora of packages in perl4 for dealing
789with command line options.
790
791If you are writing a module to expand an already existing set of
792modules, please coordinate with the author of the package. It
793helps if you follow the same naming scheme and module interaction
794scheme as the original author.
795
796=item Try to design the new module to be easy to extend and reuse.
797
798Use blessed references. Use the two argument form of bless to bless
799into the class name given as the first parameter of the constructor,
800e.g.,:
801
802 sub new {
803 my $class = shift;
804 return bless {}, $class;
805 }
806
807or even this if you'd like it to be used as either a static
808or a virtual method.
809
810 sub new {
811 my $self = shift;
812 my $class = ref($self) || $self;
813 return bless {}, $class;
814 }
815
816Pass arrays as references so more parameters can be added later
817(it's also faster). Convert functions into methods where
818appropriate. Split large methods into smaller more flexible ones.
819Inherit methods from other modules if appropriate.
820
821Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
822Generally you can delete the "C<eq 'FOO'>" part with no harm at all.
823Let the objects look after themselves! Generally, avoid hard-wired
824class names as far as possible.
825
826Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
827C<$r-E<gt>func()> would work (see L<perlbot> for more details).
828
829Use autosplit so little used or newly added functions won't be a
5a964f20 830burden to programs that don't use them. Add test functions to
f102b883
TC
831the module after __END__ either using AutoSplit or by saying:
832
833 eval join('',<main::DATA>) || die $@ unless caller();
834
835Does your module pass the 'empty subclass' test? If you say
836"C<@SUBCLASS::ISA = qw(YOURCLASS);>" your applications should be able
837to use SUBCLASS in exactly the same way as YOURCLASS. For example,
838does your application still work if you change: C<$obj = new YOURCLASS;>
839into: C<$obj = new SUBCLASS;> ?
840
841Avoid keeping any state information in your packages. It makes it
842difficult for multiple other packages to use yours. Keep state
843information in objects.
844
845Always use B<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
846Remember that you can add C<no strict qw(...);> to individual blocks
5a964f20 847of code that need less strictness. Always use B<-w>. Always use B<-w>!
f102b883
TC
848Follow the guidelines in the perlstyle(1) manual.
849
850=item Some simple style guidelines
851
5a964f20 852The perlstyle manual supplied with Perl has many helpful points.
f102b883
TC
853
854Coding style is a matter of personal taste. Many people evolve their
855style over several years as they learn what helps them write and
856maintain good code. Here's one set of assorted suggestions that
857seem to be widely used by experienced developers:
858
859Use underscores to separate words. It is generally easier to read
860$var_names_like_this than $VarNamesLikeThis, especially for
861non-native speakers of English. It's also a simple rule that works
862consistently with VAR_NAMES_LIKE_THIS.
863
864Package/Module names are an exception to this rule. Perl informally
865reserves lowercase module names for 'pragma' modules like integer
866and strict. Other modules normally begin with a capital letter and
867use mixed case with no underscores (need to be short and portable).
868
869You may find it helpful to use letter case to indicate the scope
870or nature of a variable. For example:
871
5a964f20 872 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
f102b883
TC
873 $Some_Caps_Here package-wide global/static
874 $no_caps_here function scope my() or local() variables
875
876Function and method names seem to work best as all lowercase.
877e.g., C<$obj-E<gt>as_string()>.
878
879You can use a leading underscore to indicate that a variable or
880function should not be used outside the package that defined it.
881
882=item Select what to export.
883
884Do NOT export method names!
885
886Do NOT export anything else by default without a good reason!
887
888Exports pollute the namespace of the module user. If you must
889export try to use @EXPORT_OK in preference to @EXPORT and avoid
890short or common names to reduce the risk of name clashes.
891
892Generally anything not exported is still accessible from outside the
893module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
894syntax. By convention you can use a leading underscore on names to
895indicate informally that they are 'internal' and not for public use.
896
897(It is actually possible to get private functions by saying:
898C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
899directly as a method, because a method must have a name in the symbol
900table.)
901
902As a general rule, if the module is trying to be object oriented
903then export nothing. If it's just a collection of functions then
904@EXPORT_OK anything but use @EXPORT with caution.
905
906=item Select a name for the module.
907
908This name should be as descriptive, accurate, and complete as
909possible. Avoid any risk of ambiguity. Always try to use two or
910more whole words. Generally the name should reflect what is special
911about what the module does rather than how it does it. Please use
912nested module names to group informally or categorize a module.
913There should be a very good reason for a module not to have a nested name.
914Module names should begin with a capital letter.
915
916Having 57 modules all called Sort will not make life easy for anyone
917(though having 23 called Sort::Quick is only marginally better :-).
918Imagine someone trying to install your module alongside many others.
919If in any doubt ask for suggestions in comp.lang.perl.misc.
920
921If you are developing a suite of related modules/classes it's good
922practice to use nested classes with a common prefix as this will
923avoid namespace clashes. For example: Xyz::Control, Xyz::View,
924Xyz::Model etc. Use the modules in this list as a naming guide.
925
926If adding a new module to a set, follow the original author's
927standards for naming modules and the interface to methods in
928those modules.
929
930To be portable each component of a module name should be limited to
93111 characters. If it might be used on MS-DOS then try to ensure each is
932unique in the first 8 characters. Nested modules make this easier.
933
934=item Have you got it right?
935
936How do you know that you've made the right decisions? Have you
937picked an interface design that will cause problems later? Have
938you picked the most appropriate name? Do you have any questions?
939
940The best way to know for sure, and pick up many helpful suggestions,
941is to ask someone who knows. Comp.lang.perl.misc is read by just about
942all the people who develop modules and it's the best place to ask.
943
944All you need to do is post a short summary of the module, its
945purpose and interfaces. A few lines on each of the main methods is
946probably enough. (If you post the whole module it might be ignored
947by busy people - generally the very people you want to read it!)
948
949Don't worry about posting if you can't say when the module will be
950ready - just say so in the message. It might be worth inviting
951others to help you, they may be able to complete it for you!
952
953=item README and other Additional Files.
954
955It's well known that software developers usually fully document the
956software they write. If, however, the world is in urgent need of
957your software and there is not enough time to write the full
958documentation please at least provide a README file containing:
959
960=over 10
961
962=item *
963A description of the module/package/extension etc.
964
965=item *
966A copyright notice - see below.
967
968=item *
969Prerequisites - what else you may need to have.
970
971=item *
972How to build it - possible changes to Makefile.PL etc.
973
974=item *
975How to install it.
976
977=item *
978Recent changes in this release, especially incompatibilities
979
980=item *
981Changes / enhancements you plan to make in the future.
982
983=back
984
985If the README file seems to be getting too large you may wish to
986split out some of the sections into separate files: INSTALL,
987Copying, ToDo etc.
988
989=over 4
990
991=item Adding a Copyright Notice.
992
993How you choose to license your work is a personal decision.
994The general mechanism is to assert your Copyright and then make
995a declaration of how others may copy/use/modify your work.
996
997Perl, for example, is supplied with two types of licence: The GNU
998GPL and The Artistic Licence (see the files README, Copying, and
999Artistic). Larry has good reasons for NOT just using the GNU GPL.
1000
1001My personal recommendation, out of respect for Larry, Perl, and the
5a964f20 1002Perl community at large is to state something simply like:
f102b883
TC
1003
1004 Copyright (c) 1995 Your Name. All rights reserved.
1005 This program is free software; you can redistribute it and/or
1006 modify it under the same terms as Perl itself.
1007
1008This statement should at least appear in the README file. You may
1009also wish to include it in a Copying file and your source files.
1010Remember to include the other words in addition to the Copyright.
1011
1012=item Give the module a version/issue/release number.
1013
1014To be fully compatible with the Exporter and MakeMaker modules you
1015should store your module's version number in a non-my package
1016variable called $VERSION. This should be a floating point
1017number with at least two digits after the decimal (i.e., hundredths,
1018e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1019See Exporter.pm in Perl5.001m or later for details.
1020
1021It may be handy to add a function or method to retrieve the number.
1022Use the number in announcements and archive file names when
1023releasing the module (ModuleName-1.02.tar.Z).
1024See perldoc ExtUtils::MakeMaker.pm for details.
1025
1026=item How to release and distribute a module.
1027
1028It's good idea to post an announcement of the availability of your
1029module (or the module itself if small) to the comp.lang.perl.announce
1030Usenet newsgroup. This will at least ensure very wide once-off
1031distribution.
1032
1033If possible you should place the module into a major ftp archive and
1034include details of its location in your announcement.
1035
1036Some notes about ftp archives: Please use a long descriptive file
5a964f20 1037name that includes the version number. Most incoming directories
f102b883
TC
1038will not be readable/listable, i.e., you won't be able to see your
1039file after uploading it. Remember to send your email notification
1040message as soon as possible after uploading else your file may get
1041deleted automatically. Allow time for the file to be processed
1042and/or check the file has been processed before announcing its
1043location.
1044
1045FTP Archives for Perl Modules:
1046
1047Follow the instructions and links on
1048
1049 http://franz.ww.tu-berlin.de/modulelist
1050
1051or upload to one of these sites:
1052
1053 ftp://franz.ww.tu-berlin.de/incoming
1054 ftp://ftp.cis.ufl.edu/incoming
1055
1056and notify <F<upload@franz.ww.tu-berlin.de>>.
1057
1058By using the WWW interface you can ask the Upload Server to mirror
1059your modules from your ftp or WWW site into your own directory on
1060CPAN!
1061
1062Please remember to send me an updated entry for the Module list!
1063
1064=item Take care when changing a released module.
1065
7b8d334a
GS
1066Always strive to remain compatible with previous released versions.
1067Otherwise try to add a mechanism to revert to the
f102b883
TC
1068old behaviour if people rely on it. Document incompatible changes.
1069
1070=back
1071
1072=back
1073
1074=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1075
1076=over 4
1077
1078=item There is no requirement to convert anything.
1079
1080If it ain't broke, don't fix it! Perl 4 library scripts should
1081continue to work with no problems. You may need to make some minor
1082changes (like escaping non-array @'s in double quoted strings) but
1083there is no need to convert a .pl file into a Module for just that.
1084
1085=item Consider the implications.
1086
5a964f20 1087All Perl applications that make use of the script will need to
f102b883
TC
1088be changed (slightly) if the script is converted into a module. Is
1089it worth it unless you plan to make other changes at the same time?
1090
1091=item Make the most of the opportunity.
1092
1093If you are going to convert the script to a module you can use the
1094opportunity to redesign the interface. The 'Guidelines for Module
1095Creation' above include many of the issues you should consider.
1096
1097=item The pl2pm utility will get you started.
1098
1099This utility will read *.pl files (given as parameters) and write
1100corresponding *.pm files. The pl2pm utilities does the following:
1101
1102=over 10
1103
1104=item *
1105Adds the standard Module prologue lines
1106
1107=item *
1108Converts package specifiers from ' to ::
1109
1110=item *
1111Converts die(...) to croak(...)
1112
1113=item *
1114Several other minor changes
1115
1116=back
1117
1118Being a mechanical process pl2pm is not bullet proof. The converted
1119code will need careful checking, especially any package statements.
1120Don't delete the original .pl file till the new .pm one works!
1121
1122=back
1123
1124=head2 Guidelines for Reusing Application Code
1125
1126=over 4
1127
1128=item Complete applications rarely belong in the Perl Module Library.
1129
5a964f20 1130=item Many applications contain some Perl code that could be reused.
f102b883
TC
1131
1132Help save the world! Share your code in a form that makes it easy
1133to reuse.
1134
1135=item Break-out the reusable code into one or more separate module files.
1136
1137=item Take the opportunity to reconsider and redesign the interfaces.
1138
1139=item In some cases the 'application' can then be reduced to a small
1140
1141fragment of code built on top of the reusable modules. In these cases
1142the application could invoked as:
1143
5a964f20 1144 % perl -e 'use Module::Name; method(@ARGV)' ...
f102b883 1145or
5a964f20 1146 % perl -mModule::Name ... (in perl5.002 or higher)
f102b883
TC
1147
1148=back
1149
1150=head1 NOTE
1151
1152Perl does not enforce private and public parts of its modules as you may
1153have been used to in other languages like C++, Ada, or Modula-17. Perl
1154doesn't have an infatuation with enforced privacy. It would prefer
1155that you stayed out of its living room because you weren't invited, not
1156because it has a shotgun.
1157
1158The module and its user have a contract, part of which is common law,
1159and part of which is "written". Part of the common law contract is
1160that a module doesn't pollute any namespace it wasn't asked to. The
1161written contract for the module (A.K.A. documentation) may make other
1162provisions. But then you know when you C<use RedefineTheWorld> that
1163you're redefining the world and willing to take the consequences.