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