6 chdir $FindBin::Bin or die "$0: Can't chdir $FindBin::Bin: $!";
8 my $Quiet = @ARGV && $ARGV[0] eq '-q';
10 open (OUT, ">perlmodlib.pod") or die $!;
11 my (@pragma, @mod, @MANIFEST);
13 # MANIFEST itself is Unix style filenames, so we have to assume that Unix style
14 # filenames will work.
16 open (MANIFEST, "../MANIFEST") or die $!;
17 @MANIFEST = grep !m</(?:t|demo)/>, <MANIFEST>;
18 push @MANIFEST, 'lib/Config.pod', 'lib/Errno.pm', 'lib/lib.pm',
19 'lib/DynaLoader.pm', 'lib/XSLoader.pm';
21 # If run in a clean source tree, these will be missing because they are
22 # generated by the build.
24 'encoding' => 'Allows you to write your script in non-ascii or non-utf8',
25 'lib' => 'Manipulate @INC at compile time',
26 'ops' => 'Restrict unsafe operations when compiling',
27 'Config' => 'Access Perl configuration information',
28 'DynaLoader' => 'Dynamically load C libraries into Perl code',
29 'Errno' => 'System errno constants',
30 'O' => 'Generic interface to Perl Compiler backends',
31 'Safe' => 'Compile and execute code in restricted compartments',
32 'XSLoader' => 'Dynamically load C libraries into Perl code',
35 # If run in a clean source tree, these should not be reported.
36 # These are considered 'modules' by this script, but they really are not.
37 my %suppressed = map {$_ => 1} qw(
46 next unless m|^lib/| or m|^ext/|;
47 my ($filename) = m|^(\S+)|;
48 next unless $filename =~ m!\.p(m|od)$!;
49 unless (open MOD, '<', "../$filename") {
50 warn "Couldn't open ../$filename: $!";
60 next unless /^=head1 NAME/;
66 warn "$filename missing =head1 NAME (OK if respective .pod exists)\n"
74 my $perlname = $filename;
75 $perlname =~ s!^.*\b(ext|lib)/!!;
76 $perlname =~ s!\.p(m|od)$!!;
77 $perlname =~ s!\b(\w+)/\1\b!$1!;
78 $perlname =~ s!/!::!g;
79 $perlname =~ s!-!::!g;
81 # modules with non standard locations
82 $perlname =~ s{Base64::QuotedPrint}{QuotedPrint};
84 ($name, $thing) = split / --? /, $title, 2;
86 unless ($name and $thing) {
87 warn "$filename missing name\n" unless $name;
88 warn "$filename missing thing\n" unless $thing or $Quiet;
92 next if $suppressed{$perlname};
94 $thing =~ s/^perl pragma to //i;
95 $thing = ucfirst($thing);
96 $title = "=item $perlname\n\n$thing\n\n";
98 if ($filename =~ /[A-Z]/) {
101 push @pragma, $title;
104 # if we find a generated one via the MANIFEST, no need to add later.
105 delete $generated{$perlname};
107 while (my ($name,$desc) = each %generated) {
108 my $title = "=item $name\n\n$desc\n\n";
109 if ($name =~ /[A-Z]/) {
112 push @pragma, $title;
118 Generated by perlmodlib.PL -- DO NOT EDIT!
122 perlmodlib - constructing new Perl modules and finding existing ones
124 =head1 THE PERL MODULE LIBRARY
126 Many modules are included in the Perl distribution. These are described
127 below, and all end in F<.pm>. You may discover compiled library
128 files (usually ending in F<.so>) or small pieces of modules to be
129 autoloaded (ending in F<.al>); these were automatically generated
130 by the installation process. You may also discover files in the
131 library directory that end in either F<.pl> or F<.ph>. These are
132 old libraries supplied so that old programs that use them still
133 run. The F<.pl> files will all eventually be converted into standard
134 modules, and the F<.ph> files made by B<h2ph> will probably end up
135 as extension modules made by B<h2xs>. (Some F<.ph> values may
136 already be available through the POSIX, Errno, or Fcntl modules.)
137 The B<pl2pm> file in the distribution may help in your conversion,
138 but it's just a mechanical process and therefore far from bulletproof.
140 =head2 Pragmatic Modules
142 They work somewhat like compiler directives (pragmata) in that they
143 tend to affect the compilation of your program, and thus will usually
144 work well only when used within a C<use>, or C<no>. Most of these
145 are lexically scoped, so an inner BLOCK may countermand them
152 which lasts until the end of that BLOCK.
154 Some pragmas are lexically scoped--typically those that affect the
155 C<$^H> hints variable. Others affect the current package instead,
156 like C<use vars> and C<use subs>, which allow you to predeclare a
157 variables or subroutines within a particular I<file> rather than
158 just a block. Such declarations are effective for the entire file
159 for which they were declared. You cannot rescind them with C<no
162 The following pragmas are defined (and have their own documentation).
168 print OUT $_ for (sort @pragma);
173 =head2 Standard Modules
175 Standard, bundled modules are all expected to behave in a well-defined
176 manner with respect to namespace pollution because they use the
177 Exporter module. See their own documentation for details.
179 It's possible that not all modules listed below are installed on your
180 system. For example, the GDBM_File module will not be installed if you
181 don't have the gdbm library.
187 print OUT $_ for (sort @mod);
192 To find out I<all> modules installed on your system, including
193 those without documentation or outside the standard release,
194 just use the following command (under the default win32 shell,
195 double quotes should be used instead of single quotes).
197 % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
198 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
199 no_chdir => 1 }, @INC'
201 (The -T is here to prevent '.' from being listed in @INC.)
202 They should all have their own documentation installed and accessible
203 via your system man(1) command. If you do not have a B<find>
204 program, you can use the Perl B<find2perl> program instead, which
205 generates Perl code as output you can run through perl. If you
206 have a B<man> program but it doesn't find your modules, you'll have
207 to fix your manpath. See L<perl> for details. If you have no
208 system B<man> command, you might try the B<perldoc> program.
210 Note also that the command C<perldoc perllocal> gives you a (possibly
211 incomplete) list of the modules that have been further installed on
212 your system. (The perllocal.pod file is updated by the standard MakeMaker
215 =head2 Extension Modules
217 Extension modules are written in C (or a mix of Perl and C). They
218 are usually dynamically loaded into Perl if and when you need them,
219 but may also be linked in statically. Supported extension modules
220 include Socket, Fcntl, and POSIX.
222 Many popular C extension modules do not come bundled (at least, not
223 completely) due to their sizes, volatility, or simply lack of time
224 for adequate testing and configuration across the multitude of
225 platforms on which Perl was beta-tested. You are encouraged to
226 look for them on CPAN (described below), or using web search engines
227 like Alta Vista or Google.
231 CPAN stands for Comprehensive Perl Archive Network; it's a globally
232 replicated trove of Perl materials, including documentation, style
233 guides, tricks and traps, alternate ports to non-Unix systems and
234 occasional binary distributions for these. Search engines for
235 CPAN can be found at http://www.cpan.org/
237 Most importantly, CPAN includes around a thousand unbundled modules,
238 some of which require a C compiler to build. Major categories of
245 Language Extensions and Documentation Tools
253 Operating System Interfaces
257 Networking, Device Control (modems) and InterProcess Communication
261 Data Types and Data Type Utilities
273 Interfaces to / Emulations of Other Programming Languages
277 File Names, File Systems and File Locking (see also File Handles)
281 String Processing, Language Text Processing, Parsing, and Searching
285 Option, Argument, Parameter, and Configuration File Processing
289 Internationalization and Locale
293 Authentication, Security, and Encryption
297 World Wide Web, HTML, HTTP, CGI, MIME
301 Server and Daemon Utilities
305 Archiving and Compression
309 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
317 Control Flow Utilities (callbacks and exceptions etc)
321 File Handle and Input/Output Stream Utilities
325 Miscellaneous Modules
329 The list of the registered CPAN sites as of this writing follows.
330 Please note that the sorting order is alphabetical on fields:
342 and thus the North American servers happen to be listed between the
343 European and the South American sites.
345 You should try to choose one close to you.
353 http://ftp.rucus.ru.ac.za/pub/perl/CPAN/
354 ftp://ftp.rucus.ru.ac.za/pub/perl/CPAN/
355 ftp://ftp.is.co.za/programming/perl/CPAN/
356 ftp://ftp.saix.net/pub/CPAN/
357 ftp://ftp.sun.ac.za/CPAN/CPAN/
367 http://cpan.linuxforum.net/
368 http://cpan.shellhung.org/
369 ftp://ftp.shellhung.org/pub/CPAN
370 ftp://mirrors.hknet.com/CPAN
374 http://mirrors.tf.itb.ac.id/cpan/
375 http://cpan.cbn.net.id/
376 ftp://ftp.cbn.net.id/mirror/CPAN
380 ftp://ftp.iglu.org.il/pub/CPAN/
381 http://cpan.lerner.co.il/
382 http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
383 ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
387 ftp://ftp.u-aizu.ac.jp/pub/CPAN
388 ftp://ftp.kddlabs.co.jp/CPAN/
389 ftp://ftp.ayamura.org/pub/CPAN/
390 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
392 ftp://ftp.cpan.jp/CPAN/
393 ftp://ftp.dti.ad.jp/pub/lang/CPAN/
394 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
398 http://cpan.MyBSD.org.my
399 http://mirror.leafbug.org/pub/CPAN
400 http://ossig.mncc.com.my/mirror/pub/CPAN
402 =item Russian Federation
409 ftp://ftp.isu.net.sa/pub/CPAN/
413 http://CPAN.en.com.sg/
414 ftp://cpan.en.com.sg/
415 http://mirror.averse.net/pub/CPAN
416 ftp://mirror.averse.net/pub/CPAN
417 http://cpan.oss.eznetsols.org
418 ftp://ftp.oss.eznetsols.org/cpan
422 http://CPAN.bora.net/
423 ftp://ftp.bora.net/pub/CPAN/
424 http://mirror.kr.FreeBSD.org/CPAN
425 ftp://ftp.kr.FreeBSD.org/pub/CPAN
429 ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN
430 http://cpan.cdpa.nsysu.edu.tw/
431 ftp://cpan.cdpa.nsysu.edu.tw/pub/CPAN
432 http://ftp.isu.edu.tw/pub/CPAN
433 ftp://ftp.isu.edu.tw/pub/CPAN
434 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
435 http://ftp.tku.edu.tw/pub/CPAN/
436 ftp://ftp.tku.edu.tw/pub/CPAN/
440 ftp://ftp.loxinfo.co.th/pub/cpan/
441 ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
445 =head2 Central America
451 http://ftp.ucr.ac.cr/Unix/CPAN/
452 ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
462 http://cpan.inode.at/
464 ftp://ftp.tuwien.ac.at/pub/CPAN/
468 http://ftp.easynet.be/pub/CPAN/
469 ftp://ftp.easynet.be/pub/CPAN/
470 http://cpan.skynet.be
471 ftp://ftp.cpan.skynet.be/pub/CPAN
472 ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
474 =item Bosnia and Herzegovina
476 http://cpan.blic.net/
480 http://cpan.online.bg
481 ftp://cpan.online.bg/cpan
482 http://cpan.zadnik.org
483 ftp://ftp.zadnik.org/mirrors/CPAN/
484 http://cpan.lirex.net/
485 ftp://ftp.lirex.net/pub/mirrors/CPAN
489 http://ftp.linux.hr/pub/CPAN/
490 ftp://ftp.linux.hr/pub/CPAN/
494 ftp://ftp.fi.muni.cz/pub/CPAN/
495 ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
499 http://mirrors.sunsite.dk/cpan/
500 ftp://sunsite.dk/mirrors/cpan/
501 http://cpan.cybercity.dk
502 http://www.cpan.dk/CPAN/
503 ftp://www.cpan.dk/ftp.cpan.org/CPAN/
507 ftp://ftp.ut.ee/pub/languages/perl/CPAN/
511 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
512 http://mirror.eunet.fi/CPAN
516 http://www.enstimac.fr/Perl/CPAN
517 http://ftp.u-paris10.fr/perl/CPAN
518 ftp://ftp.u-paris10.fr/perl/CPAN
519 http://cpan.mirrors.easynet.fr/
520 ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
521 ftp://ftp.club-internet.fr/pub/perl/CPAN/
523 ftp://ftp.lip6.fr/pub/perl/CPAN/
524 ftp://ftp.oleane.net/pub/mirrors/CPAN/
525 ftp://ftp.pasteur.fr/pub/computing/CPAN/
526 http://mir2.ovh.net/ftp.cpan.org
527 ftp://mir1.ovh.net/ftp.cpan.org
528 http://ftp.crihan.fr/mirrors/ftp.cpan.org/
529 ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
530 http://ftp.u-strasbg.fr/CPAN
531 ftp://ftp.u-strasbg.fr/CPAN
532 ftp://cpan.cict.fr/pub/CPAN/
533 ftp://ftp.uvsq.fr/pub/perl/CPAN/
537 ftp://ftp.rub.de/pub/CPAN/
538 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
539 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
540 ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
541 http://pandemonium.tiscali.de/pub/CPAN/
542 ftp://pandemonium.tiscali.de/pub/CPAN/
543 http://ftp.gwdg.de/pub/languages/perl/CPAN/
544 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
545 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
546 ftp://ftp.leo.org/pub/CPAN/
547 http://cpan.noris.de/
548 ftp://cpan.noris.de/pub/CPAN/
549 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
550 ftp://ftp.gmd.de/mirrors/CPAN/
554 ftp://ftp.acn.gr/pub/lang/perl
555 ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
556 ftp://ftp.ntua.gr/pub/lang/perl/
560 http://ftp.kfki.hu/packages/perl/CPAN/
561 ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
565 http://ftp.rhnet.is/pub/CPAN/
566 ftp://ftp.rhnet.is/pub/CPAN/
570 http://cpan.indigo.ie/
571 ftp://cpan.indigo.ie/pub/CPAN/
572 http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
573 ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
574 http://sunsite.compapp.dcu.ie/pub/perl/
575 ftp://sunsite.compapp.dcu.ie/pub/perl/
579 http://cpan.nettuno.it/
580 http://gusp.dyndns.org/CPAN/
581 ftp://gusp.dyndns.org/pub/CPAN
582 http://softcity.iol.it/cpan
583 ftp://softcity.iol.it/pub/cpan
584 ftp://ftp.unina.it/pub/Other/CPAN/CPAN/
585 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
586 ftp://cis.uniRoma2.it/CPAN/
587 ftp://ftp.edisontel.it/pub/CPAN_Mirror/
588 http://cpan.flashnet.it/
589 ftp://ftp.flashnet.it/pub/CPAN/
593 http://kvin.lv/pub/CPAN/
597 ftp://ftp.unix.lt/pub/CPAN/
601 ftp://download.xs4all.nl/pub/mirror/CPAN/
602 ftp://ftp.nl.uu.net/pub/CPAN/
603 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
604 http://cpan.cybercomm.nl/
605 ftp://mirror.cybercomm.nl/pub/CPAN
606 ftp://mirror.vuurwerk.nl/pub/CPAN/
607 ftp://ftp.cpan.nl/pub/CPAN/
608 http://ftp.easynet.nl/mirror/CPAN
609 ftp://ftp.easynet.nl/mirror/CPAN
610 http://archive.cs.uu.nl/mirror/CPAN/
611 ftp://ftp.cs.uu.nl/mirror/CPAN/
615 ftp://ftp.uninett.no/pub/languages/perl/CPAN
616 ftp://ftp.uit.no/pub/languages/perl/cpan/
620 ftp://ftp.mega.net.pl/CPAN
621 ftp://ftp.man.torun.pl/pub/doc/CPAN/
622 ftp://sunsite.icm.edu.pl/pub/CPAN/
626 ftp://ftp.ua.pt/pub/CPAN/
627 ftp://perl.di.uminho.pt/pub/CPAN/
628 http://cpan.dei.uc.pt/
629 ftp://ftp.dei.uc.pt/pub/CPAN
630 ftp://ftp.nfsi.pt/pub/CPAN
631 http://ftp.linux.pt/pub/mirrors/CPAN
632 ftp://ftp.linux.pt/pub/mirrors/CPAN
634 ftp://cpan.ip.pt/pub/cpan/
635 http://cpan.telepac.pt/
636 ftp://ftp.telepac.pt/pub/cpan/
640 ftp://ftp.bio-net.ro/pub/CPAN
641 ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
642 ftp://ftp.lug.ro/CPAN
643 ftp://ftp.roedu.net/pub/CPAN/
644 ftp://ftp.dntis.ro/pub/cpan/
645 ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
646 http://cpan.ambra.ro/
647 ftp://ftp.ambra.ro/pub/CPAN
648 ftp://ftp.dnttm.ro/pub/CPAN/
649 ftp://ftp.lasting.ro/pub/CPAN
650 ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
654 ftp://ftp.chg.ru/pub/lang/perl/CPAN/
655 http://cpan.rinet.ru/
656 ftp://cpan.rinet.ru/pub/mirror/CPAN/
657 ftp://ftp.aha.ru/pub/CPAN/
658 ftp://ftp.corbina.ru/pub/CPAN/
659 http://cpan.sai.msu.ru/
660 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
664 ftp://ftp.cvt.stuba.sk/pub/CPAN/
668 ftp://ftp.arnes.si/software/perl/CPAN/
672 http://cpan.imasd.elmundo.es/
673 ftp://ftp.rediris.es/mirror/CPAN/
674 ftp://ftp.ri.telefonica-data.net/CPAN
675 ftp://ftp.etse.urv.es/pub/perl/
679 http://ftp.du.se/CPAN/
680 ftp://ftp.du.se/pub/CPAN/
681 http://mirror.dataphone.se/CPAN
682 ftp://mirror.dataphone.se/pub/CPAN
683 ftp://ftp.sunet.se/pub/lang/perl/CPAN/
687 http://cpan.mirror.solnet.ch/
688 ftp://ftp.solnet.ch/mirror/CPAN/
689 ftp://ftp.danyk.ch/CPAN/
690 ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
694 http://ftp.ulak.net.tr/perl/CPAN/
695 ftp://ftp.ulak.net.tr/perl/CPAN
696 ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
702 ftp://ftp.perl.org.ua/pub/CPAN/
703 http://no-more.kiev.ua/CPAN/
704 ftp://no-more.kiev.ua/pub/CPAN/
708 http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
709 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
710 http://cpan.teleglobe.net/
711 ftp://cpan.teleglobe.net/pub/CPAN
712 http://cpan.mirror.anlx.net/
713 ftp://ftp.mirror.anlx.net/CPAN/
714 http://cpan.etla.org/
715 ftp://cpan.etla.org/pub/CPAN
716 ftp://ftp.demon.co.uk/pub/CPAN/
717 http://cpan.m.flirble.org/
718 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
719 ftp://ftp.plig.org/pub/CPAN/
720 http://cpan.hambule.co.uk/
721 http://cpan.mirrors.clockerz.net/
722 ftp://ftp.clockerz.net/pub/CPAN/
723 ftp://usit.shef.ac.uk/pub/packages/CPAN/
737 http://cpan.sunsite.ualberta.ca/
738 ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
742 http://theoryx5.uwinnipeg.ca/pub/CPAN/
743 ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
747 ftp://cpan.chebucto.ns.ca/pub/CPAN/
751 ftp://ftp.nrc.ca/pub/CPAN/
757 http://cpan.azc.uam.mx
758 ftp://cpan.azc.uam.mx/mirrors/CPAN
759 http://www.cpan.unam.mx/
760 ftp://ftp.unam.mx/pub/CPAN
761 http://www.msg.com.mx/CPAN/
762 ftp://ftp.msg.com.mx/pub/CPAN/
770 http://mirror.hiwaay.net/CPAN/
771 ftp://mirror.hiwaay.net/CPAN/
775 http://cpan.develooper.com/
777 ftp://cpan.valueclick.com/pub/CPAN/
778 http://www.mednor.net/ftp/pub/mirrors/CPAN/
779 ftp://ftp.mednor.net/pub/mirrors/CPAN/
780 http://mirrors.gossamer-threads.com/CPAN
781 ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
782 http://mirrors.kernel.org/cpan/
783 ftp://mirrors.kernel.org/pub/CPAN
784 http://cpan-sj.viaverio.com/
785 ftp://cpan-sj.viaverio.com/pub/CPAN/
786 http://cpan.digisle.net/
787 ftp://cpan.digisle.net/pub/CPAN
788 http://www.perl.com/CPAN/
789 http://www.uberlan.net/CPAN
793 ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
794 http://cpan.four10.com
798 http://ftp.lug.udel.edu/pub/CPAN
799 ftp://ftp.lug.udel.edu/pub/CPAN
801 =item District of Columbia
803 ftp://ftp.dc.aleron.net/pub/CPAN/
807 ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
808 http://mirror.csit.fsu.edu/pub/CPAN/
809 ftp://mirror.csit.fsu.edu/pub/CPAN/
810 http://cpan.mirrors.nks.net/
814 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
815 http://cpan.netnitco.net/
816 ftp://cpan.netnitco.net/pub/mirrors/CPAN/
817 http://archive.progeny.com/CPAN/
818 ftp://archive.progeny.com/CPAN/
819 http://fx.saintjoe.edu/pub/CPAN
820 ftp://ftp.saintjoe.edu/pub/CPAN
821 http://csociety-ftp.ecn.purdue.edu/pub/CPAN
822 ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
827 ftp://cpan.uky.edu/pub/CPAN/
828 http://slugsite.louisville.edu/cpan
829 ftp://slugsite.louisville.edu/CPAN
833 http://mirrors.towardex.com/CPAN
834 ftp://mirrors.towardex.com/pub/CPAN
835 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
839 ftp://cpan.cse.msu.edu/
840 http://cpan.calvin.edu/pub/CPAN
841 ftp://cpan.calvin.edu/pub/CPAN
845 http://www.oss.redundant.com/pub/CPAN
846 ftp://www.oss.redundant.com/pub/CPAN
850 http://ftp.cpanel.net/pub/CPAN/
851 ftp://ftp.cpanel.net/pub/CPAN/
852 http://cpan.teleglobe.net/
853 ftp://cpan.teleglobe.net/pub/CPAN
857 http://cpan.belfry.net/
858 http://cpan.erlbaum.net/
859 ftp://cpan.erlbaum.net/
860 http://cpan.thepirtgroup.com/
861 ftp://cpan.thepirtgroup.com/
862 ftp://ftp.stealth.net/pub/CPAN/
863 http://www.rge.com/pub/languages/perl/
864 ftp://ftp.rge.com/pub/languages/perl/
868 http://www.ibiblio.org/pub/languages/perl/CPAN
869 ftp://ftp.ibiblio.org/pub/languages/perl/CPAN
870 ftp://ftp.duke.edu/pub/perl/
871 ftp://ftp.ncsu.edu/pub/mirror/CPAN/
875 ftp://ftp.ou.edu/mirrors/CPAN/
879 ftp://ftp.orst.edu/pub/CPAN
883 http://ftp.epix.net/CPAN/
884 ftp://ftp.epix.net/pub/languages/perl/
885 http://mirrors.phenominet.com/pub/CPAN/
886 ftp://mirrors.phenominet.com/pub/CPAN/
887 http://cpan.pair.com/
888 ftp://cpan.pair.com/pub/CPAN/
889 ftp://carroll.cac.psu.edu/pub/CPAN/
893 ftp://ftp.sunsite.utk.edu/pub/CPAN/
897 http://ftp.sedl.org/pub/mirrors/CPAN/
898 http://www.binarycode.org/cpan
899 ftp://mirror.telentente.com/pub/CPAN
900 http://mirrors.theonlinerecordstore.com/CPAN
904 ftp://mirror.xmission.com/CPAN/
908 http://cpan-du.viaverio.com/
909 ftp://cpan-du.viaverio.com/pub/CPAN/
910 http://mirrors.rcn.net/pub/lang/CPAN/
911 ftp://mirrors.rcn.net/pub/lang/CPAN/
912 http://perl.secsup.org/
913 ftp://perl.secsup.org/pub/perl/
914 http://noc.cvaix.com/mirrors/CPAN/
918 http://cpan.llarian.net/
919 ftp://cpan.llarian.net/pub/CPAN/
920 http://cpan.mirrorcentral.com/
921 ftp://ftp.mirrorcentral.com/pub/CPAN/
922 ftp://ftp-mirror.internap.com/pub/CPAN/
926 http://mirror.sit.wisc.edu/pub/CPAN/
927 ftp://mirror.sit.wisc.edu/pub/CPAN/
928 http://mirror.aphix.com/CPAN
929 ftp://mirror.aphix.com/pub/CPAN
941 http://ftp.planetmirror.com/pub/CPAN/
942 ftp://ftp.planetmirror.com/pub/CPAN/
943 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
944 ftp://cpan.topend.com.au/pub/CPAN/
945 http://cpan.mirrors.ilisys.com.au
949 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
953 http://aniani.ifa.hawaii.edu/CPAN/
954 ftp://aniani.ifa.hawaii.edu/CPAN/
964 ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
965 http://www.linux.org.ar/mirrors/cpan
966 ftp://ftp.linux.org.ar/mirrors/cpan
970 ftp://cpan.pop-mg.com.br/pub/CPAN/
971 ftp://ftp.matrix.com.br/pub/perl/CPAN/
972 http://cpan.hostsul.com.br/
973 ftp://cpan.hostsul.com.br/
977 http://cpan.netglobalis.net/
978 ftp://cpan.netglobalis.net/pub/CPAN/
984 www.linux.org.ar::cpan
985 theoryx5.uwinnipeg.ca::CPAN
986 ftp.shellhung.org::CPAN
987 rsync.nic.funet.fi::CPAN
988 ftp.u-paris10.fr::CPAN
990 rsync://ftp.crihan.fr::CPAN
991 ftp.gwdg.de::FTP/languages/perl/CPAN/
994 rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
995 ftp.iglu.org.il::CPAN
996 gusp.dyndns.org::cpan
997 ftp.kddlabs.co.jp::cpan
998 ftp.ayamura.org::pub/CPAN/
999 mirror.leafbug.org::CPAN
1000 rsync.en.com.sg::CPAN
1001 mirror.averse.net::cpan
1002 rsync.oss.eznetsols.org
1003 ftp.kr.FreeBSD.org::CPAN
1005 cpan.cdpa.nsysu.edu.tw::CPAN
1006 cpan.teleglobe.net::CPAN
1007 rsync://rsync.mirror.anlx.net::CPAN
1010 cpan-du.viaverio.com::CPAN
1011 aniani.ifa.hawaii.edu::CPAN
1012 archive.progeny.com::CPAN
1013 rsync://slugsite.louisville.edu::CPAN
1014 mirror.aphix.com::CPAN
1015 cpan.teleglobe.net::CPAN
1016 ftp.lug.udel.edu::cpan
1017 mirrors.kernel.org::mirrors/CPAN
1018 mirrors.phenominet.com::CPAN
1020 cpan-sj.viaverio.com::CPAN
1021 mirror.csit.fsu.edu::CPAN
1022 csociety-ftp.ecn.purdue.edu::CPAN
1024 For an up-to-date listing of CPAN sites,
1025 see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
1027 =head1 Modules: Creation, Use, and Abuse
1029 (The following section is borrowed directly from Tim Bunce's modules
1030 file, available at your nearest CPAN site.)
1032 Perl implements a class using a package, but the presence of a
1033 package doesn't imply the presence of a class. A package is just a
1034 namespace. A class is a package that provides subroutines that can be
1035 used as methods. A method is just a subroutine that expects, as its
1036 first argument, either the name of a package (for "static" methods),
1037 or a reference to something (for "virtual" methods).
1039 A module is a file that (by convention) provides a class of the same
1040 name (sans the .pm), plus an import method in that class that can be
1041 called to fetch exported symbols. This module may implement some of
1042 its methods by loading dynamic C or C++ objects, but that should be
1043 totally transparent to the user of the module. Likewise, the module
1044 might set up an AUTOLOAD function to slurp in subroutine definitions on
1045 demand, but this is also transparent. Only the F<.pm> file is required to
1046 exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1047 the AUTOLOAD mechanism.
1049 =head2 Guidelines for Module Creation
1055 Do similar modules already exist in some form?
1057 If so, please try to reuse the existing modules either in whole or
1058 by inheriting useful features into a new class. If this is not
1059 practical try to get together with the module authors to work on
1060 extending or enhancing the functionality of the existing modules.
1061 A perfect example is the plethora of packages in perl4 for dealing
1062 with command line options.
1064 If you are writing a module to expand an already existing set of
1065 modules, please coordinate with the author of the package. It
1066 helps if you follow the same naming scheme and module interaction
1067 scheme as the original author.
1071 Try to design the new module to be easy to extend and reuse.
1073 Try to C<use warnings;> (or C<use warnings qw(...);>).
1074 Remember that you can add C<no warnings qw(...);> to individual blocks
1075 of code that need less warnings.
1077 Use blessed references. Use the two argument form of bless to bless
1078 into the class name given as the first parameter of the constructor,
1083 return bless {}, $class;
1086 or even this if you'd like it to be used as either a static
1087 or a virtual method.
1091 my $class = ref($self) || $self;
1092 return bless {}, $class;
1095 Pass arrays as references so more parameters can be added later
1096 (it's also faster). Convert functions into methods where
1097 appropriate. Split large methods into smaller more flexible ones.
1098 Inherit methods from other modules if appropriate.
1100 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1101 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1102 Let the objects look after themselves! Generally, avoid hard-wired
1103 class names as far as possible.
1105 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1106 C<< $r->func() >> would work (see L<perlbot> for more details).
1108 Use autosplit so little used or newly added functions won't be a
1109 burden to programs that don't use them. Add test functions to
1110 the module after __END__ either using AutoSplit or by saying:
1112 eval join('',<main::DATA>) || die $@ unless caller();
1114 Does your module pass the 'empty subclass' test? If you say
1115 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1116 to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1117 does your application still work if you change: C<< $obj = YOURCLASS->new(); >>
1118 into: C<< $obj = SUBCLASS->new(); >> ?
1120 Avoid keeping any state information in your packages. It makes it
1121 difficult for multiple other packages to use yours. Keep state
1122 information in objects.
1126 Try to C<use strict;> (or C<use strict qw(...);>).
1127 Remember that you can add C<no strict qw(...);> to individual blocks
1128 of code that need less strictness.
1132 Follow the guidelines in the perlstyle(1) manual.
1138 Some simple style guidelines
1140 The perlstyle manual supplied with Perl has many helpful points.
1142 Coding style is a matter of personal taste. Many people evolve their
1143 style over several years as they learn what helps them write and
1144 maintain good code. Here's one set of assorted suggestions that
1145 seem to be widely used by experienced developers:
1147 Use underscores to separate words. It is generally easier to read
1148 $var_names_like_this than $VarNamesLikeThis, especially for
1149 non-native speakers of English. It's also a simple rule that works
1150 consistently with VAR_NAMES_LIKE_THIS.
1152 Package/Module names are an exception to this rule. Perl informally
1153 reserves lowercase module names for 'pragma' modules like integer
1154 and strict. Other modules normally begin with a capital letter and
1155 use mixed case with no underscores (need to be short and portable).
1157 You may find it helpful to use letter case to indicate the scope
1158 or nature of a variable. For example:
1160 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
1161 $Some_Caps_Here package-wide global/static
1162 $no_caps_here function scope my() or local() variables
1164 Function and method names seem to work best as all lowercase.
1165 e.g., C<< $obj->as_string() >>.
1167 You can use a leading underscore to indicate that a variable or
1168 function should not be used outside the package that defined it.
1172 Select what to export.
1174 Do NOT export method names!
1176 Do NOT export anything else by default without a good reason!
1178 Exports pollute the namespace of the module user. If you must
1179 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1180 short or common names to reduce the risk of name clashes.
1182 Generally anything not exported is still accessible from outside the
1183 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1184 syntax. By convention you can use a leading underscore on names to
1185 indicate informally that they are 'internal' and not for public use.
1187 (It is actually possible to get private functions by saying:
1188 C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1189 directly as a method, because a method must have a name in the symbol
1192 As a general rule, if the module is trying to be object oriented
1193 then export nothing. If it's just a collection of functions then
1194 @EXPORT_OK anything but use @EXPORT with caution.
1198 Select a name for the module.
1200 This name should be as descriptive, accurate, and complete as
1201 possible. Avoid any risk of ambiguity. Always try to use two or
1202 more whole words. Generally the name should reflect what is special
1203 about what the module does rather than how it does it. Please use
1204 nested module names to group informally or categorize a module.
1205 There should be a very good reason for a module not to have a nested name.
1206 Module names should begin with a capital letter.
1208 Having 57 modules all called Sort will not make life easy for anyone
1209 (though having 23 called Sort::Quick is only marginally better :-).
1210 Imagine someone trying to install your module alongside many others.
1211 If in any doubt ask for suggestions in comp.lang.perl.misc.
1213 If you are developing a suite of related modules/classes it's good
1214 practice to use nested classes with a common prefix as this will
1215 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1216 Xyz::Model etc. Use the modules in this list as a naming guide.
1218 If adding a new module to a set, follow the original author's
1219 standards for naming modules and the interface to methods in
1222 If developing modules for private internal or project specific use,
1223 that will never be released to the public, then you should ensure
1224 that their names will not clash with any future public module. You
1225 can do this either by using the reserved Local::* category or by
1226 using a category name that includes an underscore like Foo_Corp::*.
1228 To be portable each component of a module name should be limited to
1229 11 characters. If it might be used on MS-DOS then try to ensure each is
1230 unique in the first 8 characters. Nested modules make this easier.
1234 Have you got it right?
1236 How do you know that you've made the right decisions? Have you
1237 picked an interface design that will cause problems later? Have
1238 you picked the most appropriate name? Do you have any questions?
1240 The best way to know for sure, and pick up many helpful suggestions,
1241 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1242 all the people who develop modules and it's the best place to ask.
1244 All you need to do is post a short summary of the module, its
1245 purpose and interfaces. A few lines on each of the main methods is
1246 probably enough. (If you post the whole module it might be ignored
1247 by busy people - generally the very people you want to read it!)
1249 Don't worry about posting if you can't say when the module will be
1250 ready - just say so in the message. It might be worth inviting
1251 others to help you, they may be able to complete it for you!
1255 README and other Additional Files.
1257 It's well known that software developers usually fully document the
1258 software they write. If, however, the world is in urgent need of
1259 your software and there is not enough time to write the full
1260 documentation please at least provide a README file containing:
1266 A description of the module/package/extension etc.
1270 A copyright notice - see below.
1274 Prerequisites - what else you may need to have.
1278 How to build it - possible changes to Makefile.PL etc.
1286 Recent changes in this release, especially incompatibilities
1290 Changes / enhancements you plan to make in the future.
1294 If the README file seems to be getting too large you may wish to
1295 split out some of the sections into separate files: INSTALL,
1302 Adding a Copyright Notice.
1304 How you choose to license your work is a personal decision.
1305 The general mechanism is to assert your Copyright and then make
1306 a declaration of how others may copy/use/modify your work.
1308 Perl, for example, is supplied with two types of licence: The GNU GPL
1309 and The Artistic Licence (see the files README, Copying, and Artistic,
1310 or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
1311 just using the GNU GPL.
1313 My personal recommendation, out of respect for Larry, Perl, and the
1314 Perl community at large is to state something simply like:
1316 Copyright (c) 1995 Your Name. All rights reserved.
1317 This program is free software; you can redistribute it and/or
1318 modify it under the same terms as Perl itself.
1320 This statement should at least appear in the README file. You may
1321 also wish to include it in a Copying file and your source files.
1322 Remember to include the other words in addition to the Copyright.
1326 Give the module a version/issue/release number.
1328 To be fully compatible with the Exporter and MakeMaker modules you
1329 should store your module's version number in a non-my package
1330 variable called $VERSION. This should be a floating point
1331 number with at least two digits after the decimal (i.e., hundredths,
1332 e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1333 See L<Exporter> for details.
1335 It may be handy to add a function or method to retrieve the number.
1336 Use the number in announcements and archive file names when
1337 releasing the module (ModuleName-1.02.tar.Z).
1338 See perldoc ExtUtils::MakeMaker.pm for details.
1342 How to release and distribute a module.
1344 It's good idea to post an announcement of the availability of your
1345 module (or the module itself if small) to the comp.lang.perl.announce
1346 Usenet newsgroup. This will at least ensure very wide once-off
1349 If possible, register the module with CPAN. You should
1350 include details of its location in your announcement.
1352 Some notes about ftp archives: Please use a long descriptive file
1353 name that includes the version number. Most incoming directories
1354 will not be readable/listable, i.e., you won't be able to see your
1355 file after uploading it. Remember to send your email notification
1356 message as soon as possible after uploading else your file may get
1357 deleted automatically. Allow time for the file to be processed
1358 and/or check the file has been processed before announcing its
1361 FTP Archives for Perl Modules:
1363 Follow the instructions and links on:
1365 http://www.cpan.org/modules/00modlist.long.html
1366 http://www.cpan.org/modules/04pause.html
1368 or upload to one of these sites:
1370 https://pause.kbx.de/pause/
1371 http://pause.perl.org/pause/
1373 and notify <modules@perl.org>.
1375 By using the WWW interface you can ask the Upload Server to mirror
1376 your modules from your ftp or WWW site into your own directory on
1379 Please remember to send me an updated entry for the Module list!
1383 Take care when changing a released module.
1385 Always strive to remain compatible with previous released versions.
1386 Otherwise try to add a mechanism to revert to the
1387 old behavior if people rely on it. Document incompatible changes.
1393 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1399 There is no requirement to convert anything.
1401 If it ain't broke, don't fix it! Perl 4 library scripts should
1402 continue to work with no problems. You may need to make some minor
1403 changes (like escaping non-array @'s in double quoted strings) but
1404 there is no need to convert a .pl file into a Module for just that.
1408 Consider the implications.
1410 All Perl applications that make use of the script will need to
1411 be changed (slightly) if the script is converted into a module. Is
1412 it worth it unless you plan to make other changes at the same time?
1416 Make the most of the opportunity.
1418 If you are going to convert the script to a module you can use the
1419 opportunity to redesign the interface. The guidelines for module
1420 creation above include many of the issues you should consider.
1424 The pl2pm utility will get you started.
1426 This utility will read *.pl files (given as parameters) and write
1427 corresponding *.pm files. The pl2pm utilities does the following:
1433 Adds the standard Module prologue lines
1437 Converts package specifiers from ' to ::
1441 Converts die(...) to croak(...)
1445 Several other minor changes
1449 Being a mechanical process pl2pm is not bullet proof. The converted
1450 code will need careful checking, especially any package statements.
1451 Don't delete the original .pl file till the new .pm one works!
1455 =head2 Guidelines for Reusing Application Code
1461 Complete applications rarely belong in the Perl Module Library.
1465 Many applications contain some Perl code that could be reused.
1467 Help save the world! Share your code in a form that makes it easy
1472 Break-out the reusable code into one or more separate module files.
1476 Take the opportunity to reconsider and redesign the interfaces.
1480 In some cases the 'application' can then be reduced to a small
1482 fragment of code built on top of the reusable modules. In these cases
1483 the application could invoked as:
1485 % perl -e 'use Module::Name; method(@ARGV)' ...
1487 % perl -mModule::Name ... (in perl5.002 or higher)
1493 Perl does not enforce private and public parts of its modules as you may
1494 have been used to in other languages like C++, Ada, or Modula-17. Perl
1495 doesn't have an infatuation with enforced privacy. It would prefer
1496 that you stayed out of its living room because you weren't invited, not
1497 because it has a shotgun.
1499 The module and its user have a contract, part of which is common law,
1500 and part of which is "written". Part of the common law contract is
1501 that a module doesn't pollute any namespace it wasn't asked to. The
1502 written contract for the module (A.K.A. documentation) may make other
1503 provisions. But then you know when you C<use RedefineTheWorld> that
1504 you're redefining the world and willing to take the consequences.
1507 close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
1508 close OUT or warn "$0: failed to close OUT (perlmodlib.pod): $!";