This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Move more URLs from http:// to https://
[perl5.git] / pod / perlmodlib.PL
CommitLineData
2e1d04bc
JH
1#!../miniperl
2
5b504182
NC
3use strict;
4use warnings;
5
bdba2fe9 6local $ENV{LC_ALL} = 'C';
1fa7ca25 7
f556af6c
NC
8my $Quiet;
9@ARGV = grep { not($_ eq '-q' and $Quiet = 1) } @ARGV;
291c64f4 10
f556af6c
NC
11if (@ARGV) {
12 my $workdir = shift;
13 chdir $workdir
14 or die "Couldn't chdir to '$workdir': $!";
15}
3d7c117d 16require './regen/regen_lib.pl';
4d671226 17
291c64f4
NC
18# MANIFEST itself is Unix style filenames, so we have to assume that Unix style
19# filenames will work.
20
f556af6c
NC
21open MANIFEST, '<', 'MANIFEST'
22 or die "Can't open MANIFEST: $!";
0f6ab019
TI
23my @files =
24 grep !m#/perl.*\.pod#,
25 grep m#(?:\.pm|\.pod|_pm\.PL)#,
26 map {s/\s.*//s; $_}
4bbd41f5 27 grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo|corpus)/# }
0f6ab019 28 <MANIFEST>;
f556af6c
NC
29close MANIFEST
30 or die "$0: failed to close MANIFEST: $!";
31
32my $out = open_new('pod/perlmodlib.pod', undef,
33 {by => "$0 extracting documentation",
34 from => 'the Perl source files'}, 1);
cf9cbb1f
NC
35
36my %exceptions = (
37 'abbrev' => 'Text::Abbrev',
38 'carp' => 'Carp',
39 'getopt' => 'Getopt::Std',
cf9cbb1f
NC
40 'Encode::MIME::NAME' => 'Encode::MIME::Name',
41 'libnetFAQ' => 'Net::libnetFAQ',
4e42dfb1
JB
42);
43
f556af6c
NC
44my (@pragma, @mod);
45
cf9cbb1f 46for my $filename (@files) {
f556af6c
NC
47 unless (open MOD, '<', $filename) {
48 warn "Couldn't open $filename: $!";
e8041d9b 49 next;
4e42dfb1 50 }
4e860d0a 51
5b504182
NC
52 my ($name, $thing);
53 my $foundit = 0;
54 {
55 local $/ = "";
56 while (<MOD>) {
57 next unless /^=head1 NAME/;
58 $foundit++;
59 last;
60 }
61 }
62 unless ($foundit) {
4bbd41f5
AC
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;
5b504182
NC
70 next;
71 }
72 my $title = <MOD>;
73 chomp $title;
f556af6c
NC
74 close MOD
75 or die "Error closing $filename: $!";
1fa7ca25 76
2085092c 77 ($name, $thing) = split /\s+--?\s+/, $title, 2;
4e42dfb1 78
5b504182
NC
79 unless ($name and $thing) {
80 warn "$filename missing name\n" unless $name;
81 warn "$filename missing thing\n" unless $thing or $Quiet;
82 next;
83 }
84
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";
90
91 if ($name =~ /[A-Z]/) {
92 push @mod, $title;
93 } else {
94 push @pragma, $title;
95 }
2e1d04bc
JH
96}
97
4bbd41f5
AC
98sub pod_for_module_has_head1_NAME {
99 my ($filename) = @_;
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";
104 local $/ = '';
105 while (my $para = <$fh>) {
106 return 1 if $para =~ /\A=head1 NAME$/m;
107 }
108 return 0;
109}
110
cf9cbb1f
NC
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)
d72ea276 114push @mod, "=item Config\n\nAccess Perl configuration information\n\n";
cf9cbb1f 115
cf9cbb1f 116
d72ea276
NC
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
71c89d21 121# Perl code for Pod. eg https://search.cpan.org/dist/perl/pod/perlmodlib.PL
cf9cbb1f 122
f556af6c 123print $out <<'=cut';
2e1d04bc
JH
124=head1 NAME
125
126perlmodlib - constructing new Perl modules and finding existing ones
127
2e1d04bc
JH
128=head1 THE PERL MODULE LIBRARY
129
7ef5744c 130Many modules are included in the Perl distribution. These are described
2e1d04bc 131below, and all end in F<.pm>. You may discover compiled library
7ef5744c 132files (usually ending in F<.so>) or small pieces of modules to be
2e1d04bc
JH
133autoloaded (ending in F<.al>); these were automatically generated
134by the installation process. You may also discover files in the
135library directory that end in either F<.pl> or F<.ph>. These are
136old libraries supplied so that old programs that use them still
137run. The F<.pl> files will all eventually be converted into standard
138modules, and the F<.ph> files made by B<h2ph> will probably end up
139as extension modules made by B<h2xs>. (Some F<.ph> values may
140already be available through the POSIX, Errno, or Fcntl modules.)
141The B<pl2pm> file in the distribution may help in your conversion,
142but it's just a mechanical process and therefore far from bulletproof.
143
144=head2 Pragmatic Modules
145
146They work somewhat like compiler directives (pragmata) in that they
147tend to affect the compilation of your program, and thus will usually
148work well only when used within a C<use>, or C<no>. Most of these
149are lexically scoped, so an inner BLOCK may countermand them
150by saying:
151
152 no integer;
153 no strict 'refs';
154 no warnings;
155
156which lasts until the end of that BLOCK.
157
158Some pragmas are lexically scoped--typically those that affect the
159C<$^H> hints variable. Others affect the current package instead,
160like C<use vars> and C<use subs>, which allow you to predeclare a
161variables or subroutines within a particular I<file> rather than
162just a block. Such declarations are effective for the entire file
163for which they were declared. You cannot rescind them with C<no
164vars> or C<no subs>.
165
166The following pragmas are defined (and have their own documentation).
167
168=over 12
169
d72ea276 170=cut
2e1d04bc 171
f556af6c 172print $out $_ for sort @pragma;
2e1d04bc 173
f556af6c 174print $out <<'=cut';
d72ea276 175
2e1d04bc
JH
176=back
177
178=head2 Standard Modules
179
180Standard, bundled modules are all expected to behave in a well-defined
181manner with respect to namespace pollution because they use the
182Exporter module. See their own documentation for details.
183
7ef5744c
RGS
184It's possible that not all modules listed below are installed on your
185system. For example, the GDBM_File module will not be installed if you
186don't have the gdbm library.
187
2e1d04bc
JH
188=over 12
189
d72ea276 190=cut
2e1d04bc 191
f556af6c 192print $out $_ for sort @mod;
2e1d04bc 193
f556af6c 194print $out <<'=cut', "=cut\n";
d72ea276 195
2e1d04bc
JH
196=back
197
198To find out I<all> modules installed on your system, including
199those without documentation or outside the standard release,
a4373870
CW
200just use the following command (under the default win32 shell,
201double quotes should be used instead of single quotes).
2e1d04bc 202
a4373870
CW
203 % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
204 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
205 no_chdir => 1 }, @INC'
2e1d04bc 206
8518420c 207(The -T is here to prevent '.' from being listed in @INC.)
2e1d04bc
JH
208They should all have their own documentation installed and accessible
209via your system man(1) command. If you do not have a B<find>
210program, you can use the Perl B<find2perl> program instead, which
211generates Perl code as output you can run through perl. If you
212have a B<man> program but it doesn't find your modules, you'll have
213to fix your manpath. See L<perl> for details. If you have no
214system B<man> command, you might try the B<perldoc> program.
215
8518420c
RGS
216Note also that the command C<perldoc perllocal> gives you a (possibly
217incomplete) list of the modules that have been further installed on
218your system. (The perllocal.pod file is updated by the standard MakeMaker
219install process.)
220
2e1d04bc
JH
221=head2 Extension Modules
222
223Extension modules are written in C (or a mix of Perl and C). They
224are usually dynamically loaded into Perl if and when you need them,
da75cd15 225but may also be linked in statically. Supported extension modules
2e1d04bc
JH
226include Socket, Fcntl, and POSIX.
227
228Many popular C extension modules do not come bundled (at least, not
229completely) due to their sizes, volatility, or simply lack of time
230for adequate testing and configuration across the multitude of
231platforms on which Perl was beta-tested. You are encouraged to
232look for them on CPAN (described below), or using web search engines
42aeee0b 233like Google or DuckDuckGo.
2e1d04bc
JH
234
235=head1 CPAN
236
237CPAN stands for Comprehensive Perl Archive Network; it's a globally
238replicated trove of Perl materials, including documentation, style
239guides, tricks and traps, alternate ports to non-Unix systems and
240occasional binary distributions for these. Search engines for
71c89d21 241CPAN can be found at https://www.cpan.org/
2e1d04bc
JH
242
243Most importantly, CPAN includes around a thousand unbundled modules,
244some of which require a C compiler to build. Major categories of
245modules are:
246
247=over
248
249=item *
ac634a9a 250
2e1d04bc
JH
251Language Extensions and Documentation Tools
252
253=item *
ac634a9a 254
2e1d04bc
JH
255Development Support
256
257=item *
ac634a9a 258
2e1d04bc
JH
259Operating System Interfaces
260
261=item *
ac634a9a 262
2e1d04bc
JH
263Networking, Device Control (modems) and InterProcess Communication
264
265=item *
ac634a9a 266
2e1d04bc
JH
267Data Types and Data Type Utilities
268
269=item *
ac634a9a 270
2e1d04bc
JH
271Database Interfaces
272
273=item *
ac634a9a 274
2e1d04bc
JH
275User Interfaces
276
277=item *
ac634a9a 278
2e1d04bc
JH
279Interfaces to / Emulations of Other Programming Languages
280
281=item *
ac634a9a 282
2e1d04bc
JH
283File Names, File Systems and File Locking (see also File Handles)
284
285=item *
ac634a9a 286
2e1d04bc
JH
287String Processing, Language Text Processing, Parsing, and Searching
288
289=item *
ac634a9a 290
2e1d04bc
JH
291Option, Argument, Parameter, and Configuration File Processing
292
293=item *
ac634a9a 294
2e1d04bc
JH
295Internationalization and Locale
296
297=item *
ac634a9a 298
2e1d04bc
JH
299Authentication, Security, and Encryption
300
301=item *
ac634a9a 302
2e1d04bc
JH
303World Wide Web, HTML, HTTP, CGI, MIME
304
305=item *
ac634a9a 306
2e1d04bc
JH
307Server and Daemon Utilities
308
309=item *
ac634a9a 310
2e1d04bc
JH
311Archiving and Compression
312
313=item *
ac634a9a 314
2e1d04bc
JH
315Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
316
317=item *
ac634a9a 318
2e1d04bc
JH
319Mail and Usenet News
320
321=item *
ac634a9a 322
2e1d04bc
JH
323Control Flow Utilities (callbacks and exceptions etc)
324
325=item *
ac634a9a 326
2e1d04bc
JH
327File Handle and Input/Output Stream Utilities
328
329=item *
ac634a9a 330
2e1d04bc
JH
331Miscellaneous Modules
332
333=back
334
9d169eb4 335The list of the registered CPAN sites follows.
5df44211
JH
336Please note that the sorting order is alphabetical on fields:
337
338Continent
339 |
340 |-->Country
341 |
342 |-->[state/province]
343 |
344 |-->ftp
345 |
346 |-->[http]
347
348and thus the North American servers happen to be listed between the
349European and the South American sites.
350
9d169eb4 351Registered CPAN sites
2e1d04bc 352
04b029fe
LB
353=for maintainers
354Generated by Porting/make_modlib_cpan.pl
355
4e860d0a
JH
356=head2 Africa
357
358=over 4
359
5df44211 360=item South Africa
4e860d0a 361
04b029fe
LB
362 http://mirror.is.co.za/pub/cpan/
363 ftp://ftp.is.co.za/pub/cpan/
9ed2d9d9
CBW
364 http://cpan.mirror.ac.za/
365 ftp://cpan.mirror.ac.za/
366 http://cpan.saix.net/
04b029fe 367 ftp://ftp.saix.net/pub/CPAN/
9ed2d9d9
CBW
368 http://ftp.wa.co.za/pub/CPAN/
369 ftp://ftp.wa.co.za/pub/CPAN/
370
371=item Uganda
372
373 http://mirror.ucu.ac.ug/cpan/
374
375=item Zimbabwe
376
377 http://mirror.zol.co.zw/CPAN/
378 ftp://mirror.zol.co.zw/CPAN/
4e860d0a
JH
379
380=back
381
382=head2 Asia
383
384=over 4
385
9ed2d9d9 386=item Bangladesh
04b029fe 387
9ed2d9d9
CBW
388 http://mirror.dhakacom.com/CPAN/
389 ftp://mirror.dhakacom.com/CPAN/
04b029fe 390
9ed2d9d9 391=item China
4e860d0a 392
9ed2d9d9 393 http://cpan.communilink.net/
04b029fe
LB
394 http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
395 ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
9ed2d9d9
CBW
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/
c165c82a 406
9d169eb4 407=item India
c165c82a 408
9ed2d9d9 409 http://cpan.excellmedia.net/
04b029fe 410 http://perlmirror.indialinks.com/
c165c82a 411
9d169eb4 412=item Indonesia
c165c82a 413
9ed2d9d9 414 http://kambing.ui.ac.id/cpan/
04b029fe 415 http://cpan.pesat.net.id/
9ed2d9d9
CBW
416 http://mirror.poliwangi.ac.id/CPAN/
417 http://kartolo.sby.datautama.net.id/CPAN/
418 http://mirror.wanxp.id/cpan/
419
420=item Iran
421
422 http://mirror.yazd.ac.ir/cpan/
423
424=item Israel
425
426 http://biocourse.weizmann.ac.il/CPAN/
c165c82a 427
5df44211 428=item Japan
c165c82a 429
9ed2d9d9
CBW
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/
04b029fe
LB
434 ftp://ftp.kddilabs.jp/CPAN/
435 http://ftp.nara.wide.ad.jp/pub/CPAN/
436 ftp://ftp.nara.wide.ad.jp/pub/CPAN/
04b029fe
LB
437 http://ftp.riken.jp/lang/CPAN/
438 ftp://ftp.riken.jp/lang/CPAN/
9ed2d9d9 439 ftp://ftp.u-aizu.ac.jp/pub/CPAN/
04b029fe
LB
440 http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
441 ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
4e860d0a 442
9ed2d9d9
CBW
443=item Kazakhstan
444
445 http://mirror.neolabs.kz/CPAN/
446 ftp://mirror.neolabs.kz/CPAN/
447
448=item Philippines
449
450 http://mirror.pregi.net/CPAN/
451 ftp://mirror.pregi.net/CPAN/
452 http://mirror.rise.ph/cpan/
453 ftp://mirror.rise.ph/cpan/
454
455=item Qatar
456
457 http://mirror.qnren.qa/CPAN/
458 ftp://mirror.qnren.qa/CPAN/
459
9d169eb4 460=item Republic of Korea
4e860d0a 461
04b029fe
LB
462 http://cpan.mirror.cdnetworks.com/
463 ftp://cpan.mirror.cdnetworks.com/CPAN/
9ed2d9d9
CBW
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/
4e860d0a 471
5df44211 472=item Singapore
4e860d0a 473
04b029fe 474 http://cpan.mirror.choon.net/
9ed2d9d9
CBW
475 http://mirror.0x.sg/CPAN/
476 ftp://mirror.0x.sg/CPAN/
4e860d0a 477
5df44211 478=item Taiwan
4e860d0a 479
9ed2d9d9
CBW
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/
04b029fe
LB
486 http://cpan.nctu.edu.tw/
487 ftp://cpan.nctu.edu.tw/
9ed2d9d9
CBW
488 http://ftp.ubuntu-tw.org/mirror/CPAN/
489 ftp://ftp.ubuntu-tw.org/mirror/CPAN/
9d169eb4
LB
490
491=item Turkey
492
9ed2d9d9
CBW
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/
4e860d0a 497
9ed2d9d9 498=item Viet Nam
4e860d0a 499
9ed2d9d9
CBW
500 http://mirrors.digipower.vn/CPAN/
501 http://mirror.downloadvn.com/cpan/
502 http://mirrors.vinahost.vn/CPAN/
4e860d0a
JH
503
504=back
505
506=head2 Europe
507
508=over 4
509
5df44211 510=item Austria
4e860d0a 511
04b029fe 512 http://cpan.inode.at/
9ed2d9d9
CBW
513 ftp://cpan.inode.at/
514 http://mirror.easyname.at/cpan/
515 ftp://mirror.easyname.at/cpan/
04b029fe
LB
516 http://gd.tuwien.ac.at/languages/perl/CPAN/
517 ftp://gd.tuwien.ac.at/pub/CPAN/
4e860d0a 518
9ed2d9d9
CBW
519=item Belarus
520
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/
525
5df44211 526=item Belgium
4e860d0a 527
9ed2d9d9 528 http://ftp.belnet.be/ftp.cpan.org/
04b029fe 529 ftp://ftp.belnet.be/mirror/ftp.cpan.org/
9ed2d9d9
CBW
530 http://cpan.cu.be/
531 http://lib.ugent.be/CPAN/
532 http://cpan.weepeetelecom.be/
4e860d0a 533
7a142657
JH
534=item Bosnia and Herzegovina
535
9ed2d9d9
CBW
536 http://cpan.mirror.ba/
537 ftp://ftp.mirror.ba/CPAN/
7a142657 538
5df44211 539=item Bulgaria
4e860d0a 540
9ed2d9d9
CBW
541 http://mirrors.neterra.net/CPAN/
542 ftp://mirrors.neterra.net/CPAN/
543 http://mirrors.netix.net/CPAN/
544 ftp://mirrors.netix.net/CPAN/
4e860d0a 545
5df44211 546=item Croatia
4e860d0a 547
04b029fe
LB
548 http://ftp.carnet.hr/pub/CPAN/
549 ftp://ftp.carnet.hr/pub/CPAN/
4e860d0a 550
5df44211 551=item Czech Republic
4e860d0a 552
9ed2d9d9
CBW
553 http://mirror.dkm.cz/cpan/
554 ftp://mirror.dkm.cz/cpan/
04b029fe 555 ftp://ftp.fi.muni.cz/pub/CPAN/
9ed2d9d9
CBW
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/
4e860d0a 560
5df44211 561=item Denmark
4e860d0a 562
04b029fe 563 http://www.cpan.dk/
9ed2d9d9
CBW
564 http://mirrors.dotsrc.org/cpan/
565 ftp://mirrors.dotsrc.org/cpan/
4e860d0a 566
5df44211 567=item Finland
4e860d0a 568
04b029fe 569 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
4e860d0a 570
5df44211 571=item France
c165c82a 572
9ed2d9d9
CBW
573 http://ftp.ciril.fr/pub/cpan/
574 ftp://ftp.ciril.fr/pub/cpan/
04b029fe
LB
575 http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
576 ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
9ed2d9d9 577 http://ftp.lip6.fr/pub/perl/CPAN/
04b029fe 578 ftp://ftp.lip6.fr/pub/perl/CPAN/
9ed2d9d9 579 http://mirror.ibcp.fr/pub/CPAN/
04b029fe 580 ftp://ftp.oleane.net/pub/CPAN/
9ed2d9d9
CBW
581 http://cpan.mirrors.ovh.net/ftp.cpan.org/
582 ftp://cpan.mirrors.ovh.net/ftp.cpan.org/
583 http://cpan.enstimac.fr/
c165c82a 584
5df44211 585=item Germany
c165c82a 586
9ed2d9d9
CBW
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/
04b029fe
LB
602 http://ftp.hosteurope.de/pub/CPAN/
603 ftp://ftp.hosteurope.de/pub/CPAN/
9ed2d9d9 604 ftp://ftp.fu-berlin.de/unix/languages/perl/
04b029fe
LB
605 http://ftp.gwdg.de/pub/languages/perl/CPAN/
606 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
9ed2d9d9
CBW
607 http://ftp.hawo.stw.uni-erlangen.de/CPAN/
608 ftp://ftp.hawo.stw.uni-erlangen.de/CPAN/
04b029fe
LB
609 http://cpan.mirror.iphh.net/
610 ftp://cpan.mirror.iphh.net/pub/CPAN/
9ed2d9d9
CBW
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/
04b029fe 615 ftp://mirror.petamem.com/CPAN/
9ed2d9d9
CBW
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/
4e860d0a 623
5df44211 624=item Greece
4e860d0a 625
9ed2d9d9 626 http://cpan.cc.uoc.gr/mirrors/CPAN/
04b029fe 627 ftp://ftp.cc.uoc.gr/mirrors/CPAN/
9ed2d9d9
CBW
628 http://ftp.ntua.gr/pub/lang/perl/
629 ftp://ftp.ntua.gr/pub/lang/perl/
4e860d0a 630
5df44211 631=item Hungary
4e860d0a 632
9ed2d9d9 633 http://mirror.met.hu/CPAN/
4e860d0a 634
5df44211 635=item Ireland
4e860d0a 636
9ed2d9d9
CBW
637 http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
638 ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
4e860d0a 639
5df44211 640=item Italy
4e860d0a 641
04b029fe 642 http://bo.mirror.garr.it/mirrors/CPAN/
9ed2d9d9 643 ftp://ftp.eutelia.it/CPAN_Mirror/
04b029fe
LB
644 http://cpan.panu.it/
645 ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
9ed2d9d9 646 http://cpan.muzzy.it/
4e860d0a 647
5df44211 648=item Latvia
4e860d0a 649
04b029fe 650 http://kvin.lv/pub/CPAN/
4e860d0a 651
5df44211 652=item Lithuania
4e860d0a 653
04b029fe
LB
654 http://ftp.litnet.lt/pub/CPAN/
655 ftp://ftp.litnet.lt/pub/CPAN/
9d169eb4 656
9ed2d9d9 657=item Moldova
9d169eb4 658
9ed2d9d9
CBW
659 http://mirror.as43289.net/pub/CPAN/
660 ftp://mirror.as43289.net/pub/CPAN/
4e860d0a 661
5df44211 662=item Netherlands
4e860d0a 663
9ed2d9d9
CBW
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/
04b029fe 675 ftp://download.xs4all.nl/pub/mirror/CPAN/
4e860d0a 676
5df44211
JH
677=item Norway
678
9ed2d9d9
CBW
679 http://cpan.uib.no/
680 ftp://cpan.uib.no/pub/CPAN/
681 ftp://ftp.uninett.no/pub/languages/perl/CPAN/
682 http://cpan.vianett.no/
5df44211
JH
683
684=item Poland
685
9ed2d9d9
CBW
686 http://ftp.agh.edu.pl/CPAN/
687 ftp://ftp.agh.edu.pl/CPAN/
688 http://ftp.piotrkosoft.net/pub/mirrors/CPAN/
04b029fe 689 ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
04b029fe 690 ftp://ftp.ps.pl/pub/CPAN/
9ed2d9d9 691 http://sunsite.icm.edu.pl/pub/CPAN/
04b029fe 692 ftp://sunsite.icm.edu.pl/pub/CPAN/
5df44211
JH
693
694=item Portugal
695
04b029fe 696 http://cpan.dcc.fc.up.pt/
9ed2d9d9
CBW
697 http://mirrors.fe.up.pt/pub/CPAN/
698 http://cpan.perl-hackers.net/
699 http://cpan.perl.pt/
4e860d0a 700
5df44211 701=item Romania
4e860d0a 702
9ed2d9d9
CBW
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/
04b029fe 709 http://mirrors.xservers.ro/CPAN/
4e860d0a 710
9ed2d9d9 711=item Russian Federation
4e860d0a 712
04b029fe
LB
713 ftp://ftp.aha.ru/CPAN/
714 http://cpan.rinet.ru/
715 ftp://cpan.rinet.ru/pub/mirror/CPAN/
9ed2d9d9 716 http://cpan-mirror.rbc.ru/pub/CPAN/
04b029fe 717 http://mirror.rol.ru/CPAN/
9ed2d9d9
CBW
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/
723
724=item Serbia
725
726 http://mirror.sbb.rs/CPAN/
727 ftp://mirror.sbb.rs/CPAN/
4e860d0a 728
5df44211 729=item Slovakia
4e860d0a 730
9ed2d9d9
CBW
731 http://cpan.lnx.sk/
732 http://tux.rainside.sk/CPAN/
733 ftp://tux.rainside.sk/CPAN/
4e860d0a 734
5df44211 735=item Slovenia
4e860d0a 736
9ed2d9d9
CBW
737 http://ftp.arnes.si/software/perl/CPAN/
738 ftp://ftp.arnes.si/software/perl/CPAN/
4e860d0a 739
5df44211 740=item Spain
4e860d0a 741
9ed2d9d9 742 http://mirrors.evowise.com/CPAN/
04b029fe 743 http://osl.ugr.es/CPAN/
9ed2d9d9 744 http://ftp.rediris.es/mirror/CPAN/
04b029fe 745 ftp://ftp.rediris.es/mirror/CPAN/
4e860d0a 746
5df44211 747=item Sweden
4e860d0a 748
9ed2d9d9
CBW
749 http://ftp.acc.umu.se/mirror/CPAN/
750 ftp://ftp.acc.umu.se/mirror/CPAN/
4e860d0a 751
5df44211 752=item Switzerland
4e860d0a 753
9ed2d9d9 754 http://www.pirbot.com/mirrors/cpan/
04b029fe
LB
755 http://mirror.switch.ch/ftp/mirror/CPAN/
756 ftp://mirror.switch.ch/mirror/CPAN/
c165c82a 757
5df44211 758=item Ukraine
c165c82a 759
9ed2d9d9
CBW
760 http://cpan.ip-connect.vn.ua/
761 ftp://cpan.ip-connect.vn.ua/mirror/cpan/
c165c82a 762
5df44211 763=item United Kingdom
d4858812 764
04b029fe
LB
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/
9ed2d9d9 769 http://mirrors.coreix.net/CPAN/
04b029fe 770 http://cpan.etla.org/
9ed2d9d9
CBW
771 ftp://cpan.etla.org/pub/CPAN/
772 http://cpan.cpantesters.org/
773 http://mirror.sax.uk.as61049.net/CPAN/
04b029fe 774 http://mirror.sov.uk.goscomb.net/CPAN/
9ed2d9d9
CBW
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/
04b029fe
LB
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/
9ed2d9d9 783 http://mirror.ukhost4u.com/CPAN/
d4858812 784
4e860d0a
JH
785=back
786
787=head2 North America
788
789=over 4
790
9d169eb4 791=item Canada
4e860d0a 792
04b029fe
LB
793 http://CPAN.mirror.rafal.ca/
794 ftp://CPAN.mirror.rafal.ca/pub/CPAN/
9ed2d9d9
CBW
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/
801
802=item Costa Rica
803
804 http://mirrors.ucr.ac.cr/CPAN/
7a142657 805
5df44211 806=item Mexico
c165c82a 807
04b029fe
LB
808 http://www.msg.com.mx/CPAN/
809 ftp://ftp.msg.com.mx/pub/CPAN/
c165c82a 810
5c5c2539 811=item United States
d4858812 812
7a142657 813=over 8
4e860d0a 814
5df44211 815=item Alabama
4e860d0a 816
9ed2d9d9 817 http://mirror.teklinks.com/CPAN/
04b029fe
LB
818
819=item Arizona
820
9ed2d9d9
CBW
821 http://mirror.n5tech.com/CPAN/
822 http://mirrors.namecheap.com/CPAN/
823 ftp://mirrors.namecheap.com/CPAN/
4e860d0a 824
5df44211 825=item California
4e860d0a 826
04b029fe 827 http://cpan.develooper.com/
9ed2d9d9
CBW
828 http://httpupdate127.cpanel.net/CPAN/
829 http://mirrors.sonic.net/cpan/
830 ftp://mirrors.sonic.net/cpan/
04b029fe 831 http://www.perl.com/CPAN/
9ed2d9d9 832 http://cpan.yimg.com/
4e860d0a 833
9d169eb4 834=item Idaho
4e860d0a 835
9ed2d9d9
CBW
836 http://mirrors.syringanetworks.net/CPAN/
837 ftp://mirrors.syringanetworks.net/CPAN/
4e860d0a 838
9d169eb4 839=item Illinois
c165c82a 840
04b029fe 841 http://cpan.mirrors.hoobly.com/
9ed2d9d9
CBW
842 http://mirror.team-cymru.org/CPAN/
843 ftp://mirror.team-cymru.org/CPAN/
c165c82a 844
5df44211 845=item Indiana
4e860d0a 846
04b029fe
LB
847 http://cpan.netnitco.net/
848 ftp://cpan.netnitco.net/pub/mirrors/CPAN/
9ed2d9d9
CBW
849 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
850
851=item Kansas
852
853 http://mirrors.concertpass.com/cpan/
4e860d0a 854
5df44211 855=item Massachusetts
4e860d0a 856
04b029fe 857 http://mirrors.ccs.neu.edu/CPAN/
4e860d0a 858
5df44211 859=item Michigan
4e860d0a 860
9ed2d9d9
CBW
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/
4e860d0a 867
9ed2d9d9 868=item New Hampshire
5c5c2539 869
9ed2d9d9 870 http://mirror.metrocast.net/cpan/
5c5c2539 871
5df44211 872=item New Jersey
4e860d0a 873
04b029fe
LB
874 http://mirror.datapipe.net/CPAN/
875 ftp://mirror.datapipe.net/pub/CPAN/
9ed2d9d9
CBW
876 http://www.hoovism.com/CPAN/
877 ftp://ftp.hoovism.com/CPAN/
878 http://cpan.mirror.nac.net/
4e860d0a 879
5df44211 880=item New York
4e860d0a 881
04b029fe
LB
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/
9ed2d9d9
CBW
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/
4e860d0a 895
5df44211 896=item North Carolina
4e860d0a 897
9ed2d9d9
CBW
898 http://httpupdate140.cpanel.net/CPAN/
899 http://mirrors.ibiblio.org/CPAN/
4e860d0a 900
5df44211 901=item Oregon
4e860d0a 902
04b029fe
LB
903 http://ftp.osuosl.org/pub/CPAN/
904 ftp://ftp.osuosl.org/pub/CPAN/
9ed2d9d9 905 http://mirror.uoregon.edu/CPAN/
4e860d0a 906
5df44211 907=item Pennsylvania
4e860d0a 908
04b029fe
LB
909 http://cpan.pair.com/
910 ftp://cpan.pair.com/pub/CPAN/
9ed2d9d9 911 http://cpan.mirrors.ionfish.org/
9d169eb4
LB
912
913=item South Carolina
914
04b029fe 915 http://cpan.mirror.clemson.edu/
4e860d0a 916
5df44211 917=item Texas
4e860d0a 918
9ed2d9d9 919 http://mirror.uta.edu/CPAN/
4e860d0a 920
5df44211 921=item Utah
4e860d0a 922
9ed2d9d9
CBW
923 http://cpan.cs.utah.edu/
924 ftp://cpan.cs.utah.edu/CPAN/
04b029fe 925 ftp://mirror.xmission.com/CPAN/
4e860d0a 926
5df44211 927=item Virginia
4e860d0a 928
9ed2d9d9 929 http://mirror.cogentco.com/pub/CPAN/
04b029fe 930 ftp://mirror.cogentco.com/pub/CPAN/
9ed2d9d9
CBW
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/
4e860d0a 935
5c5c2539 936=item Washington
4e860d0a 937
04b029fe
LB
938 http://cpan.llarian.net/
939 ftp://cpan.llarian.net/pub/CPAN/
d4858812 940
5df44211 941=item Wisconsin
d4858812 942
9ed2d9d9
CBW
943 http://cpan.mirrors.tds.net/
944 ftp://cpan.mirrors.tds.net/pub/CPAN/
4e860d0a
JH
945
946=back
947
5c5c2539
JH
948=back
949
4e860d0a
JH
950=head2 Oceania
951
952=over 4
953
5df44211 954=item Australia
4e860d0a 955
9ed2d9d9
CBW
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/
04b029fe 960 ftp://mirror.internode.on.net/pub/cpan/
9ed2d9d9
CBW
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/
965
966=item New Caledonia
967
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/
4e860d0a 972
5df44211 973=item New Zealand
d4858812 974
04b029fe 975 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
04b029fe
LB
976 http://cpan.catalyst.net.nz/CPAN/
977 ftp://cpan.catalyst.net.nz/pub/CPAN/
9ed2d9d9
CBW
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/
4e860d0a
JH
982
983=back
984
985=head2 South America
986
987=over 4
988
5df44211 989=item Argentina
4e860d0a 990
9ed2d9d9 991 http://cpan.mmgdesigns.com.ar/
4e860d0a 992
5df44211 993=item Brazil
4e860d0a 994
04b029fe 995 http://cpan.kinghost.net/
9ed2d9d9
CBW
996 http://linorg.usp.br/CPAN/
997 http://mirror.nbtelecom.com.br/CPAN/
4e860d0a 998
5df44211 999=item Chile
4e860d0a 1000
04b029fe
LB
1001 http://cpan.dcc.uchile.cl/
1002 ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
9d169eb4 1003
2e1d04bc
JH
1004=back
1005
5df44211
JH
1006=head2 RSYNC Mirrors
1007
9ed2d9d9
CBW
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/
1098
5df44211 1099
2e1d04bc 1100For an up-to-date listing of CPAN sites,
71c89d21 1101see L<https://www.cpan.org/SITES> or L<ftp://www.cpan.org/SITES>.
2e1d04bc
JH
1102
1103=head1 Modules: Creation, Use, and Abuse
1104
1105(The following section is borrowed directly from Tim Bunce's modules
1106file, available at your nearest CPAN site.)
1107
1108Perl implements a class using a package, but the presence of a
1109package doesn't imply the presence of a class. A package is just a
1110namespace. A class is a package that provides subroutines that can be
1111used as methods. A method is just a subroutine that expects, as its
1112first argument, either the name of a package (for "static" methods),
1113or a reference to something (for "virtual" methods).
1114
1115A module is a file that (by convention) provides a class of the same
1116name (sans the .pm), plus an import method in that class that can be
1117called to fetch exported symbols. This module may implement some of
1118its methods by loading dynamic C or C++ objects, but that should be
1119totally transparent to the user of the module. Likewise, the module
1120might set up an AUTOLOAD function to slurp in subroutine definitions on
1121demand, but this is also transparent. Only the F<.pm> file is required to
82e1c0d9 1122exist. See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
2e1d04bc
JH
1123the AUTOLOAD mechanism.
1124
1125=head2 Guidelines for Module Creation
1126
1127=over 4
1128
ac634a9a
JH
1129=item *
1130
1131Do similar modules already exist in some form?
2e1d04bc
JH
1132
1133If so, please try to reuse the existing modules either in whole or
1134by inheriting useful features into a new class. If this is not
1135practical try to get together with the module authors to work on
1136extending or enhancing the functionality of the existing modules.
1137A perfect example is the plethora of packages in perl4 for dealing
1138with command line options.
1139
1140If you are writing a module to expand an already existing set of
1141modules, please coordinate with the author of the package. It
1142helps if you follow the same naming scheme and module interaction
1143scheme as the original author.
1144
ac634a9a
JH
1145=item *
1146
1147Try to design the new module to be easy to extend and reuse.
2e1d04bc
JH
1148
1149Try to C<use warnings;> (or C<use warnings qw(...);>).
1150Remember that you can add C<no warnings qw(...);> to individual blocks
1151of code that need less warnings.
1152
1153Use blessed references. Use the two argument form of bless to bless
1154into the class name given as the first parameter of the constructor,
1155e.g.,:
1156
1157 sub new {
1158 my $class = shift;
1159 return bless {}, $class;
1160 }
1161
1162or even this if you'd like it to be used as either a static
1163or a virtual method.
1164
1165 sub new {
1166 my $self = shift;
1167 my $class = ref($self) || $self;
1168 return bless {}, $class;
1169 }
1170
1171Pass arrays as references so more parameters can be added later
1172(it's also faster). Convert functions into methods where
1173appropriate. Split large methods into smaller more flexible ones.
1174Inherit methods from other modules if appropriate.
1175
1176Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1177Generally you can delete the C<eq 'FOO'> part with no harm at all.
1178Let the objects look after themselves! Generally, avoid hard-wired
1179class names as far as possible.
1180
1181Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
82e1c0d9 1182C<< $r->func() >> would work.
2e1d04bc
JH
1183
1184Use autosplit so little used or newly added functions won't be a
1185burden to programs that don't use them. Add test functions to
1186the module after __END__ either using AutoSplit or by saying:
1187
1188 eval join('',<main::DATA>) || die $@ unless caller();
1189
1190Does your module pass the 'empty subclass' test? If you say
1191C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1192to use SUBCLASS in exactly the same way as YOURCLASS. For example,
63acfd00 1193does your application still work if you change: C<< $obj = YOURCLASS->new(); >>
1194into: C<< $obj = SUBCLASS->new(); >> ?
2e1d04bc
JH
1195
1196Avoid keeping any state information in your packages. It makes it
1197difficult for multiple other packages to use yours. Keep state
1198information in objects.
1199
1200Always use B<-w>.
1201
1202Try to C<use strict;> (or C<use strict qw(...);>).
1203Remember that you can add C<no strict qw(...);> to individual blocks
1204of code that need less strictness.
1205
1206Always use B<-w>.
1207
ba555bf5 1208Follow the guidelines in L<perlstyle>.
2e1d04bc
JH
1209
1210Always use B<-w>.
1211
ac634a9a
JH
1212=item *
1213
1214Some simple style guidelines
2e1d04bc
JH
1215
1216The perlstyle manual supplied with Perl has many helpful points.
1217
1218Coding style is a matter of personal taste. Many people evolve their
1219style over several years as they learn what helps them write and
1220maintain good code. Here's one set of assorted suggestions that
1221seem to be widely used by experienced developers:
1222
1223Use underscores to separate words. It is generally easier to read
1224$var_names_like_this than $VarNamesLikeThis, especially for
1225non-native speakers of English. It's also a simple rule that works
1226consistently with VAR_NAMES_LIKE_THIS.
1227
1228Package/Module names are an exception to this rule. Perl informally
1229reserves lowercase module names for 'pragma' modules like integer
1230and strict. Other modules normally begin with a capital letter and
1231use mixed case with no underscores (need to be short and portable).
1232
1233You may find it helpful to use letter case to indicate the scope
1234or nature of a variable. For example:
1235
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
1239
1240Function and method names seem to work best as all lowercase.
1241e.g., C<< $obj->as_string() >>.
1242
1243You can use a leading underscore to indicate that a variable or
1244function should not be used outside the package that defined it.
1245
ac634a9a
JH
1246=item *
1247
1248Select what to export.
2e1d04bc
JH
1249
1250Do NOT export method names!
1251
1252Do NOT export anything else by default without a good reason!
1253
1254Exports pollute the namespace of the module user. If you must
1255export try to use @EXPORT_OK in preference to @EXPORT and avoid
1256short or common names to reduce the risk of name clashes.
1257
1258Generally anything not exported is still accessible from outside the
1259module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1260syntax. By convention you can use a leading underscore on names to
1261indicate informally that they are 'internal' and not for public use.
1262
1263(It is actually possible to get private functions by saying:
1264C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1265directly as a method, because a method must have a name in the symbol
1266table.)
1267
1268As a general rule, if the module is trying to be object oriented
1269then export nothing. If it's just a collection of functions then
1270@EXPORT_OK anything but use @EXPORT with caution.
1271
ac634a9a
JH
1272=item *
1273
1274Select a name for the module.
2e1d04bc
JH
1275
1276This name should be as descriptive, accurate, and complete as
1277possible. Avoid any risk of ambiguity. Always try to use two or
1278more whole words. Generally the name should reflect what is special
1279about what the module does rather than how it does it. Please use
1280nested module names to group informally or categorize a module.
1281There should be a very good reason for a module not to have a nested name.
1282Module names should begin with a capital letter.
1283
1284Having 57 modules all called Sort will not make life easy for anyone
1285(though having 23 called Sort::Quick is only marginally better :-).
1286Imagine someone trying to install your module alongside many others.
2e1d04bc
JH
1287
1288If you are developing a suite of related modules/classes it's good
1289practice to use nested classes with a common prefix as this will
1290avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1291Xyz::Model etc. Use the modules in this list as a naming guide.
1292
1293If adding a new module to a set, follow the original author's
1294standards for naming modules and the interface to methods in
1295those modules.
1296
4844a3be
SP
1297If developing modules for private internal or project specific use,
1298that will never be released to the public, then you should ensure
1299that their names will not clash with any future public module. You
1300can do this either by using the reserved Local::* category or by
1301using a category name that includes an underscore like Foo_Corp::*.
1302
2e1d04bc
JH
1303To be portable each component of a module name should be limited to
130411 characters. If it might be used on MS-DOS then try to ensure each is
1305unique in the first 8 characters. Nested modules make this easier.
1306
f94c6c53
JK
1307For additional guidance on the naming of modules, please consult:
1308
71c89d21 1309 https://pause.perl.org/pause/query?ACTION=pause_namingmodules
f94c6c53
JK
1310
1311or send mail to the <module-authors@perl.org> mailing list.
1312
ac634a9a
JH
1313=item *
1314
1315Have you got it right?
2e1d04bc
JH
1316
1317How do you know that you've made the right decisions? Have you
1318picked an interface design that will cause problems later? Have
1319you picked the most appropriate name? Do you have any questions?
1320
1321The best way to know for sure, and pick up many helpful suggestions,
f94c6c53
JK
1322is to ask someone who knows. The <module-authors@perl.org> mailing list
1323is useful for this purpose; it's also accessible via news interface as
1324perl.module-authors at nntp.perl.org.
2e1d04bc
JH
1325
1326All you need to do is post a short summary of the module, its
1327purpose and interfaces. A few lines on each of the main methods is
1328probably enough. (If you post the whole module it might be ignored
1329by busy people - generally the very people you want to read it!)
1330
1331Don't worry about posting if you can't say when the module will be
1332ready - just say so in the message. It might be worth inviting
1333others to help you, they may be able to complete it for you!
1334
ac634a9a
JH
1335=item *
1336
1337README and other Additional Files.
2e1d04bc
JH
1338
1339It's well known that software developers usually fully document the
1340software they write. If, however, the world is in urgent need of
1341your software and there is not enough time to write the full
1342documentation please at least provide a README file containing:
1343
1344=over 10
1345
1346=item *
ac634a9a 1347
2e1d04bc
JH
1348A description of the module/package/extension etc.
1349
1350=item *
ac634a9a 1351
2e1d04bc
JH
1352A copyright notice - see below.
1353
1354=item *
ac634a9a 1355
2e1d04bc
JH
1356Prerequisites - what else you may need to have.
1357
1358=item *
ac634a9a 1359
2e1d04bc
JH
1360How to build it - possible changes to Makefile.PL etc.
1361
1362=item *
ac634a9a 1363
2e1d04bc
JH
1364How to install it.
1365
1366=item *
ac634a9a 1367
2e1d04bc
JH
1368Recent changes in this release, especially incompatibilities
1369
1370=item *
ac634a9a 1371
2e1d04bc
JH
1372Changes / enhancements you plan to make in the future.
1373
1374=back
1375
1376If the README file seems to be getting too large you may wish to
1377split out some of the sections into separate files: INSTALL,
1378Copying, ToDo etc.
1379
1380=over 4
1381
c165c82a 1382=item *
2e1d04bc 1383
c165c82a 1384Adding a Copyright Notice.
ac634a9a 1385
2e1d04bc
JH
1386How you choose to license your work is a personal decision.
1387The general mechanism is to assert your Copyright and then make
1388a declaration of how others may copy/use/modify your work.
1389
2a551100
JH
1390Perl, for example, is supplied with two types of licence: The GNU GPL
1391and The Artistic Licence (see the files README, Copying, and Artistic,
1392or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
1393just using the GNU GPL.
2e1d04bc
JH
1394
1395My personal recommendation, out of respect for Larry, Perl, and the
1396Perl community at large is to state something simply like:
1397
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.
1401
1402This statement should at least appear in the README file. You may
1403also wish to include it in a Copying file and your source files.
1404Remember to include the other words in addition to the Copyright.
1405
ac634a9a
JH
1406=item *
1407
1408Give the module a version/issue/release number.
2e1d04bc
JH
1409
1410To be fully compatible with the Exporter and MakeMaker modules you
1411should store your module's version number in a non-my package
f39335f9 1412variable called $VERSION. This should be a positive floating point
2e1d04bc
JH
1413number with at least two digits after the decimal (i.e., hundredths,
1414e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1415See L<Exporter> for details.
1416
1417It may be handy to add a function or method to retrieve the number.
1418Use the number in announcements and archive file names when
1419releasing the module (ModuleName-1.02.tar.Z).
1420See perldoc ExtUtils::MakeMaker.pm for details.
1421
ac634a9a
JH
1422=item *
1423
1424How to release and distribute a module.
2e1d04bc 1425
32356571
DC
1426If possible, register the module with CPAN. Follow the instructions
1427and links on:
2e1d04bc 1428
71c89d21 1429 https://www.cpan.org/modules/04pause.html
2e1d04bc 1430
32356571 1431and upload to:
2e1d04bc 1432
71c89d21 1433 https://pause.perl.org/
2e1d04bc 1434
32356571
DC
1435and notify <modules@perl.org>. This will allow anyone to install
1436your module using the C<cpan> tool distributed with Perl.
2e1d04bc
JH
1437
1438By using the WWW interface you can ask the Upload Server to mirror
1439your modules from your ftp or WWW site into your own directory on
1440CPAN!
1441
ac634a9a
JH
1442=item *
1443
1444Take care when changing a released module.
2e1d04bc
JH
1445
1446Always strive to remain compatible with previous released versions.
1447Otherwise try to add a mechanism to revert to the
1448old behavior if people rely on it. Document incompatible changes.
1449
1450=back
1451
abf06cc1
MS
1452=back
1453
2e1d04bc
JH
1454=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1455
1456=over 4
1457
ac634a9a
JH
1458=item *
1459
1460There is no requirement to convert anything.
2e1d04bc
JH
1461
1462If it ain't broke, don't fix it! Perl 4 library scripts should
1463continue to work with no problems. You may need to make some minor
1464changes (like escaping non-array @'s in double quoted strings) but
1465there is no need to convert a .pl file into a Module for just that.
1466
ac634a9a
JH
1467=item *
1468
1469Consider the implications.
2e1d04bc
JH
1470
1471All Perl applications that make use of the script will need to
1472be changed (slightly) if the script is converted into a module. Is
1473it worth it unless you plan to make other changes at the same time?
1474
ac634a9a
JH
1475=item *
1476
1477Make the most of the opportunity.
2e1d04bc
JH
1478
1479If you are going to convert the script to a module you can use the
1480opportunity to redesign the interface. The guidelines for module
1481creation above include many of the issues you should consider.
1482
ac634a9a
JH
1483=item *
1484
1485The pl2pm utility will get you started.
2e1d04bc
JH
1486
1487This utility will read *.pl files (given as parameters) and write
1488corresponding *.pm files. The pl2pm utilities does the following:
1489
1490=over 10
1491
1492=item *
ac634a9a 1493
2e1d04bc
JH
1494Adds the standard Module prologue lines
1495
1496=item *
ac634a9a 1497
2e1d04bc
JH
1498Converts package specifiers from ' to ::
1499
1500=item *
ac634a9a 1501
2e1d04bc
JH
1502Converts die(...) to croak(...)
1503
1504=item *
ac634a9a 1505
2e1d04bc
JH
1506Several other minor changes
1507
1508=back
1509
1510Being a mechanical process pl2pm is not bullet proof. The converted
1511code will need careful checking, especially any package statements.
1512Don't delete the original .pl file till the new .pm one works!
1513
1514=back
1515
1516=head2 Guidelines for Reusing Application Code
1517
1518=over 4
1519
ac634a9a
JH
1520=item *
1521
1522Complete applications rarely belong in the Perl Module Library.
1523
1524=item *
2e1d04bc 1525
ac634a9a 1526Many applications contain some Perl code that could be reused.
2e1d04bc
JH
1527
1528Help save the world! Share your code in a form that makes it easy
1529to reuse.
1530
ac634a9a
JH
1531=item *
1532
1533Break-out the reusable code into one or more separate module files.
1534
1535=item *
1536
1537Take the opportunity to reconsider and redesign the interfaces.
2e1d04bc 1538
ac634a9a 1539=item *
2e1d04bc 1540
ac634a9a 1541In some cases the 'application' can then be reduced to a small
2e1d04bc
JH
1542
1543fragment of code built on top of the reusable modules. In these cases
1544the application could invoked as:
1545
1546 % perl -e 'use Module::Name; method(@ARGV)' ...
1547or
1548 % perl -mModule::Name ... (in perl5.002 or higher)
1549
1550=back
1551
1552=head1 NOTE
1553
1554Perl does not enforce private and public parts of its modules as you may
1555have been used to in other languages like C++, Ada, or Modula-17. Perl
1556doesn't have an infatuation with enforced privacy. It would prefer
1557that you stayed out of its living room because you weren't invited, not
1558because it has a shotgun.
1559
1560The module and its user have a contract, part of which is common law,
1561and part of which is "written". Part of the common law contract is
1562that a module doesn't pollute any namespace it wasn't asked to. The
1563written contract for the module (A.K.A. documentation) may make other
1564provisions. But then you know when you C<use RedefineTheWorld> that
1565you're redefining the world and willing to take the consequences.
d72ea276
NC
1566
1567=cut
2e1d04bc 1568
f556af6c 1569read_only_bottom_close_and_rename($out);