1#!../miniperl 2 3open (OUT, ">perlmodlib.tmp") or die $!; 4my (@pragma, @mod); 5open (MANIFEST, "../MANIFEST") or die $!; 6 7while (<MANIFEST>) { 8 my $filename; 9 next unless s|^lib/|| or m|^ext/|; 10 ($filename) = /(\S+)/; 11 $filename =~ s|^[^/]+/|| if $filename =~ s|^ext/||; 12 next unless $filename =~ /\.p(m|od)$/; 13 next unless open (MOD, "../lib/$filename"); 14 15 my ($name, $thing); 16 my $foundit=0; 17 { 18 local $/=""; 19 while (<MOD>) { 20 next unless /^=head1 NAME/; 21 $foundit++; 22 last; 23 } 24 } 25 unless ($foundit) { 26 warn "$filename missing head1\n"; 27 next; 28 } 29 my $title = <MOD>; 30 chomp($title); 31 close MOD; 32 33 my $perlname = $filename; 34 $perlname =~ s!\.p(m|od)$!!; 35 $perlname =~ s!/!::!g; 36 37 ($name, $thing) = split / --? /, $title, 2; 38 39 unless ($name and $thing) { 40 warn "$filename missing name\n" unless $name; 41 warn "$filename missing thing\n" unless $thing; 42 next; 43 } 44 45 $thing =~ s/^perl pragma to //i; 46 $thing = ucfirst($thing); 47 $title = "=item $perlname\n\n$thing\n\n"; 48 49 # print "$perlname $thing\n"; 50 51 if ($filename=~/[A-Z]/) { 52 push @mod, $title; 53 } else { 54 push @pragma, $title; 55 } 56} 57 58print OUT <<'EOF'; 59# Generated by perlmodlib.PL DO NOT EDIT! 60 61=head1 NAME 62 63perlmodlib - constructing new Perl modules and finding existing ones 64 65=head1 DESCRIPTION 66 67=head1 THE PERL MODULE LIBRARY 68 69Many modules are included the Perl distribution. These are described 70below, and all end in F<.pm>. You may discover compiled library 71file (usually ending in F<.so>) or small pieces of modules to be 72autoloaded (ending in F<.al>); these were automatically generated 73by the installation process. You may also discover files in the 74library directory that end in either F<.pl> or F<.ph>. These are 75old libraries supplied so that old programs that use them still 76run. The F<.pl> files will all eventually be converted into standard 77modules, and the F<.ph> files made by B<h2ph> will probably end up 78as extension modules made by B<h2xs>. (Some F<.ph> values may 79already be available through the POSIX, Errno, or Fcntl modules.) 80The B<pl2pm> file in the distribution may help in your conversion, 81but it's just a mechanical process and therefore far from bulletproof. 82 83=head2 Pragmatic Modules 84 85They work somewhat like compiler directives (pragmata) in that they 86tend to affect the compilation of your program, and thus will usually 87work well only when used within a C<use>, or C<no>. Most of these 88are lexically scoped, so an inner BLOCK may countermand them 89by saying: 90 91 no integer; 92 no strict 'refs'; 93 no warnings; 94 95which lasts until the end of that BLOCK. 96 97Some pragmas are lexically scoped--typically those that affect the 98C<$^H> hints variable. Others affect the current package instead, 99like C<use vars> and C<use subs>, which allow you to predeclare a 100variables or subroutines within a particular I<file> rather than 101just a block. Such declarations are effective for the entire file 102for which they were declared. You cannot rescind them with C<no 103vars> or C<no subs>. 104 105The following pragmas are defined (and have their own documentation). 106 107=over 12 108 109EOF 110 111print OUT $_ for (sort @pragma); 112 113print OUT <<EOF; 114=back 115 116=head2 Standard Modules 117 118Standard, bundled modules are all expected to behave in a well-defined 119manner with respect to namespace pollution because they use the 120Exporter module. See their own documentation for details. 121 122=over 12 123 124EOF 125 126print OUT $_ for (sort @mod); 127 128print OUT <<'EOF'; 129=back 130 131To find out I<all> modules installed on your system, including 132those without documentation or outside the standard release, 133just do this: 134 135 % find `perl -e 'print "@INC"'` -name '*.pm' -print 136 137They should all have their own documentation installed and accessible 138via your system man(1) command. If you do not have a B<find> 139program, you can use the Perl B<find2perl> program instead, which 140generates Perl code as output you can run through perl. If you 141have a B<man> program but it doesn't find your modules, you'll have 142to fix your manpath. See L<perl> for details. If you have no 143system B<man> command, you might try the B<perldoc> program. 144 145=head2 Extension Modules 146 147Extension modules are written in C (or a mix of Perl and C). They 148are usually dynamically loaded into Perl if and when you need them, 149but may also be be linked in statically. Supported extension modules 150include Socket, Fcntl, and POSIX. 151 152Many popular C extension modules do not come bundled (at least, not 153completely) due to their sizes, volatility, or simply lack of time 154for adequate testing and configuration across the multitude of 155platforms on which Perl was beta-tested. You are encouraged to 156look for them on CPAN (described below), or using web search engines 157like Alta Vista or Deja News. 158 159=head1 CPAN 160 161CPAN stands for Comprehensive Perl Archive Network; it's a globally 162replicated trove of Perl materials, including documentation, style 163guides, tricks and traps, alternate ports to non-Unix systems and 164occasional binary distributions for these. Search engines for 165CPAN can be found at http://cpan.perl.com/ and at 166http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl . 167 168Most importantly, CPAN includes around a thousand unbundled modules, 169some of which require a C compiler to build. Major categories of 170modules are: 171 172=over 173 174=item * 175 176Language Extensions and Documentation Tools 177 178=item * 179 180Development Support 181 182=item * 183 184Operating System Interfaces 185 186=item * 187 188Networking, Device Control (modems) and InterProcess Communication 189 190=item * 191 192Data Types and Data Type Utilities 193 194=item * 195 196Database Interfaces 197 198=item * 199 200User Interfaces 201 202=item * 203 204Interfaces to / Emulations of Other Programming Languages 205 206=item * 207 208File Names, File Systems and File Locking (see also File Handles) 209 210=item * 211 212String Processing, Language Text Processing, Parsing, and Searching 213 214=item * 215 216Option, Argument, Parameter, and Configuration File Processing 217 218=item * 219 220Internationalization and Locale 221 222=item * 223 224Authentication, Security, and Encryption 225 226=item * 227 228World Wide Web, HTML, HTTP, CGI, MIME 229 230=item * 231 232Server and Daemon Utilities 233 234=item * 235 236Archiving and Compression 237 238=item * 239 240Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing 241 242=item * 243 244Mail and Usenet News 245 246=item * 247 248Control Flow Utilities (callbacks and exceptions etc) 249 250=item * 251 252File Handle and Input/Output Stream Utilities 253 254=item * 255 256Miscellaneous Modules 257 258=back 259 260Registered CPAN sites as of this writing include the following. 261You should try to choose one close to you: 262 263=head2 Africa 264 265=over 4 266 267=item * 268 269South Africa 270 271 ftp://ftp.is.co.za/programming/perl/CPAN/ 272 ftp://ftp.saix.net/pub/CPAN/ 273 ftp://ftpza.co.za/pub/mirrors/cpan/ 274 ftp://ftp.sun.ac.za/CPAN/ 275 276=back 277 278=head2 Asia 279 280=over 4 281 282=item * 283 284China 285 286 ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/ 287 http://www2.linuxforum.net/mirror/CPAN/ 288 http://cpan.shellhung.org/ 289 ftp://ftp.shellhung.org/pub/CPAN 290 291=item * 292 293Hong Kong 294 295 http://CPAN.pacific.net.hk/ 296 ftp://ftp.pacific.net.hk/pub/mirror/CPAN/ 297 298=item * 299 300Indonesia 301 302 http://piksi.itb.ac.id/CPAN/ 303 ftp://mirrors.piksi.itb.ac.id/CPAN/ 304 http://CPAN.mweb.co.id/ 305 ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/ 306 307=item * 308 309Israel 310 311 http://www.iglu.org.il:/pub/CPAN/ 312 ftp://ftp.iglu.org.il/pub/CPAN/ 313 http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ 314 ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ 315 316=item * 317 318Japan 319 320 ftp://ftp.u-aizu.ac.jp/pub/lang/perl/CPAN/ 321 ftp://ftp.kddlabs.co.jp/CPAN/ 322 http://mirror.nucba.ac.jp/mirror/Perl/ 323 ftp://mirror.nucba.ac.jp/mirror/Perl/ 324 ftp://ftp.meisei-u.ac.jp/pub/CPAN/ 325 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ 326 ftp://ftp.dti.ad.jp/pub/lang/CPAN/ 327 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/ 328 329=item * 330 331Saudi Arabia 332 333 ftp://ftp.isu.net.sa/pub/CPAN/ 334 335=item * 336 337Singapore 338 339 http://cpan.hjc.edu.sg 340 http://ftp.nus.edu.sg/unix/perl/CPAN/ 341 ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/ 342 343=item * 344 345South Korea 346 347 http://CPAN.bora.net/ 348 ftp://ftp.bora.net/pub/CPAN/ 349 http://ftp.kornet.net/CPAN/ 350 ftp://ftp.kornet.net/pub/CPAN/ 351 ftp://ftp.nuri.net/pub/CPAN/ 352 353=item * 354 355Taiwan 356 357 ftp://coda.nctu.edu.tw/UNIX/perl/CPAN 358 ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/ 359 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/ 360 361=item * 362 363Thailand 364 365 http://download.nectec.or.th/CPAN/ 366 ftp://ftp.nectec.or.th/pub/languages/CPAN/ 367 ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/ 368 369=back 370 371=head2 Central America 372 373=over 4 374 375=item * 376 377Costa Rica 378 379 ftp://ftp.linux.co.cr/mirrors/CPAN/ 380 http://ftp.ucr.ac.cr/Unix/CPAN/ 381 ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/ 382 383=back 384 385=head2 Europe 386 387=over 4 388 389=item * 390 391Austria 392 393 ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ 394 395=item * 396 397Belgium 398 399 http://ftp.easynet.be/CPAN/ 400 ftp://ftp.easynet.be/CPAN/ 401 ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ 402 403=item * 404 405Bulgaria 406 407 ftp://ftp.ntrl.net/pub/mirrors/CPAN/ 408 409=item * 410 411Croatia 412 413 ftp://ftp.linux.hr/pub/CPAN/ 414 415=item * 416 417Czech Republic 418 419 http://www.fi.muni.cz/pub/perl/ 420 ftp://ftp.fi.muni.cz/pub/perl/ 421 ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/ 422 423=item * 424 425Denmark 426 427 ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ 428 http://www.cpan.dk/CPAN/ 429 ftp://www.cpan.dk/ftp.cpan.org/CPAN/ 430 431=item * 432 433England 434 435 http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN 436 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ 437 ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ 438 ftp://ftp.flirble.org/pub/languages/perl/CPAN/ 439 ftp://ftp.plig.org/pub/CPAN/ 440 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ 441 http://mirror.uklinux.net/CPAN/ 442 ftp://mirror.uklinux.net/pub/CPAN/ 443 ftp://usit.shef.ac.uk/pub/packages/CPAN/ 444 445=item * 446 447Estonia 448 449 ftp://ftp.ut.ee/pub/languages/perl/CPAN/ 450 451=item * 452 453Finland 454 455 ftp://ftp.funet.fi/pub/languages/perl/CPAN/ 456 457=item * 458 459France 460 461 ftp://cpan.ftp.worldonline.fr/pub/CPAN/ 462 ftp://ftp.club-internet.fr/pub/perl/CPAN/ 463 ftp://ftp.lip6.fr/pub/perl/CPAN/ 464 ftp://ftp.oleane.net/pub/mirrors/CPAN/ 465 ftp://ftp.pasteur.fr/pub/computing/CPAN/ 466 ftp://cpan.cict.fr/pub/CPAN/ 467 ftp://ftp.uvsq.fr/pub/perl/CPAN/ 468 469=item * 470 471Germany 472 473 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ 474 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/ 475 ftp://ftp.uni-erlangen.de/pub/source/CPAN/ 476 ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN 477 ftp://ftp.gigabell.net/pub/CPAN/ 478 http://ftp.gwdg.de/pub/languages/perl/CPAN/ 479 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ 480 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ 481 ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/ 482 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ 483 ftp://ftp.gmd.de/mirrors/CPAN/ 484 485=item * 486 487Greece 488 489 ftp://ftp.forthnet.gr/pub/languages/perl/CPAN 490 ftp://ftp.ntua.gr/pub/lang/perl/ 491 492=item * 493 494Hungary 495 496 http://cpan.artifact.hu/ 497 ftp://cpan.artifact.hu/CPAN/ 498 ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ 499 500=item * 501 502Iceland 503 504 http://cpan.gm.is/ 505 ftp://ftp.gm.is/pub/CPAN/ 506 507=item * 508 509Ireland 510 511 http://cpan.indigo.ie/ 512 ftp://cpan.indigo.ie/pub/CPAN/ 513 http://sunsite.compapp.dcu.ie/pub/perl/ 514 ftp://sunsite.compapp.dcu.ie/pub/perl/ 515 516=item * 517 518Italy 519 520 http://cpan.nettuno.it/ 521 http://gusp.dyndns.org/CPAN/ 522 ftp://gusp.dyndns.org/pub/CPAN 523 http://softcity.iol.it/cpan 524 ftp://softcity.iol.it/pub/cpan 525 ftp://ftp.unina.it/pub/Other/CPAN/ 526 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/ 527 ftp://cis.uniRoma2.it/CPAN/ 528 ftp://ftp.edisontel.it/pub/CPAN_Mirror/ 529 ftp://ftp.flashnet.it/pub/CPAN/ 530 531=item * 532 533Latvia 534 535 http://kvin.lv/pub/CPAN/ 536 537=item * 538 539Netherlands 540 541 ftp://download.xs4all.nl/pub/mirror/CPAN/ 542 ftp://ftp.nl.uu.net/pub/CPAN/ 543 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/ 544 ftp://ftp.cpan.nl/pub/CPAN/ 545 http://www.cs.uu.nl/mirror/CPAN/ 546 ftp://ftp.cs.uu.nl/mirror/CPAN/ 547 548=item * 549 550Norway 551 552 ftp://sunsite.uio.no/pub/languages/perl/CPAN/ 553 ftp://ftp.uit.no/pub/languages/perl/cpan/ 554 555=item * 556 557Poland 558 559 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ 560 ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/ 561 ftp://ftp.man.torun.pl/pub/doc/CPAN/ 562 ftp://sunsite.icm.edu.pl/pub/CPAN/ 563 564=item * 565 566Portugal 567 568 ftp://ftp.ua.pt/pub/CPAN/ 569 ftp://perl.di.uminho.pt/pub/CPAN/ 570 ftp://ftp.ist.utl.pt/pub/CPAN/ 571 ftp://ftp.netc.pt/pub/CPAN/ 572 573=item * 574 575Romania 576 577 ftp://archive.logicnet.ro/mirrors/ftp.cpan.org/CPAN/ 578 ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/ 579 ftp://ftp.dntis.ro/pub/cpan/ 580 ftp://ftp.opsynet.com/cpan/ 581 ftp://ftp.dnttm.ro/pub/CPAN/ 582 ftp://ftp.timisoara.roedu.net/mirrors/CPAN/ 583 584=item * 585 586Russia 587 588 ftp://ftp.chg.ru/pub/lang/perl/CPAN/ 589 http://cpan.rinet.ru/ 590 ftp://cpan.rinet.ru/pub/mirror/CPAN/ 591 ftp://ftp.aha.ru/pub/CPAN/ 592 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ 593 594=item * 595 596Slovakia 597 598 ftp://ftp.entry.sk/pub/languages/perl/CPAN/ 599 600=item * 601 602Slovenia 603 604 ftp://ftp.arnes.si/software/perl/CPAN/ 605 606=item * 607 608Spain 609 610 ftp://ftp.rediris.es/mirror/CPAN/ 611 ftp://ftp.etse.urv.es/pub/perl/ 612 613=item * 614 615Sweden 616 617 http://ftp.du.se/CPAN/ 618 ftp://ftp.du.se/pub/CPAN/ 619 ftp://ftp.sunet.se/pub/lang/perl/CPAN/ 620 621=item * 622 623Switzerland 624 625 ftp://ftp.danyk.ch/CPAN/ 626 ftp://sunsite.cnlab-switch.ch/mirror/CPAN/ 627 628=item * 629 630Turkey 631 632 ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/ 633 634=back 635 636=head2 North America 637 638=over 4 639 640=item * 641 642Canada 643 644=over 8 645 646=item * 647 648Alberta 649 650 http://sunsite.ualberta.ca/pub/Mirror/CPAN/ 651 ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/ 652 653=item * 654 655Manitoba 656 657 http://theoryx5.uwinnipeg.ca/pub/CPAN/ 658 ftp://theoryx5.uwinnipeg.ca/pub/CPAN/ 659 660=item * 661 662Nova Scotia 663 664 ftp://cpan.chebucto.ns.ca/pub/CPAN/ 665 666=item * 667 668Ontario 669 670 ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/ 671 672=item * 673 674Mexico 675 676 http://www.msg.com.mx/CPAN/ 677 ftp://ftp.msg.com.mx/pub/CPAN/ 678 679=back 680 681=item * 682 683United States 684 685=over 8 686 687=item * 688 689Alabama 690 691 http://mirror.hiwaay.net/CPAN/ 692 ftp://mirror.hiwaay.net/CPAN/ 693 694=item * 695 696California 697 698 http://www.cpan.org/ 699 ftp://ftp.cpan.org/CPAN/ 700 ftp://cpan.nas.nasa.gov/pub/perl/CPAN/ 701 ftp://ftp.digital.com/pub/plan/perl/CPAN/ 702 http://www.kernel.org/pub/mirrors/cpan/ 703 ftp://ftp.kernel.org/pub/mirrors/cpan/ 704 http://www.perl.com/CPAN/ 705 http://download.sourceforge.net/mirrors/CPAN/ 706 707=item * 708 709Colorado 710 711 ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ 712 713=item * 714 715Florida 716 717 ftp://ftp.cise.ufl.edu/pub/perl/CPAN/ 718 719=item * 720 721Georgia 722 723 ftp://ftp.twoguys.org/CPAN/ 724 725=item * 726 727Illinois 728 729 http://www.neurogames.com/mirrors/CPAN 730 http://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/ 731 ftp://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/ 732 733=item * 734 735Indiana 736 737 ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/ 738 http://cpan.nitco.com/ 739 ftp://cpan.nitco.com/pub/CPAN/ 740 ftp://cpan.in-span.net/ 741 http://csociety-ftp.ecn.purdue.edu/pub/CPAN 742 ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN 743 744=item * 745 746Kentucky 747 748 http://cpan.uky.edu/ 749 ftp://cpan.uky.edu/pub/CPAN/ 750 751=item * 752 753Massachusetts 754 755 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ 756 ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ 757 758=item * 759 760New Jersey 761 762 ftp://ftp.cpanel.net/pub/CPAN/ 763 764=item * 765 766New York 767 768 ftp://ftp.freesoftware.com/pub/perl/CPAN/ 769 http://www.deao.net/mirrors/CPAN/ 770 ftp://ftp.deao.net/pub/CPAN/ 771 ftp://ftp.stealth.net/pub/mirrors/ftp.cpan.org/pub/CPAN/ 772 http://mirror.nyc.anidea.com/CPAN/ 773 ftp://mirror.nyc.anidea.com/pub/CPAN/ 774 http://www.rge.com/pub/languages/perl/ 775 ftp://ftp.rge.com/pub/languages/perl/ 776 ftp://mirrors.cloud9.net/pub/mirrors/CPAN/ 777 778=item * 779 780North Carolina 781 782 ftp://ftp.duke.edu/pub/perl/ 783 784=item * 785 786Ohio 787 788 ftp://ftp.loaded.net/pub/CPAN/ 789 790=item * 791 792Oklahoma 793 794 ftp://ftp.ou.edu/mirrors/CPAN/ 795 796=item * 797 798Oregon 799 800 ftp://ftp.orst.edu/pub/packages/CPAN/ 801 802=item * 803 804Pennsylvania 805 806 http://ftp.epix.net/CPAN/ 807 ftp://ftp.epix.net/pub/languages/perl/ 808 ftp://carroll.cac.psu.edu/pub/CPAN/ 809 810=item * 811 812Tennessee 813 814 ftp://ftp.sunsite.utk.edu/pub/CPAN/ 815 816=item * 817 818Texas 819 820 http://ftp.sedl.org/pub/mirrors/CPAN/ 821 http://jhcloos.com/pub/mirror/CPAN/ 822 ftp://jhcloos.com/pub/mirror/CPAN/ 823 824=item * 825 826Utah 827 828 ftp://mirror.xmission.com/CPAN/ 829 830=item * 831 832Virginia 833 834 http://mirrors.rcn.net/pub/lang/CPAN/ 835 ftp://mirrors.rcn.net/pub/lang/CPAN/ 836 ftp://ruff.cs.jmu.edu/pub/CPAN/ 837 http://perl.Liquidation.com/CPAN/ 838 839=item * 840 841Washington 842 843 http://cpan.llarian.net/ 844 ftp://cpan.llarian.net/pub/CPAN/ 845 ftp://ftp-mirror.internap.com/pub/CPAN/ 846 ftp://ftp.spu.edu/pub/CPAN/ 847 848=back 849 850=back 851 852=head2 Oceania 853 854=over 4 855 856=item * 857 858Australia 859 860 http://ftp.planetmirror.com/pub/CPAN/ 861 ftp://ftp.planetmirror.com/pub/CPAN/ 862 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/ 863 ftp://cpan.topend.com.au/pub/CPAN/ 864 865=item * 866 867New Zealand 868 869 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ 870 871=back 872 873=head2 South America 874 875=over 4 876 877=item * 878 879Argentina 880 881 ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/ 882 883=item * 884 885Brazil 886 887 ftp://cpan.pop-mg.com.br/pub/CPAN/ 888 ftp://ftp.matrix.com.br/pub/perl/ 889 ftp://cpan.if.usp.br/pub/mirror/CPAN/ 890 891=item * 892 893Chile 894 895 ftp://ftp.psinet.cl/pub/programming/perl/CPAN/ 896 ftp://sunsite.dcc.uchile.cl/pub/lang/perl/ 897 898=back 899 900For an up-to-date listing of CPAN sites, 901see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES . 902 903=head1 Modules: Creation, Use, and Abuse 904 905(The following section is borrowed directly from Tim Bunce's modules 906file, available at your nearest CPAN site.) 907 908Perl implements a class using a package, but the presence of a 909package doesn't imply the presence of a class. A package is just a 910namespace. A class is a package that provides subroutines that can be 911used as methods. A method is just a subroutine that expects, as its 912first argument, either the name of a package (for "static" methods), 913or a reference to something (for "virtual" methods). 914 915A module is a file that (by convention) provides a class of the same 916name (sans the .pm), plus an import method in that class that can be 917called to fetch exported symbols. This module may implement some of 918its methods by loading dynamic C or C++ objects, but that should be 919totally transparent to the user of the module. Likewise, the module 920might set up an AUTOLOAD function to slurp in subroutine definitions on 921demand, but this is also transparent. Only the F<.pm> file is required to 922exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about 923the AUTOLOAD mechanism. 924 925=head2 Guidelines for Module Creation 926 927=over 4 928 929=item * 930 931Do similar modules already exist in some form? 932 933If so, please try to reuse the existing modules either in whole or 934by inheriting useful features into a new class. If this is not 935practical try to get together with the module authors to work on 936extending or enhancing the functionality of the existing modules. 937A perfect example is the plethora of packages in perl4 for dealing 938with command line options. 939 940If you are writing a module to expand an already existing set of 941modules, please coordinate with the author of the package. It 942helps if you follow the same naming scheme and module interaction 943scheme as the original author. 944 945=item * 946 947Try to design the new module to be easy to extend and reuse. 948 949Try to C<use warnings;> (or C<use warnings qw(...);>). 950Remember that you can add C<no warnings qw(...);> to individual blocks 951of code that need less warnings. 952 953Use blessed references. Use the two argument form of bless to bless 954into the class name given as the first parameter of the constructor, 955e.g.,: 956 957 sub new { 958 my $class = shift; 959 return bless {}, $class; 960 } 961 962or even this if you'd like it to be used as either a static 963or a virtual method. 964 965 sub new { 966 my $self = shift; 967 my $class = ref($self) || $self; 968 return bless {}, $class; 969 } 970 971Pass arrays as references so more parameters can be added later 972(it's also faster). Convert functions into methods where 973appropriate. Split large methods into smaller more flexible ones. 974Inherit methods from other modules if appropriate. 975 976Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>. 977Generally you can delete the C<eq 'FOO'> part with no harm at all. 978Let the objects look after themselves! Generally, avoid hard-wired 979class names as far as possible. 980 981Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and 982C<< $r->func() >> would work (see L<perlbot> for more details). 983 984Use autosplit so little used or newly added functions won't be a 985burden to programs that don't use them. Add test functions to 986the module after __END__ either using AutoSplit or by saying: 987 988 eval join('',<main::DATA>) || die $@ unless caller(); 989 990Does your module pass the 'empty subclass' test? If you say 991C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able 992to use SUBCLASS in exactly the same way as YOURCLASS. For example, 993does your application still work if you change: C<$obj = new YOURCLASS;> 994into: C<$obj = new SUBCLASS;> ? 995 996Avoid keeping any state information in your packages. It makes it 997difficult for multiple other packages to use yours. Keep state 998information in objects. 999 1000Always use B<-w>. 1001 1002Try to C<use strict;> (or C<use strict qw(...);>). 1003Remember that you can add C<no strict qw(...);> to individual blocks 1004of code that need less strictness. 1005 1006Always use B<-w>. 1007 1008Follow the guidelines in the perlstyle(1) manual. 1009 1010Always use B<-w>. 1011 1012=item * 1013 1014Some simple style guidelines 1015 1016The perlstyle manual supplied with Perl has many helpful points. 1017 1018Coding style is a matter of personal taste. Many people evolve their 1019style over several years as they learn what helps them write and 1020maintain good code. Here's one set of assorted suggestions that 1021seem to be widely used by experienced developers: 1022 1023Use underscores to separate words. It is generally easier to read 1024$var_names_like_this than $VarNamesLikeThis, especially for 1025non-native speakers of English. It's also a simple rule that works 1026consistently with VAR_NAMES_LIKE_THIS. 1027 1028Package/Module names are an exception to this rule. Perl informally 1029reserves lowercase module names for 'pragma' modules like integer 1030and strict. Other modules normally begin with a capital letter and 1031use mixed case with no underscores (need to be short and portable). 1032 1033You may find it helpful to use letter case to indicate the scope 1034or nature of a variable. For example: 1035 1036 $ALL_CAPS_HERE constants only (beware clashes with Perl vars) 1037 $Some_Caps_Here package-wide global/static 1038 $no_caps_here function scope my() or local() variables 1039 1040Function and method names seem to work best as all lowercase. 1041e.g., C<< $obj->as_string() >>. 1042 1043You can use a leading underscore to indicate that a variable or 1044function should not be used outside the package that defined it. 1045 1046=item * 1047 1048Select what to export. 1049 1050Do NOT export method names! 1051 1052Do NOT export anything else by default without a good reason! 1053 1054Exports pollute the namespace of the module user. If you must 1055export try to use @EXPORT_OK in preference to @EXPORT and avoid 1056short or common names to reduce the risk of name clashes. 1057 1058Generally anything not exported is still accessible from outside the 1059module using the ModuleName::item_name (or C<< $blessed_ref->method >>) 1060syntax. By convention you can use a leading underscore on names to 1061indicate informally that they are 'internal' and not for public use. 1062 1063(It is actually possible to get private functions by saying: 1064C<my $subref = sub { ... }; &$subref;>. But there's no way to call that 1065directly as a method, because a method must have a name in the symbol 1066table.) 1067 1068As a general rule, if the module is trying to be object oriented 1069then export nothing. If it's just a collection of functions then 1070@EXPORT_OK anything but use @EXPORT with caution. 1071 1072=item * 1073 1074Select a name for the module. 1075 1076This name should be as descriptive, accurate, and complete as 1077possible. Avoid any risk of ambiguity. Always try to use two or 1078more whole words. Generally the name should reflect what is special 1079about what the module does rather than how it does it. Please use 1080nested module names to group informally or categorize a module. 1081There should be a very good reason for a module not to have a nested name. 1082Module names should begin with a capital letter. 1083 1084Having 57 modules all called Sort will not make life easy for anyone 1085(though having 23 called Sort::Quick is only marginally better :-). 1086Imagine someone trying to install your module alongside many others. 1087If in any doubt ask for suggestions in comp.lang.perl.misc. 1088 1089If you are developing a suite of related modules/classes it's good 1090practice to use nested classes with a common prefix as this will 1091avoid namespace clashes. For example: Xyz::Control, Xyz::View, 1092Xyz::Model etc. Use the modules in this list as a naming guide. 1093 1094If adding a new module to a set, follow the original author's 1095standards for naming modules and the interface to methods in 1096those modules. 1097 1098If developing modules for private internal or project specific use, 1099that will never be released to the public, then you should ensure 1100that their names will not clash with any future public module. You 1101can do this either by using the reserved Local::* category or by 1102using a category name that includes an underscore like Foo_Corp::*. 1103 1104To be portable each component of a module name should be limited to 110511 characters. If it might be used on MS-DOS then try to ensure each is 1106unique in the first 8 characters. Nested modules make this easier. 1107 1108=item * 1109 1110Have you got it right? 1111 1112How do you know that you've made the right decisions? Have you 1113picked an interface design that will cause problems later? Have 1114you picked the most appropriate name? Do you have any questions? 1115 1116The best way to know for sure, and pick up many helpful suggestions, 1117is to ask someone who knows. Comp.lang.perl.misc is read by just about 1118all the people who develop modules and it's the best place to ask. 1119 1120All you need to do is post a short summary of the module, its 1121purpose and interfaces. A few lines on each of the main methods is 1122probably enough. (If you post the whole module it might be ignored 1123by busy people - generally the very people you want to read it!) 1124 1125Don't worry about posting if you can't say when the module will be 1126ready - just say so in the message. It might be worth inviting 1127others to help you, they may be able to complete it for you! 1128 1129=item * 1130 1131README and other Additional Files. 1132 1133It's well known that software developers usually fully document the 1134software they write. If, however, the world is in urgent need of 1135your software and there is not enough time to write the full 1136documentation please at least provide a README file containing: 1137 1138=over 10 1139 1140=item * 1141 1142A description of the module/package/extension etc. 1143 1144=item * 1145 1146A copyright notice - see below. 1147 1148=item * 1149 1150Prerequisites - what else you may need to have. 1151 1152=item * 1153 1154How to build it - possible changes to Makefile.PL etc. 1155 1156=item * 1157 1158How to install it. 1159 1160=item * 1161 1162Recent changes in this release, especially incompatibilities 1163 1164=item * 1165 1166Changes / enhancements you plan to make in the future. 1167 1168=back 1169 1170If the README file seems to be getting too large you may wish to 1171split out some of the sections into separate files: INSTALL, 1172Copying, ToDo etc. 1173 1174=over 4 1175 1176=item Adding a Copyright Notice. 1177 1178 1179How you choose to license your work is a personal decision. 1180The general mechanism is to assert your Copyright and then make 1181a declaration of how others may copy/use/modify your work. 1182 1183Perl, for example, is supplied with two types of licence: The GNU 1184GPL and The Artistic Licence (see the files README, Copying, and 1185Artistic). Larry has good reasons for NOT just using the GNU GPL. 1186 1187My personal recommendation, out of respect for Larry, Perl, and the 1188Perl community at large is to state something simply like: 1189 1190 Copyright (c) 1995 Your Name. All rights reserved. 1191 This program is free software; you can redistribute it and/or 1192 modify it under the same terms as Perl itself. 1193 1194This statement should at least appear in the README file. You may 1195also wish to include it in a Copying file and your source files. 1196Remember to include the other words in addition to the Copyright. 1197 1198=item * 1199 1200Give the module a version/issue/release number. 1201 1202To be fully compatible with the Exporter and MakeMaker modules you 1203should store your module's version number in a non-my package 1204variable called $VERSION. This should be a floating point 1205number with at least two digits after the decimal (i.e., hundredths, 1206e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version. 1207See L<Exporter> for details. 1208 1209It may be handy to add a function or method to retrieve the number. 1210Use the number in announcements and archive file names when 1211releasing the module (ModuleName-1.02.tar.Z). 1212See perldoc ExtUtils::MakeMaker.pm for details. 1213 1214=item * 1215 1216How to release and distribute a module. 1217 1218It's good idea to post an announcement of the availability of your 1219module (or the module itself if small) to the comp.lang.perl.announce 1220Usenet newsgroup. This will at least ensure very wide once-off 1221distribution. 1222 1223If possible, register the module with CPAN. You should 1224include details of its location in your announcement. 1225 1226Some notes about ftp archives: Please use a long descriptive file 1227name that includes the version number. Most incoming directories 1228will not be readable/listable, i.e., you won't be able to see your 1229file after uploading it. Remember to send your email notification 1230message as soon as possible after uploading else your file may get 1231deleted automatically. Allow time for the file to be processed 1232and/or check the file has been processed before announcing its 1233location. 1234 1235FTP Archives for Perl Modules: 1236 1237Follow the instructions and links on: 1238 1239 http://www.cpan.org/modules/00modlist.long.html 1240 http://www.cpan.org/modules/04pause.html 1241 1242or upload to one of these sites: 1243 1244 https://pause.kbx.de/pause/ 1245 http://pause.perl.org/pause/ 1246 1247and notify <modules@perl.org>. 1248 1249By using the WWW interface you can ask the Upload Server to mirror 1250your modules from your ftp or WWW site into your own directory on 1251CPAN! 1252 1253Please remember to send me an updated entry for the Module list! 1254 1255=item * 1256 1257Take care when changing a released module. 1258 1259Always strive to remain compatible with previous released versions. 1260Otherwise try to add a mechanism to revert to the 1261old behavior if people rely on it. Document incompatible changes. 1262 1263=back 1264 1265=back 1266 1267=head2 Guidelines for Converting Perl 4 Library Scripts into Modules 1268 1269=over 4 1270 1271=item * 1272 1273There is no requirement to convert anything. 1274 1275If it ain't broke, don't fix it! Perl 4 library scripts should 1276continue to work with no problems. You may need to make some minor 1277changes (like escaping non-array @'s in double quoted strings) but 1278there is no need to convert a .pl file into a Module for just that. 1279 1280=item * 1281 1282Consider the implications. 1283 1284All Perl applications that make use of the script will need to 1285be changed (slightly) if the script is converted into a module. Is 1286it worth it unless you plan to make other changes at the same time? 1287 1288=item * 1289 1290Make the most of the opportunity. 1291 1292If you are going to convert the script to a module you can use the 1293opportunity to redesign the interface. The guidelines for module 1294creation above include many of the issues you should consider. 1295 1296=item * 1297 1298The pl2pm utility will get you started. 1299 1300This utility will read *.pl files (given as parameters) and write 1301corresponding *.pm files. The pl2pm utilities does the following: 1302 1303=over 10 1304 1305=item * 1306 1307Adds the standard Module prologue lines 1308 1309=item * 1310 1311Converts package specifiers from ' to :: 1312 1313=item * 1314 1315Converts die(...) to croak(...) 1316 1317=item * 1318 1319Several other minor changes 1320 1321=back 1322 1323Being a mechanical process pl2pm is not bullet proof. The converted 1324code will need careful checking, especially any package statements. 1325Don't delete the original .pl file till the new .pm one works! 1326 1327=back 1328 1329=head2 Guidelines for Reusing Application Code 1330 1331=over 4 1332 1333=item * 1334 1335Complete applications rarely belong in the Perl Module Library. 1336 1337=item * 1338 1339Many applications contain some Perl code that could be reused. 1340 1341Help save the world! Share your code in a form that makes it easy 1342to reuse. 1343 1344=item * 1345 1346Break-out the reusable code into one or more separate module files. 1347 1348=item * 1349 1350Take the opportunity to reconsider and redesign the interfaces. 1351 1352=item * 1353 1354In some cases the 'application' can then be reduced to a small 1355 1356fragment of code built on top of the reusable modules. In these cases 1357the application could invoked as: 1358 1359 % perl -e 'use Module::Name; method(@ARGV)' ... 1360or 1361 % perl -mModule::Name ... (in perl5.002 or higher) 1362 1363=back 1364 1365=head1 NOTE 1366 1367Perl does not enforce private and public parts of its modules as you may 1368have been used to in other languages like C++, Ada, or Modula-17. Perl 1369doesn't have an infatuation with enforced privacy. It would prefer 1370that you stayed out of its living room because you weren't invited, not 1371because it has a shotgun. 1372 1373The module and its user have a contract, part of which is common law, 1374and part of which is "written". Part of the common law contract is 1375that a module doesn't pollute any namespace it wasn't asked to. The 1376written contract for the module (A.K.A. documentation) may make other 1377provisions. But then you know when you C<use RedefineTheWorld> that 1378you're redefining the world and willing to take the consequences. 1379EOF 1380 1381close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!"; 1382close OUT or warn "$0: failed to close OUT (perlmodlib.tmp): $!"; 1383 1384