pod/perlmodlib.PL

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