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