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