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