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