6 local $ENV{LC_ALL} = 'C';
9 @ARGV = grep { not($_ eq '-q' and $Quiet = 1) } @ARGV;
14 or die "Couldn't chdir to '$workdir': $!";
16 require './regen/regen_lib.pl';
18 # MANIFEST itself is Unix style filenames, so we have to assume that Unix style
19 # filenames will work.
21 open MANIFEST, '<', 'MANIFEST'
22 or die "Can't open MANIFEST: $!";
24 grep !m#/perl.*\.pod#,
25 grep m#(?:\.pm|\.pod|_pm\.PL)#,
27 grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo|corpus)/# }
30 or die "$0: failed to close MANIFEST: $!";
32 my $out = open_new('pod/perlmodlib.pod', undef,
33 {by => "$0 extracting documentation",
34 from => 'the Perl source files'}, 1);
37 'abbrev' => 'Text::Abbrev',
39 'getopt' => 'Getopt::Std',
40 'Encode::MIME::NAME' => 'Encode::MIME::Name',
41 'libnetFAQ' => 'Net::libnetFAQ',
46 for my $filename (@files) {
47 unless (open MOD, '<', $filename) {
48 warn "Couldn't open $filename: $!";
57 next unless /^=head1 NAME/;
63 next if pod_for_module_has_head1_NAME($filename);
64 die "p5p-controlled module $filename missing =head1 NAME\n"
65 if $filename !~ m{^(dist/|cpan/)}n # under our direct control
66 && $filename !~ m{/_[^/]+\z} # not private
67 && $filename ne 'lib/meta_notation.pm' # no pod
68 && $filename ne 'lib/overload/numbers.pm'; # no pod
69 warn "$filename missing =head1 NAME\n" unless $Quiet;
75 or die "Error closing $filename: $!";
77 ($name, $thing) = split /\s+--?\s+/, $title, 2;
79 unless ($name and $thing) {
80 warn "$filename missing name\n" unless $name;
81 warn "$filename missing thing\n" unless $thing or $Quiet;
85 $name =~ s/[^A-Za-z0-9_:\$<>].*//;
86 $name = $exceptions{$name} || $name;
87 $thing =~ s/^perl pragma to //i;
88 $thing = ucfirst $thing;
89 $title = "=item $name\n\n$thing\n\n";
91 if ($name =~ /[A-Z]/) {
98 sub pod_for_module_has_head1_NAME {
100 (my $pod_file = $filename) =~ s/\.pm\z/.pod/ or return 0;
101 return 0 if !-e $pod_file;
102 open my $fh, '<', $pod_file
103 or die "Can't open $pod_file for reading: $!\n";
105 while (my $para = <$fh>) {
106 return 1 if $para =~ /\A=head1 NAME$/m;
111 # Much easier to special case it like this than special case the depending on
112 # and parsing lib/Config.pod, or special case opening configpm and finding its
113 # =head1 (which is not found with the $/="" above)
114 push @mod, "=item Config\n\nAccess Perl configuration information\n\n";
117 # The intent of using =cut as the heredoc terminator is to make the whole file
118 # parse as (reasonably) sane Pod as-is to anything that attempts to
119 # brute-force treat it as such. The content is already useful - this just
120 # makes it tidier, by stopping anything doing this mistaking the rest of the
121 # Perl code for Pod. eg https://metacpan.org/pod/perlmodlib
126 perlmodlib - constructing new Perl modules and finding existing ones
128 =head1 THE PERL MODULE LIBRARY
130 Many modules are included in the Perl distribution. These are described
131 below, and all end in F<.pm>. You may discover compiled library
132 files (usually ending in F<.so>) or small pieces of modules to be
133 autoloaded (ending in F<.al>); these were automatically generated
134 by the installation process. You may also discover files in the
135 library directory that end in either F<.pl> or F<.ph>. These are
136 old libraries supplied so that old programs that use them still
137 run. The F<.pl> files will all eventually be converted into standard
138 modules, and the F<.ph> files made by B<h2ph> will probably end up
139 as extension modules made by B<h2xs>. (Some F<.ph> values may
140 already be available through the POSIX, Errno, or Fcntl modules.)
141 The B<pl2pm> file in the distribution may help in your conversion,
142 but it's just a mechanical process and therefore far from bulletproof.
144 =head2 Pragmatic Modules
146 They work somewhat like compiler directives (pragmata) in that they
147 tend to affect the compilation of your program, and thus will usually
148 work well only when used within a C<use>, or C<no>. Most of these
149 are lexically scoped, so an inner BLOCK may countermand them
156 which lasts until the end of that BLOCK.
158 Some pragmas are lexically scoped--typically those that affect the
159 C<$^H> hints variable. Others affect the current package instead,
160 like C<use vars> and C<use subs>, which allow you to predeclare a
161 variables or subroutines within a particular I<file> rather than
162 just a block. Such declarations are effective for the entire file
163 for which they were declared. You cannot rescind them with C<no
166 The following pragmas are defined (and have their own documentation).
172 print $out $_ for sort @pragma;
178 =head2 Standard Modules
180 Standard, bundled modules are all expected to behave in a well-defined
181 manner with respect to namespace pollution because they use the
182 Exporter module. See their own documentation for details.
184 It's possible that not all modules listed below are installed on your
185 system. For example, the GDBM_File module will not be installed if you
186 don't have the gdbm library.
192 print $out $_ for sort @mod;
194 print $out <<'=cut', "=cut\n";
198 To find out I<all> modules installed on your system, including
199 those without documentation or outside the standard release,
200 just use the following command (under the default win32 shell,
201 double quotes should be used instead of single quotes).
203 % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
204 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
205 no_chdir => 1 }, @INC'
207 (The -T is here to prevent '.' from being listed in @INC.)
208 They should all have their own documentation installed and accessible
209 via your system man(1) command. If you do not have a B<find>
210 program, you can use the Perl B<find2perl> program instead, which
211 generates Perl code as output you can run through perl. If you
212 have a B<man> program but it doesn't find your modules, you'll have
213 to fix your manpath. See L<perl> for details. If you have no
214 system B<man> command, you might try the B<perldoc> program.
216 Note also that the command C<perldoc perllocal> gives you a (possibly
217 incomplete) list of the modules that have been further installed on
218 your system. (The perllocal.pod file is updated by the standard MakeMaker
221 =head2 Extension Modules
223 Extension modules are written in C (or a mix of Perl and C). They
224 are usually dynamically loaded into Perl if and when you need them,
225 but may also be linked in statically. Supported extension modules
226 include Socket, Fcntl, and POSIX.
228 Many popular C extension modules do not come bundled (at least, not
229 completely) due to their sizes, volatility, or simply lack of time
230 for adequate testing and configuration across the multitude of
231 platforms on which Perl was beta-tested. You are encouraged to
232 look for them on CPAN (described below), or using web search engines
233 like Google or DuckDuckGo.
237 CPAN stands for Comprehensive Perl Archive Network; it's a globally
238 replicated trove of Perl materials, including documentation, style
239 guides, tricks and traps, alternate ports to non-Unix systems and
240 occasional binary distributions for these. Search engines for
241 CPAN can be found at https://www.cpan.org/
243 Most importantly, CPAN includes around a thousand unbundled modules,
244 some of which require a C compiler to build. Major categories of
251 Language Extensions and Documentation Tools
259 Operating System Interfaces
263 Networking, Device Control (modems) and InterProcess Communication
267 Data Types and Data Type Utilities
279 Interfaces to / Emulations of Other Programming Languages
283 File Names, File Systems and File Locking (see also File Handles)
287 String Processing, Language Text Processing, Parsing, and Searching
291 Option, Argument, Parameter, and Configuration File Processing
295 Internationalization and Locale
299 Authentication, Security, and Encryption
303 World Wide Web, HTML, HTTP, CGI, MIME
307 Server and Daemon Utilities
311 Archiving and Compression
315 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
323 Control Flow Utilities (callbacks and exceptions etc)
327 File Handle and Input/Output Stream Utilities
331 Miscellaneous Modules
335 You can find the CPAN online at L<https://www.cpan.org/>
337 =head1 Modules: Creation, Use, and Abuse
339 (The following section is borrowed directly from Tim Bunce's modules
340 file, available at your nearest CPAN site.)
342 Perl implements a class using a package, but the presence of a
343 package doesn't imply the presence of a class. A package is just a
344 namespace. A class is a package that provides subroutines that can be
345 used as methods. A method is just a subroutine that expects, as its
346 first argument, either the name of a package (for "static" methods),
347 or a reference to something (for "virtual" methods).
349 A module is a file that (by convention) provides a class of the same
350 name (sans the .pm), plus an import method in that class that can be
351 called to fetch exported symbols. This module may implement some of
352 its methods by loading dynamic C or C++ objects, but that should be
353 totally transparent to the user of the module. Likewise, the module
354 might set up an AUTOLOAD function to slurp in subroutine definitions on
355 demand, but this is also transparent. Only the F<.pm> file is required to
356 exist. See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
357 the AUTOLOAD mechanism.
359 =head2 Guidelines for Module Creation
365 Do similar modules already exist in some form?
367 If so, please try to reuse the existing modules either in whole or
368 by inheriting useful features into a new class. If this is not
369 practical try to get together with the module authors to work on
370 extending or enhancing the functionality of the existing modules.
371 A perfect example is the plethora of packages in perl4 for dealing
372 with command line options.
374 If you are writing a module to expand an already existing set of
375 modules, please coordinate with the author of the package. It
376 helps if you follow the same naming scheme and module interaction
377 scheme as the original author.
381 Try to design the new module to be easy to extend and reuse.
383 Try to C<use warnings;> (or C<use warnings qw(...);>).
384 Remember that you can add C<no warnings qw(...);> to individual blocks
385 of code that need less warnings.
387 Use blessed references. Use the two argument form of bless to bless
388 into the class name given as the first parameter of the constructor,
393 return bless {}, $class;
396 or even this if you'd like it to be used as either a static
401 my $class = ref($self) || $self;
402 return bless {}, $class;
405 Pass arrays as references so more parameters can be added later
406 (it's also faster). Convert functions into methods where
407 appropriate. Split large methods into smaller more flexible ones.
408 Inherit methods from other modules if appropriate.
410 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
411 Generally you can delete the C<eq 'FOO'> part with no harm at all.
412 Let the objects look after themselves! Generally, avoid hard-wired
413 class names as far as possible.
415 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
416 C<< $r->func() >> would work.
418 Use autosplit so little used or newly added functions won't be a
419 burden to programs that don't use them. Add test functions to
420 the module after __END__ either using AutoSplit or by saying:
422 eval join('',<main::DATA>) || die $@ unless caller();
424 Does your module pass the 'empty subclass' test? If you say
425 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
426 to use SUBCLASS in exactly the same way as YOURCLASS. For example,
427 does your application still work if you change: C<< $obj = YOURCLASS->new(); >>
428 into: C<< $obj = SUBCLASS->new(); >> ?
430 Avoid keeping any state information in your packages. It makes it
431 difficult for multiple other packages to use yours. Keep state
432 information in objects.
436 Try to C<use strict;> (or C<use strict qw(...);>).
437 Remember that you can add C<no strict qw(...);> to individual blocks
438 of code that need less strictness.
442 Follow the guidelines in L<perlstyle>.
448 Some simple style guidelines
450 The perlstyle manual supplied with Perl has many helpful points.
452 Coding style is a matter of personal taste. Many people evolve their
453 style over several years as they learn what helps them write and
454 maintain good code. Here's one set of assorted suggestions that
455 seem to be widely used by experienced developers:
457 Use underscores to separate words. It is generally easier to read
458 $var_names_like_this than $VarNamesLikeThis, especially for
459 non-native speakers of English. It's also a simple rule that works
460 consistently with VAR_NAMES_LIKE_THIS.
462 Package/Module names are an exception to this rule. Perl informally
463 reserves lowercase module names for 'pragma' modules like integer
464 and strict. Other modules normally begin with a capital letter and
465 use mixed case with no underscores (need to be short and portable).
467 You may find it helpful to use letter case to indicate the scope
468 or nature of a variable. For example:
470 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
471 $Some_Caps_Here package-wide global/static
472 $no_caps_here function scope my() or local() variables
474 Function and method names seem to work best as all lowercase.
475 e.g., C<< $obj->as_string() >>.
477 You can use a leading underscore to indicate that a variable or
478 function should not be used outside the package that defined it.
482 Select what to export.
484 Do NOT export method names!
486 Do NOT export anything else by default without a good reason!
488 Exports pollute the namespace of the module user. If you must
489 export try to use @EXPORT_OK in preference to @EXPORT and avoid
490 short or common names to reduce the risk of name clashes.
492 Generally anything not exported is still accessible from outside the
493 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
494 syntax. By convention you can use a leading underscore on names to
495 indicate informally that they are 'internal' and not for public use.
497 (It is actually possible to get private functions by saying:
498 C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
499 directly as a method, because a method must have a name in the symbol
502 As a general rule, if the module is trying to be object oriented
503 then export nothing. If it's just a collection of functions then
504 @EXPORT_OK anything but use @EXPORT with caution.
508 Select a name for the module.
510 This name should be as descriptive, accurate, and complete as
511 possible. Avoid any risk of ambiguity. Always try to use two or
512 more whole words. Generally the name should reflect what is special
513 about what the module does rather than how it does it. Please use
514 nested module names to group informally or categorize a module.
515 There should be a very good reason for a module not to have a nested name.
516 Module names should begin with a capital letter.
518 Having 57 modules all called Sort will not make life easy for anyone
519 (though having 23 called Sort::Quick is only marginally better :-).
520 Imagine someone trying to install your module alongside many others.
522 If you are developing a suite of related modules/classes it's good
523 practice to use nested classes with a common prefix as this will
524 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
525 Xyz::Model etc. Use the modules in this list as a naming guide.
527 If adding a new module to a set, follow the original author's
528 standards for naming modules and the interface to methods in
531 If developing modules for private internal or project specific use,
532 that will never be released to the public, then you should ensure
533 that their names will not clash with any future public module. You
534 can do this either by using the reserved Local::* category or by
535 using a category name that includes an underscore like Foo_Corp::*.
537 To be portable each component of a module name should be limited to
538 11 characters. If it might be used on MS-DOS then try to ensure each is
539 unique in the first 8 characters. Nested modules make this easier.
541 For additional guidance on the naming of modules, please consult:
543 https://pause.perl.org/pause/query?ACTION=pause_namingmodules
545 or send mail to the <module-authors@perl.org> mailing list.
549 Have you got it right?
551 How do you know that you've made the right decisions? Have you
552 picked an interface design that will cause problems later? Have
553 you picked the most appropriate name? Do you have any questions?
555 The best way to know for sure, and pick up many helpful suggestions,
556 is to ask someone who knows. The <module-authors@perl.org> mailing list
557 is useful for this purpose; it's also accessible via news interface as
558 perl.module-authors at nntp.perl.org.
560 All you need to do is post a short summary of the module, its
561 purpose and interfaces. A few lines on each of the main methods is
562 probably enough. (If you post the whole module it might be ignored
563 by busy people - generally the very people you want to read it!)
565 Don't worry about posting if you can't say when the module will be
566 ready - just say so in the message. It might be worth inviting
567 others to help you, they may be able to complete it for you!
571 README and other Additional Files.
573 It's well known that software developers usually fully document the
574 software they write. If, however, the world is in urgent need of
575 your software and there is not enough time to write the full
576 documentation please at least provide a README file containing:
582 A description of the module/package/extension etc.
586 A copyright notice - see below.
590 Prerequisites - what else you may need to have.
594 How to build it - possible changes to Makefile.PL etc.
602 Recent changes in this release, especially incompatibilities
606 Changes / enhancements you plan to make in the future.
610 If the README file seems to be getting too large you may wish to
611 split out some of the sections into separate files: INSTALL,
618 Adding a Copyright Notice.
620 How you choose to license your work is a personal decision.
621 The general mechanism is to assert your Copyright and then make
622 a declaration of how others may copy/use/modify your work.
624 Perl, for example, is supplied with two types of licence: The GNU GPL
625 and The Artistic Licence (see the files README, Copying, and Artistic,
626 or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
627 just using the GNU GPL.
629 My personal recommendation, out of respect for Larry, Perl, and the
630 Perl community at large is to state something simply like:
632 Copyright (c) 1995 Your Name. All rights reserved.
633 This program is free software; you can redistribute it and/or
634 modify it under the same terms as Perl itself.
636 This statement should at least appear in the README file. You may
637 also wish to include it in a Copying file and your source files.
638 Remember to include the other words in addition to the Copyright.
642 Give the module a version/issue/release number.
644 To be fully compatible with the Exporter and MakeMaker modules you
645 should store your module's version number in a non-my package
646 variable called $VERSION. This should be a positive floating point
647 number with at least two digits after the decimal (i.e., hundredths,
648 e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
649 See L<Exporter> for details.
651 It may be handy to add a function or method to retrieve the number.
652 Use the number in announcements and archive file names when
653 releasing the module (ModuleName-1.02.tar.Z).
654 See perldoc ExtUtils::MakeMaker.pm for details.
658 How to release and distribute a module.
660 If possible, register the module with CPAN. Follow the instructions
663 https://www.cpan.org/modules/04pause.html
667 https://pause.perl.org/
669 and notify <modules@perl.org>. This will allow anyone to install
670 your module using the C<cpan> tool distributed with Perl.
672 By using the WWW interface you can ask the Upload Server to mirror
673 your modules from your ftp or WWW site into your own directory on
678 Take care when changing a released module.
680 Always strive to remain compatible with previous released versions.
681 Otherwise try to add a mechanism to revert to the
682 old behavior if people rely on it. Document incompatible changes.
688 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
694 There is no requirement to convert anything.
696 If it ain't broke, don't fix it! Perl 4 library scripts should
697 continue to work with no problems. You may need to make some minor
698 changes (like escaping non-array @'s in double quoted strings) but
699 there is no need to convert a .pl file into a Module for just that.
703 Consider the implications.
705 All Perl applications that make use of the script will need to
706 be changed (slightly) if the script is converted into a module. Is
707 it worth it unless you plan to make other changes at the same time?
711 Make the most of the opportunity.
713 If you are going to convert the script to a module you can use the
714 opportunity to redesign the interface. The guidelines for module
715 creation above include many of the issues you should consider.
719 The pl2pm utility will get you started.
721 This utility will read *.pl files (given as parameters) and write
722 corresponding *.pm files. The pl2pm utilities does the following:
728 Adds the standard Module prologue lines
732 Converts package specifiers from ' to ::
736 Converts die(...) to croak(...)
740 Several other minor changes
744 Being a mechanical process pl2pm is not bullet proof. The converted
745 code will need careful checking, especially any package statements.
746 Don't delete the original .pl file till the new .pm one works!
750 =head2 Guidelines for Reusing Application Code
756 Complete applications rarely belong in the Perl Module Library.
760 Many applications contain some Perl code that could be reused.
762 Help save the world! Share your code in a form that makes it easy
767 Break-out the reusable code into one or more separate module files.
771 Take the opportunity to reconsider and redesign the interfaces.
775 In some cases the 'application' can then be reduced to a small
777 fragment of code built on top of the reusable modules. In these cases
778 the application could invoked as:
780 % perl -e 'use Module::Name; method(@ARGV)' ...
782 % perl -mModule::Name ... (in perl5.002 or higher)
788 Perl does not enforce private and public parts of its modules as you may
789 have been used to in other languages like C++, Ada, or Modula-17. Perl
790 doesn't have an infatuation with enforced privacy. It would prefer
791 that you stayed out of its living room because you weren't invited, not
792 because it has a shotgun.
794 The module and its user have a contract, part of which is common law,
795 and part of which is "written". Part of the common law contract is
796 that a module doesn't pollute any namespace it wasn't asked to. The
797 written contract for the module (A.K.A. documentation) may make other
798 provisions. But then you know when you C<use RedefineTheWorld> that
799 you're redefining the world and willing to take the consequences.
803 read_only_bottom_close_and_rename($out);