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