This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Watch out for cross compiling for EPOC (usually done on linux)
[perl5.git] / pod / perlmodlib.PL
CommitLineData
2e1d04bc
JH
1#!../miniperl
2
3open (OUT, ">perlmodlib.tmp") or die $!;
4my (@pragma, @mod);
5open (MANIFEST, "../MANIFEST") or die $!;
6
7while (<MANIFEST>) {
8 my $filename;
9 next unless s|^lib/|| or m|^ext/|;
10 ($filename) = /(\S+)/;
11 $filename =~ s|^[^/]+/|| if $filename =~ s|^ext/||;
12 next unless $filename =~ /\.pm$/;
13 next unless open (MOD, "../lib/$filename");
14 my ($name, $thing);
15 my $foundit=0;
16 {local $/="";
17 while (<MOD>) {
18 next unless /^=head1 NAME/;
19 $foundit++;
20 last;
21 }
22 }
23 next unless $foundit;
24 my $title = <MOD>;
25 chomp($title);
26 close MOD;
27
28 my $perlname = $filename;
29 $perlname =~ s|\.pm$||;
30 $perlname =~ s|/|::|g;
31
32 ($name, $thing) = split / - /, $title,2;
33 next unless $name and $thing;
34 $thing=~s/^perl pragma to //i;
35 $thing=ucfirst($thing);
36 $title = "=item $perlname\n\n$thing\n\n";
37
38 if ($filename=~/[A-Z]/) {
39 push @mod, $title;
40 } else {
41 push @pragma, $title;
42 }
43}
44
45print OUT <<'EOF';
46=head1 NAME
47
48perlmodlib - constructing new Perl modules and finding existing ones
49
50=head1 DESCRIPTION
51
52=head1 THE PERL MODULE LIBRARY
53
54Many modules are included the Perl distribution. These are described
55below, and all end in F<.pm>. You may discover compiled library
56file (usually ending in F<.so>) or small pieces of modules to be
57autoloaded (ending in F<.al>); these were automatically generated
58by the installation process. You may also discover files in the
59library directory that end in either F<.pl> or F<.ph>. These are
60old libraries supplied so that old programs that use them still
61run. The F<.pl> files will all eventually be converted into standard
62modules, and the F<.ph> files made by B<h2ph> will probably end up
63as extension modules made by B<h2xs>. (Some F<.ph> values may
64already be available through the POSIX, Errno, or Fcntl modules.)
65The B<pl2pm> file in the distribution may help in your conversion,
66but it's just a mechanical process and therefore far from bulletproof.
67
68=head2 Pragmatic Modules
69
70They work somewhat like compiler directives (pragmata) in that they
71tend to affect the compilation of your program, and thus will usually
72work well only when used within a C<use>, or C<no>. Most of these
73are lexically scoped, so an inner BLOCK may countermand them
74by saying:
75
76 no integer;
77 no strict 'refs';
78 no warnings;
79
80which lasts until the end of that BLOCK.
81
82Some pragmas are lexically scoped--typically those that affect the
83C<$^H> hints variable. Others affect the current package instead,
84like C<use vars> and C<use subs>, which allow you to predeclare a
85variables or subroutines within a particular I<file> rather than
86just a block. Such declarations are effective for the entire file
87for which they were declared. You cannot rescind them with C<no
88vars> or C<no subs>.
89
90The following pragmas are defined (and have their own documentation).
91
92=over 12
93
94EOF
95
96print OUT $_ for (sort @pragma);
97
98print OUT <<EOF;
99=back
100
101=head2 Standard Modules
102
103Standard, bundled modules are all expected to behave in a well-defined
104manner with respect to namespace pollution because they use the
105Exporter module. See their own documentation for details.
106
107=over 12
108
109EOF
110
111print OUT $_ for (sort @mod);
112
113print OUT <<'EOF';
114=back
115
116To find out I<all> modules installed on your system, including
117those without documentation or outside the standard release,
309a139e 118just do this:
2e1d04bc
JH
119
120 % find `perl -e 'print "@INC"'` -name '*.pm' -print
121
122They should all have their own documentation installed and accessible
123via your system man(1) command. If you do not have a B<find>
124program, you can use the Perl B<find2perl> program instead, which
125generates Perl code as output you can run through perl. If you
126have a B<man> program but it doesn't find your modules, you'll have
127to fix your manpath. See L<perl> for details. If you have no
128system B<man> command, you might try the B<perldoc> program.
129
130=head2 Extension Modules
131
132Extension modules are written in C (or a mix of Perl and C). They
133are usually dynamically loaded into Perl if and when you need them,
134but may also be be linked in statically. Supported extension modules
135include Socket, Fcntl, and POSIX.
136
137Many popular C extension modules do not come bundled (at least, not
138completely) due to their sizes, volatility, or simply lack of time
139for adequate testing and configuration across the multitude of
140platforms on which Perl was beta-tested. You are encouraged to
141look for them on CPAN (described below), or using web search engines
142like Alta Vista or Deja News.
143
144=head1 CPAN
145
146CPAN stands for Comprehensive Perl Archive Network; it's a globally
147replicated trove of Perl materials, including documentation, style
148guides, tricks and traps, alternate ports to non-Unix systems and
149occasional binary distributions for these. Search engines for
150CPAN can be found at http://cpan.perl.com/ and at
151http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
152
153Most importantly, CPAN includes around a thousand unbundled modules,
154some of which require a C compiler to build. Major categories of
155modules are:
156
157=over
158
159=item *
160Language Extensions and Documentation Tools
161
162=item *
163Development Support
164
165=item *
166Operating System Interfaces
167
168=item *
169Networking, Device Control (modems) and InterProcess Communication
170
171=item *
172Data Types and Data Type Utilities
173
174=item *
175Database Interfaces
176
177=item *
178User Interfaces
179
180=item *
181Interfaces to / Emulations of Other Programming Languages
182
183=item *
184File Names, File Systems and File Locking (see also File Handles)
185
186=item *
187String Processing, Language Text Processing, Parsing, and Searching
188
189=item *
190Option, Argument, Parameter, and Configuration File Processing
191
192=item *
193Internationalization and Locale
194
195=item *
196Authentication, Security, and Encryption
197
198=item *
199World Wide Web, HTML, HTTP, CGI, MIME
200
201=item *
202Server and Daemon Utilities
203
204=item *
205Archiving and Compression
206
207=item *
208Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
209
210=item *
211Mail and Usenet News
212
213=item *
214Control Flow Utilities (callbacks and exceptions etc)
215
216=item *
217File Handle and Input/Output Stream Utilities
218
219=item *
220Miscellaneous Modules
221
222=back
223
224Registered CPAN sites as of this writing include the following.
225You should try to choose one close to you:
226
227=over
228
229=item Africa
230
231 South Africa ftp://ftp.is.co.za/programming/perl/CPAN/
232 ftp://ftp.saix.net/pub/CPAN/
233 ftp://ftp.sun.ac.za/CPAN/
234 ftp://ftpza.co.za/pub/mirrors/cpan/
235
236
237=item Asia
238
239 China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
240 Hong Kong ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
241 Indonesia ftp://malone.piksi.itb.ac.id/pub/CPAN/
242 Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
243 Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/
244 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
245 ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
246 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
247 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
248 ftp://mirror.nucba.ac.jp/mirror/Perl/
249 Saudi-Arabia ftp://ftp.isu.net.sa/pub/CPAN/
250 Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
251 South Korea ftp://ftp.bora.net/pub/CPAN/
252 ftp://ftp.kornet.net/pub/CPAN/
253 ftp://ftp.nuri.net/pub/CPAN/
254 Taiwan ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
255 ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/
256 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
257 Thailand ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
258
259
260=item Australasia
261
262 Australia ftp://cpan.topend.com.au/pub/CPAN/
263 ftp://ftp.labyrinth.net.au/pub/perl-CPAN/
264 ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
265 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
266 New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
267 ftp://sunsite.net.nz/pub/languages/perl/CPAN/
268
269
270=item Central America
271
272 Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
273
274
275=item Europe
276
277 Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
278 Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
279 Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/
280 Croatia ftp://ftp.linux.hr/pub/CPAN/
281 Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
282 ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
283 Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
284 Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/
285 Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/
286 France ftp://ftp.grolier.fr/pub/perl/CPAN/
287 ftp://ftp.lip6.fr/pub/perl/CPAN/
288 ftp://ftp.oleane.net/pub/mirrors/CPAN/
289 ftp://ftp.pasteur.fr/pub/computing/CPAN/
290 ftp://ftp.uvsq.fr/pub/perl/CPAN/
291 German ftp://ftp.gigabell.net/pub/CPAN/
292 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
293 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
294 ftp://ftp.gmd.de/packages/CPAN/
295 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
296
297ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
298 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
299 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
300 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
301 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
302 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
303 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
304 ftp://ftp.gmd.de/packages/CPAN/
305 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
306
307ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
308 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
309 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
310 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
311 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
312 Greece ftp://ftp.ntua.gr/pub/lang/perl/
313 Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
314 Iceland ftp://ftp.gm.is/pub/CPAN/
315 Ireland ftp://cpan.indigo.ie/pub/CPAN/
316 ftp://sunsite.compapp.dcu.ie/pub/perl/
317 Italy ftp://cis.uniRoma2.it/CPAN/
318 ftp://ftp.flashnet.it/pub/CPAN/
319 ftp://ftp.unina.it/pub/Other/CPAN/
320 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
321 Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/
322 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
323 Norway ftp://ftp.uit.no/pub/languages/perl/cpan/
324 ftp://sunsite.uio.no/pub/languages/perl/CPAN/
325 Poland ftp://ftp.man.torun.pl/pub/CPAN/
326 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
327 ftp://sunsite.icm.edu.pl/pub/CPAN/
328 Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
329 ftp://ftp.ist.utl.pt/pub/CPAN/
330 ftp://ftp.ua.pt/pub/CPAN/
331 Romania ftp://ftp.dnttm.ro/pub/CPAN/
332 Russia ftp://ftp.chg.ru/pub/lang/perl/CPAN/
333 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
334 Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/
335 Slovenia ftp://ftp.arnes.si/software/perl/CPAN/
336 Spain ftp://ftp.etse.urv.es/pub/perl/
337 ftp://ftp.rediris.es/mirror/CPAN/
338 Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/
339 Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
340 Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
341 United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
342 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
343
344ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
345 ftp://ftp.plig.org/pub/CPAN/
346 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
347
348
349=item North America
350
351 Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
352 California ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
353 ftp://cpan.valueclick.com/CPAN/
354 ftp://ftp.cdrom.com/pub/perl/CPAN/
355 http://download.sourceforge.net/mirrors/CPAN/
356 Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
357 Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
358 Georgia ftp://ftp.twoguys.org/CPAN/
359 Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
360 Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
361 ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
362 Kentucky ftp://ftp.uky.edu/CPAN/
363 Manitoba ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
364 Massachusetts
365ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
366 ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
367 Mexico ftp://ftp.msg.com.mx/pub/CPAN/
368 New York ftp://ftp.deao.net/pub/CPAN/
369 ftp://ftp.rge.com/pub/languages/perl/
370 North Carolina ftp://ftp.duke.edu/pub/perl/
371 Nova Scotia ftp://cpan.chebucto.ns.ca/pub/CPAN/
372 Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/
373 Ontario ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
374 Oregon ftp://ftp.orst.edu/pub/packages/CPAN/
375 Pennsylvania ftp://ftp.epix.net/pub/languages/perl/
376 Tennessee ftp://ftp.sunsite.utk.edu/pub/CPAN/
377 Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/
378 ftp://jhcloos.com/pub/mirror/CPAN/
379 Utah ftp://mirror.xmission.com/CPAN/
380 Virginia ftp://ftp.perl.org/pub/perl/CPAN/
381 ftp://ruff.cs.jmu.edu/pub/CPAN/
382 Washington ftp://ftp-mirror.internap.com/pub/CPAN/
383 ftp://ftp.llarian.net/pub/CPAN/
384 ftp://ftp.spu.edu/pub/CPAN/
385
386
387=item South America
388
389 Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/
390 ftp://ftp.matrix.com.br/pub/perl/
391 Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/
392
393=back
394
395For an up-to-date listing of CPAN sites,
396see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
397
398=head1 Modules: Creation, Use, and Abuse
399
400(The following section is borrowed directly from Tim Bunce's modules
401file, available at your nearest CPAN site.)
402
403Perl implements a class using a package, but the presence of a
404package doesn't imply the presence of a class. A package is just a
405namespace. A class is a package that provides subroutines that can be
406used as methods. A method is just a subroutine that expects, as its
407first argument, either the name of a package (for "static" methods),
408or a reference to something (for "virtual" methods).
409
410A module is a file that (by convention) provides a class of the same
411name (sans the .pm), plus an import method in that class that can be
412called to fetch exported symbols. This module may implement some of
413its methods by loading dynamic C or C++ objects, but that should be
414totally transparent to the user of the module. Likewise, the module
415might set up an AUTOLOAD function to slurp in subroutine definitions on
416demand, but this is also transparent. Only the F<.pm> file is required to
417exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
418the AUTOLOAD mechanism.
419
420=head2 Guidelines for Module Creation
421
422=over 4
423
424=item Do similar modules already exist in some form?
425
426If so, please try to reuse the existing modules either in whole or
427by inheriting useful features into a new class. If this is not
428practical try to get together with the module authors to work on
429extending or enhancing the functionality of the existing modules.
430A perfect example is the plethora of packages in perl4 for dealing
431with command line options.
432
433If you are writing a module to expand an already existing set of
434modules, please coordinate with the author of the package. It
435helps if you follow the same naming scheme and module interaction
436scheme as the original author.
437
438=item Try to design the new module to be easy to extend and reuse.
439
440Try to C<use warnings;> (or C<use warnings qw(...);>).
441Remember that you can add C<no warnings qw(...);> to individual blocks
442of code that need less warnings.
443
444Use blessed references. Use the two argument form of bless to bless
445into the class name given as the first parameter of the constructor,
446e.g.,:
447
448 sub new {
449 my $class = shift;
450 return bless {}, $class;
451 }
452
453or even this if you'd like it to be used as either a static
454or a virtual method.
455
456 sub new {
457 my $self = shift;
458 my $class = ref($self) || $self;
459 return bless {}, $class;
460 }
461
462Pass arrays as references so more parameters can be added later
463(it's also faster). Convert functions into methods where
464appropriate. Split large methods into smaller more flexible ones.
465Inherit methods from other modules if appropriate.
466
467Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
468Generally you can delete the C<eq 'FOO'> part with no harm at all.
469Let the objects look after themselves! Generally, avoid hard-wired
470class names as far as possible.
471
472Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
473C<< $r->func() >> would work (see L<perlbot> for more details).
474
475Use autosplit so little used or newly added functions won't be a
476burden to programs that don't use them. Add test functions to
477the module after __END__ either using AutoSplit or by saying:
478
479 eval join('',<main::DATA>) || die $@ unless caller();
480
481Does your module pass the 'empty subclass' test? If you say
482C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
483to use SUBCLASS in exactly the same way as YOURCLASS. For example,
484does your application still work if you change: C<$obj = new YOURCLASS;>
485into: C<$obj = new SUBCLASS;> ?
486
487Avoid keeping any state information in your packages. It makes it
488difficult for multiple other packages to use yours. Keep state
489information in objects.
490
491Always use B<-w>.
492
493Try to C<use strict;> (or C<use strict qw(...);>).
494Remember that you can add C<no strict qw(...);> to individual blocks
495of code that need less strictness.
496
497Always use B<-w>.
498
499Follow the guidelines in the perlstyle(1) manual.
500
501Always use B<-w>.
502
503=item Some simple style guidelines
504
505The perlstyle manual supplied with Perl has many helpful points.
506
507Coding style is a matter of personal taste. Many people evolve their
508style over several years as they learn what helps them write and
509maintain good code. Here's one set of assorted suggestions that
510seem to be widely used by experienced developers:
511
512Use underscores to separate words. It is generally easier to read
513$var_names_like_this than $VarNamesLikeThis, especially for
514non-native speakers of English. It's also a simple rule that works
515consistently with VAR_NAMES_LIKE_THIS.
516
517Package/Module names are an exception to this rule. Perl informally
518reserves lowercase module names for 'pragma' modules like integer
519and strict. Other modules normally begin with a capital letter and
520use mixed case with no underscores (need to be short and portable).
521
522You may find it helpful to use letter case to indicate the scope
523or nature of a variable. For example:
524
525 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
526 $Some_Caps_Here package-wide global/static
527 $no_caps_here function scope my() or local() variables
528
529Function and method names seem to work best as all lowercase.
530e.g., C<< $obj->as_string() >>.
531
532You can use a leading underscore to indicate that a variable or
533function should not be used outside the package that defined it.
534
535=item Select what to export.
536
537Do NOT export method names!
538
539Do NOT export anything else by default without a good reason!
540
541Exports pollute the namespace of the module user. If you must
542export try to use @EXPORT_OK in preference to @EXPORT and avoid
543short or common names to reduce the risk of name clashes.
544
545Generally anything not exported is still accessible from outside the
546module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
547syntax. By convention you can use a leading underscore on names to
548indicate informally that they are 'internal' and not for public use.
549
550(It is actually possible to get private functions by saying:
551C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
552directly as a method, because a method must have a name in the symbol
553table.)
554
555As a general rule, if the module is trying to be object oriented
556then export nothing. If it's just a collection of functions then
557@EXPORT_OK anything but use @EXPORT with caution.
558
559=item Select a name for the module.
560
561This name should be as descriptive, accurate, and complete as
562possible. Avoid any risk of ambiguity. Always try to use two or
563more whole words. Generally the name should reflect what is special
564about what the module does rather than how it does it. Please use
565nested module names to group informally or categorize a module.
566There should be a very good reason for a module not to have a nested name.
567Module names should begin with a capital letter.
568
569Having 57 modules all called Sort will not make life easy for anyone
570(though having 23 called Sort::Quick is only marginally better :-).
571Imagine someone trying to install your module alongside many others.
572If in any doubt ask for suggestions in comp.lang.perl.misc.
573
574If you are developing a suite of related modules/classes it's good
575practice to use nested classes with a common prefix as this will
576avoid namespace clashes. For example: Xyz::Control, Xyz::View,
577Xyz::Model etc. Use the modules in this list as a naming guide.
578
579If adding a new module to a set, follow the original author's
580standards for naming modules and the interface to methods in
581those modules.
582
4844a3be
SP
583If developing modules for private internal or project specific use,
584that will never be released to the public, then you should ensure
585that their names will not clash with any future public module. You
586can do this either by using the reserved Local::* category or by
587using a category name that includes an underscore like Foo_Corp::*.
588
2e1d04bc
JH
589To be portable each component of a module name should be limited to
59011 characters. If it might be used on MS-DOS then try to ensure each is
591unique in the first 8 characters. Nested modules make this easier.
592
593=item Have you got it right?
594
595How do you know that you've made the right decisions? Have you
596picked an interface design that will cause problems later? Have
597you picked the most appropriate name? Do you have any questions?
598
599The best way to know for sure, and pick up many helpful suggestions,
600is to ask someone who knows. Comp.lang.perl.misc is read by just about
601all the people who develop modules and it's the best place to ask.
602
603All you need to do is post a short summary of the module, its
604purpose and interfaces. A few lines on each of the main methods is
605probably enough. (If you post the whole module it might be ignored
606by busy people - generally the very people you want to read it!)
607
608Don't worry about posting if you can't say when the module will be
609ready - just say so in the message. It might be worth inviting
610others to help you, they may be able to complete it for you!
611
612=item README and other Additional Files.
613
614It's well known that software developers usually fully document the
615software they write. If, however, the world is in urgent need of
616your software and there is not enough time to write the full
617documentation please at least provide a README file containing:
618
619=over 10
620
621=item *
622A description of the module/package/extension etc.
623
624=item *
625A copyright notice - see below.
626
627=item *
628Prerequisites - what else you may need to have.
629
630=item *
631How to build it - possible changes to Makefile.PL etc.
632
633=item *
634How to install it.
635
636=item *
637Recent changes in this release, especially incompatibilities
638
639=item *
640Changes / enhancements you plan to make in the future.
641
642=back
643
644If the README file seems to be getting too large you may wish to
645split out some of the sections into separate files: INSTALL,
646Copying, ToDo etc.
647
648=over 4
649
650=item Adding a Copyright Notice.
651
652How you choose to license your work is a personal decision.
653The general mechanism is to assert your Copyright and then make
654a declaration of how others may copy/use/modify your work.
655
656Perl, for example, is supplied with two types of licence: The GNU
657GPL and The Artistic Licence (see the files README, Copying, and
658Artistic). Larry has good reasons for NOT just using the GNU GPL.
659
660My personal recommendation, out of respect for Larry, Perl, and the
661Perl community at large is to state something simply like:
662
663 Copyright (c) 1995 Your Name. All rights reserved.
664 This program is free software; you can redistribute it and/or
665 modify it under the same terms as Perl itself.
666
667This statement should at least appear in the README file. You may
668also wish to include it in a Copying file and your source files.
669Remember to include the other words in addition to the Copyright.
670
671=item Give the module a version/issue/release number.
672
673To be fully compatible with the Exporter and MakeMaker modules you
674should store your module's version number in a non-my package
675variable called $VERSION. This should be a floating point
676number with at least two digits after the decimal (i.e., hundredths,
677e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
678See L<Exporter> for details.
679
680It may be handy to add a function or method to retrieve the number.
681Use the number in announcements and archive file names when
682releasing the module (ModuleName-1.02.tar.Z).
683See perldoc ExtUtils::MakeMaker.pm for details.
684
685=item How to release and distribute a module.
686
687It's good idea to post an announcement of the availability of your
688module (or the module itself if small) to the comp.lang.perl.announce
689Usenet newsgroup. This will at least ensure very wide once-off
690distribution.
691
692If possible, register the module with CPAN. You should
693include details of its location in your announcement.
694
695Some notes about ftp archives: Please use a long descriptive file
696name that includes the version number. Most incoming directories
697will not be readable/listable, i.e., you won't be able to see your
698file after uploading it. Remember to send your email notification
699message as soon as possible after uploading else your file may get
700deleted automatically. Allow time for the file to be processed
701and/or check the file has been processed before announcing its
702location.
703
704FTP Archives for Perl Modules:
705
706Follow the instructions and links on:
707
708 http://www.perl.com/CPAN/modules/00modlist.long.html
709 http://www.perl.com/CPAN/modules/04pause.html
710
711or upload to one of these sites:
712
713 https://pause.kbx.de/pause/
714 http://pause.perl.org/pause/
715
716and notify <modules@perl.org>.
717
718By using the WWW interface you can ask the Upload Server to mirror
719your modules from your ftp or WWW site into your own directory on
720CPAN!
721
722Please remember to send me an updated entry for the Module list!
723
724=item Take care when changing a released module.
725
726Always strive to remain compatible with previous released versions.
727Otherwise try to add a mechanism to revert to the
728old behavior if people rely on it. Document incompatible changes.
729
730=back
731
732=back
733
734=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
735
736=over 4
737
738=item There is no requirement to convert anything.
739
740If it ain't broke, don't fix it! Perl 4 library scripts should
741continue to work with no problems. You may need to make some minor
742changes (like escaping non-array @'s in double quoted strings) but
743there is no need to convert a .pl file into a Module for just that.
744
745=item Consider the implications.
746
747All Perl applications that make use of the script will need to
748be changed (slightly) if the script is converted into a module. Is
749it worth it unless you plan to make other changes at the same time?
750
751=item Make the most of the opportunity.
752
753If you are going to convert the script to a module you can use the
754opportunity to redesign the interface. The guidelines for module
755creation above include many of the issues you should consider.
756
757=item The pl2pm utility will get you started.
758
759This utility will read *.pl files (given as parameters) and write
760corresponding *.pm files. The pl2pm utilities does the following:
761
762=over 10
763
764=item *
765Adds the standard Module prologue lines
766
767=item *
768Converts package specifiers from ' to ::
769
770=item *
771Converts die(...) to croak(...)
772
773=item *
774Several other minor changes
775
776=back
777
778Being a mechanical process pl2pm is not bullet proof. The converted
779code will need careful checking, especially any package statements.
780Don't delete the original .pl file till the new .pm one works!
781
782=back
783
784=head2 Guidelines for Reusing Application Code
785
786=over 4
787
788=item Complete applications rarely belong in the Perl Module Library.
789
790=item Many applications contain some Perl code that could be reused.
791
792Help save the world! Share your code in a form that makes it easy
793to reuse.
794
795=item Break-out the reusable code into one or more separate module files.
796
797=item Take the opportunity to reconsider and redesign the interfaces.
798
799=item In some cases the 'application' can then be reduced to a small
800
801fragment of code built on top of the reusable modules. In these cases
802the application could invoked as:
803
804 % perl -e 'use Module::Name; method(@ARGV)' ...
805or
806 % perl -mModule::Name ... (in perl5.002 or higher)
807
808=back
809
810=head1 NOTE
811
812Perl does not enforce private and public parts of its modules as you may
813have been used to in other languages like C++, Ada, or Modula-17. Perl
814doesn't have an infatuation with enforced privacy. It would prefer
815that you stayed out of its living room because you weren't invited, not
816because it has a shotgun.
817
818The module and its user have a contract, part of which is common law,
819and part of which is "written". Part of the common law contract is
820that a module doesn't pollute any namespace it wasn't asked to. The
821written contract for the module (A.K.A. documentation) may make other
822provisions. But then you know when you C<use RedefineTheWorld> that
823you're redefining the world and willing to take the consequences.
824EOF
825
826close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
827close OUT or warn "$0: failed to close OUT (perlmodlib.tmp): $!";
828