pod/perlmodlib.PL

   1 #!../miniperl
   2
   3 use strict;
   4 use warnings;
   5
   6 local $ENV{LC_ALL} = 'C';
   7
   8 my $Quiet;
   9 @ARGV = grep { not($_ eq '-q' and $Quiet = 1) } @ARGV;
  10
  11 if (@ARGV) {
  12     my $workdir = shift;
  13     chdir $workdir
  14         or die "Couldn't chdir to '$workdir': $!";
  15 }
  16 require './regen/regen_lib.pl';
  17
  18 # MANIFEST itself is Unix style filenames, so we have to assume that Unix style
  19 # filenames will work.
  20
  21 open MANIFEST, '<', 'MANIFEST'
  22     or die "Can't open MANIFEST: $!";
  23 my @files =
  24     grep !m#/perl.*\.pod#,
  25     grep m#(?:\.pm|\.pod|_pm\.PL)#,
  26     map {s/\s.*//s; $_}
  27     grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo)/# }
  28     <MANIFEST>;
  29 close MANIFEST
  30     or die "$0: failed to close MANIFEST: $!";
  31
  32 my $out = open_new('pod/perlmodlib.pod', undef,
  33                    {by => "$0 extracting documentation",
  34                     from => 'the Perl source files'}, 1);
  35
  36 my %exceptions = (
  37     'abbrev' => 'Text::Abbrev',
  38     'carp' => 'Carp',
  39     'getopt' => 'Getopt::Std',
  40     'Encode::MIME::NAME' => 'Encode::MIME::Name',
  41     'libnetFAQ' => 'Net::libnetFAQ',
  42 );
  43
  44 my (@pragma, @mod);
  45
  46 for my $filename (@files) {
  47     unless (open MOD, '<', $filename) {
  48         warn "Couldn't open $filename: $!";
  49         next;
  50     }
  51
  52     my ($name, $thing);
  53     my $foundit = 0;
  54     {
  55         local $/ = "";
  56         while (<MOD>) {
  57             next unless /^=head1 NAME/;
  58             $foundit++;
  59             last;
  60         }
  61     }
  62     unless ($foundit) {
  63         warn "$filename missing =head1 NAME (OK if respective .pod exists)\n"
  64             unless $Quiet;
  65         next;
  66     }
  67     my $title = <MOD>;
  68     chomp $title;
  69     close MOD
  70         or die "Error closing $filename: $!";
  71
  72     ($name, $thing) = split / --? /, $title, 2;
  73
  74     unless ($name and $thing) {
  75         warn "$filename missing name\n"  unless $name;
  76         warn "$filename missing thing\n" unless $thing or $Quiet;
  77         next;
  78     }
  79
  80     $name =~ s/[^A-Za-z0-9_:\$<>].*//;
  81     $name = $exceptions{$name} || $name;
  82     $thing =~ s/^perl pragma to //i;
  83     $thing = ucfirst $thing;
  84     $title = "=item $name\n\n$thing\n\n";
  85
  86     if ($name =~ /[A-Z]/) {
  87         push @mod, $title;
  88     } else {
  89         push @pragma, $title;
  90     }
  91 }
  92
  93 # Much easier to special case it like this than special case the depending on
  94 # and parsing lib/Config.pod, or special case opening configpm and finding its
  95 # =head1 (which is not found with the $/="" above)
  96 push @mod, "=item Config\n\nAccess Perl configuration information\n\n";
  97
  98
  99 # The intent of using =cut as the heredoc terminator is to make the whole file
 100 # parse as (reasonably) sane Pod as-is to anything that attempts to
 101 # brute-force treat it as such. The content is already useful - this just
 102 # makes it tidier, by stopping anything doing this mistaking the rest of the
 103 # Perl code for Pod. eg http://search.cpan.org/dist/perl/pod/perlmodlib.PL
 104
 105 print $out <<'=cut';
 106 =head1 NAME
 107
 108 perlmodlib - constructing new Perl modules and finding existing ones
 109
 110 =head1 THE PERL MODULE LIBRARY
 111
 112 Many modules are included in the Perl distribution.  These are described
 113 below, and all end in F<.pm>.  You may discover compiled library
 114 files (usually ending in F<.so>) or small pieces of modules to be
 115 autoloaded (ending in F<.al>); these were automatically generated
 116 by the installation process.  You may also discover files in the
 117 library directory that end in either F<.pl> or F<.ph>.  These are
 118 old libraries supplied so that old programs that use them still
 119 run.  The F<.pl> files will all eventually be converted into standard
 120 modules, and the F<.ph> files made by B<h2ph> will probably end up
 121 as extension modules made by B<h2xs>.  (Some F<.ph> values may
 122 already be available through the POSIX, Errno, or Fcntl modules.)
 123 The B<pl2pm> file in the distribution may help in your conversion,
 124 but it's just a mechanical process and therefore far from bulletproof.
 125
 126 =head2 Pragmatic Modules
 127
 128 They work somewhat like compiler directives (pragmata) in that they
 129 tend to affect the compilation of your program, and thus will usually
 130 work well only when used within a C<use>, or C<no>.  Most of these
 131 are lexically scoped, so an inner BLOCK may countermand them
 132 by saying:
 133
 134     no integer;
 135     no strict 'refs';
 136     no warnings;
 137
 138 which lasts until the end of that BLOCK.
 139
 140 Some pragmas are lexically scoped--typically those that affect the
 141 C<$^H> hints variable.  Others affect the current package instead,
 142 like C<use vars> and C<use subs>, which allow you to predeclare a
 143 variables or subroutines within a particular I<file> rather than
 144 just a block.  Such declarations are effective for the entire file
 145 for which they were declared.  You cannot rescind them with C<no
 146 vars> or C<no subs>.
 147
 148 The following pragmas are defined (and have their own documentation).
 149
 150 =over 12
 151
 152 =cut
 153
 154 print $out $_ for sort @pragma;
 155
 156 print $out <<'=cut';
 157
 158 =back
 159
 160 =head2 Standard Modules
 161
 162 Standard, bundled modules are all expected to behave in a well-defined
 163 manner with respect to namespace pollution because they use the
 164 Exporter module.  See their own documentation for details.
 165
 166 It's possible that not all modules listed below are installed on your
 167 system. For example, the GDBM_File module will not be installed if you
 168 don't have the gdbm library.
 169
 170 =over 12
 171
 172 =cut
 173
 174 print $out $_ for sort @mod;
 175
 176 print $out <<'=cut', "=cut\n";
 177
 178 =back
 179
 180 To find out I<all> modules installed on your system, including
 181 those without documentation or outside the standard release,
 182 just use the following command (under the default win32 shell,
 183 double quotes should be used instead of single quotes).
 184
 185     % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
 186       'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
 187       no_chdir => 1 }, @INC'
 188
 189 (The -T is here to prevent '.' from being listed in @INC.)
 190 They should all have their own documentation installed and accessible
 191 via your system man(1) command.  If you do not have a B<find>
 192 program, you can use the Perl B<find2perl> program instead, which
 193 generates Perl code as output you can run through perl.  If you
 194 have a B<man> program but it doesn't find your modules, you'll have
 195 to fix your manpath.  See L<perl> for details.  If you have no
 196 system B<man> command, you might try the B<perldoc> program.
 197
 198 Note also that the command C<perldoc perllocal> gives you a (possibly
 199 incomplete) list of the modules that have been further installed on
 200 your system. (The perllocal.pod file is updated by the standard MakeMaker
 201 install process.)
 202
 203 =head2 Extension Modules
 204
 205 Extension modules are written in C (or a mix of Perl and C).  They
 206 are usually dynamically loaded into Perl if and when you need them,
 207 but may also be linked in statically.  Supported extension modules
 208 include Socket, Fcntl, and POSIX.
 209
 210 Many popular C extension modules do not come bundled (at least, not
 211 completely) due to their sizes, volatility, or simply lack of time
 212 for adequate testing and configuration across the multitude of
 213 platforms on which Perl was beta-tested.  You are encouraged to
 214 look for them on CPAN (described below), or using web search engines
 215 like Alta Vista or Google.
 216
 217 =head1 CPAN
 218
 219 CPAN stands for Comprehensive Perl Archive Network; it's a globally
 220 replicated trove of Perl materials, including documentation, style
 221 guides, tricks and traps, alternate ports to non-Unix systems and
 222 occasional binary distributions for these.   Search engines for
 223 CPAN can be found at http://www.cpan.org/
 224
 225 Most importantly, CPAN includes around a thousand unbundled modules,
 226 some of which require a C compiler to build.  Major categories of
 227 modules are:
 228
 229 =over
 230
 231 =item *
 232
 233 Language Extensions and Documentation Tools
 234
 235 =item *
 236
 237 Development Support
 238
 239 =item *
 240
 241 Operating System Interfaces
 242
 243 =item *
 244
 245 Networking, Device Control (modems) and InterProcess Communication
 246
 247 =item *
 248
 249 Data Types and Data Type Utilities
 250
 251 =item *
 252
 253 Database Interfaces
 254
 255 =item *
 256
 257 User Interfaces
 258
 259 =item *
 260
 261 Interfaces to / Emulations of Other Programming Languages
 262
 263 =item *
 264
 265 File Names, File Systems and File Locking (see also File Handles)
 266
 267 =item *
 268
 269 String Processing, Language Text Processing, Parsing, and Searching
 270
 271 =item *
 272
 273 Option, Argument, Parameter, and Configuration File Processing
 274
 275 =item *
 276
 277 Internationalization and Locale
 278
 279 =item *
 280
 281 Authentication, Security, and Encryption
 282
 283 =item *
 284
 285 World Wide Web, HTML, HTTP, CGI, MIME
 286
 287 =item *
 288
 289 Server and Daemon Utilities
 290
 291 =item *
 292
 293 Archiving and Compression
 294
 295 =item *
 296
 297 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
 298
 299 =item *
 300
 301 Mail and Usenet News
 302
 303 =item *
 304
 305 Control Flow Utilities (callbacks and exceptions etc)
 306
 307 =item *
 308
 309 File Handle and Input/Output Stream Utilities
 310
 311 =item *
 312
 313 Miscellaneous Modules
 314
 315 =back
 316
 317 The list of the registered CPAN sites follows.
 318 Please note that the sorting order is alphabetical on fields:
 319
 320 Continent
 321    |
 322    |-->Country
 323          |
 324          |-->[state/province]
 325                    |
 326                    |-->ftp
 327                    |
 328                    |-->[http]
 329
 330 and thus the North American servers happen to be listed between the
 331 European and the South American sites.
 332
 333 Registered CPAN sites
 334
 335 =for maintainers
 336 Generated by Porting/make_modlib_cpan.pl
 337
 338 =head2 Africa
 339
 340 =over 4
 341
 342 =item South Africa
 343
 344   http://mirror.is.co.za/pub/cpan/
 345   ftp://ftp.is.co.za/pub/cpan/
 346   http://cpan.mirror.ac.za/
 347   ftp://cpan.mirror.ac.za/
 348   http://cpan.saix.net/
 349   ftp://ftp.saix.net/pub/CPAN/
 350   http://ftp.wa.co.za/pub/CPAN/
 351   ftp://ftp.wa.co.za/pub/CPAN/
 352
 353 =item Uganda
 354
 355   http://mirror.ucu.ac.ug/cpan/
 356
 357 =item Zimbabwe
 358
 359   http://mirror.zol.co.zw/CPAN/
 360   ftp://mirror.zol.co.zw/CPAN/
 361
 362 =back
 363
 364 =head2 Asia
 365
 366 =over 4
 367
 368 =item Bangladesh
 369
 370   http://mirror.dhakacom.com/CPAN/
 371   ftp://mirror.dhakacom.com/CPAN/
 372
 373 =item China
 374
 375   http://cpan.communilink.net/
 376   http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
 377   ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
 378   http://mirrors.hust.edu.cn/CPAN/
 379   http://mirrors.neusoft.edu.cn/cpan/
 380   http://mirror.lzu.edu.cn/CPAN/
 381   http://mirrors.163.com/cpan/
 382   http://mirrors.sohu.com/CPAN/
 383   http://mirrors.ustc.edu.cn/CPAN/
 384   ftp://mirrors.ustc.edu.cn/CPAN/
 385   http://mirrors.xmu.edu.cn/CPAN/
 386   ftp://mirrors.xmu.edu.cn/CPAN/
 387   http://mirrors.zju.edu.cn/CPAN/
 388
 389 =item India
 390
 391   http://cpan.excellmedia.net/
 392   http://perlmirror.indialinks.com/
 393
 394 =item Indonesia
 395
 396   http://kambing.ui.ac.id/cpan/
 397   http://cpan.pesat.net.id/
 398   http://mirror.poliwangi.ac.id/CPAN/
 399   http://kartolo.sby.datautama.net.id/CPAN/
 400   http://mirror.wanxp.id/cpan/
 401
 402 =item Iran
 403
 404   http://mirror.yazd.ac.ir/cpan/
 405
 406 =item Israel
 407
 408   http://biocourse.weizmann.ac.il/CPAN/
 409
 410 =item Japan
 411
 412   http://ftp.jaist.ac.jp/pub/CPAN/
 413   ftp://ftp.jaist.ac.jp/pub/CPAN/
 414   http://mirror.jre655.com/CPAN/
 415   ftp://mirror.jre655.com/CPAN/
 416   ftp://ftp.kddilabs.jp/CPAN/
 417   http://ftp.nara.wide.ad.jp/pub/CPAN/
 418   ftp://ftp.nara.wide.ad.jp/pub/CPAN/
 419   http://ftp.riken.jp/lang/CPAN/
 420   ftp://ftp.riken.jp/lang/CPAN/
 421   ftp://ftp.u-aizu.ac.jp/pub/CPAN/
 422   http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
 423   ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
 424
 425 =item Kazakhstan
 426
 427   http://mirror.neolabs.kz/CPAN/
 428   ftp://mirror.neolabs.kz/CPAN/
 429
 430 =item Philippines
 431
 432   http://mirror.pregi.net/CPAN/
 433   ftp://mirror.pregi.net/CPAN/
 434   http://mirror.rise.ph/cpan/
 435   ftp://mirror.rise.ph/cpan/
 436
 437 =item Qatar
 438
 439   http://mirror.qnren.qa/CPAN/
 440   ftp://mirror.qnren.qa/CPAN/
 441
 442 =item Republic of Korea
 443
 444   http://cpan.mirror.cdnetworks.com/
 445   ftp://cpan.mirror.cdnetworks.com/CPAN/
 446   http://ftp.kaist.ac.kr/pub/CPAN/
 447   ftp://ftp.kaist.ac.kr/CPAN/
 448   http://ftp.kr.freebsd.org/pub/CPAN/
 449   ftp://ftp.kr.freebsd.org/pub/CPAN/
 450   http://mirror.navercorp.com/CPAN/
 451   http://ftp.neowiz.com/CPAN/
 452   ftp://ftp.neowiz.com/CPAN/
 453
 454 =item Singapore
 455
 456   http://cpan.mirror.choon.net/
 457   http://mirror.0x.sg/CPAN/
 458   ftp://mirror.0x.sg/CPAN/
 459
 460 =item Taiwan
 461
 462   http://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
 463   ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
 464   http://cpan.stu.edu.tw/
 465   ftp://ftp.stu.edu.tw/CPAN/
 466   http://ftp.yzu.edu.tw/CPAN/
 467   ftp://ftp.yzu.edu.tw/CPAN/
 468   http://cpan.nctu.edu.tw/
 469   ftp://cpan.nctu.edu.tw/
 470   http://ftp.ubuntu-tw.org/mirror/CPAN/
 471   ftp://ftp.ubuntu-tw.org/mirror/CPAN/
 472
 473 =item Turkey
 474
 475   http://cpan.ulak.net.tr/
 476   ftp://ftp.ulak.net.tr/pub/perl/CPAN/
 477   http://mirror.vit.com.tr/mirror/CPAN/
 478   ftp://mirror.vit.com.tr/CPAN/
 479
 480 =item Viet Nam
 481
 482   http://mirrors.digipower.vn/CPAN/
 483   http://mirror.downloadvn.com/cpan/
 484   http://mirrors.vinahost.vn/CPAN/
 485
 486 =back
 487
 488 =head2 Europe
 489
 490 =over 4
 491
 492 =item Austria
 493
 494   http://cpan.inode.at/
 495   ftp://cpan.inode.at/
 496   http://mirror.easyname.at/cpan/
 497   ftp://mirror.easyname.at/cpan/
 498   http://gd.tuwien.ac.at/languages/perl/CPAN/
 499   ftp://gd.tuwien.ac.at/pub/CPAN/
 500
 501 =item Belarus
 502
 503   http://ftp.byfly.by/pub/CPAN/
 504   ftp://ftp.byfly.by/pub/CPAN/
 505   http://mirror.datacenter.by/pub/CPAN/
 506   ftp://mirror.datacenter.by/pub/CPAN/
 507
 508 =item Belgium
 509
 510   http://ftp.belnet.be/ftp.cpan.org/
 511   ftp://ftp.belnet.be/mirror/ftp.cpan.org/
 512   http://cpan.cu.be/
 513   http://lib.ugent.be/CPAN/
 514   http://cpan.weepeetelecom.be/
 515
 516 =item Bosnia and Herzegovina
 517
 518   http://cpan.mirror.ba/
 519   ftp://ftp.mirror.ba/CPAN/
 520
 521 =item Bulgaria
 522
 523   http://mirrors.neterra.net/CPAN/
 524   ftp://mirrors.neterra.net/CPAN/
 525   http://mirrors.netix.net/CPAN/
 526   ftp://mirrors.netix.net/CPAN/
 527
 528 =item Croatia
 529
 530   http://ftp.carnet.hr/pub/CPAN/
 531   ftp://ftp.carnet.hr/pub/CPAN/
 532
 533 =item Czech Republic
 534
 535   http://mirror.dkm.cz/cpan/
 536   ftp://mirror.dkm.cz/cpan/
 537   ftp://ftp.fi.muni.cz/pub/CPAN/
 538   http://mirrors.nic.cz/CPAN/
 539   ftp://mirrors.nic.cz/pub/CPAN/
 540   http://cpan.mirror.vutbr.cz/
 541   ftp://mirror.vutbr.cz/cpan/
 542
 543 =item Denmark
 544
 545   http://www.cpan.dk/
 546   http://mirrors.dotsrc.org/cpan/
 547   ftp://mirrors.dotsrc.org/cpan/
 548
 549 =item Finland
 550
 551   ftp://ftp.funet.fi/pub/languages/perl/CPAN/
 552
 553 =item France
 554
 555   http://ftp.ciril.fr/pub/cpan/
 556   ftp://ftp.ciril.fr/pub/cpan/
 557   http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
 558   ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
 559   http://ftp.lip6.fr/pub/perl/CPAN/
 560   ftp://ftp.lip6.fr/pub/perl/CPAN/
 561   http://mirror.ibcp.fr/pub/CPAN/
 562   ftp://ftp.oleane.net/pub/CPAN/
 563   http://cpan.mirrors.ovh.net/ftp.cpan.org/
 564   ftp://cpan.mirrors.ovh.net/ftp.cpan.org/
 565   http://cpan.enstimac.fr/
 566
 567 =item Germany
 568
 569   http://mirror.23media.de/cpan/
 570   ftp://mirror.23media.de/cpan/
 571   http://artfiles.org/cpan.org/
 572   ftp://artfiles.org/cpan.org/
 573   http://mirror.bibleonline.ru/cpan/
 574   http://mirror.checkdomain.de/CPAN/
 575   ftp://mirror.checkdomain.de/CPAN/
 576   http://cpan.noris.de/
 577   http://mirror.de.leaseweb.net/CPAN/
 578   ftp://mirror.de.leaseweb.net/CPAN/
 579   http://cpan.mirror.euserv.net/
 580   ftp://mirror.euserv.net/cpan/
 581   http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
 582   ftp://mirror.fraunhofer.de/CPAN/
 583   ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
 584   http://ftp.hosteurope.de/pub/CPAN/
 585   ftp://ftp.hosteurope.de/pub/CPAN/
 586   ftp://ftp.fu-berlin.de/unix/languages/perl/
 587   http://ftp.gwdg.de/pub/languages/perl/CPAN/
 588   ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
 589   http://ftp.hawo.stw.uni-erlangen.de/CPAN/
 590   ftp://ftp.hawo.stw.uni-erlangen.de/CPAN/
 591   http://cpan.mirror.iphh.net/
 592   ftp://cpan.mirror.iphh.net/pub/CPAN/
 593   ftp://ftp.mpi-inf.mpg.de/pub/perl/CPAN/
 594   http://cpan.netbet.org/
 595   http://mirror.netcologne.de/cpan/
 596   ftp://mirror.netcologne.de/cpan/
 597   ftp://mirror.petamem.com/CPAN/
 598   http://www.planet-elektronik.de/CPAN/
 599   http://ftp.halifax.rwth-aachen.de/cpan/
 600   ftp://ftp.halifax.rwth-aachen.de/cpan/
 601   http://mirror.softaculous.com/cpan/
 602   http://ftp.u-tx.net/CPAN/
 603   ftp://ftp.u-tx.net/CPAN/
 604   http://mirror.reismil.ch/CPAN/
 605
 606 =item Greece
 607
 608   http://cpan.cc.uoc.gr/mirrors/CPAN/
 609   ftp://ftp.cc.uoc.gr/mirrors/CPAN/
 610   http://ftp.ntua.gr/pub/lang/perl/
 611   ftp://ftp.ntua.gr/pub/lang/perl/
 612
 613 =item Hungary
 614
 615   http://mirror.met.hu/CPAN/
 616
 617 =item Ireland
 618
 619   http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
 620   ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
 621
 622 =item Italy
 623
 624   http://bo.mirror.garr.it/mirrors/CPAN/
 625   ftp://ftp.eutelia.it/CPAN_Mirror/
 626   http://cpan.panu.it/
 627   ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
 628   http://cpan.muzzy.it/
 629
 630 =item Latvia
 631
 632   http://kvin.lv/pub/CPAN/
 633
 634 =item Lithuania
 635
 636   http://ftp.litnet.lt/pub/CPAN/
 637   ftp://ftp.litnet.lt/pub/CPAN/
 638
 639 =item Moldova
 640
 641   http://mirror.as43289.net/pub/CPAN/
 642   ftp://mirror.as43289.net/pub/CPAN/
 643
 644 =item Netherlands
 645
 646   http://cpan.cs.uu.nl/
 647   ftp://ftp.cs.uu.nl/pub/CPAN/
 648   http://mirror.nl.leaseweb.net/CPAN/
 649   ftp://mirror.nl.leaseweb.net/CPAN/
 650   http://ftp.nluug.nl/languages/perl/CPAN/
 651   ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
 652   http://mirror.transip.net/CPAN/
 653   ftp://mirror.transip.net/CPAN/
 654   http://cpan.mirror.triple-it.nl/
 655   http://ftp.tudelft.nl/cpan/
 656   ftp://ftp.tudelft.nl/pub/CPAN/
 657   ftp://download.xs4all.nl/pub/mirror/CPAN/
 658
 659 =item Norway
 660
 661   http://cpan.uib.no/
 662   ftp://cpan.uib.no/pub/CPAN/
 663   ftp://ftp.uninett.no/pub/languages/perl/CPAN/
 664   http://cpan.vianett.no/
 665
 666 =item Poland
 667
 668   http://ftp.agh.edu.pl/CPAN/
 669   ftp://ftp.agh.edu.pl/CPAN/
 670   http://ftp.piotrkosoft.net/pub/mirrors/CPAN/
 671   ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
 672   ftp://ftp.ps.pl/pub/CPAN/
 673   http://sunsite.icm.edu.pl/pub/CPAN/
 674   ftp://sunsite.icm.edu.pl/pub/CPAN/
 675
 676 =item Portugal
 677
 678   http://cpan.dcc.fc.up.pt/
 679   http://mirrors.fe.up.pt/pub/CPAN/
 680   http://cpan.perl-hackers.net/
 681   http://cpan.perl.pt/
 682
 683 =item Romania
 684
 685   http://mirrors.hostingromania.ro/cpan.org/
 686   ftp://ftp.lug.ro/CPAN/
 687   http://mirrors.m247.ro/CPAN/
 688   http://mirrors.evowise.com/CPAN/
 689   http://mirrors.teentelecom.net/CPAN/
 690   ftp://mirrors.teentelecom.net/CPAN/
 691   http://mirrors.xservers.ro/CPAN/
 692
 693 =item Russian Federation
 694
 695   ftp://ftp.aha.ru/CPAN/
 696   http://cpan.rinet.ru/
 697   ftp://cpan.rinet.ru/pub/mirror/CPAN/
 698   http://cpan-mirror.rbc.ru/pub/CPAN/
 699   http://mirror.rol.ru/CPAN/
 700   http://cpan.uni-altai.ru/
 701   http://cpan.webdesk.ru/
 702   ftp://cpan.webdesk.ru/cpan/
 703   http://mirror.yandex.ru/mirrors/cpan/
 704   ftp://mirror.yandex.ru/mirrors/cpan/
 705
 706 =item Serbia
 707
 708   http://mirror.sbb.rs/CPAN/
 709   ftp://mirror.sbb.rs/CPAN/
 710
 711 =item Slovakia
 712
 713   http://cpan.lnx.sk/
 714   http://tux.rainside.sk/CPAN/
 715   ftp://tux.rainside.sk/CPAN/
 716
 717 =item Slovenia
 718
 719   http://ftp.arnes.si/software/perl/CPAN/
 720   ftp://ftp.arnes.si/software/perl/CPAN/
 721
 722 =item Spain
 723
 724   http://mirrors.evowise.com/CPAN/
 725   http://osl.ugr.es/CPAN/
 726   http://ftp.rediris.es/mirror/CPAN/
 727   ftp://ftp.rediris.es/mirror/CPAN/
 728
 729 =item Sweden
 730
 731   http://ftp.acc.umu.se/mirror/CPAN/
 732   ftp://ftp.acc.umu.se/mirror/CPAN/
 733
 734 =item Switzerland
 735
 736   http://www.pirbot.com/mirrors/cpan/
 737   http://mirror.switch.ch/ftp/mirror/CPAN/
 738   ftp://mirror.switch.ch/mirror/CPAN/
 739
 740 =item Ukraine
 741
 742   http://cpan.ip-connect.vn.ua/
 743   ftp://cpan.ip-connect.vn.ua/mirror/cpan/
 744
 745 =item United Kingdom
 746
 747   http://cpan.mirror.anlx.net/
 748   ftp://ftp.mirror.anlx.net/CPAN/
 749   http://mirror.bytemark.co.uk/CPAN/
 750   ftp://mirror.bytemark.co.uk/CPAN/
 751   http://mirrors.coreix.net/CPAN/
 752   http://cpan.etla.org/
 753   ftp://cpan.etla.org/pub/CPAN/
 754   http://cpan.cpantesters.org/
 755   http://mirror.sax.uk.as61049.net/CPAN/
 756   http://mirror.sov.uk.goscomb.net/CPAN/
 757   http://www.mirrorservice.org/sites/cpan.perl.org/CPAN/
 758   ftp://ftp.mirrorservice.org/sites/cpan.perl.org/CPAN/
 759   http://mirror.ox.ac.uk/sites/www.cpan.org/
 760   ftp://mirror.ox.ac.uk/sites/www.cpan.org/
 761   http://ftp.ticklers.org/pub/CPAN/
 762   ftp://ftp.ticklers.org/pub/CPAN/
 763   http://cpan.mirrors.uk2.net/
 764   ftp://mirrors.uk2.net/pub/CPAN/
 765   http://mirror.ukhost4u.com/CPAN/
 766
 767 =back
 768
 769 =head2 North America
 770
 771 =over 4
 772
 773 =item Canada
 774
 775   http://CPAN.mirror.rafal.ca/
 776   ftp://CPAN.mirror.rafal.ca/pub/CPAN/
 777   http://mirror.csclub.uwaterloo.ca/CPAN/
 778   ftp://mirror.csclub.uwaterloo.ca/CPAN/
 779   http://mirrors.gossamer-threads.com/CPAN/
 780   http://mirror.its.dal.ca/cpan/
 781   ftp://mirror.its.dal.ca/cpan/
 782   ftp://ftp.ottix.net/pub/CPAN/
 783
 784 =item Costa Rica
 785
 786   http://mirrors.ucr.ac.cr/CPAN/
 787
 788 =item Mexico
 789
 790   http://www.msg.com.mx/CPAN/
 791   ftp://ftp.msg.com.mx/pub/CPAN/
 792
 793 =item United States
 794
 795 =over 8
 796
 797 =item Alabama
 798
 799   http://mirror.teklinks.com/CPAN/
 800
 801 =item Arizona
 802
 803   http://mirror.n5tech.com/CPAN/
 804   http://mirrors.namecheap.com/CPAN/
 805   ftp://mirrors.namecheap.com/CPAN/
 806
 807 =item California
 808
 809   http://cpan.develooper.com/
 810   http://httpupdate127.cpanel.net/CPAN/
 811   http://mirrors.sonic.net/cpan/
 812   ftp://mirrors.sonic.net/cpan/
 813   http://www.perl.com/CPAN/
 814   http://cpan.yimg.com/
 815
 816 =item Idaho
 817
 818   http://mirrors.syringanetworks.net/CPAN/
 819   ftp://mirrors.syringanetworks.net/CPAN/
 820
 821 =item Illinois
 822
 823   http://cpan.mirrors.hoobly.com/
 824   http://mirror.team-cymru.org/CPAN/
 825   ftp://mirror.team-cymru.org/CPAN/
 826
 827 =item Indiana
 828
 829   http://cpan.netnitco.net/
 830   ftp://cpan.netnitco.net/pub/mirrors/CPAN/
 831   ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
 832
 833 =item Kansas
 834
 835   http://mirrors.concertpass.com/cpan/
 836
 837 =item Massachusetts
 838
 839   http://mirrors.ccs.neu.edu/CPAN/
 840
 841 =item Michigan
 842
 843   http://cpan.cse.msu.edu/
 844   ftp://cpan.cse.msu.edu/
 845   http://httpupdate118.cpanel.net/CPAN/
 846   http://mirrors-usa.go-parts.com/cpan/
 847   http://ftp.wayne.edu/CPAN/
 848   ftp://ftp.wayne.edu/CPAN/
 849
 850 =item New Hampshire
 851
 852   http://mirror.metrocast.net/cpan/
 853
 854 =item New Jersey
 855
 856   http://mirror.datapipe.net/CPAN/
 857   ftp://mirror.datapipe.net/pub/CPAN/
 858   http://www.hoovism.com/CPAN/
 859   ftp://ftp.hoovism.com/CPAN/
 860   http://cpan.mirror.nac.net/
 861
 862 =item New York
 863
 864   http://mirror.cc.columbia.edu/pub/software/cpan/
 865   ftp://mirror.cc.columbia.edu/pub/software/cpan/
 866   http://cpan.belfry.net/
 867   http://cpan.erlbaum.net/
 868   ftp://cpan.erlbaum.net/CPAN/
 869   http://cpan.hexten.net/
 870   ftp://cpan.hexten.net/
 871   http://mirror.nyi.net/CPAN/
 872   ftp://mirror.nyi.net/pub/CPAN/
 873   http://noodle.portalus.net/CPAN/
 874   ftp://noodle.portalus.net/CPAN/
 875   http://mirrors.rit.edu/CPAN/
 876   ftp://mirrors.rit.edu/CPAN/
 877
 878 =item North Carolina
 879
 880   http://httpupdate140.cpanel.net/CPAN/
 881   http://mirrors.ibiblio.org/CPAN/
 882
 883 =item Oregon
 884
 885   http://ftp.osuosl.org/pub/CPAN/
 886   ftp://ftp.osuosl.org/pub/CPAN/
 887   http://mirror.uoregon.edu/CPAN/
 888
 889 =item Pennsylvania
 890
 891   http://cpan.pair.com/
 892   ftp://cpan.pair.com/pub/CPAN/
 893   http://cpan.mirrors.ionfish.org/
 894
 895 =item South Carolina
 896
 897   http://cpan.mirror.clemson.edu/
 898
 899 =item Texas
 900
 901   http://mirror.uta.edu/CPAN/
 902
 903 =item Utah
 904
 905   http://cpan.cs.utah.edu/
 906   ftp://cpan.cs.utah.edu/CPAN/
 907   ftp://mirror.xmission.com/CPAN/
 908
 909 =item Virginia
 910
 911   http://mirror.cogentco.com/pub/CPAN/
 912   ftp://mirror.cogentco.com/pub/CPAN/
 913   http://mirror.jmu.edu/pub/CPAN/
 914   ftp://mirror.jmu.edu/pub/CPAN/
 915   http://mirror.us.leaseweb.net/CPAN/
 916   ftp://mirror.us.leaseweb.net/CPAN/
 917
 918 =item Washington
 919
 920   http://cpan.llarian.net/
 921   ftp://cpan.llarian.net/pub/CPAN/
 922
 923 =item Wisconsin
 924
 925   http://cpan.mirrors.tds.net/
 926   ftp://cpan.mirrors.tds.net/pub/CPAN/
 927
 928 =back
 929
 930 =back
 931
 932 =head2 Oceania
 933
 934 =over 4
 935
 936 =item Australia
 937
 938   http://mirror.as24220.net/pub/cpan/
 939   ftp://mirror.as24220.net/pub/cpan/
 940   http://cpan.mirrors.ilisys.com.au/
 941   http://cpan.mirror.digitalpacific.com.au/
 942   ftp://mirror.internode.on.net/pub/cpan/
 943   http://mirror.optusnet.com.au/CPAN/
 944   http://cpan.mirror.serversaustralia.com.au/
 945   http://cpan.uberglobalmirror.com/
 946   http://mirror.waia.asn.au/pub/cpan/
 947
 948 =item New Caledonia
 949
 950   http://cpan.lagoon.nc/pub/CPAN/
 951   ftp://cpan.lagoon.nc/pub/CPAN/
 952   http://cpan.nautile.nc/CPAN/
 953   ftp://cpan.nautile.nc/CPAN/
 954
 955 =item New Zealand
 956
 957   ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
 958   http://cpan.catalyst.net.nz/CPAN/
 959   ftp://cpan.catalyst.net.nz/pub/CPAN/
 960   http://cpan.inspire.net.nz/
 961   ftp://cpan.inspire.net.nz/cpan/
 962   http://mirror.webtastix.net/CPAN/
 963   ftp://mirror.webtastix.net/CPAN/
 964
 965 =back
 966
 967 =head2 South America
 968
 969 =over 4
 970
 971 =item Argentina
 972
 973   http://cpan.mmgdesigns.com.ar/
 974
 975 =item Brazil
 976
 977   http://cpan.kinghost.net/
 978   http://linorg.usp.br/CPAN/
 979   http://mirror.nbtelecom.com.br/CPAN/
 980
 981 =item Chile
 982
 983   http://cpan.dcc.uchile.cl/
 984   ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
 985
 986 =back
 987
 988 =head2 RSYNC Mirrors
 989
 990                 rsync://ftp.is.co.za/IS-Mirror/ftp.cpan.org/
 991                 rsync://mirror.ac.za/CPAN/
 992                 rsync://mirror.zol.co.zw/CPAN/
 993                 rsync://mirror.dhakacom.com/CPAN/
 994                 rsync://mirrors.ustc.edu.cn/CPAN/
 995                 rsync://mirrors.xmu.edu.cn/CPAN/
 996                 rsync://kambing.ui.ac.id/CPAN/
 997                 rsync://ftp.jaist.ac.jp/pub/CPAN/
 998                 rsync://mirror.jre655.com/CPAN/
 999                 rsync://ftp.kddilabs.jp/cpan/
1000                 rsync://ftp.nara.wide.ad.jp/cpan/
1001                 rsync://ftp.riken.jp/cpan/
1002                 rsync://mirror.neolabs.kz/CPAN/
1003                 rsync://mirror.qnren.qa/CPAN/
1004                 rsync://ftp.neowiz.com/CPAN/
1005                 rsync://mirror.0x.sg/CPAN/
1006                 rsync://ftp.yzu.edu.tw/pub/CPAN/
1007                 rsync://ftp.ubuntu-tw.org/CPAN/
1008                 rsync://mirrors.digipower.vn/CPAN/
1009                 rsync://cpan.inode.at/CPAN/
1010                 rsync://ftp.byfly.by/CPAN/
1011                 rsync://mirror.datacenter.by/CPAN/
1012                 rsync://ftp.belnet.be/cpan/
1013                 rsync://cpan.mirror.ba/CPAN/
1014                 rsync://mirrors.neterra.net/CPAN/
1015                 rsync://mirrors.netix.net/CPAN/
1016                 rsync://mirror.dkm.cz/cpan/
1017                 rsync://mirrors.nic.cz/CPAN/
1018                 rsync://cpan.mirror.vutbr.cz/cpan/
1019                 rsync://rsync.nic.funet.fi/CPAN/
1020                 rsync://ftp.ciril.fr/pub/cpan/
1021                 rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
1022                 rsync://cpan.mirrors.ovh.net/CPAN/
1023                 rsync://mirror.de.leaseweb.net/CPAN/
1024                 rsync://mirror.euserv.net/cpan/
1025                 rsync://ftp-stud.hs-esslingen.de/CPAN/
1026                 rsync://ftp.gwdg.de/pub/languages/perl/CPAN/
1027                 rsync://ftp.hawo.stw.uni-erlangen.de/CPAN/
1028                 rsync://cpan.mirror.iphh.net/CPAN/
1029                 rsync://mirror.netcologne.de/cpan/
1030                 rsync://ftp.halifax.rwth-aachen.de/cpan/
1031                 rsync://ftp.ntua.gr/CPAN/
1032                 rsync://mirror.met.hu/CPAN/
1033                 rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
1034                 rsync://rsync.panu.it/CPAN/
1035                 rsync://mirror.as43289.net/CPAN/
1036                 rsync://rsync.cs.uu.nl/CPAN/
1037                 rsync://mirror.nl.leaseweb.net/CPAN/
1038                 rsync://ftp.nluug.nl/CPAN/
1039                 rsync://mirror.transip.net/CPAN/
1040                 rsync://cpan.uib.no/cpan/
1041                 rsync://cpan.vianett.no/CPAN/
1042                 rsync://cpan.perl-hackers.net/CPAN/
1043                 rsync://cpan.perl.pt/cpan/
1044                 rsync://mirrors.m247.ro/CPAN/
1045                 rsync://mirrors.teentelecom.net/CPAN/
1046                 rsync://cpan.webdesk.ru/CPAN/
1047                 rsync://mirror.yandex.ru/mirrors/cpan/
1048                 rsync://mirror.sbb.rs/CPAN/
1049                 rsync://ftp.acc.umu.se/mirror/CPAN/
1050                 rsync://rsync.pirbot.com/ftp/cpan/
1051                 rsync://cpan.ip-connect.vn.ua/CPAN/
1052                 rsync://rsync.mirror.anlx.net/CPAN/
1053                 rsync://mirror.bytemark.co.uk/CPAN/
1054                 rsync://mirror.sax.uk.as61049.net/CPAN/
1055                 rsync://rsync.mirrorservice.org/cpan.perl.org/CPAN/
1056                 rsync://ftp.ticklers.org/CPAN/
1057                 rsync://mirrors.uk2.net/CPAN/
1058                 rsync://CPAN.mirror.rafal.ca/CPAN/
1059                 rsync://mirror.csclub.uwaterloo.ca/CPAN/
1060                 rsync://mirrors.namecheap.com/CPAN/
1061                 rsync://mirrors.syringanetworks.net/CPAN/
1062                 rsync://mirror.team-cymru.org/CPAN/
1063                 rsync://debian.cse.msu.edu/cpan/
1064                 rsync://mirrors-usa.go-parts.com/mirrors/cpan/
1065                 rsync://rsync.hoovism.com/CPAN/
1066                 rsync://mirror.cc.columbia.edu/cpan/
1067                 rsync://noodle.portalus.net/CPAN/
1068                 rsync://mirrors.rit.edu/cpan/
1069                 rsync://mirrors.ibiblio.org/CPAN/
1070                 rsync://cpan.pair.com/CPAN/
1071                 rsync://cpan.cs.utah.edu/CPAN/
1072                 rsync://mirror.cogentco.com/CPAN/
1073                 rsync://mirror.jmu.edu/CPAN/
1074                 rsync://mirror.us.leaseweb.net/CPAN/
1075                 rsync://cpan.mirror.digitalpacific.com.au/cpan/
1076                 rsync://mirror.internode.on.net/cpan/
1077                 rsync://uberglobalmirror.com/cpan/
1078                 rsync://cpan.lagoon.nc/cpan/
1079                 rsync://mirrors.mmgdesigns.com.ar/CPAN/
1080
1081
1082 For an up-to-date listing of CPAN sites,
1083 see L<http://www.cpan.org/SITES> or L<ftp://www.cpan.org/SITES>.
1084
1085 =head1 Modules: Creation, Use, and Abuse
1086
1087 (The following section is borrowed directly from Tim Bunce's modules
1088 file, available at your nearest CPAN site.)
1089
1090 Perl implements a class using a package, but the presence of a
1091 package doesn't imply the presence of a class.  A package is just a
1092 namespace.  A class is a package that provides subroutines that can be
1093 used as methods.  A method is just a subroutine that expects, as its
1094 first argument, either the name of a package (for "static" methods),
1095 or a reference to something (for "virtual" methods).
1096
1097 A module is a file that (by convention) provides a class of the same
1098 name (sans the .pm), plus an import method in that class that can be
1099 called to fetch exported symbols.  This module may implement some of
1100 its methods by loading dynamic C or C++ objects, but that should be
1101 totally transparent to the user of the module.  Likewise, the module
1102 might set up an AUTOLOAD function to slurp in subroutine definitions on
1103 demand, but this is also transparent.  Only the F<.pm> file is required to
1104 exist.  See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
1105 the AUTOLOAD mechanism.
1106
1107 =head2 Guidelines for Module Creation
1108
1109 =over 4
1110
1111 =item  *
1112
1113 Do similar modules already exist in some form?
1114
1115 If so, please try to reuse the existing modules either in whole or
1116 by inheriting useful features into a new class.  If this is not
1117 practical try to get together with the module authors to work on
1118 extending or enhancing the functionality of the existing modules.
1119 A perfect example is the plethora of packages in perl4 for dealing
1120 with command line options.
1121
1122 If you are writing a module to expand an already existing set of
1123 modules, please coordinate with the author of the package.  It
1124 helps if you follow the same naming scheme and module interaction
1125 scheme as the original author.
1126
1127 =item  *
1128
1129 Try to design the new module to be easy to extend and reuse.
1130
1131 Try to C<use warnings;> (or C<use warnings qw(...);>).
1132 Remember that you can add C<no warnings qw(...);> to individual blocks
1133 of code that need less warnings.
1134
1135 Use blessed references.  Use the two argument form of bless to bless
1136 into the class name given as the first parameter of the constructor,
1137 e.g.,:
1138
1139  sub new {
1140      my $class = shift;
1141      return bless {}, $class;
1142  }
1143
1144 or even this if you'd like it to be used as either a static
1145 or a virtual method.
1146
1147  sub new {
1148      my $self  = shift;
1149      my $class = ref($self) || $self;
1150      return bless {}, $class;
1151  }
1152
1153 Pass arrays as references so more parameters can be added later
1154 (it's also faster).  Convert functions into methods where
1155 appropriate.  Split large methods into smaller more flexible ones.
1156 Inherit methods from other modules if appropriate.
1157
1158 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1159 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1160 Let the objects look after themselves! Generally, avoid hard-wired
1161 class names as far as possible.
1162
1163 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1164 C<< $r->func() >> would work.
1165
1166 Use autosplit so little used or newly added functions won't be a
1167 burden to programs that don't use them. Add test functions to
1168 the module after __END__ either using AutoSplit or by saying:
1169
1170  eval join('',<main::DATA>) || die $@ unless caller();
1171
1172 Does your module pass the 'empty subclass' test? If you say
1173 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1174 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1175 does your application still work if you change:  C<< $obj = YOURCLASS->new(); >>
1176 into: C<< $obj = SUBCLASS->new(); >> ?
1177
1178 Avoid keeping any state information in your packages. It makes it
1179 difficult for multiple other packages to use yours. Keep state
1180 information in objects.
1181
1182 Always use B<-w>.
1183
1184 Try to C<use strict;> (or C<use strict qw(...);>).
1185 Remember that you can add C<no strict qw(...);> to individual blocks
1186 of code that need less strictness.
1187
1188 Always use B<-w>.
1189
1190 Follow the guidelines in L<perlstyle>.
1191
1192 Always use B<-w>.
1193
1194 =item  *
1195
1196 Some simple style guidelines
1197
1198 The perlstyle manual supplied with Perl has many helpful points.
1199
1200 Coding style is a matter of personal taste. Many people evolve their
1201 style over several years as they learn what helps them write and
1202 maintain good code.  Here's one set of assorted suggestions that
1203 seem to be widely used by experienced developers:
1204
1205 Use underscores to separate words.  It is generally easier to read
1206 $var_names_like_this than $VarNamesLikeThis, especially for
1207 non-native speakers of English. It's also a simple rule that works
1208 consistently with VAR_NAMES_LIKE_THIS.
1209
1210 Package/Module names are an exception to this rule. Perl informally
1211 reserves lowercase module names for 'pragma' modules like integer
1212 and strict. Other modules normally begin with a capital letter and
1213 use mixed case with no underscores (need to be short and portable).
1214
1215 You may find it helpful to use letter case to indicate the scope
1216 or nature of a variable. For example:
1217
1218  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1219  $Some_Caps_Here  package-wide global/static
1220  $no_caps_here    function scope my() or local() variables
1221
1222 Function and method names seem to work best as all lowercase.
1223 e.g., C<< $obj->as_string() >>.
1224
1225 You can use a leading underscore to indicate that a variable or
1226 function should not be used outside the package that defined it.
1227
1228 =item  *
1229
1230 Select what to export.
1231
1232 Do NOT export method names!
1233
1234 Do NOT export anything else by default without a good reason!
1235
1236 Exports pollute the namespace of the module user.  If you must
1237 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1238 short or common names to reduce the risk of name clashes.
1239
1240 Generally anything not exported is still accessible from outside the
1241 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1242 syntax.  By convention you can use a leading underscore on names to
1243 indicate informally that they are 'internal' and not for public use.
1244
1245 (It is actually possible to get private functions by saying:
1246 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
1247 directly as a method, because a method must have a name in the symbol
1248 table.)
1249
1250 As a general rule, if the module is trying to be object oriented
1251 then export nothing. If it's just a collection of functions then
1252 @EXPORT_OK anything but use @EXPORT with caution.
1253
1254 =item  *
1255
1256 Select a name for the module.
1257
1258 This name should be as descriptive, accurate, and complete as
1259 possible.  Avoid any risk of ambiguity. Always try to use two or
1260 more whole words.  Generally the name should reflect what is special
1261 about what the module does rather than how it does it.  Please use
1262 nested module names to group informally or categorize a module.
1263 There should be a very good reason for a module not to have a nested name.
1264 Module names should begin with a capital letter.
1265
1266 Having 57 modules all called Sort will not make life easy for anyone
1267 (though having 23 called Sort::Quick is only marginally better :-).
1268 Imagine someone trying to install your module alongside many others.
1269
1270 If you are developing a suite of related modules/classes it's good
1271 practice to use nested classes with a common prefix as this will
1272 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1273 Xyz::Model etc. Use the modules in this list as a naming guide.
1274
1275 If adding a new module to a set, follow the original author's
1276 standards for naming modules and the interface to methods in
1277 those modules.
1278
1279 If developing modules for private internal or project specific use,
1280 that will never be released to the public, then you should ensure
1281 that their names will not clash with any future public module. You
1282 can do this either by using the reserved Local::* category or by
1283 using a category name that includes an underscore like Foo_Corp::*.
1284
1285 To be portable each component of a module name should be limited to
1286 11 characters. If it might be used on MS-DOS then try to ensure each is
1287 unique in the first 8 characters. Nested modules make this easier.
1288
1289 For additional guidance on the naming of modules, please consult:
1290
1291     http://pause.perl.org/pause/query?ACTION=pause_namingmodules
1292
1293 or send mail to the <module-authors@perl.org> mailing list.
1294
1295 =item  *
1296
1297 Have you got it right?
1298
1299 How do you know that you've made the right decisions? Have you
1300 picked an interface design that will cause problems later? Have
1301 you picked the most appropriate name? Do you have any questions?
1302
1303 The best way to know for sure, and pick up many helpful suggestions,
1304 is to ask someone who knows. The <module-authors@perl.org> mailing list
1305 is useful for this purpose; it's also accessible via news interface as
1306 perl.module-authors at nntp.perl.org.
1307
1308 All you need to do is post a short summary of the module, its
1309 purpose and interfaces. A few lines on each of the main methods is
1310 probably enough. (If you post the whole module it might be ignored
1311 by busy people - generally the very people you want to read it!)
1312
1313 Don't worry about posting if you can't say when the module will be
1314 ready - just say so in the message. It might be worth inviting
1315 others to help you, they may be able to complete it for you!
1316
1317 =item  *
1318
1319 README and other Additional Files.
1320
1321 It's well known that software developers usually fully document the
1322 software they write. If, however, the world is in urgent need of
1323 your software and there is not enough time to write the full
1324 documentation please at least provide a README file containing:
1325
1326 =over 10
1327
1328 =item *
1329
1330 A description of the module/package/extension etc.
1331
1332 =item *
1333
1334 A copyright notice - see below.
1335
1336 =item *
1337
1338 Prerequisites - what else you may need to have.
1339
1340 =item *
1341
1342 How to build it - possible changes to Makefile.PL etc.
1343
1344 =item *
1345
1346 How to install it.
1347
1348 =item *
1349
1350 Recent changes in this release, especially incompatibilities
1351
1352 =item *
1353
1354 Changes / enhancements you plan to make in the future.
1355
1356 =back
1357
1358 If the README file seems to be getting too large you may wish to
1359 split out some of the sections into separate files: INSTALL,
1360 Copying, ToDo etc.
1361
1362 =over 4
1363
1364 =item *
1365
1366 Adding a Copyright Notice.
1367
1368 How you choose to license your work is a personal decision.
1369 The general mechanism is to assert your Copyright and then make
1370 a declaration of how others may copy/use/modify your work.
1371
1372 Perl, for example, is supplied with two types of licence: The GNU GPL
1373 and The Artistic Licence (see the files README, Copying, and Artistic,
1374 or L<perlgpl> and L<perlartistic>).  Larry has good reasons for NOT
1375 just using the GNU GPL.
1376
1377 My personal recommendation, out of respect for Larry, Perl, and the
1378 Perl community at large is to state something simply like:
1379
1380  Copyright (c) 1995 Your Name. All rights reserved.
1381  This program is free software; you can redistribute it and/or
1382  modify it under the same terms as Perl itself.
1383
1384 This statement should at least appear in the README file. You may
1385 also wish to include it in a Copying file and your source files.
1386 Remember to include the other words in addition to the Copyright.
1387
1388 =item  *
1389
1390 Give the module a version/issue/release number.
1391
1392 To be fully compatible with the Exporter and MakeMaker modules you
1393 should store your module's version number in a non-my package
1394 variable called $VERSION.  This should be a positive floating point
1395 number with at least two digits after the decimal (i.e., hundredths,
1396 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
1397 See L<Exporter> for details.
1398
1399 It may be handy to add a function or method to retrieve the number.
1400 Use the number in announcements and archive file names when
1401 releasing the module (ModuleName-1.02.tar.Z).
1402 See perldoc ExtUtils::MakeMaker.pm for details.
1403
1404 =item  *
1405
1406 How to release and distribute a module.
1407
1408 If possible, register the module with CPAN. Follow the instructions
1409 and links on:
1410
1411    http://www.cpan.org/modules/04pause.html
1412
1413 and upload to:
1414
1415    http://pause.perl.org/
1416
1417 and notify <modules@perl.org>. This will allow anyone to install
1418 your module using the C<cpan> tool distributed with Perl.
1419
1420 By using the WWW interface you can ask the Upload Server to mirror
1421 your modules from your ftp or WWW site into your own directory on
1422 CPAN!
1423
1424 =item  *
1425
1426 Take care when changing a released module.
1427
1428 Always strive to remain compatible with previous released versions.
1429 Otherwise try to add a mechanism to revert to the
1430 old behavior if people rely on it.  Document incompatible changes.
1431
1432 =back
1433
1434 =back
1435
1436 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1437
1438 =over 4
1439
1440 =item  *
1441
1442 There is no requirement to convert anything.
1443
1444 If it ain't broke, don't fix it! Perl 4 library scripts should
1445 continue to work with no problems. You may need to make some minor
1446 changes (like escaping non-array @'s in double quoted strings) but
1447 there is no need to convert a .pl file into a Module for just that.
1448
1449 =item  *
1450
1451 Consider the implications.
1452
1453 All Perl applications that make use of the script will need to
1454 be changed (slightly) if the script is converted into a module.  Is
1455 it worth it unless you plan to make other changes at the same time?
1456
1457 =item  *
1458
1459 Make the most of the opportunity.
1460
1461 If you are going to convert the script to a module you can use the
1462 opportunity to redesign the interface.  The guidelines for module
1463 creation above include many of the issues you should consider.
1464
1465 =item  *
1466
1467 The pl2pm utility will get you started.
1468
1469 This utility will read *.pl files (given as parameters) and write
1470 corresponding *.pm files. The pl2pm utilities does the following:
1471
1472 =over 10
1473
1474 =item *
1475
1476 Adds the standard Module prologue lines
1477
1478 =item *
1479
1480 Converts package specifiers from ' to ::
1481
1482 =item *
1483
1484 Converts die(...) to croak(...)
1485
1486 =item *
1487
1488 Several other minor changes
1489
1490 =back
1491
1492 Being a mechanical process pl2pm is not bullet proof. The converted
1493 code will need careful checking, especially any package statements.
1494 Don't delete the original .pl file till the new .pm one works!
1495
1496 =back
1497
1498 =head2 Guidelines for Reusing Application Code
1499
1500 =over 4
1501
1502 =item  *
1503
1504 Complete applications rarely belong in the Perl Module Library.
1505
1506 =item  *
1507
1508 Many applications contain some Perl code that could be reused.
1509
1510 Help save the world! Share your code in a form that makes it easy
1511 to reuse.
1512
1513 =item  *
1514
1515 Break-out the reusable code into one or more separate module files.
1516
1517 =item  *
1518
1519 Take the opportunity to reconsider and redesign the interfaces.
1520
1521 =item  *
1522
1523 In some cases the 'application' can then be reduced to a small
1524
1525 fragment of code built on top of the reusable modules. In these cases
1526 the application could invoked as:
1527
1528      % perl -e 'use Module::Name; method(@ARGV)' ...
1529 or
1530      % perl -mModule::Name ...    (in perl5.002 or higher)
1531
1532 =back
1533
1534 =head1 NOTE
1535
1536 Perl does not enforce private and public parts of its modules as you may
1537 have been used to in other languages like C++, Ada, or Modula-17.  Perl
1538 doesn't have an infatuation with enforced privacy.  It would prefer
1539 that you stayed out of its living room because you weren't invited, not
1540 because it has a shotgun.
1541
1542 The module and its user have a contract, part of which is common law,
1543 and part of which is "written".  Part of the common law contract is
1544 that a module doesn't pollute any namespace it wasn't asked to.  The
1545 written contract for the module (A.K.A. documentation) may make other
1546 provisions.  But then you know when you C<use RedefineTheWorld> that
1547 you're redefining the world and willing to take the consequences.
1548
1549 =cut
1550
1551 read_only_bottom_close_and_rename($out);