pod/perlmodlib.PL

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