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 http://search.cpan.org/dist/perl/pod/perlmodlib.PL
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 http://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 The list of the registered CPAN sites follows.
336 Please note that the sorting order is alphabetical on fields:
348 and thus the North American servers happen to be listed between the
349 European and the South American sites.
351 Registered CPAN sites
354 Generated by Porting/make_modlib_cpan.pl
362 http://mirror.is.co.za/pub/cpan/
363 ftp://ftp.is.co.za/pub/cpan/
364 http://cpan.mirror.ac.za/
365 ftp://cpan.mirror.ac.za/
366 http://cpan.saix.net/
367 ftp://ftp.saix.net/pub/CPAN/
368 http://ftp.wa.co.za/pub/CPAN/
369 ftp://ftp.wa.co.za/pub/CPAN/
373 http://mirror.ucu.ac.ug/cpan/
377 http://mirror.zol.co.zw/CPAN/
378 ftp://mirror.zol.co.zw/CPAN/
388 http://mirror.dhakacom.com/CPAN/
389 ftp://mirror.dhakacom.com/CPAN/
393 http://cpan.communilink.net/
394 http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
395 ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
396 http://mirrors.hust.edu.cn/CPAN/
397 http://mirrors.neusoft.edu.cn/cpan/
398 http://mirror.lzu.edu.cn/CPAN/
399 http://mirrors.163.com/cpan/
400 http://mirrors.sohu.com/CPAN/
401 http://mirrors.ustc.edu.cn/CPAN/
402 ftp://mirrors.ustc.edu.cn/CPAN/
403 http://mirrors.xmu.edu.cn/CPAN/
404 ftp://mirrors.xmu.edu.cn/CPAN/
405 http://mirrors.zju.edu.cn/CPAN/
409 http://cpan.excellmedia.net/
410 http://perlmirror.indialinks.com/
414 http://kambing.ui.ac.id/cpan/
415 http://cpan.pesat.net.id/
416 http://mirror.poliwangi.ac.id/CPAN/
417 http://kartolo.sby.datautama.net.id/CPAN/
418 http://mirror.wanxp.id/cpan/
422 http://mirror.yazd.ac.ir/cpan/
426 http://biocourse.weizmann.ac.il/CPAN/
430 http://ftp.jaist.ac.jp/pub/CPAN/
431 ftp://ftp.jaist.ac.jp/pub/CPAN/
432 http://mirror.jre655.com/CPAN/
433 ftp://mirror.jre655.com/CPAN/
434 ftp://ftp.kddilabs.jp/CPAN/
435 http://ftp.nara.wide.ad.jp/pub/CPAN/
436 ftp://ftp.nara.wide.ad.jp/pub/CPAN/
437 http://ftp.riken.jp/lang/CPAN/
438 ftp://ftp.riken.jp/lang/CPAN/
439 ftp://ftp.u-aizu.ac.jp/pub/CPAN/
440 http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
441 ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
445 http://mirror.neolabs.kz/CPAN/
446 ftp://mirror.neolabs.kz/CPAN/
450 http://mirror.pregi.net/CPAN/
451 ftp://mirror.pregi.net/CPAN/
452 http://mirror.rise.ph/cpan/
453 ftp://mirror.rise.ph/cpan/
457 http://mirror.qnren.qa/CPAN/
458 ftp://mirror.qnren.qa/CPAN/
460 =item Republic of Korea
462 http://cpan.mirror.cdnetworks.com/
463 ftp://cpan.mirror.cdnetworks.com/CPAN/
464 http://ftp.kaist.ac.kr/pub/CPAN/
465 ftp://ftp.kaist.ac.kr/CPAN/
466 http://ftp.kr.freebsd.org/pub/CPAN/
467 ftp://ftp.kr.freebsd.org/pub/CPAN/
468 http://mirror.navercorp.com/CPAN/
469 http://ftp.neowiz.com/CPAN/
470 ftp://ftp.neowiz.com/CPAN/
474 http://cpan.mirror.choon.net/
475 http://mirror.0x.sg/CPAN/
476 ftp://mirror.0x.sg/CPAN/
480 http://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
481 ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
482 http://cpan.stu.edu.tw/
483 ftp://ftp.stu.edu.tw/CPAN/
484 http://ftp.yzu.edu.tw/CPAN/
485 ftp://ftp.yzu.edu.tw/CPAN/
486 http://cpan.nctu.edu.tw/
487 ftp://cpan.nctu.edu.tw/
488 http://ftp.ubuntu-tw.org/mirror/CPAN/
489 ftp://ftp.ubuntu-tw.org/mirror/CPAN/
493 http://cpan.ulak.net.tr/
494 ftp://ftp.ulak.net.tr/pub/perl/CPAN/
495 http://mirror.vit.com.tr/mirror/CPAN/
496 ftp://mirror.vit.com.tr/CPAN/
500 http://mirrors.digipower.vn/CPAN/
501 http://mirror.downloadvn.com/cpan/
502 http://mirrors.vinahost.vn/CPAN/
512 http://cpan.inode.at/
514 http://mirror.easyname.at/cpan/
515 ftp://mirror.easyname.at/cpan/
516 http://gd.tuwien.ac.at/languages/perl/CPAN/
517 ftp://gd.tuwien.ac.at/pub/CPAN/
521 http://ftp.byfly.by/pub/CPAN/
522 ftp://ftp.byfly.by/pub/CPAN/
523 http://mirror.datacenter.by/pub/CPAN/
524 ftp://mirror.datacenter.by/pub/CPAN/
528 http://ftp.belnet.be/ftp.cpan.org/
529 ftp://ftp.belnet.be/mirror/ftp.cpan.org/
531 http://lib.ugent.be/CPAN/
532 http://cpan.weepeetelecom.be/
534 =item Bosnia and Herzegovina
536 http://cpan.mirror.ba/
537 ftp://ftp.mirror.ba/CPAN/
541 http://mirrors.neterra.net/CPAN/
542 ftp://mirrors.neterra.net/CPAN/
543 http://mirrors.netix.net/CPAN/
544 ftp://mirrors.netix.net/CPAN/
548 http://ftp.carnet.hr/pub/CPAN/
549 ftp://ftp.carnet.hr/pub/CPAN/
553 http://mirror.dkm.cz/cpan/
554 ftp://mirror.dkm.cz/cpan/
555 ftp://ftp.fi.muni.cz/pub/CPAN/
556 http://mirrors.nic.cz/CPAN/
557 ftp://mirrors.nic.cz/pub/CPAN/
558 http://cpan.mirror.vutbr.cz/
559 ftp://mirror.vutbr.cz/cpan/
564 http://mirrors.dotsrc.org/cpan/
565 ftp://mirrors.dotsrc.org/cpan/
569 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
573 http://ftp.ciril.fr/pub/cpan/
574 ftp://ftp.ciril.fr/pub/cpan/
575 http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
576 ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
577 http://ftp.lip6.fr/pub/perl/CPAN/
578 ftp://ftp.lip6.fr/pub/perl/CPAN/
579 http://mirror.ibcp.fr/pub/CPAN/
580 ftp://ftp.oleane.net/pub/CPAN/
581 http://cpan.mirrors.ovh.net/ftp.cpan.org/
582 ftp://cpan.mirrors.ovh.net/ftp.cpan.org/
583 http://cpan.enstimac.fr/
587 http://mirror.23media.de/cpan/
588 ftp://mirror.23media.de/cpan/
589 http://artfiles.org/cpan.org/
590 ftp://artfiles.org/cpan.org/
591 http://mirror.bibleonline.ru/cpan/
592 http://mirror.checkdomain.de/CPAN/
593 ftp://mirror.checkdomain.de/CPAN/
594 http://cpan.noris.de/
595 http://mirror.de.leaseweb.net/CPAN/
596 ftp://mirror.de.leaseweb.net/CPAN/
597 http://cpan.mirror.euserv.net/
598 ftp://mirror.euserv.net/cpan/
599 http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
600 ftp://mirror.fraunhofer.de/CPAN/
601 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
602 http://ftp.hosteurope.de/pub/CPAN/
603 ftp://ftp.hosteurope.de/pub/CPAN/
604 ftp://ftp.fu-berlin.de/unix/languages/perl/
605 http://ftp.gwdg.de/pub/languages/perl/CPAN/
606 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
607 http://ftp.hawo.stw.uni-erlangen.de/CPAN/
608 ftp://ftp.hawo.stw.uni-erlangen.de/CPAN/
609 http://cpan.mirror.iphh.net/
610 ftp://cpan.mirror.iphh.net/pub/CPAN/
611 ftp://ftp.mpi-inf.mpg.de/pub/perl/CPAN/
612 http://cpan.netbet.org/
613 http://mirror.netcologne.de/cpan/
614 ftp://mirror.netcologne.de/cpan/
615 ftp://mirror.petamem.com/CPAN/
616 http://www.planet-elektronik.de/CPAN/
617 http://ftp.halifax.rwth-aachen.de/cpan/
618 ftp://ftp.halifax.rwth-aachen.de/cpan/
619 http://mirror.softaculous.com/cpan/
620 http://ftp.u-tx.net/CPAN/
621 ftp://ftp.u-tx.net/CPAN/
622 http://mirror.reismil.ch/CPAN/
626 http://cpan.cc.uoc.gr/mirrors/CPAN/
627 ftp://ftp.cc.uoc.gr/mirrors/CPAN/
628 http://ftp.ntua.gr/pub/lang/perl/
629 ftp://ftp.ntua.gr/pub/lang/perl/
633 http://mirror.met.hu/CPAN/
637 http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
638 ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
642 http://bo.mirror.garr.it/mirrors/CPAN/
643 ftp://ftp.eutelia.it/CPAN_Mirror/
645 ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
646 http://cpan.muzzy.it/
650 http://kvin.lv/pub/CPAN/
654 http://ftp.litnet.lt/pub/CPAN/
655 ftp://ftp.litnet.lt/pub/CPAN/
659 http://mirror.as43289.net/pub/CPAN/
660 ftp://mirror.as43289.net/pub/CPAN/
664 http://cpan.cs.uu.nl/
665 ftp://ftp.cs.uu.nl/pub/CPAN/
666 http://mirror.nl.leaseweb.net/CPAN/
667 ftp://mirror.nl.leaseweb.net/CPAN/
668 http://ftp.nluug.nl/languages/perl/CPAN/
669 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
670 http://mirror.transip.net/CPAN/
671 ftp://mirror.transip.net/CPAN/
672 http://cpan.mirror.triple-it.nl/
673 http://ftp.tudelft.nl/cpan/
674 ftp://ftp.tudelft.nl/pub/CPAN/
675 ftp://download.xs4all.nl/pub/mirror/CPAN/
680 ftp://cpan.uib.no/pub/CPAN/
681 ftp://ftp.uninett.no/pub/languages/perl/CPAN/
682 http://cpan.vianett.no/
686 http://ftp.agh.edu.pl/CPAN/
687 ftp://ftp.agh.edu.pl/CPAN/
688 http://ftp.piotrkosoft.net/pub/mirrors/CPAN/
689 ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
690 ftp://ftp.ps.pl/pub/CPAN/
691 http://sunsite.icm.edu.pl/pub/CPAN/
692 ftp://sunsite.icm.edu.pl/pub/CPAN/
696 http://cpan.dcc.fc.up.pt/
697 http://mirrors.fe.up.pt/pub/CPAN/
698 http://cpan.perl-hackers.net/
703 http://mirrors.hostingromania.ro/cpan.org/
704 ftp://ftp.lug.ro/CPAN/
705 http://mirrors.m247.ro/CPAN/
706 http://mirrors.evowise.com/CPAN/
707 http://mirrors.teentelecom.net/CPAN/
708 ftp://mirrors.teentelecom.net/CPAN/
709 http://mirrors.xservers.ro/CPAN/
711 =item Russian Federation
713 ftp://ftp.aha.ru/CPAN/
714 http://cpan.rinet.ru/
715 ftp://cpan.rinet.ru/pub/mirror/CPAN/
716 http://cpan-mirror.rbc.ru/pub/CPAN/
717 http://mirror.rol.ru/CPAN/
718 http://cpan.uni-altai.ru/
719 http://cpan.webdesk.ru/
720 ftp://cpan.webdesk.ru/cpan/
721 http://mirror.yandex.ru/mirrors/cpan/
722 ftp://mirror.yandex.ru/mirrors/cpan/
726 http://mirror.sbb.rs/CPAN/
727 ftp://mirror.sbb.rs/CPAN/
732 http://tux.rainside.sk/CPAN/
733 ftp://tux.rainside.sk/CPAN/
737 http://ftp.arnes.si/software/perl/CPAN/
738 ftp://ftp.arnes.si/software/perl/CPAN/
742 http://mirrors.evowise.com/CPAN/
743 http://osl.ugr.es/CPAN/
744 http://ftp.rediris.es/mirror/CPAN/
745 ftp://ftp.rediris.es/mirror/CPAN/
749 http://ftp.acc.umu.se/mirror/CPAN/
750 ftp://ftp.acc.umu.se/mirror/CPAN/
754 http://www.pirbot.com/mirrors/cpan/
755 http://mirror.switch.ch/ftp/mirror/CPAN/
756 ftp://mirror.switch.ch/mirror/CPAN/
760 http://cpan.ip-connect.vn.ua/
761 ftp://cpan.ip-connect.vn.ua/mirror/cpan/
765 http://cpan.mirror.anlx.net/
766 ftp://ftp.mirror.anlx.net/CPAN/
767 http://mirror.bytemark.co.uk/CPAN/
768 ftp://mirror.bytemark.co.uk/CPAN/
769 http://mirrors.coreix.net/CPAN/
770 http://cpan.etla.org/
771 ftp://cpan.etla.org/pub/CPAN/
772 http://cpan.cpantesters.org/
773 http://mirror.sax.uk.as61049.net/CPAN/
774 http://mirror.sov.uk.goscomb.net/CPAN/
775 http://www.mirrorservice.org/sites/cpan.perl.org/CPAN/
776 ftp://ftp.mirrorservice.org/sites/cpan.perl.org/CPAN/
777 http://mirror.ox.ac.uk/sites/www.cpan.org/
778 ftp://mirror.ox.ac.uk/sites/www.cpan.org/
779 http://ftp.ticklers.org/pub/CPAN/
780 ftp://ftp.ticklers.org/pub/CPAN/
781 http://cpan.mirrors.uk2.net/
782 ftp://mirrors.uk2.net/pub/CPAN/
783 http://mirror.ukhost4u.com/CPAN/
793 http://CPAN.mirror.rafal.ca/
794 ftp://CPAN.mirror.rafal.ca/pub/CPAN/
795 http://mirror.csclub.uwaterloo.ca/CPAN/
796 ftp://mirror.csclub.uwaterloo.ca/CPAN/
797 http://mirrors.gossamer-threads.com/CPAN/
798 http://mirror.its.dal.ca/cpan/
799 ftp://mirror.its.dal.ca/cpan/
800 ftp://ftp.ottix.net/pub/CPAN/
804 http://mirrors.ucr.ac.cr/CPAN/
808 http://www.msg.com.mx/CPAN/
809 ftp://ftp.msg.com.mx/pub/CPAN/
817 http://mirror.teklinks.com/CPAN/
821 http://mirror.n5tech.com/CPAN/
822 http://mirrors.namecheap.com/CPAN/
823 ftp://mirrors.namecheap.com/CPAN/
827 http://cpan.develooper.com/
828 http://httpupdate127.cpanel.net/CPAN/
829 http://mirrors.sonic.net/cpan/
830 ftp://mirrors.sonic.net/cpan/
831 http://www.perl.com/CPAN/
832 http://cpan.yimg.com/
836 http://mirrors.syringanetworks.net/CPAN/
837 ftp://mirrors.syringanetworks.net/CPAN/
841 http://cpan.mirrors.hoobly.com/
842 http://mirror.team-cymru.org/CPAN/
843 ftp://mirror.team-cymru.org/CPAN/
847 http://cpan.netnitco.net/
848 ftp://cpan.netnitco.net/pub/mirrors/CPAN/
849 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
853 http://mirrors.concertpass.com/cpan/
857 http://mirrors.ccs.neu.edu/CPAN/
861 http://cpan.cse.msu.edu/
862 ftp://cpan.cse.msu.edu/
863 http://httpupdate118.cpanel.net/CPAN/
864 http://mirrors-usa.go-parts.com/cpan/
865 http://ftp.wayne.edu/CPAN/
866 ftp://ftp.wayne.edu/CPAN/
870 http://mirror.metrocast.net/cpan/
874 http://mirror.datapipe.net/CPAN/
875 ftp://mirror.datapipe.net/pub/CPAN/
876 http://www.hoovism.com/CPAN/
877 ftp://ftp.hoovism.com/CPAN/
878 http://cpan.mirror.nac.net/
882 http://mirror.cc.columbia.edu/pub/software/cpan/
883 ftp://mirror.cc.columbia.edu/pub/software/cpan/
884 http://cpan.belfry.net/
885 http://cpan.erlbaum.net/
886 ftp://cpan.erlbaum.net/CPAN/
887 http://cpan.hexten.net/
888 ftp://cpan.hexten.net/
889 http://mirror.nyi.net/CPAN/
890 ftp://mirror.nyi.net/pub/CPAN/
891 http://noodle.portalus.net/CPAN/
892 ftp://noodle.portalus.net/CPAN/
893 http://mirrors.rit.edu/CPAN/
894 ftp://mirrors.rit.edu/CPAN/
898 http://httpupdate140.cpanel.net/CPAN/
899 http://mirrors.ibiblio.org/CPAN/
903 http://ftp.osuosl.org/pub/CPAN/
904 ftp://ftp.osuosl.org/pub/CPAN/
905 http://mirror.uoregon.edu/CPAN/
909 http://cpan.pair.com/
910 ftp://cpan.pair.com/pub/CPAN/
911 http://cpan.mirrors.ionfish.org/
915 http://cpan.mirror.clemson.edu/
919 http://mirror.uta.edu/CPAN/
923 http://cpan.cs.utah.edu/
924 ftp://cpan.cs.utah.edu/CPAN/
925 ftp://mirror.xmission.com/CPAN/
929 http://mirror.cogentco.com/pub/CPAN/
930 ftp://mirror.cogentco.com/pub/CPAN/
931 http://mirror.jmu.edu/pub/CPAN/
932 ftp://mirror.jmu.edu/pub/CPAN/
933 http://mirror.us.leaseweb.net/CPAN/
934 ftp://mirror.us.leaseweb.net/CPAN/
938 http://cpan.llarian.net/
939 ftp://cpan.llarian.net/pub/CPAN/
943 http://cpan.mirrors.tds.net/
944 ftp://cpan.mirrors.tds.net/pub/CPAN/
956 http://mirror.as24220.net/pub/cpan/
957 ftp://mirror.as24220.net/pub/cpan/
958 http://cpan.mirrors.ilisys.com.au/
959 http://cpan.mirror.digitalpacific.com.au/
960 ftp://mirror.internode.on.net/pub/cpan/
961 http://mirror.optusnet.com.au/CPAN/
962 http://cpan.mirror.serversaustralia.com.au/
963 http://cpan.uberglobalmirror.com/
964 http://mirror.waia.asn.au/pub/cpan/
968 http://cpan.lagoon.nc/pub/CPAN/
969 ftp://cpan.lagoon.nc/pub/CPAN/
970 http://cpan.nautile.nc/CPAN/
971 ftp://cpan.nautile.nc/CPAN/
975 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
976 http://cpan.catalyst.net.nz/CPAN/
977 ftp://cpan.catalyst.net.nz/pub/CPAN/
978 http://cpan.inspire.net.nz/
979 ftp://cpan.inspire.net.nz/cpan/
980 http://mirror.webtastix.net/CPAN/
981 ftp://mirror.webtastix.net/CPAN/
991 http://cpan.mmgdesigns.com.ar/
995 http://cpan.kinghost.net/
996 http://linorg.usp.br/CPAN/
997 http://mirror.nbtelecom.com.br/CPAN/
1001 http://cpan.dcc.uchile.cl/
1002 ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
1006 =head2 RSYNC Mirrors
1008 rsync://ftp.is.co.za/IS-Mirror/ftp.cpan.org/
1009 rsync://mirror.ac.za/CPAN/
1010 rsync://mirror.zol.co.zw/CPAN/
1011 rsync://mirror.dhakacom.com/CPAN/
1012 rsync://mirrors.ustc.edu.cn/CPAN/
1013 rsync://mirrors.xmu.edu.cn/CPAN/
1014 rsync://kambing.ui.ac.id/CPAN/
1015 rsync://ftp.jaist.ac.jp/pub/CPAN/
1016 rsync://mirror.jre655.com/CPAN/
1017 rsync://ftp.kddilabs.jp/cpan/
1018 rsync://ftp.nara.wide.ad.jp/cpan/
1019 rsync://ftp.riken.jp/cpan/
1020 rsync://mirror.neolabs.kz/CPAN/
1021 rsync://mirror.qnren.qa/CPAN/
1022 rsync://ftp.neowiz.com/CPAN/
1023 rsync://mirror.0x.sg/CPAN/
1024 rsync://ftp.yzu.edu.tw/pub/CPAN/
1025 rsync://ftp.ubuntu-tw.org/CPAN/
1026 rsync://mirrors.digipower.vn/CPAN/
1027 rsync://cpan.inode.at/CPAN/
1028 rsync://ftp.byfly.by/CPAN/
1029 rsync://mirror.datacenter.by/CPAN/
1030 rsync://ftp.belnet.be/cpan/
1031 rsync://cpan.mirror.ba/CPAN/
1032 rsync://mirrors.neterra.net/CPAN/
1033 rsync://mirrors.netix.net/CPAN/
1034 rsync://mirror.dkm.cz/cpan/
1035 rsync://mirrors.nic.cz/CPAN/
1036 rsync://cpan.mirror.vutbr.cz/cpan/
1037 rsync://rsync.nic.funet.fi/CPAN/
1038 rsync://ftp.ciril.fr/pub/cpan/
1039 rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
1040 rsync://cpan.mirrors.ovh.net/CPAN/
1041 rsync://mirror.de.leaseweb.net/CPAN/
1042 rsync://mirror.euserv.net/cpan/
1043 rsync://ftp-stud.hs-esslingen.de/CPAN/
1044 rsync://ftp.gwdg.de/pub/languages/perl/CPAN/
1045 rsync://ftp.hawo.stw.uni-erlangen.de/CPAN/
1046 rsync://cpan.mirror.iphh.net/CPAN/
1047 rsync://mirror.netcologne.de/cpan/
1048 rsync://ftp.halifax.rwth-aachen.de/cpan/
1049 rsync://ftp.ntua.gr/CPAN/
1050 rsync://mirror.met.hu/CPAN/
1051 rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
1052 rsync://rsync.panu.it/CPAN/
1053 rsync://mirror.as43289.net/CPAN/
1054 rsync://rsync.cs.uu.nl/CPAN/
1055 rsync://mirror.nl.leaseweb.net/CPAN/
1056 rsync://ftp.nluug.nl/CPAN/
1057 rsync://mirror.transip.net/CPAN/
1058 rsync://cpan.uib.no/cpan/
1059 rsync://cpan.vianett.no/CPAN/
1060 rsync://cpan.perl-hackers.net/CPAN/
1061 rsync://cpan.perl.pt/cpan/
1062 rsync://mirrors.m247.ro/CPAN/
1063 rsync://mirrors.teentelecom.net/CPAN/
1064 rsync://cpan.webdesk.ru/CPAN/
1065 rsync://mirror.yandex.ru/mirrors/cpan/
1066 rsync://mirror.sbb.rs/CPAN/
1067 rsync://ftp.acc.umu.se/mirror/CPAN/
1068 rsync://rsync.pirbot.com/ftp/cpan/
1069 rsync://cpan.ip-connect.vn.ua/CPAN/
1070 rsync://rsync.mirror.anlx.net/CPAN/
1071 rsync://mirror.bytemark.co.uk/CPAN/
1072 rsync://mirror.sax.uk.as61049.net/CPAN/
1073 rsync://rsync.mirrorservice.org/cpan.perl.org/CPAN/
1074 rsync://ftp.ticklers.org/CPAN/
1075 rsync://mirrors.uk2.net/CPAN/
1076 rsync://CPAN.mirror.rafal.ca/CPAN/
1077 rsync://mirror.csclub.uwaterloo.ca/CPAN/
1078 rsync://mirrors.namecheap.com/CPAN/
1079 rsync://mirrors.syringanetworks.net/CPAN/
1080 rsync://mirror.team-cymru.org/CPAN/
1081 rsync://debian.cse.msu.edu/cpan/
1082 rsync://mirrors-usa.go-parts.com/mirrors/cpan/
1083 rsync://rsync.hoovism.com/CPAN/
1084 rsync://mirror.cc.columbia.edu/cpan/
1085 rsync://noodle.portalus.net/CPAN/
1086 rsync://mirrors.rit.edu/cpan/
1087 rsync://mirrors.ibiblio.org/CPAN/
1088 rsync://cpan.pair.com/CPAN/
1089 rsync://cpan.cs.utah.edu/CPAN/
1090 rsync://mirror.cogentco.com/CPAN/
1091 rsync://mirror.jmu.edu/CPAN/
1092 rsync://mirror.us.leaseweb.net/CPAN/
1093 rsync://cpan.mirror.digitalpacific.com.au/cpan/
1094 rsync://mirror.internode.on.net/cpan/
1095 rsync://uberglobalmirror.com/cpan/
1096 rsync://cpan.lagoon.nc/cpan/
1097 rsync://mirrors.mmgdesigns.com.ar/CPAN/
1100 For an up-to-date listing of CPAN sites,
1101 see L<http://www.cpan.org/SITES> or L<ftp://www.cpan.org/SITES>.
1103 =head1 Modules: Creation, Use, and Abuse
1105 (The following section is borrowed directly from Tim Bunce's modules
1106 file, available at your nearest CPAN site.)
1108 Perl implements a class using a package, but the presence of a
1109 package doesn't imply the presence of a class. A package is just a
1110 namespace. A class is a package that provides subroutines that can be
1111 used as methods. A method is just a subroutine that expects, as its
1112 first argument, either the name of a package (for "static" methods),
1113 or a reference to something (for "virtual" methods).
1115 A module is a file that (by convention) provides a class of the same
1116 name (sans the .pm), plus an import method in that class that can be
1117 called to fetch exported symbols. This module may implement some of
1118 its methods by loading dynamic C or C++ objects, but that should be
1119 totally transparent to the user of the module. Likewise, the module
1120 might set up an AUTOLOAD function to slurp in subroutine definitions on
1121 demand, but this is also transparent. Only the F<.pm> file is required to
1122 exist. See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
1123 the AUTOLOAD mechanism.
1125 =head2 Guidelines for Module Creation
1131 Do similar modules already exist in some form?
1133 If so, please try to reuse the existing modules either in whole or
1134 by inheriting useful features into a new class. If this is not
1135 practical try to get together with the module authors to work on
1136 extending or enhancing the functionality of the existing modules.
1137 A perfect example is the plethora of packages in perl4 for dealing
1138 with command line options.
1140 If you are writing a module to expand an already existing set of
1141 modules, please coordinate with the author of the package. It
1142 helps if you follow the same naming scheme and module interaction
1143 scheme as the original author.
1147 Try to design the new module to be easy to extend and reuse.
1149 Try to C<use warnings;> (or C<use warnings qw(...);>).
1150 Remember that you can add C<no warnings qw(...);> to individual blocks
1151 of code that need less warnings.
1153 Use blessed references. Use the two argument form of bless to bless
1154 into the class name given as the first parameter of the constructor,
1159 return bless {}, $class;
1162 or even this if you'd like it to be used as either a static
1163 or a virtual method.
1167 my $class = ref($self) || $self;
1168 return bless {}, $class;
1171 Pass arrays as references so more parameters can be added later
1172 (it's also faster). Convert functions into methods where
1173 appropriate. Split large methods into smaller more flexible ones.
1174 Inherit methods from other modules if appropriate.
1176 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1177 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1178 Let the objects look after themselves! Generally, avoid hard-wired
1179 class names as far as possible.
1181 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1182 C<< $r->func() >> would work.
1184 Use autosplit so little used or newly added functions won't be a
1185 burden to programs that don't use them. Add test functions to
1186 the module after __END__ either using AutoSplit or by saying:
1188 eval join('',<main::DATA>) || die $@ unless caller();
1190 Does your module pass the 'empty subclass' test? If you say
1191 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1192 to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1193 does your application still work if you change: C<< $obj = YOURCLASS->new(); >>
1194 into: C<< $obj = SUBCLASS->new(); >> ?
1196 Avoid keeping any state information in your packages. It makes it
1197 difficult for multiple other packages to use yours. Keep state
1198 information in objects.
1202 Try to C<use strict;> (or C<use strict qw(...);>).
1203 Remember that you can add C<no strict qw(...);> to individual blocks
1204 of code that need less strictness.
1208 Follow the guidelines in L<perlstyle>.
1214 Some simple style guidelines
1216 The perlstyle manual supplied with Perl has many helpful points.
1218 Coding style is a matter of personal taste. Many people evolve their
1219 style over several years as they learn what helps them write and
1220 maintain good code. Here's one set of assorted suggestions that
1221 seem to be widely used by experienced developers:
1223 Use underscores to separate words. It is generally easier to read
1224 $var_names_like_this than $VarNamesLikeThis, especially for
1225 non-native speakers of English. It's also a simple rule that works
1226 consistently with VAR_NAMES_LIKE_THIS.
1228 Package/Module names are an exception to this rule. Perl informally
1229 reserves lowercase module names for 'pragma' modules like integer
1230 and strict. Other modules normally begin with a capital letter and
1231 use mixed case with no underscores (need to be short and portable).
1233 You may find it helpful to use letter case to indicate the scope
1234 or nature of a variable. For example:
1236 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
1237 $Some_Caps_Here package-wide global/static
1238 $no_caps_here function scope my() or local() variables
1240 Function and method names seem to work best as all lowercase.
1241 e.g., C<< $obj->as_string() >>.
1243 You can use a leading underscore to indicate that a variable or
1244 function should not be used outside the package that defined it.
1248 Select what to export.
1250 Do NOT export method names!
1252 Do NOT export anything else by default without a good reason!
1254 Exports pollute the namespace of the module user. If you must
1255 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1256 short or common names to reduce the risk of name clashes.
1258 Generally anything not exported is still accessible from outside the
1259 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1260 syntax. By convention you can use a leading underscore on names to
1261 indicate informally that they are 'internal' and not for public use.
1263 (It is actually possible to get private functions by saying:
1264 C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1265 directly as a method, because a method must have a name in the symbol
1268 As a general rule, if the module is trying to be object oriented
1269 then export nothing. If it's just a collection of functions then
1270 @EXPORT_OK anything but use @EXPORT with caution.
1274 Select a name for the module.
1276 This name should be as descriptive, accurate, and complete as
1277 possible. Avoid any risk of ambiguity. Always try to use two or
1278 more whole words. Generally the name should reflect what is special
1279 about what the module does rather than how it does it. Please use
1280 nested module names to group informally or categorize a module.
1281 There should be a very good reason for a module not to have a nested name.
1282 Module names should begin with a capital letter.
1284 Having 57 modules all called Sort will not make life easy for anyone
1285 (though having 23 called Sort::Quick is only marginally better :-).
1286 Imagine someone trying to install your module alongside many others.
1288 If you are developing a suite of related modules/classes it's good
1289 practice to use nested classes with a common prefix as this will
1290 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1291 Xyz::Model etc. Use the modules in this list as a naming guide.
1293 If adding a new module to a set, follow the original author's
1294 standards for naming modules and the interface to methods in
1297 If developing modules for private internal or project specific use,
1298 that will never be released to the public, then you should ensure
1299 that their names will not clash with any future public module. You
1300 can do this either by using the reserved Local::* category or by
1301 using a category name that includes an underscore like Foo_Corp::*.
1303 To be portable each component of a module name should be limited to
1304 11 characters. If it might be used on MS-DOS then try to ensure each is
1305 unique in the first 8 characters. Nested modules make this easier.
1307 For additional guidance on the naming of modules, please consult:
1309 http://pause.perl.org/pause/query?ACTION=pause_namingmodules
1311 or send mail to the <module-authors@perl.org> mailing list.
1315 Have you got it right?
1317 How do you know that you've made the right decisions? Have you
1318 picked an interface design that will cause problems later? Have
1319 you picked the most appropriate name? Do you have any questions?
1321 The best way to know for sure, and pick up many helpful suggestions,
1322 is to ask someone who knows. The <module-authors@perl.org> mailing list
1323 is useful for this purpose; it's also accessible via news interface as
1324 perl.module-authors at nntp.perl.org.
1326 All you need to do is post a short summary of the module, its
1327 purpose and interfaces. A few lines on each of the main methods is
1328 probably enough. (If you post the whole module it might be ignored
1329 by busy people - generally the very people you want to read it!)
1331 Don't worry about posting if you can't say when the module will be
1332 ready - just say so in the message. It might be worth inviting
1333 others to help you, they may be able to complete it for you!
1337 README and other Additional Files.
1339 It's well known that software developers usually fully document the
1340 software they write. If, however, the world is in urgent need of
1341 your software and there is not enough time to write the full
1342 documentation please at least provide a README file containing:
1348 A description of the module/package/extension etc.
1352 A copyright notice - see below.
1356 Prerequisites - what else you may need to have.
1360 How to build it - possible changes to Makefile.PL etc.
1368 Recent changes in this release, especially incompatibilities
1372 Changes / enhancements you plan to make in the future.
1376 If the README file seems to be getting too large you may wish to
1377 split out some of the sections into separate files: INSTALL,
1384 Adding a Copyright Notice.
1386 How you choose to license your work is a personal decision.
1387 The general mechanism is to assert your Copyright and then make
1388 a declaration of how others may copy/use/modify your work.
1390 Perl, for example, is supplied with two types of licence: The GNU GPL
1391 and The Artistic Licence (see the files README, Copying, and Artistic,
1392 or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
1393 just using the GNU GPL.
1395 My personal recommendation, out of respect for Larry, Perl, and the
1396 Perl community at large is to state something simply like:
1398 Copyright (c) 1995 Your Name. All rights reserved.
1399 This program is free software; you can redistribute it and/or
1400 modify it under the same terms as Perl itself.
1402 This statement should at least appear in the README file. You may
1403 also wish to include it in a Copying file and your source files.
1404 Remember to include the other words in addition to the Copyright.
1408 Give the module a version/issue/release number.
1410 To be fully compatible with the Exporter and MakeMaker modules you
1411 should store your module's version number in a non-my package
1412 variable called $VERSION. This should be a positive floating point
1413 number with at least two digits after the decimal (i.e., hundredths,
1414 e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1415 See L<Exporter> for details.
1417 It may be handy to add a function or method to retrieve the number.
1418 Use the number in announcements and archive file names when
1419 releasing the module (ModuleName-1.02.tar.Z).
1420 See perldoc ExtUtils::MakeMaker.pm for details.
1424 How to release and distribute a module.
1426 If possible, register the module with CPAN. Follow the instructions
1429 http://www.cpan.org/modules/04pause.html
1433 http://pause.perl.org/
1435 and notify <modules@perl.org>. This will allow anyone to install
1436 your module using the C<cpan> tool distributed with Perl.
1438 By using the WWW interface you can ask the Upload Server to mirror
1439 your modules from your ftp or WWW site into your own directory on
1444 Take care when changing a released module.
1446 Always strive to remain compatible with previous released versions.
1447 Otherwise try to add a mechanism to revert to the
1448 old behavior if people rely on it. Document incompatible changes.
1454 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1460 There is no requirement to convert anything.
1462 If it ain't broke, don't fix it! Perl 4 library scripts should
1463 continue to work with no problems. You may need to make some minor
1464 changes (like escaping non-array @'s in double quoted strings) but
1465 there is no need to convert a .pl file into a Module for just that.
1469 Consider the implications.
1471 All Perl applications that make use of the script will need to
1472 be changed (slightly) if the script is converted into a module. Is
1473 it worth it unless you plan to make other changes at the same time?
1477 Make the most of the opportunity.
1479 If you are going to convert the script to a module you can use the
1480 opportunity to redesign the interface. The guidelines for module
1481 creation above include many of the issues you should consider.
1485 The pl2pm utility will get you started.
1487 This utility will read *.pl files (given as parameters) and write
1488 corresponding *.pm files. The pl2pm utilities does the following:
1494 Adds the standard Module prologue lines
1498 Converts package specifiers from ' to ::
1502 Converts die(...) to croak(...)
1506 Several other minor changes
1510 Being a mechanical process pl2pm is not bullet proof. The converted
1511 code will need careful checking, especially any package statements.
1512 Don't delete the original .pl file till the new .pm one works!
1516 =head2 Guidelines for Reusing Application Code
1522 Complete applications rarely belong in the Perl Module Library.
1526 Many applications contain some Perl code that could be reused.
1528 Help save the world! Share your code in a form that makes it easy
1533 Break-out the reusable code into one or more separate module files.
1537 Take the opportunity to reconsider and redesign the interfaces.
1541 In some cases the 'application' can then be reduced to a small
1543 fragment of code built on top of the reusable modules. In these cases
1544 the application could invoked as:
1546 % perl -e 'use Module::Name; method(@ARGV)' ...
1548 % perl -mModule::Name ... (in perl5.002 or higher)
1554 Perl does not enforce private and public parts of its modules as you may
1555 have been used to in other languages like C++, Ada, or Modula-17. Perl
1556 doesn't have an infatuation with enforced privacy. It would prefer
1557 that you stayed out of its living room because you weren't invited, not
1558 because it has a shotgun.
1560 The module and its user have a contract, part of which is common law,
1561 and part of which is "written". Part of the common law contract is
1562 that a module doesn't pollute any namespace it wasn't asked to. The
1563 written contract for the module (A.K.A. documentation) may make other
1564 provisions. But then you know when you C<use RedefineTheWorld> that
1565 you're redefining the world and willing to take the consequences.
1569 read_only_bottom_close_and_rename($out);