3 open (OUT, ">perlmodlib.tmp") or die $!;
5 open (MANIFEST, "../MANIFEST") or die $!;
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");
18 next unless /^=head1 NAME/;
28 my $perlname = $filename;
29 $perlname =~ s|\.pm$||;
30 $perlname =~ s|/|::|g;
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";
38 if ($filename=~/[A-Z]/) {
48 perlmodlib - constructing new Perl modules and finding existing ones
52 =head1 THE PERL MODULE LIBRARY
54 Many modules are included the Perl distribution. These are described
55 below, and all end in F<.pm>. You may discover compiled library
56 file (usually ending in F<.so>) or small pieces of modules to be
57 autoloaded (ending in F<.al>); these were automatically generated
58 by the installation process. You may also discover files in the
59 library directory that end in either F<.pl> or F<.ph>. These are
60 old libraries supplied so that old programs that use them still
61 run. The F<.pl> files will all eventually be converted into standard
62 modules, and the F<.ph> files made by B<h2ph> will probably end up
63 as extension modules made by B<h2xs>. (Some F<.ph> values may
64 already be available through the POSIX, Errno, or Fcntl modules.)
65 The B<pl2pm> file in the distribution may help in your conversion,
66 but it's just a mechanical process and therefore far from bulletproof.
68 =head2 Pragmatic Modules
70 They work somewhat like compiler directives (pragmata) in that they
71 tend to affect the compilation of your program, and thus will usually
72 work well only when used within a C<use>, or C<no>. Most of these
73 are lexically scoped, so an inner BLOCK may countermand them
80 which lasts until the end of that BLOCK.
82 Some pragmas are lexically scoped--typically those that affect the
83 C<$^H> hints variable. Others affect the current package instead,
84 like C<use vars> and C<use subs>, which allow you to predeclare a
85 variables or subroutines within a particular I<file> rather than
86 just a block. Such declarations are effective for the entire file
87 for which they were declared. You cannot rescind them with C<no
90 The following pragmas are defined (and have their own documentation).
96 print OUT $_ for (sort @pragma);
101 =head2 Standard Modules
103 Standard, bundled modules are all expected to behave in a well-defined
104 manner with respect to namespace pollution because they use the
105 Exporter module. See their own documentation for details.
111 print OUT $_ for (sort @mod);
116 To find out I<all> modules installed on your system, including
117 those without documentation or outside the standard release,
120 % find `perl -e 'print "@INC"'` -name '*.pm' -print
122 They should all have their own documentation installed and accessible
123 via your system man(1) command. If you do not have a B<find>
124 program, you can use the Perl B<find2perl> program instead, which
125 generates Perl code as output you can run through perl. If you
126 have a B<man> program but it doesn't find your modules, you'll have
127 to fix your manpath. See L<perl> for details. If you have no
128 system B<man> command, you might try the B<perldoc> program.
130 =head2 Extension Modules
132 Extension modules are written in C (or a mix of Perl and C). They
133 are usually dynamically loaded into Perl if and when you need them,
134 but may also be be linked in statically. Supported extension modules
135 include Socket, Fcntl, and POSIX.
137 Many popular C extension modules do not come bundled (at least, not
138 completely) due to their sizes, volatility, or simply lack of time
139 for adequate testing and configuration across the multitude of
140 platforms on which Perl was beta-tested. You are encouraged to
141 look for them on CPAN (described below), or using web search engines
142 like Alta Vista or Deja News.
146 CPAN stands for Comprehensive Perl Archive Network; it's a globally
147 replicated trove of Perl materials, including documentation, style
148 guides, tricks and traps, alternate ports to non-Unix systems and
149 occasional binary distributions for these. Search engines for
150 CPAN can be found at http://cpan.perl.com/ and at
151 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
153 Most importantly, CPAN includes around a thousand unbundled modules,
154 some of which require a C compiler to build. Major categories of
160 Language Extensions and Documentation Tools
166 Operating System Interfaces
169 Networking, Device Control (modems) and InterProcess Communication
172 Data Types and Data Type Utilities
181 Interfaces to / Emulations of Other Programming Languages
184 File Names, File Systems and File Locking (see also File Handles)
187 String Processing, Language Text Processing, Parsing, and Searching
190 Option, Argument, Parameter, and Configuration File Processing
193 Internationalization and Locale
196 Authentication, Security, and Encryption
199 World Wide Web, HTML, HTTP, CGI, MIME
202 Server and Daemon Utilities
205 Archiving and Compression
208 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
214 Control Flow Utilities (callbacks and exceptions etc)
217 File Handle and Input/Output Stream Utilities
220 Miscellaneous Modules
224 Registered CPAN sites as of this writing include the following.
225 You should try to choose one close to you:
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/
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/
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/
270 =item Central America
272 Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
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/
297 ftp://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/
307 ftp://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/
344 ftp://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/
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/
365 ftp://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/
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/
395 For an up-to-date listing of CPAN sites,
396 see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
398 =head1 Modules: Creation, Use, and Abuse
400 (The following section is borrowed directly from Tim Bunce's modules
401 file, available at your nearest CPAN site.)
403 Perl implements a class using a package, but the presence of a
404 package doesn't imply the presence of a class. A package is just a
405 namespace. A class is a package that provides subroutines that can be
406 used as methods. A method is just a subroutine that expects, as its
407 first argument, either the name of a package (for "static" methods),
408 or a reference to something (for "virtual" methods).
410 A module is a file that (by convention) provides a class of the same
411 name (sans the .pm), plus an import method in that class that can be
412 called to fetch exported symbols. This module may implement some of
413 its methods by loading dynamic C or C++ objects, but that should be
414 totally transparent to the user of the module. Likewise, the module
415 might set up an AUTOLOAD function to slurp in subroutine definitions on
416 demand, but this is also transparent. Only the F<.pm> file is required to
417 exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
418 the AUTOLOAD mechanism.
420 =head2 Guidelines for Module Creation
424 =item Do similar modules already exist in some form?
426 If so, please try to reuse the existing modules either in whole or
427 by inheriting useful features into a new class. If this is not
428 practical try to get together with the module authors to work on
429 extending or enhancing the functionality of the existing modules.
430 A perfect example is the plethora of packages in perl4 for dealing
431 with command line options.
433 If you are writing a module to expand an already existing set of
434 modules, please coordinate with the author of the package. It
435 helps if you follow the same naming scheme and module interaction
436 scheme as the original author.
438 =item Try to design the new module to be easy to extend and reuse.
440 Try to C<use warnings;> (or C<use warnings qw(...);>).
441 Remember that you can add C<no warnings qw(...);> to individual blocks
442 of code that need less warnings.
444 Use blessed references. Use the two argument form of bless to bless
445 into the class name given as the first parameter of the constructor,
450 return bless {}, $class;
453 or even this if you'd like it to be used as either a static
458 my $class = ref($self) || $self;
459 return bless {}, $class;
462 Pass arrays as references so more parameters can be added later
463 (it's also faster). Convert functions into methods where
464 appropriate. Split large methods into smaller more flexible ones.
465 Inherit methods from other modules if appropriate.
467 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
468 Generally you can delete the C<eq 'FOO'> part with no harm at all.
469 Let the objects look after themselves! Generally, avoid hard-wired
470 class names as far as possible.
472 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
473 C<< $r->func() >> would work (see L<perlbot> for more details).
475 Use autosplit so little used or newly added functions won't be a
476 burden to programs that don't use them. Add test functions to
477 the module after __END__ either using AutoSplit or by saying:
479 eval join('',<main::DATA>) || die $@ unless caller();
481 Does your module pass the 'empty subclass' test? If you say
482 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
483 to use SUBCLASS in exactly the same way as YOURCLASS. For example,
484 does your application still work if you change: C<$obj = new YOURCLASS;>
485 into: C<$obj = new SUBCLASS;> ?
487 Avoid keeping any state information in your packages. It makes it
488 difficult for multiple other packages to use yours. Keep state
489 information in objects.
493 Try to C<use strict;> (or C<use strict qw(...);>).
494 Remember that you can add C<no strict qw(...);> to individual blocks
495 of code that need less strictness.
499 Follow the guidelines in the perlstyle(1) manual.
503 =item Some simple style guidelines
505 The perlstyle manual supplied with Perl has many helpful points.
507 Coding style is a matter of personal taste. Many people evolve their
508 style over several years as they learn what helps them write and
509 maintain good code. Here's one set of assorted suggestions that
510 seem to be widely used by experienced developers:
512 Use underscores to separate words. It is generally easier to read
513 $var_names_like_this than $VarNamesLikeThis, especially for
514 non-native speakers of English. It's also a simple rule that works
515 consistently with VAR_NAMES_LIKE_THIS.
517 Package/Module names are an exception to this rule. Perl informally
518 reserves lowercase module names for 'pragma' modules like integer
519 and strict. Other modules normally begin with a capital letter and
520 use mixed case with no underscores (need to be short and portable).
522 You may find it helpful to use letter case to indicate the scope
523 or nature of a variable. For example:
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
529 Function and method names seem to work best as all lowercase.
530 e.g., C<< $obj->as_string() >>.
532 You can use a leading underscore to indicate that a variable or
533 function should not be used outside the package that defined it.
535 =item Select what to export.
537 Do NOT export method names!
539 Do NOT export anything else by default without a good reason!
541 Exports pollute the namespace of the module user. If you must
542 export try to use @EXPORT_OK in preference to @EXPORT and avoid
543 short or common names to reduce the risk of name clashes.
545 Generally anything not exported is still accessible from outside the
546 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
547 syntax. By convention you can use a leading underscore on names to
548 indicate informally that they are 'internal' and not for public use.
550 (It is actually possible to get private functions by saying:
551 C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
552 directly as a method, because a method must have a name in the symbol
555 As a general rule, if the module is trying to be object oriented
556 then export nothing. If it's just a collection of functions then
557 @EXPORT_OK anything but use @EXPORT with caution.
559 =item Select a name for the module.
561 This name should be as descriptive, accurate, and complete as
562 possible. Avoid any risk of ambiguity. Always try to use two or
563 more whole words. Generally the name should reflect what is special
564 about what the module does rather than how it does it. Please use
565 nested module names to group informally or categorize a module.
566 There should be a very good reason for a module not to have a nested name.
567 Module names should begin with a capital letter.
569 Having 57 modules all called Sort will not make life easy for anyone
570 (though having 23 called Sort::Quick is only marginally better :-).
571 Imagine someone trying to install your module alongside many others.
572 If in any doubt ask for suggestions in comp.lang.perl.misc.
574 If you are developing a suite of related modules/classes it's good
575 practice to use nested classes with a common prefix as this will
576 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
577 Xyz::Model etc. Use the modules in this list as a naming guide.
579 If adding a new module to a set, follow the original author's
580 standards for naming modules and the interface to methods in
583 To be portable each component of a module name should be limited to
584 11 characters. If it might be used on MS-DOS then try to ensure each is
585 unique in the first 8 characters. Nested modules make this easier.
587 =item Have you got it right?
589 How do you know that you've made the right decisions? Have you
590 picked an interface design that will cause problems later? Have
591 you picked the most appropriate name? Do you have any questions?
593 The best way to know for sure, and pick up many helpful suggestions,
594 is to ask someone who knows. Comp.lang.perl.misc is read by just about
595 all the people who develop modules and it's the best place to ask.
597 All you need to do is post a short summary of the module, its
598 purpose and interfaces. A few lines on each of the main methods is
599 probably enough. (If you post the whole module it might be ignored
600 by busy people - generally the very people you want to read it!)
602 Don't worry about posting if you can't say when the module will be
603 ready - just say so in the message. It might be worth inviting
604 others to help you, they may be able to complete it for you!
606 =item README and other Additional Files.
608 It's well known that software developers usually fully document the
609 software they write. If, however, the world is in urgent need of
610 your software and there is not enough time to write the full
611 documentation please at least provide a README file containing:
616 A description of the module/package/extension etc.
619 A copyright notice - see below.
622 Prerequisites - what else you may need to have.
625 How to build it - possible changes to Makefile.PL etc.
631 Recent changes in this release, especially incompatibilities
634 Changes / enhancements you plan to make in the future.
638 If the README file seems to be getting too large you may wish to
639 split out some of the sections into separate files: INSTALL,
644 =item Adding a Copyright Notice.
646 How you choose to license your work is a personal decision.
647 The general mechanism is to assert your Copyright and then make
648 a declaration of how others may copy/use/modify your work.
650 Perl, for example, is supplied with two types of licence: The GNU
651 GPL and The Artistic Licence (see the files README, Copying, and
652 Artistic). Larry has good reasons for NOT just using the GNU GPL.
654 My personal recommendation, out of respect for Larry, Perl, and the
655 Perl community at large is to state something simply like:
657 Copyright (c) 1995 Your Name. All rights reserved.
658 This program is free software; you can redistribute it and/or
659 modify it under the same terms as Perl itself.
661 This statement should at least appear in the README file. You may
662 also wish to include it in a Copying file and your source files.
663 Remember to include the other words in addition to the Copyright.
665 =item Give the module a version/issue/release number.
667 To be fully compatible with the Exporter and MakeMaker modules you
668 should store your module's version number in a non-my package
669 variable called $VERSION. This should be a floating point
670 number with at least two digits after the decimal (i.e., hundredths,
671 e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
672 See L<Exporter> for details.
674 It may be handy to add a function or method to retrieve the number.
675 Use the number in announcements and archive file names when
676 releasing the module (ModuleName-1.02.tar.Z).
677 See perldoc ExtUtils::MakeMaker.pm for details.
679 =item How to release and distribute a module.
681 It's good idea to post an announcement of the availability of your
682 module (or the module itself if small) to the comp.lang.perl.announce
683 Usenet newsgroup. This will at least ensure very wide once-off
686 If possible, register the module with CPAN. You should
687 include details of its location in your announcement.
689 Some notes about ftp archives: Please use a long descriptive file
690 name that includes the version number. Most incoming directories
691 will not be readable/listable, i.e., you won't be able to see your
692 file after uploading it. Remember to send your email notification
693 message as soon as possible after uploading else your file may get
694 deleted automatically. Allow time for the file to be processed
695 and/or check the file has been processed before announcing its
698 FTP Archives for Perl Modules:
700 Follow the instructions and links on:
702 http://www.perl.com/CPAN/modules/00modlist.long.html
703 http://www.perl.com/CPAN/modules/04pause.html
705 or upload to one of these sites:
707 https://pause.kbx.de/pause/
708 http://pause.perl.org/pause/
710 and notify <modules@perl.org>.
712 By using the WWW interface you can ask the Upload Server to mirror
713 your modules from your ftp or WWW site into your own directory on
716 Please remember to send me an updated entry for the Module list!
718 =item Take care when changing a released module.
720 Always strive to remain compatible with previous released versions.
721 Otherwise try to add a mechanism to revert to the
722 old behavior if people rely on it. Document incompatible changes.
728 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
732 =item There is no requirement to convert anything.
734 If it ain't broke, don't fix it! Perl 4 library scripts should
735 continue to work with no problems. You may need to make some minor
736 changes (like escaping non-array @'s in double quoted strings) but
737 there is no need to convert a .pl file into a Module for just that.
739 =item Consider the implications.
741 All Perl applications that make use of the script will need to
742 be changed (slightly) if the script is converted into a module. Is
743 it worth it unless you plan to make other changes at the same time?
745 =item Make the most of the opportunity.
747 If you are going to convert the script to a module you can use the
748 opportunity to redesign the interface. The guidelines for module
749 creation above include many of the issues you should consider.
751 =item The pl2pm utility will get you started.
753 This utility will read *.pl files (given as parameters) and write
754 corresponding *.pm files. The pl2pm utilities does the following:
759 Adds the standard Module prologue lines
762 Converts package specifiers from ' to ::
765 Converts die(...) to croak(...)
768 Several other minor changes
772 Being a mechanical process pl2pm is not bullet proof. The converted
773 code will need careful checking, especially any package statements.
774 Don't delete the original .pl file till the new .pm one works!
778 =head2 Guidelines for Reusing Application Code
782 =item Complete applications rarely belong in the Perl Module Library.
784 =item Many applications contain some Perl code that could be reused.
786 Help save the world! Share your code in a form that makes it easy
789 =item Break-out the reusable code into one or more separate module files.
791 =item Take the opportunity to reconsider and redesign the interfaces.
793 =item In some cases the 'application' can then be reduced to a small
795 fragment of code built on top of the reusable modules. In these cases
796 the application could invoked as:
798 % perl -e 'use Module::Name; method(@ARGV)' ...
800 % perl -mModule::Name ... (in perl5.002 or higher)
806 Perl does not enforce private and public parts of its modules as you may
807 have been used to in other languages like C++, Ada, or Modula-17. Perl
808 doesn't have an infatuation with enforced privacy. It would prefer
809 that you stayed out of its living room because you weren't invited, not
810 because it has a shotgun.
812 The module and its user have a contract, part of which is common law,
813 and part of which is "written". Part of the common law contract is
814 that a module doesn't pollute any namespace it wasn't asked to. The
815 written contract for the module (A.K.A. documentation) may make other
816 provisions. But then you know when you C<use RedefineTheWorld> that
817 you're redefining the world and willing to take the consequences.
820 close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
821 close OUT or warn "$0: failed to close OUT (perlmodlib.tmp): $!";