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