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