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