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