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