This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add program which generates the list of registered CPAN sites in perlmodlib.PL
[perl5.git] / pod / perlmodlib.PL
CommitLineData
2e1d04bc
JH
1#!../miniperl
2
5b504182
NC
3use strict;
4use warnings;
5
1fa7ca25
JH
6$ENV{LC_ALL} = 'C';
7
291c64f4
NC
8use FindBin;
9chdir $FindBin::Bin or die "$0: Can't chdir $FindBin::Bin: $!";
10
11my $Quiet = @ARGV && $ARGV[0] eq '-q';
12
b7da254d 13open (OUT, ">perlmodlib.pod") or die $!;
cf9cbb1f 14my (@pragma, @mod, @files);
4d671226 15
291c64f4
NC
16# MANIFEST itself is Unix style filenames, so we have to assume that Unix style
17# filenames will work.
18
2e1d04bc 19open (MANIFEST, "../MANIFEST") or die $!;
cf9cbb1f 20@files = grep m#(?:\.pm|\.pod|_pm\.PL)#, map {s/\s.*//s; $_}
955fcc32 21 grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo)/# } <MANIFEST>;
cf9cbb1f
NC
22
23my %exceptions = (
24 'abbrev' => 'Text::Abbrev',
25 'carp' => 'Carp',
26 'getopt' => 'Getopt::Std',
27 'B<CGI::Carp>' => 'CGI::Carp',
28 'ModuleInfo' => 'Module::Build::ModuleInfo',
29 '$notes_name' => 'Module::Build::Notes',
30 'Encode::MIME::NAME' => 'Encode::MIME::Name',
31 'libnetFAQ' => 'Net::libnetFAQ',
4e42dfb1
JB
32);
33
cf9cbb1f 34for my $filename (@files) {
e8041d9b
NC
35 unless (open MOD, '<', "../$filename") {
36 warn "Couldn't open ../$filename: $!";
37 next;
4e42dfb1 38 }
4e860d0a 39
5b504182
NC
40 my ($name, $thing);
41 my $foundit = 0;
42 {
43 local $/ = "";
44 while (<MOD>) {
45 next unless /^=head1 NAME/;
46 $foundit++;
47 last;
48 }
49 }
50 unless ($foundit) {
51 warn "$filename missing =head1 NAME (OK if respective .pod exists)\n"
52 unless $Quiet;
53 next;
54 }
55 my $title = <MOD>;
56 chomp $title;
57 close MOD;
1fa7ca25 58
5b504182 59 ($name, $thing) = split / --? /, $title, 2;
4e42dfb1 60
5b504182
NC
61 unless ($name and $thing) {
62 warn "$filename missing name\n" unless $name;
63 warn "$filename missing thing\n" unless $thing or $Quiet;
64 next;
65 }
66
67 $name =~ s/[^A-Za-z0-9_:\$<>].*//;
68 $name = $exceptions{$name} || $name;
69 $thing =~ s/^perl pragma to //i;
70 $thing = ucfirst $thing;
71 $title = "=item $name\n\n$thing\n\n";
72
73 if ($name =~ /[A-Z]/) {
74 push @mod, $title;
75 } else {
76 push @pragma, $title;
77 }
2e1d04bc
JH
78}
79
cf9cbb1f
NC
80# Much easier to special case it like this than special case the depending on
81# and parsing lib/Config.pod, or special case opening configpm and finding its
82# =head1 (which is not found with the $/="" above)
83push @mod, <<'CONFIG';
84=item Config
85
86Access Perl configuration information
87
88CONFIG
89
2e1d04bc 90print OUT <<'EOF';
c165c82a
JH
91=for maintainers
92Generated by perlmodlib.PL -- DO NOT EDIT!
843dbe26 93
2e1d04bc
JH
94=head1 NAME
95
96perlmodlib - constructing new Perl modules and finding existing ones
97
2e1d04bc
JH
98=head1 THE PERL MODULE LIBRARY
99
7ef5744c 100Many modules are included in the Perl distribution. These are described
2e1d04bc 101below, and all end in F<.pm>. You may discover compiled library
7ef5744c 102files (usually ending in F<.so>) or small pieces of modules to be
2e1d04bc
JH
103autoloaded (ending in F<.al>); these were automatically generated
104by the installation process. You may also discover files in the
105library directory that end in either F<.pl> or F<.ph>. These are
106old libraries supplied so that old programs that use them still
107run. The F<.pl> files will all eventually be converted into standard
108modules, and the F<.ph> files made by B<h2ph> will probably end up
109as extension modules made by B<h2xs>. (Some F<.ph> values may
110already be available through the POSIX, Errno, or Fcntl modules.)
111The B<pl2pm> file in the distribution may help in your conversion,
112but it's just a mechanical process and therefore far from bulletproof.
113
114=head2 Pragmatic Modules
115
116They work somewhat like compiler directives (pragmata) in that they
117tend to affect the compilation of your program, and thus will usually
118work well only when used within a C<use>, or C<no>. Most of these
119are lexically scoped, so an inner BLOCK may countermand them
120by saying:
121
122 no integer;
123 no strict 'refs';
124 no warnings;
125
126which lasts until the end of that BLOCK.
127
128Some pragmas are lexically scoped--typically those that affect the
129C<$^H> hints variable. Others affect the current package instead,
130like C<use vars> and C<use subs>, which allow you to predeclare a
131variables or subroutines within a particular I<file> rather than
132just a block. Such declarations are effective for the entire file
133for which they were declared. You cannot rescind them with C<no
134vars> or C<no subs>.
135
136The following pragmas are defined (and have their own documentation).
137
138=over 12
139
140EOF
141
142print OUT $_ for (sort @pragma);
143
144print OUT <<EOF;
145=back
146
147=head2 Standard Modules
148
149Standard, bundled modules are all expected to behave in a well-defined
150manner with respect to namespace pollution because they use the
151Exporter module. See their own documentation for details.
152
7ef5744c
RGS
153It's possible that not all modules listed below are installed on your
154system. For example, the GDBM_File module will not be installed if you
155don't have the gdbm library.
156
2e1d04bc
JH
157=over 12
158
159EOF
160
161print OUT $_ for (sort @mod);
162
163print OUT <<'EOF';
164=back
165
166To find out I<all> modules installed on your system, including
167those without documentation or outside the standard release,
a4373870
CW
168just use the following command (under the default win32 shell,
169double quotes should be used instead of single quotes).
2e1d04bc 170
a4373870
CW
171 % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
172 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
173 no_chdir => 1 }, @INC'
2e1d04bc 174
8518420c 175(The -T is here to prevent '.' from being listed in @INC.)
2e1d04bc
JH
176They should all have their own documentation installed and accessible
177via your system man(1) command. If you do not have a B<find>
178program, you can use the Perl B<find2perl> program instead, which
179generates Perl code as output you can run through perl. If you
180have a B<man> program but it doesn't find your modules, you'll have
181to fix your manpath. See L<perl> for details. If you have no
182system B<man> command, you might try the B<perldoc> program.
183
8518420c
RGS
184Note also that the command C<perldoc perllocal> gives you a (possibly
185incomplete) list of the modules that have been further installed on
186your system. (The perllocal.pod file is updated by the standard MakeMaker
187install process.)
188
2e1d04bc
JH
189=head2 Extension Modules
190
191Extension modules are written in C (or a mix of Perl and C). They
192are usually dynamically loaded into Perl if and when you need them,
da75cd15 193but may also be linked in statically. Supported extension modules
2e1d04bc
JH
194include Socket, Fcntl, and POSIX.
195
196Many popular C extension modules do not come bundled (at least, not
197completely) due to their sizes, volatility, or simply lack of time
198for adequate testing and configuration across the multitude of
199platforms on which Perl was beta-tested. You are encouraged to
200look for them on CPAN (described below), or using web search engines
7ef5744c 201like Alta Vista or Google.
2e1d04bc
JH
202
203=head1 CPAN
204
205CPAN stands for Comprehensive Perl Archive Network; it's a globally
206replicated trove of Perl materials, including documentation, style
207guides, tricks and traps, alternate ports to non-Unix systems and
208occasional binary distributions for these. Search engines for
1577cd80 209CPAN can be found at http://www.cpan.org/
2e1d04bc
JH
210
211Most importantly, CPAN includes around a thousand unbundled modules,
212some of which require a C compiler to build. Major categories of
213modules are:
214
215=over
216
217=item *
ac634a9a 218
2e1d04bc
JH
219Language Extensions and Documentation Tools
220
221=item *
ac634a9a 222
2e1d04bc
JH
223Development Support
224
225=item *
ac634a9a 226
2e1d04bc
JH
227Operating System Interfaces
228
229=item *
ac634a9a 230
2e1d04bc
JH
231Networking, Device Control (modems) and InterProcess Communication
232
233=item *
ac634a9a 234
2e1d04bc
JH
235Data Types and Data Type Utilities
236
237=item *
ac634a9a 238
2e1d04bc
JH
239Database Interfaces
240
241=item *
ac634a9a 242
2e1d04bc
JH
243User Interfaces
244
245=item *
ac634a9a 246
2e1d04bc
JH
247Interfaces to / Emulations of Other Programming Languages
248
249=item *
ac634a9a 250
2e1d04bc
JH
251File Names, File Systems and File Locking (see also File Handles)
252
253=item *
ac634a9a 254
2e1d04bc
JH
255String Processing, Language Text Processing, Parsing, and Searching
256
257=item *
ac634a9a 258
2e1d04bc
JH
259Option, Argument, Parameter, and Configuration File Processing
260
261=item *
ac634a9a 262
2e1d04bc
JH
263Internationalization and Locale
264
265=item *
ac634a9a 266
2e1d04bc
JH
267Authentication, Security, and Encryption
268
269=item *
ac634a9a 270
2e1d04bc
JH
271World Wide Web, HTML, HTTP, CGI, MIME
272
273=item *
ac634a9a 274
2e1d04bc
JH
275Server and Daemon Utilities
276
277=item *
ac634a9a 278
2e1d04bc
JH
279Archiving and Compression
280
281=item *
ac634a9a 282
2e1d04bc
JH
283Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
284
285=item *
ac634a9a 286
2e1d04bc
JH
287Mail and Usenet News
288
289=item *
ac634a9a 290
2e1d04bc
JH
291Control Flow Utilities (callbacks and exceptions etc)
292
293=item *
ac634a9a 294
2e1d04bc
JH
295File Handle and Input/Output Stream Utilities
296
297=item *
ac634a9a 298
2e1d04bc
JH
299Miscellaneous Modules
300
301=back
302
9d169eb4 303The list of the registered CPAN sites follows.
5df44211
JH
304Please note that the sorting order is alphabetical on fields:
305
306Continent
307 |
308 |-->Country
309 |
310 |-->[state/province]
311 |
312 |-->ftp
313 |
314 |-->[http]
315
316and thus the North American servers happen to be listed between the
317European and the South American sites.
318
9d169eb4 319Registered CPAN sites
2e1d04bc 320
4e860d0a
JH
321=head2 Africa
322
323=over 4
324
5df44211 325=item South Africa
4e860d0a 326
9d169eb4
LB
327 http://cpan.mirror.ac.za/
328 ftp://cpan.mirror.ac.za/
329 http://mirror.is.co.za/pub/cpan/
330 ftp://ftp.is.co.za/pub/cpan/
5df44211 331 ftp://ftp.saix.net/pub/CPAN/
4e860d0a
JH
332
333=back
334
335=head2 Asia
336
337=over 4
338
9d169eb4 339=item Hong Kong
4e860d0a 340
9d169eb4
LB
341 http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
342 ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
343 http://mirrors.geoexpat.com/cpan/
c165c82a 344
9d169eb4 345=item India
c165c82a 346
9d169eb4 347 http://perlmirror.indialinks.com/
c165c82a 348
9d169eb4 349=item Indonesia
c165c82a 350
9d169eb4
LB
351 http://cpan.biz.net.id/
352 http://komo.vlsm.org/CPAN/
353 ftp://komo.vlsm.org/CPAN/
354 http://cpan.pesat.net.id/
355 http://mirror.unej.ac.id/cpan/
356 ftp://mirror.unej.ac.id/cpan/
c165c82a 357
5df44211 358=item Japan
c165c82a 359
5df44211 360 ftp://ftp.u-aizu.ac.jp/pub/CPAN
9d169eb4
LB
361 ftp://ftp.kddilabs.jp/CPAN/
362 http://ftp.nara.wide.ad.jp/pub/CPAN/
363 ftp://ftp.nara.wide.ad.jp/pub/CPAN/
364 http://ftp.jaist.ac.jp/pub/CPAN/
365 ftp://ftp.jaist.ac.jp/pub/CPAN/
5df44211
JH
366 ftp://ftp.dti.ad.jp/pub/lang/CPAN/
367 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
9d169eb4
LB
368 http://ftp.riken.jp/lang/CPAN/
369 ftp://ftp.riken.jp/lang/CPAN/
370 http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
371 ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
c165c82a 372
9d169eb4 373=item Kazakhstan
c165c82a 374
9d169eb4 375 http://mirror.linuxiso.kz/CPAN/
4e860d0a 376
9d169eb4 377=item Republic of Korea
4e860d0a 378
9d169eb4
LB
379 http://ftp.kaist.ac.kr/pub/CPAN
380 ftp://ftp.kaist.ac.kr/pub/CPAN
381 http://cpan.mirror.cdnetworks.com/
382 ftp://cpan.mirror.cdnetworks.com/CPAN/
383 http://cpan.sarang.net/
384 ftp://cpan.sarang.net/CPAN/
4e860d0a 385
9d169eb4 386=item Russia
4e860d0a 387
9d169eb4
LB
388 http://cpan.tomsk.ru/
389 ftp://cpan.tomsk.ru/
4e860d0a 390
5df44211 391=item Singapore
4e860d0a 392
5df44211
JH
393 http://mirror.averse.net/pub/CPAN
394 ftp://mirror.averse.net/pub/CPAN
9d169eb4 395 http://cpan.mirror.choon.net/
5c5c2539
JH
396 http://cpan.oss.eznetsols.org
397 ftp://ftp.oss.eznetsols.org/cpan
4e860d0a 398
5df44211 399=item Taiwan
4e860d0a 400
9d169eb4
LB
401 http://ftp.cse.yzu.edu.tw/pub/CPAN/
402 ftp://ftp.cse.yzu.edu.tw/pub/CPAN/
403 http://cpan.nctu.edu.tw/
404 ftp://cpan.nctu.edu.tw/
405 ftp://ftp.ncu.edu.tw/CPAN/
5c5c2539 406 http://cpan.cdpa.nsysu.edu.tw/
9d169eb4
LB
407 ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
408 http://cpan.stu.edu.tw
409 ftp://ftp.stu.edu.tw/CPAN
410 http://ftp.stu.edu.tw/CPAN
411 ftp://ftp.stu.edu.tw/pub/CPAN
412 http://cpan.cs.pu.edu.tw/
413 ftp://cpan.cs.pu.edu.tw/pub/CPAN
7a142657 414
5df44211 415=item Thailand
4e860d0a 416
9d169eb4
LB
417 http://mirrors.issp.co.th/cpan/
418 ftp://mirrors.issp.co.th/cpan/
419
420=item Turkey
421
422 http://cpan.gazi.edu.tr/
423 http://cpan.ulak.net.tr
424 ftp://ftp.ulak.net.tr/pub/CPAN
425
426=item Viet Nam
427
428 http://mirror-fpt-telecom.fpt.net/cpan/
429 ftp://mirror-fpt-telecom.fpt.net/cpan/
4e860d0a
JH
430
431=back
432
433=head2 Central America
434
435=over 4
436
5df44211 437=item Costa Rica
4e860d0a 438
9d169eb4
LB
439 http://mirrors.ucr.ac.cr/CPAN/
440 ftp://mirrors.ucr.ac.cr/CPAN/
4e860d0a
JH
441
442=back
443
444=head2 Europe
445
446=over 4
447
5df44211 448=item Austria
4e860d0a 449
2e75584a
JH
450 http://cpan.inode.at/
451 ftp://cpan.inode.at
9d169eb4
LB
452 http://gd.tuwien.ac.at/languages/perl/CPAN/
453 ftp://gd.tuwien.ac.at/pub/CPAN/
4e860d0a 454
5df44211 455=item Belgium
4e860d0a 456
9d169eb4
LB
457 http://ftp.belnet.be/mirror/ftp.cpan.org/
458 ftp://ftp.belnet.be/mirror/ftp.cpan.org/
5df44211 459 http://ftp.easynet.be/pub/CPAN/
9d169eb4
LB
460 http://cpan.weepee.org/
461 http://cpan.fluoline.net/
4e860d0a 462
7a142657
JH
463=item Bosnia and Herzegovina
464
465 http://cpan.blic.net/
466
5df44211 467=item Bulgaria
4e860d0a 468
9d169eb4
LB
469 http://cpan.cbox.biz/
470 ftp://cpan.cbox.biz/cpan/
471 http://cpan.digsys.bg/
472 ftp://ftp.digsys.bg/pub/CPAN
4e860d0a 473
5df44211 474=item Croatia
4e860d0a 475
9d169eb4
LB
476 http://ftp.carnet.hr/pub/CPAN/
477 ftp://ftp.carnet.hr/pub/CPAN/
4e860d0a 478
5df44211 479=item Czech Republic
4e860d0a 480
5df44211 481 ftp://ftp.fi.muni.cz/pub/CPAN/
9d169eb4 482 http://archive.cpan.cz/
4e860d0a 483
5df44211 484=item Denmark
4e860d0a 485
9d169eb4
LB
486 http://mirrors.dotsrc.org/cpan
487 ftp://mirrors.dotsrc.org/cpan/
488 http://www.cpan.dk/
489 http://mirror.uni-c.dk/pub/CPAN/
4e860d0a 490
5df44211 491=item Finland
4e860d0a 492
5df44211 493 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
5c5c2539 494 http://mirror.eunet.fi/CPAN
4e860d0a 495
5df44211 496=item France
c165c82a 497
9d169eb4
LB
498 http://cpan.enstimac.fr/
499 ftp://ftp.inria.fr/pub/CPAN/
500 http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
501 ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
5df44211 502 ftp://ftp.lip6.fr/pub/perl/CPAN/
5df44211
JH
503 http://mir2.ovh.net/ftp.cpan.org
504 ftp://mir1.ovh.net/ftp.cpan.org
9d169eb4
LB
505 http://cpan.miroir-francais.fr/
506 ftp://miroir-francais.fr/pub/cpan/
507 ftp://ftp.oleane.net/pub/CPAN/
5c5c2539
JH
508 http://ftp.crihan.fr/mirrors/ftp.cpan.org/
509 ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
5df44211
JH
510 http://ftp.u-strasbg.fr/CPAN
511 ftp://ftp.u-strasbg.fr/CPAN
9d169eb4 512 http://cpan.cict.fr/
5df44211 513 ftp://cpan.cict.fr/pub/CPAN/
c165c82a 514
5df44211 515=item Germany
c165c82a 516
9d169eb4
LB
517 ftp://ftp.fu-berlin.de/unix/languages/perl/
518 http://mirrors.softliste.de/cpan/
5c5c2539 519 ftp://ftp.rub.de/pub/CPAN/
9d169eb4
LB
520 http://www.planet-elektronik.de/CPAN/
521 http://ftp.hosteurope.de/pub/CPAN/
522 ftp://ftp.hosteurope.de/pub/CPAN/
523 http://www.mirrorspace.org/cpan/
524 http://mirror.netcologne.de/cpan/
525 ftp://mirror.netcologne.de/cpan/
5df44211 526 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
9d169eb4
LB
527 http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
528 ftp://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
529 http://mirrors.zerg.biz/cpan/
5df44211
JH
530 http://ftp.gwdg.de/pub/languages/perl/CPAN/
531 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
9d169eb4
LB
532 http://dl.ambiweb.de/mirrors/ftp.cpan.org/
533 http://cpan.mirror.clusters.kg/
534 http://cpan.mirror.iphh.net/
535 ftp://cpan.mirror.iphh.net/pub/CPAN/
536 http://cpan.mirroring.de/
537 http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
538 ftp://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
539 http://ftp.cw.net/pub/CPAN/
540 ftp://ftp.cw.net/pub/CPAN/
541 http://cpan.cpantesters.org/
542 ftp://cpan.cpantesters.org/CPAN/
543 http://cpan.mirrored.de/
544 ftp://mirror.petamem.com/CPAN/
5df44211
JH
545 http://cpan.noris.de/
546 ftp://cpan.noris.de/pub/CPAN/
547 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
548 ftp://ftp.gmd.de/mirrors/CPAN/
4e860d0a 549
5df44211 550=item Greece
4e860d0a 551
5df44211
JH
552 ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
553 ftp://ftp.ntua.gr/pub/lang/perl/
9d169eb4
LB
554 http://cpan.cc.uoc.gr/
555 ftp://ftp.cc.uoc.gr/mirrors/CPAN/
4e860d0a 556
5df44211 557=item Hungary
4e860d0a 558
9d169eb4
LB
559 http://cpan.mirrors.enexis.hu/
560 ftp://cpan.mirrors.enexis.hu/mirrors/cpan/
561 http://cpan.hu/
4e860d0a 562
5df44211 563=item Iceland
4e860d0a 564
5df44211
JH
565 http://ftp.rhnet.is/pub/CPAN/
566 ftp://ftp.rhnet.is/pub/CPAN/
4e860d0a 567
5df44211 568=item Ireland
4e860d0a 569
9d169eb4
LB
570 http://ftp.esat.net/pub/languages/perl/CPAN/
571 ftp://ftp.esat.net/pub/languages/perl/CPAN/
5c5c2539
JH
572 http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
573 ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
4e860d0a 574
5df44211 575=item Italy
4e860d0a 576
9d169eb4
LB
577 http://bo.mirror.garr.it/mirrors/CPAN/
578 http://cpan.panu.it/
579 ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
580 http://cpan.fastbull.org/
4e860d0a 581
5df44211 582=item Latvia
4e860d0a 583
5df44211 584 http://kvin.lv/pub/CPAN/
4e860d0a 585
5df44211 586=item Lithuania
4e860d0a 587
9d169eb4
LB
588 http://ftp.litnet.lt/pub/CPAN/
589 ftp://ftp.litnet.lt/pub/CPAN/
590
591=item Malta
592
593 http://cpan.waldonet.net.mt/
4e860d0a 594
5df44211 595=item Netherlands
4e860d0a 596
9d169eb4
LB
597 ftp://ftp.quicknet.nl/pub/CPAN/
598 http://mirror.hostfuss.com/CPAN/
599 ftp://mirror.hostfuss.com/CPAN/
600 http://mirrors3.kernel.org/cpan/
601 ftp://mirrors3.kernel.org/pub/CPAN/
602 http://cpan.osmirror.nl/
603 ftp://ftp.osmirror.nl/pub/cpan/
604 http://cpan.mirror.versatel.nl/
605 ftp://ftp.mirror.versatel.nl/cpan/
5df44211 606 ftp://download.xs4all.nl/pub/mirror/CPAN/
9d169eb4
LB
607 http://mirror.leaseweb.com/CPAN/
608 ftp://mirror.leaseweb.com/CPAN/
5df44211 609 ftp://ftp.cpan.nl/pub/CPAN/
5df44211
JH
610 http://archive.cs.uu.nl/mirror/CPAN/
611 ftp://ftp.cs.uu.nl/mirror/CPAN/
9d169eb4 612 http://https://luxitude.net/cpan/
4e860d0a 613
5df44211
JH
614=item Norway
615
616 ftp://ftp.uninett.no/pub/languages/perl/CPAN
617 ftp://ftp.uit.no/pub/languages/perl/cpan/
618
619=item Poland
620
9d169eb4
LB
621 http://mirror.icis.pcz.pl/CPAN/
622 ftp://mirror.icis.pcz.pl/CPAN/
623 http://piotrkosoft.net/pub/mirrors/CPAN/
624 ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
625 http://ftp.man.poznan.pl/pub/CPAN
626 ftp://ftp.man.poznan.pl/pub/CPAN
5df44211 627 ftp://sunsite.icm.edu.pl/pub/CPAN/
9d169eb4 628 ftp://ftp.tpnet.pl/d4/CPAN/
5df44211
JH
629
630=item Portugal
631
5df44211
JH
632 http://cpan.dei.uc.pt/
633 ftp://ftp.dei.uc.pt/pub/CPAN
9d169eb4
LB
634 ftp://ftp.ist.utl.pt/pub/CPAN/
635 http://cpan.perl.pt/
5df44211
JH
636 http://cpan.ip.pt/
637 ftp://cpan.ip.pt/pub/cpan/
9d169eb4
LB
638 http://mirrors.nfsi.pt/CPAN/
639 ftp://mirrors.nfsi.pt/pub/CPAN/
640 http://cpan.dcc.fc.up.pt/
4e860d0a 641
5df44211 642=item Romania
4e860d0a 643
9d169eb4
LB
644 http://ftp.astral.ro/pub/CPAN/
645 ftp://ftp.astral.ro/pub/CPAN/
7a142657 646 ftp://ftp.lug.ro/CPAN
9d169eb4
LB
647 http://mirrors.xservers.ro/CPAN/
648 http://mirrors.hostingromania.ro/ftp.cpan.org/
649 ftp://ftp.hostingromania.ro/mirrors/ftp.cpan.org/
5c5c2539 650 ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
5c5c2539 651 ftp://ftp.ambra.ro/pub/CPAN
4e860d0a 652
5df44211 653=item Russia
4e860d0a 654
9d169eb4 655 ftp://ftp.aha.ru/CPAN/
5df44211
JH
656 http://cpan.rinet.ru/
657 ftp://cpan.rinet.ru/pub/mirror/CPAN/
9d169eb4
LB
658 ftp://ftp.SpringDaemons.com/pub/CPAN/
659 http://cpan.nx1.ru/
660 ftp://cpan.nx1.ru/
661 http://mirror.rol.ru/CPAN/
662 http://ftp.silvernet.ru/CPAN/
663 http://ftp.spbu.ru/CPAN/
664 ftp://ftp.spbu.ru/CPAN/
4e860d0a 665
5df44211 666=item Slovakia
4e860d0a 667
9d169eb4 668 http://cpan.fyxm.net/
4e860d0a 669
5df44211 670=item Slovenia
4e860d0a 671
9d169eb4 672 http://www.klevze.si/cpan
4e860d0a 673
5df44211 674=item Spain
4e860d0a 675
9d169eb4 676 http://osl.ugr.es/CPAN/
5df44211 677 ftp://ftp.rediris.es/mirror/CPAN/
9d169eb4
LB
678 http://ftp.gui.uva.es/sites/cpan.org/
679 ftp://ftp.gui.uva.es/sites/cpan.org/
4e860d0a 680
5df44211 681=item Sweden
4e860d0a 682
9d169eb4
LB
683 http://mirrors4.kernel.org/cpan/
684 ftp://mirrors4.kernel.org/pub/CPAN/
4e860d0a 685
5df44211 686=item Switzerland
4e860d0a 687
7a142657
JH
688 http://cpan.mirror.solnet.ch/
689 ftp://ftp.solnet.ch/mirror/CPAN/
9d169eb4
LB
690 http://mirror.switch.ch/ftp/mirror/CPAN/
691 ftp://mirror.switch.ch/mirror/CPAN/
c165c82a 692
5df44211 693=item Ukraine
c165c82a 694
9d169eb4
LB
695 http://cpan.makeperl.org/
696 ftp://cpan.makeperl.org/pub/CPAN
5df44211 697 http://cpan.org.ua/
5c5c2539
JH
698 http://no-more.kiev.ua/CPAN/
699 ftp://no-more.kiev.ua/pub/CPAN/
9d169eb4
LB
700 http://cpan.gafol.net/
701 ftp://ftp.gafol.net/pub/cpan/
c165c82a 702
5df44211 703=item United Kingdom
d4858812 704
9d169eb4
LB
705 http://www.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
706 ftp://ftp.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
707 http://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
708 ftp://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
709 http://www.mirror.8086.net/sites/CPAN/
710 ftp://ftp.mirror.8086.net/sites/CPAN/
5c5c2539
JH
711 http://cpan.mirror.anlx.net/
712 ftp://ftp.mirror.anlx.net/CPAN/
9d169eb4
LB
713 http://mirror.bytemark.co.uk/CPAN/
714 ftp://mirror.bytemark.co.uk/CPAN/
7a142657
JH
715 http://cpan.etla.org/
716 ftp://cpan.etla.org/pub/CPAN
5df44211 717 ftp://ftp.demon.co.uk/pub/CPAN/
9d169eb4
LB
718 http://mirror.sov.uk.goscomb.net/CPAN/
719 ftp://mirror.sov.uk.goscomb.net/pub/CPAN/
720 http://ftp.plig.net/pub/CPAN/
721 ftp://ftp.plig.net/pub/CPAN/
722 http://ftp.ticklers.org/pub/CPAN/
723 ftp://ftp.ticklers.org/pub/CPAN/
724 http://cpan.mirrors.uk2.net/
725 ftp://mirrors.uk2.net/pub/CPAN/
726 http://mirror.ox.ac.uk/sites/www.cpan.org/
727 ftp://mirror.ox.ac.uk/sites/www.cpan.org/
d4858812 728
4e860d0a
JH
729=back
730
731=head2 North America
732
733=over 4
734
9d169eb4 735=item Bahamas
5c5c2539 736
9d169eb4 737 http://www.securehost.com/mirror/CPAN/
5c5c2539 738
9d169eb4 739=item Canada
4e860d0a 740
9d169eb4
LB
741 http://cpan.justanotherperlhacker.com/pub/CPAN/
742 ftp://cpan.justanotherperlhacker.com/pub/CPAN/
743 http://cpan.arcticnetwork.ca
744 ftp://mirror.arcticnetwork.ca/pub/CPAN
5c5c2539
JH
745 http://cpan.sunsite.ualberta.ca/
746 ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
5df44211
JH
747 http://theoryx5.uwinnipeg.ca/pub/CPAN/
748 ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
9d169eb4
LB
749 http://arwen.cs.dal.ca/mirror/CPAN/
750 ftp://arwen.cs.dal.ca/pub/mirror/CPAN/
751 http://CPAN.mirror.rafal.ca/
752 ftp://CPAN.mirror.rafal.ca/pub/CPAN/
5c5c2539 753 ftp://ftp.nrc.ca/pub/CPAN/
9d169eb4
LB
754 http://mirror.csclub.uwaterloo.ca/pub/CPAN/
755 ftp://mirror.csclub.uwaterloo.ca/pub/CPAN/
7a142657 756
5df44211 757=item Mexico
c165c82a 758
5df44211
JH
759 http://www.msg.com.mx/CPAN/
760 ftp://ftp.msg.com.mx/pub/CPAN/
c165c82a 761
5c5c2539 762=item United States
d4858812 763
7a142657 764=over 8
4e860d0a 765
5df44211 766=item Alabama
4e860d0a 767
5df44211
JH
768 http://mirror.hiwaay.net/CPAN/
769 ftp://mirror.hiwaay.net/CPAN/
4e860d0a 770
5df44211 771=item California
4e860d0a 772
9d169eb4
LB
773 http://cpan.knowledgematters.net/
774 http://cpan.binkerton.com/
5df44211 775 http://cpan.develooper.com/
5df44211 776 http://mirrors.gossamer-threads.com/CPAN
9d169eb4 777 http://cpan.schatt.com/
5df44211
JH
778 http://mirrors.kernel.org/cpan/
779 ftp://mirrors.kernel.org/pub/CPAN
9d169eb4
LB
780 http://mirrors2.kernel.org/cpan/
781 ftp://mirrors2.kernel.org/pub/CPAN/
782 http://cpan.mirrors.redwire.net/
783 http://cpan.mirror.facebook.net/
784 http://mirrors1.kernel.org/cpan/
785 ftp://mirrors1.kernel.org/pub/CPAN/
7a142657
JH
786 http://cpan-sj.viaverio.com/
787 ftp://cpan-sj.viaverio.com/pub/CPAN/
5df44211 788 http://www.perl.com/CPAN/
9d169eb4 789 http://cpan.yahoo.com/
4e860d0a 790
9d169eb4 791=item Florida
4e860d0a 792
9d169eb4
LB
793 ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
794 http://mirror.atlantic.net/pub/CPAN/
795 ftp://mirror.atlantic.net/pub/CPAN/
796 http://mirror.candidhosting.com/pub/CPAN
797 ftp://mirror.candidhosting.com/pub/CPAN
4e860d0a 798
9d169eb4 799=item Idaho
4e860d0a 800
9d169eb4
LB
801 http://mirror.its.uidaho.edu/pub/cpan/
802 ftp://mirror.its.uidaho.edu/cpan/
4e860d0a 803
9d169eb4 804=item Illinois
c165c82a 805
9d169eb4
LB
806 http://cpan.mirrors.hoobly.com/
807 http://cpan.uchicago.edu/pub/CPAN/
808 ftp://cpan.uchicago.edu/pub/CPAN/
809 http://mirrors.servercentral.net/CPAN/
810 http://www.stathy.com/CPAN/
811 ftp://www.stathy.com/CPAN/
c165c82a 812
5df44211 813=item Indiana
4e860d0a 814
5df44211
JH
815 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
816 http://cpan.netnitco.net/
817 ftp://cpan.netnitco.net/pub/mirrors/CPAN/
9d169eb4
LB
818 http://ftp.ndlug.nd.edu/pub/perl/
819 ftp://ftp.ndlug.nd.edu/pub/perl/
5c5c2539 820 http://fx.saintjoe.edu/pub/CPAN
4e860d0a 821
5df44211 822=item Massachusetts
4e860d0a 823
5df44211 824 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
4e860d0a 825
5df44211 826=item Michigan
4e860d0a 827
9d169eb4
LB
828 http://ftp.wayne.edu/cpan/
829 ftp://ftp.wayne.edu/cpan/
4e860d0a 830
9d169eb4 831=item Minnesota
5c5c2539 832
9d169eb4 833 http://cpan.msi.umn.edu/
5c5c2539 834
5df44211 835=item New Jersey
4e860d0a 836
9d169eb4
LB
837 http://mirror.datapipe.net/CPAN/
838 ftp://mirror.datapipe.net/pub/CPAN/
4e860d0a 839
5df44211 840=item New York
4e860d0a 841
9d169eb4
LB
842 http://mirrors.24-7-solutions.net/pub/CPAN/
843 ftp://mirrors.24-7-solutions.net/pub/CPAN/
844 http://mirror.cc.columbia.edu/pub/software/cpan/
845 ftp://mirror.cc.columbia.edu/pub/software/cpan/
5df44211 846 http://cpan.belfry.net/
5c5c2539 847 http://cpan.erlbaum.net/
9d169eb4
LB
848 ftp://cpan.erlbaum.net/CPAN/
849 http://cpan.hexten.net/
850 ftp://cpan.hexten.net/
851 http://ftp.fxcorporate.com/CPAN/
852 ftp://ftp.fxcorporate.com/pub/CPAN/
853 ftp://mirror.nyi.net/CPAN/
854 http://mirror.rit.edu/CPAN/
855 ftp://mirror.rit.edu/CPAN/
4e860d0a 856
5df44211 857=item North Carolina
4e860d0a 858
9d169eb4 859 http://www.ibiblio.org/pub/mirrors/CPAN
5c5c2539 860 ftp://ftp.ncsu.edu/pub/mirror/CPAN/
4e860d0a 861
5df44211 862=item Oregon
4e860d0a 863
9d169eb4
LB
864 http://ftp.osuosl.org/pub/CPAN/
865 ftp://ftp.osuosl.org/pub/CPAN/
4e860d0a 866
5df44211 867=item Pennsylvania
4e860d0a 868
5df44211
JH
869 http://ftp.epix.net/CPAN/
870 ftp://ftp.epix.net/pub/languages/perl/
5df44211
JH
871 http://cpan.pair.com/
872 ftp://cpan.pair.com/pub/CPAN/
9d169eb4
LB
873
874=item South Carolina
875
876 http://cpan.mirror.clemson.edu/
4e860d0a 877
5df44211 878=item Tennessee
4e860d0a 879
9d169eb4 880 http://mira.sunsite.utk.edu/CPAN/
4e860d0a 881
5df44211 882=item Texas
4e860d0a 883
9d169eb4 884 http://mirror.uta.edu/CPAN
4e860d0a 885
5df44211 886=item Utah
4e860d0a 887
9d169eb4
LB
888 http://cpan.cs.utah.edu
889 ftp://cpan.cs.utah.edu/pub/CPAN/
5df44211 890 ftp://mirror.xmission.com/CPAN/
4e860d0a 891
5df44211 892=item Virginia
4e860d0a 893
7a142657
JH
894 http://cpan-du.viaverio.com/
895 ftp://cpan-du.viaverio.com/pub/CPAN/
5df44211
JH
896 http://perl.secsup.org/
897 ftp://perl.secsup.org/pub/perl/
9d169eb4 898 ftp://mirror.cogentco.com/pub/CPAN/
4e860d0a 899
5c5c2539 900=item Washington
4e860d0a 901
5df44211
JH
902 http://cpan.llarian.net/
903 ftp://cpan.llarian.net/pub/CPAN/
5df44211 904 ftp://ftp-mirror.internap.com/pub/CPAN/
d4858812 905
5df44211 906=item Wisconsin
d4858812 907
9d169eb4
LB
908 http://cpan.mirrors.tds.net
909 ftp://cpan.mirrors.tds.net/pub/CPAN
5df44211
JH
910 http://mirror.sit.wisc.edu/pub/CPAN/
911 ftp://mirror.sit.wisc.edu/pub/CPAN/
4e860d0a
JH
912
913=back
914
5c5c2539
JH
915=back
916
4e860d0a
JH
917=head2 Oceania
918
919=over 4
920
5df44211 921=item Australia
4e860d0a 922
9d169eb4
LB
923 http://mirror.internode.on.net/pub/cpan/
924 ftp://mirror.internode.on.net/pub/cpan/
925 http://cpan.mirror.aussiehq.net.au/
926 http://mirror.as24220.net/cpan/
927 ftp://mirror.as24220.net/cpan/
4e860d0a 928
5df44211 929=item New Zealand
d4858812 930
5df44211 931 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
9d169eb4
LB
932 http://cpan.inspire.net.nz
933 ftp://cpan.inspire.net.nz/cpan
934 http://cpan.catalyst.net.nz/CPAN/
935 ftp://cpan.catalyst.net.nz/pub/CPAN/
4e860d0a
JH
936
937=back
938
939=head2 South America
940
941=over 4
942
5df44211 943=item Argentina
4e860d0a 944
9d169eb4
LB
945 http://cpan.patan.com.ar/
946 http://cpan.localhost.net.ar
947 ftp://mirrors.localhost.net.ar/pub/mirrors/CPAN
4e860d0a 948
5df44211 949=item Brazil
4e860d0a 950
5df44211 951 ftp://cpan.pop-mg.com.br/pub/CPAN/
9d169eb4
LB
952 http://ftp.pucpr.br/CPAN
953 ftp://ftp.pucpr.br/CPAN
954 http://cpan.kinghost.net/
955 ftp://ftp.linorg.usp.br/CPAN
4e860d0a 956
5df44211 957=item Chile
4e860d0a 958
9d169eb4
LB
959 http://cpan.dcc.uchile.cl/
960 ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
961
962=item Colombia
963
964 http://www.laqee.unal.edu.co/CPAN/
2e1d04bc
JH
965
966=back
967
5df44211
JH
968=head2 RSYNC Mirrors
969
9d169eb4
LB
970 mirror.as24220.net::cpan
971 cpan.inode.at::CPAN
972 gd.tuwien.ac.at::CPAN
973 ftp.belnet.be::packages/cpan
974 rsync.linorg.usp.br::CPAN
975 rsync.arcticnetwork.ca::CPAN
976 CPAN.mirror.rafal.ca::CPAN
977 mirror.csclub.uwaterloo.ca::CPAN
7a142657 978 theoryx5.uwinnipeg.ca::CPAN
9d169eb4
LB
979 www.laqee.unal.edu.co::CPAN
980 mirror.uni-c.dk::CPAN
7a142657 981 rsync.nic.funet.fi::CPAN
9d169eb4 982 rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
7a142657 983 mir1.ovh.net::CPAN
9d169eb4
LB
984 miroir-francais.fr::cpan
985 ftp.crihan.fr::CPAN
986 rsync://mirror.cict.fr/cpan/
987 rsync://mirror.netcologne.de/cpan/
988 ftp-stud.hs-esslingen.de::CPAN/
7a142657 989 ftp.gwdg.de::FTP/languages/perl/CPAN/
9d169eb4
LB
990 cpan.mirror.iphh.net::CPAN
991 cpan.cpantesters.org::cpan
992 cpan.hu::CPAN
993 komo.vlsm.org::CPAN
994 mirror.unej.ac.id::cpan
995 ftp.esat.net::/pub/languages/perl/CPAN
996 ftp.heanet.ie::mirrors/ftp.perl.org/pub/CPAN
997 rsync.panu.it::CPAN
998 cpan.fastbull.org::CPAN
999 ftp.kddilabs.jp::cpan
1000 ftp.nara.wide.ad.jp::cpan/
1001 rsync://ftp.jaist.ac.jp/pub/CPAN/
1002 rsync://ftp.riken.jp/cpan/
1003 mirror.linuxiso.kz::CPAN
1004 rsync://mirrors3.kernel.org/mirrors/CPAN/
1005 rsync://rsync.osmirror.nl/cpan/
1006 mirror.leaseweb.com::CPAN
1007 cpan.nautile.nc::CPAN
1008 mirror.icis.pcz.pl::CPAN
1009 piotrkosoft.net::mirrors/CPAN
1010 rsync://cpan.perl.pt/
1011 ftp.kaist.ac.kr::cpan
1012 cpan.sarang.net::CPAN
7a142657
JH
1013 mirror.averse.net::cpan
1014 rsync.oss.eznetsols.org
9d169eb4
LB
1015 mirror.ac.za::cpan
1016 ftp.is.co.za::IS-Mirror/ftp.cpan.org/
1017 rsync://ftp.gui.uva.es/cpan/
1018 rsync://mirrors4.kernel.org/mirrors/CPAN/
7a142657 1019 ftp.solnet.ch::CPAN
9d169eb4
LB
1020 ftp.ulak.net.tr::CPAN
1021 gafol.net::cpan
1022 rsync.mirrorservice.org::ftp.funet.fi/pub/
1023 rsync://rsync.mirror.8086.net/CPAN/
1024 rsync.mirror.anlx.net::CPAN
1025 mirror.bytemark.co.uk::CPAN
1026 ftp.plig.net::CPAN
1027 rsync://ftp.ticklers.org:CPAN/
1028 mirrors.ibiblio.org::CPAN
7a142657 1029 cpan-du.viaverio.com::CPAN
9d169eb4
LB
1030 mirror.hiwaay.net::CPAN
1031 rsync://mira.sunsite.utk.edu/CPAN/
1032 cpan.mirrors.tds.net::CPAN
1033 mirror.its.uidaho.edu::cpan
1034 rsync://mirror.cc.columbia.edu::cpan/
1035 ftp.fxcorporate.com::CPAN
1036 rsync.atlantic.net::CPAN
7a142657 1037 mirrors.kernel.org::mirrors/CPAN
9d169eb4 1038 rsync://mirrors2.kernel.org/mirrors/CPAN/
7a142657 1039 cpan.pair.com::CPAN
9d169eb4
LB
1040 rsync://mirror.rit.edu/CPAN/
1041 rsync://mirror.facebook.net/cpan/
1042 rsync://mirrors1.kernel.org/mirrors/CPAN/
7a142657 1043 cpan-sj.viaverio.com::CPAN
5df44211 1044
2e1d04bc 1045For an up-to-date listing of CPAN sites,
4e860d0a 1046see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
2e1d04bc
JH
1047
1048=head1 Modules: Creation, Use, and Abuse
1049
1050(The following section is borrowed directly from Tim Bunce's modules
1051file, available at your nearest CPAN site.)
1052
1053Perl implements a class using a package, but the presence of a
1054package doesn't imply the presence of a class. A package is just a
1055namespace. A class is a package that provides subroutines that can be
1056used as methods. A method is just a subroutine that expects, as its
1057first argument, either the name of a package (for "static" methods),
1058or a reference to something (for "virtual" methods).
1059
1060A module is a file that (by convention) provides a class of the same
1061name (sans the .pm), plus an import method in that class that can be
1062called to fetch exported symbols. This module may implement some of
1063its methods by loading dynamic C or C++ objects, but that should be
1064totally transparent to the user of the module. Likewise, the module
1065might set up an AUTOLOAD function to slurp in subroutine definitions on
1066demand, but this is also transparent. Only the F<.pm> file is required to
1067exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1068the AUTOLOAD mechanism.
1069
1070=head2 Guidelines for Module Creation
1071
1072=over 4
1073
ac634a9a
JH
1074=item *
1075
1076Do similar modules already exist in some form?
2e1d04bc
JH
1077
1078If so, please try to reuse the existing modules either in whole or
1079by inheriting useful features into a new class. If this is not
1080practical try to get together with the module authors to work on
1081extending or enhancing the functionality of the existing modules.
1082A perfect example is the plethora of packages in perl4 for dealing
1083with command line options.
1084
1085If you are writing a module to expand an already existing set of
1086modules, please coordinate with the author of the package. It
1087helps if you follow the same naming scheme and module interaction
1088scheme as the original author.
1089
ac634a9a
JH
1090=item *
1091
1092Try to design the new module to be easy to extend and reuse.
2e1d04bc
JH
1093
1094Try to C<use warnings;> (or C<use warnings qw(...);>).
1095Remember that you can add C<no warnings qw(...);> to individual blocks
1096of code that need less warnings.
1097
1098Use blessed references. Use the two argument form of bless to bless
1099into the class name given as the first parameter of the constructor,
1100e.g.,:
1101
1102 sub new {
1103 my $class = shift;
1104 return bless {}, $class;
1105 }
1106
1107or even this if you'd like it to be used as either a static
1108or a virtual method.
1109
1110 sub new {
1111 my $self = shift;
1112 my $class = ref($self) || $self;
1113 return bless {}, $class;
1114 }
1115
1116Pass arrays as references so more parameters can be added later
1117(it's also faster). Convert functions into methods where
1118appropriate. Split large methods into smaller more flexible ones.
1119Inherit methods from other modules if appropriate.
1120
1121Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1122Generally you can delete the C<eq 'FOO'> part with no harm at all.
1123Let the objects look after themselves! Generally, avoid hard-wired
1124class names as far as possible.
1125
1126Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1127C<< $r->func() >> would work (see L<perlbot> for more details).
1128
1129Use autosplit so little used or newly added functions won't be a
1130burden to programs that don't use them. Add test functions to
1131the module after __END__ either using AutoSplit or by saying:
1132
1133 eval join('',<main::DATA>) || die $@ unless caller();
1134
1135Does your module pass the 'empty subclass' test? If you say
1136C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1137to use SUBCLASS in exactly the same way as YOURCLASS. For example,
63acfd00 1138does your application still work if you change: C<< $obj = YOURCLASS->new(); >>
1139into: C<< $obj = SUBCLASS->new(); >> ?
2e1d04bc
JH
1140
1141Avoid keeping any state information in your packages. It makes it
1142difficult for multiple other packages to use yours. Keep state
1143information in objects.
1144
1145Always use B<-w>.
1146
1147Try to C<use strict;> (or C<use strict qw(...);>).
1148Remember that you can add C<no strict qw(...);> to individual blocks
1149of code that need less strictness.
1150
1151Always use B<-w>.
1152
ba555bf5 1153Follow the guidelines in L<perlstyle>.
2e1d04bc
JH
1154
1155Always use B<-w>.
1156
ac634a9a
JH
1157=item *
1158
1159Some simple style guidelines
2e1d04bc
JH
1160
1161The perlstyle manual supplied with Perl has many helpful points.
1162
1163Coding style is a matter of personal taste. Many people evolve their
1164style over several years as they learn what helps them write and
1165maintain good code. Here's one set of assorted suggestions that
1166seem to be widely used by experienced developers:
1167
1168Use underscores to separate words. It is generally easier to read
1169$var_names_like_this than $VarNamesLikeThis, especially for
1170non-native speakers of English. It's also a simple rule that works
1171consistently with VAR_NAMES_LIKE_THIS.
1172
1173Package/Module names are an exception to this rule. Perl informally
1174reserves lowercase module names for 'pragma' modules like integer
1175and strict. Other modules normally begin with a capital letter and
1176use mixed case with no underscores (need to be short and portable).
1177
1178You may find it helpful to use letter case to indicate the scope
1179or nature of a variable. For example:
1180
1181 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
1182 $Some_Caps_Here package-wide global/static
1183 $no_caps_here function scope my() or local() variables
1184
1185Function and method names seem to work best as all lowercase.
1186e.g., C<< $obj->as_string() >>.
1187
1188You can use a leading underscore to indicate that a variable or
1189function should not be used outside the package that defined it.
1190
ac634a9a
JH
1191=item *
1192
1193Select what to export.
2e1d04bc
JH
1194
1195Do NOT export method names!
1196
1197Do NOT export anything else by default without a good reason!
1198
1199Exports pollute the namespace of the module user. If you must
1200export try to use @EXPORT_OK in preference to @EXPORT and avoid
1201short or common names to reduce the risk of name clashes.
1202
1203Generally anything not exported is still accessible from outside the
1204module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1205syntax. By convention you can use a leading underscore on names to
1206indicate informally that they are 'internal' and not for public use.
1207
1208(It is actually possible to get private functions by saying:
1209C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1210directly as a method, because a method must have a name in the symbol
1211table.)
1212
1213As a general rule, if the module is trying to be object oriented
1214then export nothing. If it's just a collection of functions then
1215@EXPORT_OK anything but use @EXPORT with caution.
1216
ac634a9a
JH
1217=item *
1218
1219Select a name for the module.
2e1d04bc
JH
1220
1221This name should be as descriptive, accurate, and complete as
1222possible. Avoid any risk of ambiguity. Always try to use two or
1223more whole words. Generally the name should reflect what is special
1224about what the module does rather than how it does it. Please use
1225nested module names to group informally or categorize a module.
1226There should be a very good reason for a module not to have a nested name.
1227Module names should begin with a capital letter.
1228
1229Having 57 modules all called Sort will not make life easy for anyone
1230(though having 23 called Sort::Quick is only marginally better :-).
1231Imagine someone trying to install your module alongside many others.
1232If in any doubt ask for suggestions in comp.lang.perl.misc.
1233
1234If you are developing a suite of related modules/classes it's good
1235practice to use nested classes with a common prefix as this will
1236avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1237Xyz::Model etc. Use the modules in this list as a naming guide.
1238
1239If adding a new module to a set, follow the original author's
1240standards for naming modules and the interface to methods in
1241those modules.
1242
4844a3be
SP
1243If developing modules for private internal or project specific use,
1244that will never be released to the public, then you should ensure
1245that their names will not clash with any future public module. You
1246can do this either by using the reserved Local::* category or by
1247using a category name that includes an underscore like Foo_Corp::*.
1248
2e1d04bc
JH
1249To be portable each component of a module name should be limited to
125011 characters. If it might be used on MS-DOS then try to ensure each is
1251unique in the first 8 characters. Nested modules make this easier.
1252
ac634a9a
JH
1253=item *
1254
1255Have you got it right?
2e1d04bc
JH
1256
1257How do you know that you've made the right decisions? Have you
1258picked an interface design that will cause problems later? Have
1259you picked the most appropriate name? Do you have any questions?
1260
1261The best way to know for sure, and pick up many helpful suggestions,
1262is to ask someone who knows. Comp.lang.perl.misc is read by just about
1263all the people who develop modules and it's the best place to ask.
1264
1265All you need to do is post a short summary of the module, its
1266purpose and interfaces. A few lines on each of the main methods is
1267probably enough. (If you post the whole module it might be ignored
1268by busy people - generally the very people you want to read it!)
1269
1270Don't worry about posting if you can't say when the module will be
1271ready - just say so in the message. It might be worth inviting
1272others to help you, they may be able to complete it for you!
1273
ac634a9a
JH
1274=item *
1275
1276README and other Additional Files.
2e1d04bc
JH
1277
1278It's well known that software developers usually fully document the
1279software they write. If, however, the world is in urgent need of
1280your software and there is not enough time to write the full
1281documentation please at least provide a README file containing:
1282
1283=over 10
1284
1285=item *
ac634a9a 1286
2e1d04bc
JH
1287A description of the module/package/extension etc.
1288
1289=item *
ac634a9a 1290
2e1d04bc
JH
1291A copyright notice - see below.
1292
1293=item *
ac634a9a 1294
2e1d04bc
JH
1295Prerequisites - what else you may need to have.
1296
1297=item *
ac634a9a 1298
2e1d04bc
JH
1299How to build it - possible changes to Makefile.PL etc.
1300
1301=item *
ac634a9a 1302
2e1d04bc
JH
1303How to install it.
1304
1305=item *
ac634a9a 1306
2e1d04bc
JH
1307Recent changes in this release, especially incompatibilities
1308
1309=item *
ac634a9a 1310
2e1d04bc
JH
1311Changes / enhancements you plan to make in the future.
1312
1313=back
1314
1315If the README file seems to be getting too large you may wish to
1316split out some of the sections into separate files: INSTALL,
1317Copying, ToDo etc.
1318
1319=over 4
1320
c165c82a 1321=item *
2e1d04bc 1322
c165c82a 1323Adding a Copyright Notice.
ac634a9a 1324
2e1d04bc
JH
1325How you choose to license your work is a personal decision.
1326The general mechanism is to assert your Copyright and then make
1327a declaration of how others may copy/use/modify your work.
1328
2a551100
JH
1329Perl, for example, is supplied with two types of licence: The GNU GPL
1330and The Artistic Licence (see the files README, Copying, and Artistic,
1331or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
1332just using the GNU GPL.
2e1d04bc
JH
1333
1334My personal recommendation, out of respect for Larry, Perl, and the
1335Perl community at large is to state something simply like:
1336
1337 Copyright (c) 1995 Your Name. All rights reserved.
1338 This program is free software; you can redistribute it and/or
1339 modify it under the same terms as Perl itself.
1340
1341This statement should at least appear in the README file. You may
1342also wish to include it in a Copying file and your source files.
1343Remember to include the other words in addition to the Copyright.
1344
ac634a9a
JH
1345=item *
1346
1347Give the module a version/issue/release number.
2e1d04bc
JH
1348
1349To be fully compatible with the Exporter and MakeMaker modules you
1350should store your module's version number in a non-my package
1351variable called $VERSION. This should be a floating point
1352number with at least two digits after the decimal (i.e., hundredths,
1353e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1354See L<Exporter> for details.
1355
1356It may be handy to add a function or method to retrieve the number.
1357Use the number in announcements and archive file names when
1358releasing the module (ModuleName-1.02.tar.Z).
1359See perldoc ExtUtils::MakeMaker.pm for details.
1360
ac634a9a
JH
1361=item *
1362
1363How to release and distribute a module.
2e1d04bc
JH
1364
1365It's good idea to post an announcement of the availability of your
1366module (or the module itself if small) to the comp.lang.perl.announce
1367Usenet newsgroup. This will at least ensure very wide once-off
1368distribution.
1369
1370If possible, register the module with CPAN. You should
1371include details of its location in your announcement.
1372
1373Some notes about ftp archives: Please use a long descriptive file
1374name that includes the version number. Most incoming directories
1375will not be readable/listable, i.e., you won't be able to see your
1376file after uploading it. Remember to send your email notification
1377message as soon as possible after uploading else your file may get
1378deleted automatically. Allow time for the file to be processed
1379and/or check the file has been processed before announcing its
1380location.
1381
1382FTP Archives for Perl Modules:
1383
1384Follow the instructions and links on:
1385
4e860d0a
JH
1386 http://www.cpan.org/modules/00modlist.long.html
1387 http://www.cpan.org/modules/04pause.html
2e1d04bc
JH
1388
1389or upload to one of these sites:
1390
1391 https://pause.kbx.de/pause/
e59066d8 1392 http://pause.perl.org/
2e1d04bc
JH
1393
1394and notify <modules@perl.org>.
1395
1396By using the WWW interface you can ask the Upload Server to mirror
1397your modules from your ftp or WWW site into your own directory on
1398CPAN!
1399
1400Please remember to send me an updated entry for the Module list!
1401
ac634a9a
JH
1402=item *
1403
1404Take care when changing a released module.
2e1d04bc
JH
1405
1406Always strive to remain compatible with previous released versions.
1407Otherwise try to add a mechanism to revert to the
1408old behavior if people rely on it. Document incompatible changes.
1409
1410=back
1411
abf06cc1
MS
1412=back
1413
2e1d04bc
JH
1414=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1415
1416=over 4
1417
ac634a9a
JH
1418=item *
1419
1420There is no requirement to convert anything.
2e1d04bc
JH
1421
1422If it ain't broke, don't fix it! Perl 4 library scripts should
1423continue to work with no problems. You may need to make some minor
1424changes (like escaping non-array @'s in double quoted strings) but
1425there is no need to convert a .pl file into a Module for just that.
1426
ac634a9a
JH
1427=item *
1428
1429Consider the implications.
2e1d04bc
JH
1430
1431All Perl applications that make use of the script will need to
1432be changed (slightly) if the script is converted into a module. Is
1433it worth it unless you plan to make other changes at the same time?
1434
ac634a9a
JH
1435=item *
1436
1437Make the most of the opportunity.
2e1d04bc
JH
1438
1439If you are going to convert the script to a module you can use the
1440opportunity to redesign the interface. The guidelines for module
1441creation above include many of the issues you should consider.
1442
ac634a9a
JH
1443=item *
1444
1445The pl2pm utility will get you started.
2e1d04bc
JH
1446
1447This utility will read *.pl files (given as parameters) and write
1448corresponding *.pm files. The pl2pm utilities does the following:
1449
1450=over 10
1451
1452=item *
ac634a9a 1453
2e1d04bc
JH
1454Adds the standard Module prologue lines
1455
1456=item *
ac634a9a 1457
2e1d04bc
JH
1458Converts package specifiers from ' to ::
1459
1460=item *
ac634a9a 1461
2e1d04bc
JH
1462Converts die(...) to croak(...)
1463
1464=item *
ac634a9a 1465
2e1d04bc
JH
1466Several other minor changes
1467
1468=back
1469
1470Being a mechanical process pl2pm is not bullet proof. The converted
1471code will need careful checking, especially any package statements.
1472Don't delete the original .pl file till the new .pm one works!
1473
1474=back
1475
1476=head2 Guidelines for Reusing Application Code
1477
1478=over 4
1479
ac634a9a
JH
1480=item *
1481
1482Complete applications rarely belong in the Perl Module Library.
1483
1484=item *
2e1d04bc 1485
ac634a9a 1486Many applications contain some Perl code that could be reused.
2e1d04bc
JH
1487
1488Help save the world! Share your code in a form that makes it easy
1489to reuse.
1490
ac634a9a
JH
1491=item *
1492
1493Break-out the reusable code into one or more separate module files.
1494
1495=item *
1496
1497Take the opportunity to reconsider and redesign the interfaces.
2e1d04bc 1498
ac634a9a 1499=item *
2e1d04bc 1500
ac634a9a 1501In some cases the 'application' can then be reduced to a small
2e1d04bc
JH
1502
1503fragment of code built on top of the reusable modules. In these cases
1504the application could invoked as:
1505
1506 % perl -e 'use Module::Name; method(@ARGV)' ...
1507or
1508 % perl -mModule::Name ... (in perl5.002 or higher)
1509
1510=back
1511
1512=head1 NOTE
1513
1514Perl does not enforce private and public parts of its modules as you may
1515have been used to in other languages like C++, Ada, or Modula-17. Perl
1516doesn't have an infatuation with enforced privacy. It would prefer
1517that you stayed out of its living room because you weren't invited, not
1518because it has a shotgun.
1519
1520The module and its user have a contract, part of which is common law,
1521and part of which is "written". Part of the common law contract is
1522that a module doesn't pollute any namespace it wasn't asked to. The
1523written contract for the module (A.K.A. documentation) may make other
1524provisions. But then you know when you C<use RedefineTheWorld> that
1525you're redefining the world and willing to take the consequences.
1526EOF
1527
1528close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
b7da254d 1529close OUT or warn "$0: failed to close OUT (perlmodlib.pod): $!";
2e1d04bc 1530