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