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, <<'CONFIG'; 84=item Config 85 86Access Perl configuration information 87 88CONFIG 89 90print OUT <<'EOF'; 91=for maintainers 92Generated by perlmodlib.PL -- DO NOT EDIT! 93 94=head1 NAME 95 96perlmodlib - constructing new Perl modules and finding existing ones 97 98=head1 THE PERL MODULE LIBRARY 99 100Many modules are included in the Perl distribution. These are described 101below, and all end in F<.pm>. You may discover compiled library 102files (usually ending in F<.so>) or small pieces of modules to be 103autoloaded (ending in F<.al>); these were automatically generated 104by the installation process. You may also discover files in the 105library directory that end in either F<.pl> or F<.ph>. These are 106old libraries supplied so that old programs that use them still 107run. The F<.pl> files will all eventually be converted into standard 108modules, and the F<.ph> files made by B<h2ph> will probably end up 109as extension modules made by B<h2xs>. (Some F<.ph> values may 110already be available through the POSIX, Errno, or Fcntl modules.) 111The B<pl2pm> file in the distribution may help in your conversion, 112but it's just a mechanical process and therefore far from bulletproof. 113 114=head2 Pragmatic Modules 115 116They work somewhat like compiler directives (pragmata) in that they 117tend to affect the compilation of your program, and thus will usually 118work well only when used within a C<use>, or C<no>. Most of these 119are lexically scoped, so an inner BLOCK may countermand them 120by saying: 121 122 no integer; 123 no strict 'refs'; 124 no warnings; 125 126which lasts until the end of that BLOCK. 127 128Some pragmas are lexically scoped--typically those that affect the 129C<$^H> hints variable. Others affect the current package instead, 130like C<use vars> and C<use subs>, which allow you to predeclare a 131variables or subroutines within a particular I<file> rather than 132just a block. Such declarations are effective for the entire file 133for which they were declared. You cannot rescind them with C<no 134vars> or C<no subs>. 135 136The following pragmas are defined (and have their own documentation). 137 138=over 12 139 140EOF 141 142print OUT $_ for (sort @pragma); 143 144print OUT <<EOF; 145=back 146 147=head2 Standard Modules 148 149Standard, bundled modules are all expected to behave in a well-defined 150manner with respect to namespace pollution because they use the 151Exporter module. See their own documentation for details. 152 153It's possible that not all modules listed below are installed on your 154system. For example, the GDBM_File module will not be installed if you 155don't have the gdbm library. 156 157=over 12 158 159EOF 160 161print OUT $_ for (sort @mod); 162 163print OUT <<'EOF'; 164=back 165 166To find out I<all> modules installed on your system, including 167those without documentation or outside the standard release, 168just use the following command (under the default win32 shell, 169double quotes should be used instead of single quotes). 170 171 % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \ 172 'find { wanted => sub { print canonpath $_ if /\.pm\z/ }, 173 no_chdir => 1 }, @INC' 174 175(The -T is here to prevent '.' from being listed in @INC.) 176They should all have their own documentation installed and accessible 177via your system man(1) command. If you do not have a B<find> 178program, you can use the Perl B<find2perl> program instead, which 179generates Perl code as output you can run through perl. If you 180have a B<man> program but it doesn't find your modules, you'll have 181to fix your manpath. See L<perl> for details. If you have no 182system B<man> command, you might try the B<perldoc> program. 183 184Note also that the command C<perldoc perllocal> gives you a (possibly 185incomplete) list of the modules that have been further installed on 186your system. (The perllocal.pod file is updated by the standard MakeMaker 187install process.) 188 189=head2 Extension Modules 190 191Extension modules are written in C (or a mix of Perl and C). They 192are usually dynamically loaded into Perl if and when you need them, 193but may also be linked in statically. Supported extension modules 194include Socket, Fcntl, and POSIX. 195 196Many popular C extension modules do not come bundled (at least, not 197completely) due to their sizes, volatility, or simply lack of time 198for adequate testing and configuration across the multitude of 199platforms on which Perl was beta-tested. You are encouraged to 200look for them on CPAN (described below), or using web search engines 201like Alta Vista or Google. 202 203=head1 CPAN 204 205CPAN stands for Comprehensive Perl Archive Network; it's a globally 206replicated trove of Perl materials, including documentation, style 207guides, tricks and traps, alternate ports to non-Unix systems and 208occasional binary distributions for these. Search engines for 209CPAN can be found at http://www.cpan.org/ 210 211Most importantly, CPAN includes around a thousand unbundled modules, 212some of which require a C compiler to build. Major categories of 213modules are: 214 215=over 216 217=item * 218 219Language Extensions and Documentation Tools 220 221=item * 222 223Development Support 224 225=item * 226 227Operating System Interfaces 228 229=item * 230 231Networking, Device Control (modems) and InterProcess Communication 232 233=item * 234 235Data Types and Data Type Utilities 236 237=item * 238 239Database Interfaces 240 241=item * 242 243User Interfaces 244 245=item * 246 247Interfaces to / Emulations of Other Programming Languages 248 249=item * 250 251File Names, File Systems and File Locking (see also File Handles) 252 253=item * 254 255String Processing, Language Text Processing, Parsing, and Searching 256 257=item * 258 259Option, Argument, Parameter, and Configuration File Processing 260 261=item * 262 263Internationalization and Locale 264 265=item * 266 267Authentication, Security, and Encryption 268 269=item * 270 271World Wide Web, HTML, HTTP, CGI, MIME 272 273=item * 274 275Server and Daemon Utilities 276 277=item * 278 279Archiving and Compression 280 281=item * 282 283Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing 284 285=item * 286 287Mail and Usenet News 288 289=item * 290 291Control Flow Utilities (callbacks and exceptions etc) 292 293=item * 294 295File Handle and Input/Output Stream Utilities 296 297=item * 298 299Miscellaneous Modules 300 301=back 302 303The list of the registered CPAN sites follows. 304Please note that the sorting order is alphabetical on fields: 305 306Continent 307 | 308 |-->Country 309 | 310 |-->[state/province] 311 | 312 |-->ftp 313 | 314 |-->[http] 315 316and thus the North American servers happen to be listed between the 317European and the South American sites. 318 319Registered CPAN sites 320 321=head2 Africa 322 323=over 4 324 325=item South Africa 326 327 http://cpan.mirror.ac.za/ 328 ftp://cpan.mirror.ac.za/ 329 http://mirror.is.co.za/pub/cpan/ 330 ftp://ftp.is.co.za/pub/cpan/ 331 ftp://ftp.saix.net/pub/CPAN/ 332 333=back 334 335=head2 Asia 336 337=over 4 338 339=item Hong Kong 340 341 http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/ 342 ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/ 343 http://mirrors.geoexpat.com/cpan/ 344 345=item India 346 347 http://perlmirror.indialinks.com/ 348 349=item Indonesia 350 351 http://cpan.biz.net.id/ 352 http://komo.vlsm.org/CPAN/ 353 ftp://komo.vlsm.org/CPAN/ 354 http://cpan.pesat.net.id/ 355 http://mirror.unej.ac.id/cpan/ 356 ftp://mirror.unej.ac.id/cpan/ 357 358=item Japan 359 360 ftp://ftp.u-aizu.ac.jp/pub/CPAN 361 ftp://ftp.kddilabs.jp/CPAN/ 362 http://ftp.nara.wide.ad.jp/pub/CPAN/ 363 ftp://ftp.nara.wide.ad.jp/pub/CPAN/ 364 http://ftp.jaist.ac.jp/pub/CPAN/ 365 ftp://ftp.jaist.ac.jp/pub/CPAN/ 366 ftp://ftp.dti.ad.jp/pub/lang/CPAN/ 367 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/ 368 http://ftp.riken.jp/lang/CPAN/ 369 ftp://ftp.riken.jp/lang/CPAN/ 370 http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/ 371 ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/ 372 373=item Kazakhstan 374 375 http://mirror.linuxiso.kz/CPAN/ 376 377=item Republic of Korea 378 379 http://ftp.kaist.ac.kr/pub/CPAN 380 ftp://ftp.kaist.ac.kr/pub/CPAN 381 http://cpan.mirror.cdnetworks.com/ 382 ftp://cpan.mirror.cdnetworks.com/CPAN/ 383 http://cpan.sarang.net/ 384 ftp://cpan.sarang.net/CPAN/ 385 386=item Russia 387 388 http://cpan.tomsk.ru/ 389 ftp://cpan.tomsk.ru/ 390 391=item Singapore 392 393 http://mirror.averse.net/pub/CPAN 394 ftp://mirror.averse.net/pub/CPAN 395 http://cpan.mirror.choon.net/ 396 http://cpan.oss.eznetsols.org 397 ftp://ftp.oss.eznetsols.org/cpan 398 399=item Taiwan 400 401 http://ftp.cse.yzu.edu.tw/pub/CPAN/ 402 ftp://ftp.cse.yzu.edu.tw/pub/CPAN/ 403 http://cpan.nctu.edu.tw/ 404 ftp://cpan.nctu.edu.tw/ 405 ftp://ftp.ncu.edu.tw/CPAN/ 406 http://cpan.cdpa.nsysu.edu.tw/ 407 ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/ 408 http://cpan.stu.edu.tw 409 ftp://ftp.stu.edu.tw/CPAN 410 http://ftp.stu.edu.tw/CPAN 411 ftp://ftp.stu.edu.tw/pub/CPAN 412 http://cpan.cs.pu.edu.tw/ 413 ftp://cpan.cs.pu.edu.tw/pub/CPAN 414 415=item Thailand 416 417 http://mirrors.issp.co.th/cpan/ 418 ftp://mirrors.issp.co.th/cpan/ 419 420=item Turkey 421 422 http://cpan.gazi.edu.tr/ 423 http://cpan.ulak.net.tr 424 ftp://ftp.ulak.net.tr/pub/CPAN 425 426=item Viet Nam 427 428 http://mirror-fpt-telecom.fpt.net/cpan/ 429 ftp://mirror-fpt-telecom.fpt.net/cpan/ 430 431=back 432 433=head2 Central America 434 435=over 4 436 437=item Costa Rica 438 439 http://mirrors.ucr.ac.cr/CPAN/ 440 ftp://mirrors.ucr.ac.cr/CPAN/ 441 442=back 443 444=head2 Europe 445 446=over 4 447 448=item Austria 449 450 http://cpan.inode.at/ 451 ftp://cpan.inode.at 452 http://gd.tuwien.ac.at/languages/perl/CPAN/ 453 ftp://gd.tuwien.ac.at/pub/CPAN/ 454 455=item Belgium 456 457 http://ftp.belnet.be/mirror/ftp.cpan.org/ 458 ftp://ftp.belnet.be/mirror/ftp.cpan.org/ 459 http://ftp.easynet.be/pub/CPAN/ 460 http://cpan.weepee.org/ 461 http://cpan.fluoline.net/ 462 463=item Bosnia and Herzegovina 464 465 http://cpan.blic.net/ 466 467=item Bulgaria 468 469 http://cpan.cbox.biz/ 470 ftp://cpan.cbox.biz/cpan/ 471 http://cpan.digsys.bg/ 472 ftp://ftp.digsys.bg/pub/CPAN 473 474=item Croatia 475 476 http://ftp.carnet.hr/pub/CPAN/ 477 ftp://ftp.carnet.hr/pub/CPAN/ 478 479=item Czech Republic 480 481 ftp://ftp.fi.muni.cz/pub/CPAN/ 482 http://archive.cpan.cz/ 483 484=item Denmark 485 486 http://mirrors.dotsrc.org/cpan 487 ftp://mirrors.dotsrc.org/cpan/ 488 http://www.cpan.dk/ 489 http://mirror.uni-c.dk/pub/CPAN/ 490 491=item Finland 492 493 ftp://ftp.funet.fi/pub/languages/perl/CPAN/ 494 http://mirror.eunet.fi/CPAN 495 496=item France 497 498 http://cpan.enstimac.fr/ 499 ftp://ftp.inria.fr/pub/CPAN/ 500 http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ 501 ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ 502 ftp://ftp.lip6.fr/pub/perl/CPAN/ 503 http://mir2.ovh.net/ftp.cpan.org 504 ftp://mir1.ovh.net/ftp.cpan.org 505 http://cpan.miroir-francais.fr/ 506 ftp://miroir-francais.fr/pub/cpan/ 507 ftp://ftp.oleane.net/pub/CPAN/ 508 http://ftp.crihan.fr/mirrors/ftp.cpan.org/ 509 ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/ 510 http://ftp.u-strasbg.fr/CPAN 511 ftp://ftp.u-strasbg.fr/CPAN 512 http://cpan.cict.fr/ 513 ftp://cpan.cict.fr/pub/CPAN/ 514 515=item Germany 516 517 ftp://ftp.fu-berlin.de/unix/languages/perl/ 518 http://mirrors.softliste.de/cpan/ 519 ftp://ftp.rub.de/pub/CPAN/ 520 http://www.planet-elektronik.de/CPAN/ 521 http://ftp.hosteurope.de/pub/CPAN/ 522 ftp://ftp.hosteurope.de/pub/CPAN/ 523 http://www.mirrorspace.org/cpan/ 524 http://mirror.netcologne.de/cpan/ 525 ftp://mirror.netcologne.de/cpan/ 526 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/ 527 http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/ 528 ftp://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/ 529 http://mirrors.zerg.biz/cpan/ 530 http://ftp.gwdg.de/pub/languages/perl/CPAN/ 531 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ 532 http://dl.ambiweb.de/mirrors/ftp.cpan.org/ 533 http://cpan.mirror.clusters.kg/ 534 http://cpan.mirror.iphh.net/ 535 ftp://cpan.mirror.iphh.net/pub/CPAN/ 536 http://cpan.mirroring.de/ 537 http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/ 538 ftp://mirror.informatik.uni-mannheim.de/pub/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 http://cpan.fastbull.org/ 581 582=item Latvia 583 584 http://kvin.lv/pub/CPAN/ 585 586=item Lithuania 587 588 http://ftp.litnet.lt/pub/CPAN/ 589 ftp://ftp.litnet.lt/pub/CPAN/ 590 591=item Malta 592 593 http://cpan.waldonet.net.mt/ 594 595=item Netherlands 596 597 ftp://ftp.quicknet.nl/pub/CPAN/ 598 http://mirror.hostfuss.com/CPAN/ 599 ftp://mirror.hostfuss.com/CPAN/ 600 http://mirrors3.kernel.org/cpan/ 601 ftp://mirrors3.kernel.org/pub/CPAN/ 602 http://cpan.osmirror.nl/ 603 ftp://ftp.osmirror.nl/pub/cpan/ 604 http://cpan.mirror.versatel.nl/ 605 ftp://ftp.mirror.versatel.nl/cpan/ 606 ftp://download.xs4all.nl/pub/mirror/CPAN/ 607 http://mirror.leaseweb.com/CPAN/ 608 ftp://mirror.leaseweb.com/CPAN/ 609 ftp://ftp.cpan.nl/pub/CPAN/ 610 http://archive.cs.uu.nl/mirror/CPAN/ 611 ftp://ftp.cs.uu.nl/mirror/CPAN/ 612 http://https://luxitude.net/cpan/ 613 614=item Norway 615 616 ftp://ftp.uninett.no/pub/languages/perl/CPAN 617 ftp://ftp.uit.no/pub/languages/perl/cpan/ 618 619=item Poland 620 621 http://mirror.icis.pcz.pl/CPAN/ 622 ftp://mirror.icis.pcz.pl/CPAN/ 623 http://piotrkosoft.net/pub/mirrors/CPAN/ 624 ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/ 625 http://ftp.man.poznan.pl/pub/CPAN 626 ftp://ftp.man.poznan.pl/pub/CPAN 627 ftp://sunsite.icm.edu.pl/pub/CPAN/ 628 ftp://ftp.tpnet.pl/d4/CPAN/ 629 630=item Portugal 631 632 http://cpan.dei.uc.pt/ 633 ftp://ftp.dei.uc.pt/pub/CPAN 634 ftp://ftp.ist.utl.pt/pub/CPAN/ 635 http://cpan.perl.pt/ 636 http://cpan.ip.pt/ 637 ftp://cpan.ip.pt/pub/cpan/ 638 http://mirrors.nfsi.pt/CPAN/ 639 ftp://mirrors.nfsi.pt/pub/CPAN/ 640 http://cpan.dcc.fc.up.pt/ 641 642=item Romania 643 644 http://ftp.astral.ro/pub/CPAN/ 645 ftp://ftp.astral.ro/pub/CPAN/ 646 ftp://ftp.lug.ro/CPAN 647 http://mirrors.xservers.ro/CPAN/ 648 http://mirrors.hostingromania.ro/ftp.cpan.org/ 649 ftp://ftp.hostingromania.ro/mirrors/ftp.cpan.org/ 650 ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/ 651 ftp://ftp.ambra.ro/pub/CPAN 652 653=item Russia 654 655 ftp://ftp.aha.ru/CPAN/ 656 http://cpan.rinet.ru/ 657 ftp://cpan.rinet.ru/pub/mirror/CPAN/ 658 ftp://ftp.SpringDaemons.com/pub/CPAN/ 659 http://cpan.nx1.ru/ 660 ftp://cpan.nx1.ru/ 661 http://mirror.rol.ru/CPAN/ 662 http://ftp.silvernet.ru/CPAN/ 663 http://ftp.spbu.ru/CPAN/ 664 ftp://ftp.spbu.ru/CPAN/ 665 666=item Slovakia 667 668 http://cpan.fyxm.net/ 669 670=item Slovenia 671 672 http://www.klevze.si/cpan 673 674=item Spain 675 676 http://osl.ugr.es/CPAN/ 677 ftp://ftp.rediris.es/mirror/CPAN/ 678 http://ftp.gui.uva.es/sites/cpan.org/ 679 ftp://ftp.gui.uva.es/sites/cpan.org/ 680 681=item Sweden 682 683 http://mirrors4.kernel.org/cpan/ 684 ftp://mirrors4.kernel.org/pub/CPAN/ 685 686=item Switzerland 687 688 http://cpan.mirror.solnet.ch/ 689 ftp://ftp.solnet.ch/mirror/CPAN/ 690 http://mirror.switch.ch/ftp/mirror/CPAN/ 691 ftp://mirror.switch.ch/mirror/CPAN/ 692 693=item Ukraine 694 695 http://cpan.makeperl.org/ 696 ftp://cpan.makeperl.org/pub/CPAN 697 http://cpan.org.ua/ 698 http://no-more.kiev.ua/CPAN/ 699 ftp://no-more.kiev.ua/pub/CPAN/ 700 http://cpan.gafol.net/ 701 ftp://ftp.gafol.net/pub/cpan/ 702 703=item United Kingdom 704 705 http://www.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/ 706 ftp://ftp.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/ 707 http://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/ 708 ftp://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/ 709 http://www.mirror.8086.net/sites/CPAN/ 710 ftp://ftp.mirror.8086.net/sites/CPAN/ 711 http://cpan.mirror.anlx.net/ 712 ftp://ftp.mirror.anlx.net/CPAN/ 713 http://mirror.bytemark.co.uk/CPAN/ 714 ftp://mirror.bytemark.co.uk/CPAN/ 715 http://cpan.etla.org/ 716 ftp://cpan.etla.org/pub/CPAN 717 ftp://ftp.demon.co.uk/pub/CPAN/ 718 http://mirror.sov.uk.goscomb.net/CPAN/ 719 ftp://mirror.sov.uk.goscomb.net/pub/CPAN/ 720 http://ftp.plig.net/pub/CPAN/ 721 ftp://ftp.plig.net/pub/CPAN/ 722 http://ftp.ticklers.org/pub/CPAN/ 723 ftp://ftp.ticklers.org/pub/CPAN/ 724 http://cpan.mirrors.uk2.net/ 725 ftp://mirrors.uk2.net/pub/CPAN/ 726 http://mirror.ox.ac.uk/sites/www.cpan.org/ 727 ftp://mirror.ox.ac.uk/sites/www.cpan.org/ 728 729=back 730 731=head2 North America 732 733=over 4 734 735=item Bahamas 736 737 http://www.securehost.com/mirror/CPAN/ 738 739=item Canada 740 741 http://cpan.justanotherperlhacker.com/pub/CPAN/ 742 ftp://cpan.justanotherperlhacker.com/pub/CPAN/ 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 California 772 773 http://cpan.knowledgematters.net/ 774 http://cpan.binkerton.com/ 775 http://cpan.develooper.com/ 776 http://mirrors.gossamer-threads.com/CPAN 777 http://cpan.schatt.com/ 778 http://mirrors.kernel.org/cpan/ 779 ftp://mirrors.kernel.org/pub/CPAN 780 http://mirrors2.kernel.org/cpan/ 781 ftp://mirrors2.kernel.org/pub/CPAN/ 782 http://cpan.mirrors.redwire.net/ 783 http://cpan.mirror.facebook.net/ 784 http://mirrors1.kernel.org/cpan/ 785 ftp://mirrors1.kernel.org/pub/CPAN/ 786 http://cpan-sj.viaverio.com/ 787 ftp://cpan-sj.viaverio.com/pub/CPAN/ 788 http://www.perl.com/CPAN/ 789 http://cpan.yahoo.com/ 790 791=item Florida 792 793 ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/ 794 http://mirror.atlantic.net/pub/CPAN/ 795 ftp://mirror.atlantic.net/pub/CPAN/ 796 http://mirror.candidhosting.com/pub/CPAN 797 ftp://mirror.candidhosting.com/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 http://fx.saintjoe.edu/pub/CPAN 821 822=item Massachusetts 823 824 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ 825 826=item Michigan 827 828 http://ftp.wayne.edu/cpan/ 829 ftp://ftp.wayne.edu/cpan/ 830 831=item Minnesota 832 833 http://cpan.msi.umn.edu/ 834 835=item New Jersey 836 837 http://mirror.datapipe.net/CPAN/ 838 ftp://mirror.datapipe.net/pub/CPAN/ 839 840=item New York 841 842 http://mirrors.24-7-solutions.net/pub/CPAN/ 843 ftp://mirrors.24-7-solutions.net/pub/CPAN/ 844 http://mirror.cc.columbia.edu/pub/software/cpan/ 845 ftp://mirror.cc.columbia.edu/pub/software/cpan/ 846 http://cpan.belfry.net/ 847 http://cpan.erlbaum.net/ 848 ftp://cpan.erlbaum.net/CPAN/ 849 http://cpan.hexten.net/ 850 ftp://cpan.hexten.net/ 851 http://ftp.fxcorporate.com/CPAN/ 852 ftp://ftp.fxcorporate.com/pub/CPAN/ 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 http://cpan.cs.utah.edu 889 ftp://cpan.cs.utah.edu/pub/CPAN/ 890 ftp://mirror.xmission.com/CPAN/ 891 892=item Virginia 893 894 http://cpan-du.viaverio.com/ 895 ftp://cpan-du.viaverio.com/pub/CPAN/ 896 http://perl.secsup.org/ 897 ftp://perl.secsup.org/pub/perl/ 898 ftp://mirror.cogentco.com/pub/CPAN/ 899 900=item Washington 901 902 http://cpan.llarian.net/ 903 ftp://cpan.llarian.net/pub/CPAN/ 904 ftp://ftp-mirror.internap.com/pub/CPAN/ 905 906=item Wisconsin 907 908 http://cpan.mirrors.tds.net 909 ftp://cpan.mirrors.tds.net/pub/CPAN 910 http://mirror.sit.wisc.edu/pub/CPAN/ 911 ftp://mirror.sit.wisc.edu/pub/CPAN/ 912 913=back 914 915=back 916 917=head2 Oceania 918 919=over 4 920 921=item Australia 922 923 http://mirror.internode.on.net/pub/cpan/ 924 ftp://mirror.internode.on.net/pub/cpan/ 925 http://cpan.mirror.aussiehq.net.au/ 926 http://mirror.as24220.net/cpan/ 927 ftp://mirror.as24220.net/cpan/ 928 929=item New Zealand 930 931 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ 932 http://cpan.inspire.net.nz 933 ftp://cpan.inspire.net.nz/cpan 934 http://cpan.catalyst.net.nz/CPAN/ 935 ftp://cpan.catalyst.net.nz/pub/CPAN/ 936 937=back 938 939=head2 South America 940 941=over 4 942 943=item Argentina 944 945 http://cpan.patan.com.ar/ 946 http://cpan.localhost.net.ar 947 ftp://mirrors.localhost.net.ar/pub/mirrors/CPAN 948 949=item Brazil 950 951 ftp://cpan.pop-mg.com.br/pub/CPAN/ 952 http://ftp.pucpr.br/CPAN 953 ftp://ftp.pucpr.br/CPAN 954 http://cpan.kinghost.net/ 955 ftp://ftp.linorg.usp.br/CPAN 956 957=item Chile 958 959 http://cpan.dcc.uchile.cl/ 960 ftp://cpan.dcc.uchile.cl/pub/lang/cpan/ 961 962=item Colombia 963 964 http://www.laqee.unal.edu.co/CPAN/ 965 966=back 967 968=head2 RSYNC Mirrors 969 970 mirror.as24220.net::cpan 971 cpan.inode.at::CPAN 972 gd.tuwien.ac.at::CPAN 973 ftp.belnet.be::packages/cpan 974 rsync.linorg.usp.br::CPAN 975 rsync.arcticnetwork.ca::CPAN 976 CPAN.mirror.rafal.ca::CPAN 977 mirror.csclub.uwaterloo.ca::CPAN 978 theoryx5.uwinnipeg.ca::CPAN 979 www.laqee.unal.edu.co::CPAN 980 mirror.uni-c.dk::CPAN 981 rsync.nic.funet.fi::CPAN 982 rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/ 983 mir1.ovh.net::CPAN 984 miroir-francais.fr::cpan 985 ftp.crihan.fr::CPAN 986 rsync://mirror.cict.fr/cpan/ 987 rsync://mirror.netcologne.de/cpan/ 988 ftp-stud.hs-esslingen.de::CPAN/ 989 ftp.gwdg.de::FTP/languages/perl/CPAN/ 990 cpan.mirror.iphh.net::CPAN 991 cpan.cpantesters.org::cpan 992 cpan.hu::CPAN 993 komo.vlsm.org::CPAN 994 mirror.unej.ac.id::cpan 995 ftp.esat.net::/pub/languages/perl/CPAN 996 ftp.heanet.ie::mirrors/ftp.perl.org/pub/CPAN 997 rsync.panu.it::CPAN 998 cpan.fastbull.org::CPAN 999 ftp.kddilabs.jp::cpan 1000 ftp.nara.wide.ad.jp::cpan/ 1001 rsync://ftp.jaist.ac.jp/pub/CPAN/ 1002 rsync://ftp.riken.jp/cpan/ 1003 mirror.linuxiso.kz::CPAN 1004 rsync://mirrors3.kernel.org/mirrors/CPAN/ 1005 rsync://rsync.osmirror.nl/cpan/ 1006 mirror.leaseweb.com::CPAN 1007 cpan.nautile.nc::CPAN 1008 mirror.icis.pcz.pl::CPAN 1009 piotrkosoft.net::mirrors/CPAN 1010 rsync://cpan.perl.pt/ 1011 ftp.kaist.ac.kr::cpan 1012 cpan.sarang.net::CPAN 1013 mirror.averse.net::cpan 1014 rsync.oss.eznetsols.org 1015 mirror.ac.za::cpan 1016 ftp.is.co.za::IS-Mirror/ftp.cpan.org/ 1017 rsync://ftp.gui.uva.es/cpan/ 1018 rsync://mirrors4.kernel.org/mirrors/CPAN/ 1019 ftp.solnet.ch::CPAN 1020 ftp.ulak.net.tr::CPAN 1021 gafol.net::cpan 1022 rsync.mirrorservice.org::ftp.funet.fi/pub/ 1023 rsync://rsync.mirror.8086.net/CPAN/ 1024 rsync.mirror.anlx.net::CPAN 1025 mirror.bytemark.co.uk::CPAN 1026 ftp.plig.net::CPAN 1027 rsync://ftp.ticklers.org:CPAN/ 1028 mirrors.ibiblio.org::CPAN 1029 cpan-du.viaverio.com::CPAN 1030 mirror.hiwaay.net::CPAN 1031 rsync://mira.sunsite.utk.edu/CPAN/ 1032 cpan.mirrors.tds.net::CPAN 1033 mirror.its.uidaho.edu::cpan 1034 rsync://mirror.cc.columbia.edu::cpan/ 1035 ftp.fxcorporate.com::CPAN 1036 rsync.atlantic.net::CPAN 1037 mirrors.kernel.org::mirrors/CPAN 1038 rsync://mirrors2.kernel.org/mirrors/CPAN/ 1039 cpan.pair.com::CPAN 1040 rsync://mirror.rit.edu/CPAN/ 1041 rsync://mirror.facebook.net/cpan/ 1042 rsync://mirrors1.kernel.org/mirrors/CPAN/ 1043 cpan-sj.viaverio.com::CPAN 1044 1045For an up-to-date listing of CPAN sites, 1046see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES . 1047 1048=head1 Modules: Creation, Use, and Abuse 1049 1050(The following section is borrowed directly from Tim Bunce's modules 1051file, available at your nearest CPAN site.) 1052 1053Perl implements a class using a package, but the presence of a 1054package doesn't imply the presence of a class. A package is just a 1055namespace. A class is a package that provides subroutines that can be 1056used as methods. A method is just a subroutine that expects, as its 1057first argument, either the name of a package (for "static" methods), 1058or a reference to something (for "virtual" methods). 1059 1060A module is a file that (by convention) provides a class of the same 1061name (sans the .pm), plus an import method in that class that can be 1062called to fetch exported symbols. This module may implement some of 1063its methods by loading dynamic C or C++ objects, but that should be 1064totally transparent to the user of the module. Likewise, the module 1065might set up an AUTOLOAD function to slurp in subroutine definitions on 1066demand, but this is also transparent. Only the F<.pm> file is required to 1067exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about 1068the AUTOLOAD mechanism. 1069 1070=head2 Guidelines for Module Creation 1071 1072=over 4 1073 1074=item * 1075 1076Do similar modules already exist in some form? 1077 1078If so, please try to reuse the existing modules either in whole or 1079by inheriting useful features into a new class. If this is not 1080practical try to get together with the module authors to work on 1081extending or enhancing the functionality of the existing modules. 1082A perfect example is the plethora of packages in perl4 for dealing 1083with command line options. 1084 1085If you are writing a module to expand an already existing set of 1086modules, please coordinate with the author of the package. It 1087helps if you follow the same naming scheme and module interaction 1088scheme as the original author. 1089 1090=item * 1091 1092Try to design the new module to be easy to extend and reuse. 1093 1094Try to C<use warnings;> (or C<use warnings qw(...);>). 1095Remember that you can add C<no warnings qw(...);> to individual blocks 1096of code that need less warnings. 1097 1098Use blessed references. Use the two argument form of bless to bless 1099into the class name given as the first parameter of the constructor, 1100e.g.,: 1101 1102 sub new { 1103 my $class = shift; 1104 return bless {}, $class; 1105 } 1106 1107or even this if you'd like it to be used as either a static 1108or a virtual method. 1109 1110 sub new { 1111 my $self = shift; 1112 my $class = ref($self) || $self; 1113 return bless {}, $class; 1114 } 1115 1116Pass arrays as references so more parameters can be added later 1117(it's also faster). Convert functions into methods where 1118appropriate. Split large methods into smaller more flexible ones. 1119Inherit methods from other modules if appropriate. 1120 1121Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>. 1122Generally you can delete the C<eq 'FOO'> part with no harm at all. 1123Let the objects look after themselves! Generally, avoid hard-wired 1124class names as far as possible. 1125 1126Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and 1127C<< $r->func() >> would work (see L<perlbot> for more details). 1128 1129Use autosplit so little used or newly added functions won't be a 1130burden to programs that don't use them. Add test functions to 1131the module after __END__ either using AutoSplit or by saying: 1132 1133 eval join('',<main::DATA>) || die $@ unless caller(); 1134 1135Does your module pass the 'empty subclass' test? If you say 1136C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able 1137to use SUBCLASS in exactly the same way as YOURCLASS. For example, 1138does your application still work if you change: C<< $obj = YOURCLASS->new(); >> 1139into: C<< $obj = SUBCLASS->new(); >> ? 1140 1141Avoid keeping any state information in your packages. It makes it 1142difficult for multiple other packages to use yours. Keep state 1143information in objects. 1144 1145Always use B<-w>. 1146 1147Try to C<use strict;> (or C<use strict qw(...);>). 1148Remember that you can add C<no strict qw(...);> to individual blocks 1149of code that need less strictness. 1150 1151Always use B<-w>. 1152 1153Follow the guidelines in L<perlstyle>. 1154 1155Always use B<-w>. 1156 1157=item * 1158 1159Some simple style guidelines 1160 1161The perlstyle manual supplied with Perl has many helpful points. 1162 1163Coding style is a matter of personal taste. Many people evolve their 1164style over several years as they learn what helps them write and 1165maintain good code. Here's one set of assorted suggestions that 1166seem to be widely used by experienced developers: 1167 1168Use underscores to separate words. It is generally easier to read 1169$var_names_like_this than $VarNamesLikeThis, especially for 1170non-native speakers of English. It's also a simple rule that works 1171consistently with VAR_NAMES_LIKE_THIS. 1172 1173Package/Module names are an exception to this rule. Perl informally 1174reserves lowercase module names for 'pragma' modules like integer 1175and strict. Other modules normally begin with a capital letter and 1176use mixed case with no underscores (need to be short and portable). 1177 1178You may find it helpful to use letter case to indicate the scope 1179or nature of a variable. For example: 1180 1181 $ALL_CAPS_HERE constants only (beware clashes with Perl vars) 1182 $Some_Caps_Here package-wide global/static 1183 $no_caps_here function scope my() or local() variables 1184 1185Function and method names seem to work best as all lowercase. 1186e.g., C<< $obj->as_string() >>. 1187 1188You can use a leading underscore to indicate that a variable or 1189function should not be used outside the package that defined it. 1190 1191=item * 1192 1193Select what to export. 1194 1195Do NOT export method names! 1196 1197Do NOT export anything else by default without a good reason! 1198 1199Exports pollute the namespace of the module user. If you must 1200export try to use @EXPORT_OK in preference to @EXPORT and avoid 1201short or common names to reduce the risk of name clashes. 1202 1203Generally anything not exported is still accessible from outside the 1204module using the ModuleName::item_name (or C<< $blessed_ref->method >>) 1205syntax. By convention you can use a leading underscore on names to 1206indicate informally that they are 'internal' and not for public use. 1207 1208(It is actually possible to get private functions by saying: 1209C<my $subref = sub { ... }; &$subref;>. But there's no way to call that 1210directly as a method, because a method must have a name in the symbol 1211table.) 1212 1213As a general rule, if the module is trying to be object oriented 1214then export nothing. If it's just a collection of functions then 1215@EXPORT_OK anything but use @EXPORT with caution. 1216 1217=item * 1218 1219Select a name for the module. 1220 1221This name should be as descriptive, accurate, and complete as 1222possible. Avoid any risk of ambiguity. Always try to use two or 1223more whole words. Generally the name should reflect what is special 1224about what the module does rather than how it does it. Please use 1225nested module names to group informally or categorize a module. 1226There should be a very good reason for a module not to have a nested name. 1227Module names should begin with a capital letter. 1228 1229Having 57 modules all called Sort will not make life easy for anyone 1230(though having 23 called Sort::Quick is only marginally better :-). 1231Imagine someone trying to install your module alongside many others. 1232If in any doubt ask for suggestions in comp.lang.perl.misc. 1233 1234If you are developing a suite of related modules/classes it's good 1235practice to use nested classes with a common prefix as this will 1236avoid namespace clashes. For example: Xyz::Control, Xyz::View, 1237Xyz::Model etc. Use the modules in this list as a naming guide. 1238 1239If adding a new module to a set, follow the original author's 1240standards for naming modules and the interface to methods in 1241those modules. 1242 1243If developing modules for private internal or project specific use, 1244that will never be released to the public, then you should ensure 1245that their names will not clash with any future public module. You 1246can do this either by using the reserved Local::* category or by 1247using a category name that includes an underscore like Foo_Corp::*. 1248 1249To be portable each component of a module name should be limited to 125011 characters. If it might be used on MS-DOS then try to ensure each is 1251unique in the first 8 characters. Nested modules make this easier. 1252 1253=item * 1254 1255Have you got it right? 1256 1257How do you know that you've made the right decisions? Have you 1258picked an interface design that will cause problems later? Have 1259you picked the most appropriate name? Do you have any questions? 1260 1261The best way to know for sure, and pick up many helpful suggestions, 1262is to ask someone who knows. Comp.lang.perl.misc is read by just about 1263all the people who develop modules and it's the best place to ask. 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 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=head2 Guidelines for Converting Perl 4 Library Scripts into Modules 1413 1414=over 4 1415 1416=item * 1417 1418There is no requirement to convert anything. 1419 1420If it ain't broke, don't fix it! Perl 4 library scripts should 1421continue to work with no problems. You may need to make some minor 1422changes (like escaping non-array @'s in double quoted strings) but 1423there is no need to convert a .pl file into a Module for just that. 1424 1425=item * 1426 1427Consider the implications. 1428 1429All Perl applications that make use of the script will need to 1430be changed (slightly) if the script is converted into a module. Is 1431it worth it unless you plan to make other changes at the same time? 1432 1433=item * 1434 1435Make the most of the opportunity. 1436 1437If you are going to convert the script to a module you can use the 1438opportunity to redesign the interface. The guidelines for module 1439creation above include many of the issues you should consider. 1440 1441=item * 1442 1443The pl2pm utility will get you started. 1444 1445This utility will read *.pl files (given as parameters) and write 1446corresponding *.pm files. The pl2pm utilities does the following: 1447 1448=over 10 1449 1450=item * 1451 1452Adds the standard Module prologue lines 1453 1454=item * 1455 1456Converts package specifiers from ' to :: 1457 1458=item * 1459 1460Converts die(...) to croak(...) 1461 1462=item * 1463 1464Several other minor changes 1465 1466=back 1467 1468Being a mechanical process pl2pm is not bullet proof. The converted 1469code will need careful checking, especially any package statements. 1470Don't delete the original .pl file till the new .pm one works! 1471 1472=back 1473 1474=head2 Guidelines for Reusing Application Code 1475 1476=over 4 1477 1478=item * 1479 1480Complete applications rarely belong in the Perl Module Library. 1481 1482=item * 1483 1484Many applications contain some Perl code that could be reused. 1485 1486Help save the world! Share your code in a form that makes it easy 1487to reuse. 1488 1489=item * 1490 1491Break-out the reusable code into one or more separate module files. 1492 1493=item * 1494 1495Take the opportunity to reconsider and redesign the interfaces. 1496 1497=item * 1498 1499In some cases the 'application' can then be reduced to a small 1500 1501fragment of code built on top of the reusable modules. In these cases 1502the application could invoked as: 1503 1504 % perl -e 'use Module::Name; method(@ARGV)' ... 1505or 1506 % perl -mModule::Name ... (in perl5.002 or higher) 1507 1508=back 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. 1526EOF 1527 1528close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!"; 1529close OUT or warn "$0: failed to close OUT (perlmodlib.pod): $!"; 1530 1531