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