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