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# || m#^ext#} grep !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 as of this writing 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 319You should try to choose one close to you. 320 321=head2 Africa 322 323=over 4 324 325=item South Africa 326 327 http://ftp.rucus.ru.ac.za/pub/perl/CPAN/ 328 ftp://ftp.rucus.ru.ac.za/pub/perl/CPAN/ 329 ftp://ftp.is.co.za/programming/perl/CPAN/ 330 ftp://ftp.saix.net/pub/CPAN/ 331 ftp://ftp.sun.ac.za/CPAN/CPAN/ 332 333=back 334 335=head2 Asia 336 337=over 4 338 339=item China 340 341 http://cpan.linuxforum.net/ 342 http://cpan.shellhung.org/ 343 ftp://ftp.shellhung.org/pub/CPAN 344 ftp://mirrors.hknet.com/CPAN 345 346=item Indonesia 347 348 http://mirrors.tf.itb.ac.id/cpan/ 349 http://cpan.cbn.net.id/ 350 ftp://ftp.cbn.net.id/mirror/CPAN 351 352=item Israel 353 354 ftp://ftp.iglu.org.il/pub/CPAN/ 355 http://cpan.lerner.co.il/ 356 http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ 357 ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ 358 359=item Japan 360 361 ftp://ftp.u-aizu.ac.jp/pub/CPAN 362 ftp://ftp.kddlabs.co.jp/CPAN/ 363 ftp://ftp.ayamura.org/pub/CPAN/ 364 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ 365 http://ftp.cpan.jp/ 366 ftp://ftp.cpan.jp/CPAN/ 367 ftp://ftp.dti.ad.jp/pub/lang/CPAN/ 368 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/ 369 370=item Malaysia 371 372 http://cpan.MyBSD.org.my 373 http://mirror.leafbug.org/pub/CPAN 374 http://ossig.mncc.com.my/mirror/pub/CPAN 375 376=item Russian Federation 377 378 http://cpan.tomsk.ru 379 ftp://cpan.tomsk.ru/ 380 381=item Saudi Arabia 382 383 ftp://ftp.isu.net.sa/pub/CPAN/ 384 385=item Singapore 386 387 http://CPAN.en.com.sg/ 388 ftp://cpan.en.com.sg/ 389 http://mirror.averse.net/pub/CPAN 390 ftp://mirror.averse.net/pub/CPAN 391 http://cpan.oss.eznetsols.org 392 ftp://ftp.oss.eznetsols.org/cpan 393 394=item South Korea 395 396 http://CPAN.bora.net/ 397 ftp://ftp.bora.net/pub/CPAN/ 398 http://mirror.kr.FreeBSD.org/CPAN 399 ftp://ftp.kr.FreeBSD.org/pub/CPAN 400 401=item Taiwan 402 403 ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN 404 http://cpan.cdpa.nsysu.edu.tw/ 405 ftp://cpan.cdpa.nsysu.edu.tw/pub/CPAN 406 http://ftp.isu.edu.tw/pub/CPAN 407 ftp://ftp.isu.edu.tw/pub/CPAN 408 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/ 409 http://ftp.tku.edu.tw/pub/CPAN/ 410 ftp://ftp.tku.edu.tw/pub/CPAN/ 411 412=item Thailand 413 414 ftp://ftp.loxinfo.co.th/pub/cpan/ 415 ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/ 416 417=back 418 419=head2 Central America 420 421=over 4 422 423=item Costa Rica 424 425 http://ftp.ucr.ac.cr/Unix/CPAN/ 426 ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/ 427 428=back 429 430=head2 Europe 431 432=over 4 433 434=item Austria 435 436 http://cpan.inode.at/ 437 ftp://cpan.inode.at 438 ftp://ftp.tuwien.ac.at/pub/CPAN/ 439 440=item Belgium 441 442 http://ftp.easynet.be/pub/CPAN/ 443 ftp://ftp.easynet.be/pub/CPAN/ 444 http://cpan.skynet.be 445 ftp://ftp.cpan.skynet.be/pub/CPAN 446 ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ 447 448=item Bosnia and Herzegovina 449 450 http://cpan.blic.net/ 451 452=item Bulgaria 453 454 http://cpan.online.bg 455 ftp://cpan.online.bg/cpan 456 http://cpan.zadnik.org 457 ftp://ftp.zadnik.org/mirrors/CPAN/ 458 http://cpan.lirex.net/ 459 ftp://ftp.lirex.net/pub/mirrors/CPAN 460 461=item Croatia 462 463 http://ftp.linux.hr/pub/CPAN/ 464 ftp://ftp.linux.hr/pub/CPAN/ 465 466=item Czech Republic 467 468 ftp://ftp.fi.muni.cz/pub/CPAN/ 469 ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/ 470 471=item Denmark 472 473 http://mirrors.sunsite.dk/cpan/ 474 ftp://sunsite.dk/mirrors/cpan/ 475 http://cpan.cybercity.dk 476 http://www.cpan.dk/CPAN/ 477 ftp://www.cpan.dk/ftp.cpan.org/CPAN/ 478 479=item Estonia 480 481 ftp://ftp.ut.ee/pub/languages/perl/CPAN/ 482 483=item Finland 484 485 ftp://ftp.funet.fi/pub/languages/perl/CPAN/ 486 http://mirror.eunet.fi/CPAN 487 488=item France 489 490 http://www.enstimac.fr/Perl/CPAN 491 http://ftp.u-paris10.fr/perl/CPAN 492 ftp://ftp.u-paris10.fr/perl/CPAN 493 http://cpan.mirrors.easynet.fr/ 494 ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/ 495 ftp://ftp.club-internet.fr/pub/perl/CPAN/ 496 http://fr.cpan.org/ 497 ftp://ftp.lip6.fr/pub/perl/CPAN/ 498 ftp://ftp.oleane.net/pub/mirrors/CPAN/ 499 ftp://ftp.pasteur.fr/pub/computing/CPAN/ 500 http://mir2.ovh.net/ftp.cpan.org 501 ftp://mir1.ovh.net/ftp.cpan.org 502 http://ftp.crihan.fr/mirrors/ftp.cpan.org/ 503 ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/ 504 http://ftp.u-strasbg.fr/CPAN 505 ftp://ftp.u-strasbg.fr/CPAN 506 ftp://cpan.cict.fr/pub/CPAN/ 507 ftp://ftp.uvsq.fr/pub/perl/CPAN/ 508 509=item Germany 510 511 ftp://ftp.rub.de/pub/CPAN/ 512 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/ 513 ftp://ftp.uni-erlangen.de/pub/source/CPAN/ 514 ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN 515 http://pandemonium.tiscali.de/pub/CPAN/ 516 ftp://pandemonium.tiscali.de/pub/CPAN/ 517 http://ftp.gwdg.de/pub/languages/perl/CPAN/ 518 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ 519 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ 520 ftp://ftp.leo.org/pub/CPAN/ 521 http://cpan.noris.de/ 522 ftp://cpan.noris.de/pub/CPAN/ 523 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ 524 ftp://ftp.gmd.de/mirrors/CPAN/ 525 526=item Greece 527 528 ftp://ftp.acn.gr/pub/lang/perl 529 ftp://ftp.forthnet.gr/pub/languages/perl/CPAN 530 ftp://ftp.ntua.gr/pub/lang/perl/ 531 532=item Hungary 533 534 http://ftp.kfki.hu/packages/perl/CPAN/ 535 ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ 536 537=item Iceland 538 539 http://ftp.rhnet.is/pub/CPAN/ 540 ftp://ftp.rhnet.is/pub/CPAN/ 541 542=item Ireland 543 544 http://cpan.indigo.ie/ 545 ftp://cpan.indigo.ie/pub/CPAN/ 546 http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN 547 ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN 548 http://sunsite.compapp.dcu.ie/pub/perl/ 549 ftp://sunsite.compapp.dcu.ie/pub/perl/ 550 551=item Italy 552 553 http://cpan.nettuno.it/ 554 http://gusp.dyndns.org/CPAN/ 555 ftp://gusp.dyndns.org/pub/CPAN 556 http://softcity.iol.it/cpan 557 ftp://softcity.iol.it/pub/cpan 558 ftp://ftp.unina.it/pub/Other/CPAN/CPAN/ 559 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/ 560 ftp://cis.uniRoma2.it/CPAN/ 561 ftp://ftp.edisontel.it/pub/CPAN_Mirror/ 562 http://cpan.flashnet.it/ 563 ftp://ftp.flashnet.it/pub/CPAN/ 564 565=item Latvia 566 567 http://kvin.lv/pub/CPAN/ 568 569=item Lithuania 570 571 ftp://ftp.unix.lt/pub/CPAN/ 572 573=item Netherlands 574 575 ftp://download.xs4all.nl/pub/mirror/CPAN/ 576 ftp://ftp.nl.uu.net/pub/CPAN/ 577 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/ 578 http://cpan.cybercomm.nl/ 579 ftp://mirror.cybercomm.nl/pub/CPAN 580 ftp://mirror.vuurwerk.nl/pub/CPAN/ 581 ftp://ftp.cpan.nl/pub/CPAN/ 582 http://ftp.easynet.nl/mirror/CPAN 583 ftp://ftp.easynet.nl/mirror/CPAN 584 http://archive.cs.uu.nl/mirror/CPAN/ 585 ftp://ftp.cs.uu.nl/mirror/CPAN/ 586 587=item Norway 588 589 ftp://ftp.uninett.no/pub/languages/perl/CPAN 590 ftp://ftp.uit.no/pub/languages/perl/cpan/ 591 592=item Poland 593 594 ftp://ftp.mega.net.pl/CPAN 595 ftp://ftp.man.torun.pl/pub/doc/CPAN/ 596 ftp://sunsite.icm.edu.pl/pub/CPAN/ 597 598=item Portugal 599 600 ftp://ftp.ua.pt/pub/CPAN/ 601 ftp://perl.di.uminho.pt/pub/CPAN/ 602 http://cpan.dei.uc.pt/ 603 ftp://ftp.dei.uc.pt/pub/CPAN 604 ftp://ftp.nfsi.pt/pub/CPAN 605 http://ftp.linux.pt/pub/mirrors/CPAN 606 ftp://ftp.linux.pt/pub/mirrors/CPAN 607 http://cpan.ip.pt/ 608 ftp://cpan.ip.pt/pub/cpan/ 609 http://cpan.telepac.pt/ 610 ftp://ftp.telepac.pt/pub/cpan/ 611 612=item Romania 613 614 ftp://ftp.bio-net.ro/pub/CPAN 615 ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/ 616 ftp://ftp.lug.ro/CPAN 617 ftp://ftp.roedu.net/pub/CPAN/ 618 ftp://ftp.dntis.ro/pub/cpan/ 619 ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/ 620 http://cpan.ambra.ro/ 621 ftp://ftp.ambra.ro/pub/CPAN 622 ftp://ftp.dnttm.ro/pub/CPAN/ 623 ftp://ftp.lasting.ro/pub/CPAN 624 ftp://ftp.timisoara.roedu.net/mirrors/CPAN/ 625 626=item Russia 627 628 ftp://ftp.chg.ru/pub/lang/perl/CPAN/ 629 http://cpan.rinet.ru/ 630 ftp://cpan.rinet.ru/pub/mirror/CPAN/ 631 ftp://ftp.aha.ru/pub/CPAN/ 632 ftp://ftp.corbina.ru/pub/CPAN/ 633 http://cpan.sai.msu.ru/ 634 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ 635 636=item Slovakia 637 638 ftp://ftp.cvt.stuba.sk/pub/CPAN/ 639 640=item Slovenia 641 642 ftp://ftp.arnes.si/software/perl/CPAN/ 643 644=item Spain 645 646 http://cpan.imasd.elmundo.es/ 647 ftp://ftp.rediris.es/mirror/CPAN/ 648 ftp://ftp.ri.telefonica-data.net/CPAN 649 ftp://ftp.etse.urv.es/pub/perl/ 650 651=item Sweden 652 653 http://ftp.du.se/CPAN/ 654 ftp://ftp.du.se/pub/CPAN/ 655 http://mirror.dataphone.se/CPAN 656 ftp://mirror.dataphone.se/pub/CPAN 657 ftp://ftp.sunet.se/pub/lang/perl/CPAN/ 658 659=item Switzerland 660 661 http://cpan.mirror.solnet.ch/ 662 ftp://ftp.solnet.ch/mirror/CPAN/ 663 ftp://ftp.danyk.ch/CPAN/ 664 ftp://sunsite.cnlab-switch.ch/mirror/CPAN/ 665 666=item Turkey 667 668 http://ftp.ulak.net.tr/perl/CPAN/ 669 ftp://ftp.ulak.net.tr/perl/CPAN 670 ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/ 671 672=item Ukraine 673 674 http://cpan.org.ua/ 675 ftp://cpan.org.ua/ 676 ftp://ftp.perl.org.ua/pub/CPAN/ 677 http://no-more.kiev.ua/CPAN/ 678 ftp://no-more.kiev.ua/pub/CPAN/ 679 680=item United Kingdom 681 682 http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN 683 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ 684 http://cpan.teleglobe.net/ 685 ftp://cpan.teleglobe.net/pub/CPAN 686 http://cpan.mirror.anlx.net/ 687 ftp://ftp.mirror.anlx.net/CPAN/ 688 http://cpan.etla.org/ 689 ftp://cpan.etla.org/pub/CPAN 690 ftp://ftp.demon.co.uk/pub/CPAN/ 691 http://cpan.m.flirble.org/ 692 ftp://ftp.flirble.org/pub/languages/perl/CPAN/ 693 ftp://ftp.plig.org/pub/CPAN/ 694 http://cpan.hambule.co.uk/ 695 http://cpan.mirrors.clockerz.net/ 696 ftp://ftp.clockerz.net/pub/CPAN/ 697 ftp://usit.shef.ac.uk/pub/packages/CPAN/ 698 699=back 700 701=head2 North America 702 703=over 4 704 705=item Canada 706 707=over 8 708 709=item Alberta 710 711 http://cpan.sunsite.ualberta.ca/ 712 ftp://cpan.sunsite.ualberta.ca/pub/CPAN/ 713 714=item Manitoba 715 716 http://theoryx5.uwinnipeg.ca/pub/CPAN/ 717 ftp://theoryx5.uwinnipeg.ca/pub/CPAN/ 718 719=item Nova Scotia 720 721 ftp://cpan.chebucto.ns.ca/pub/CPAN/ 722 723=item Ontario 724 725 ftp://ftp.nrc.ca/pub/CPAN/ 726 727=back 728 729=item Mexico 730 731 http://cpan.azc.uam.mx 732 ftp://cpan.azc.uam.mx/mirrors/CPAN 733 http://www.cpan.unam.mx/ 734 ftp://ftp.unam.mx/pub/CPAN 735 http://www.msg.com.mx/CPAN/ 736 ftp://ftp.msg.com.mx/pub/CPAN/ 737 738=item United States 739 740=over 8 741 742=item Alabama 743 744 http://mirror.hiwaay.net/CPAN/ 745 ftp://mirror.hiwaay.net/CPAN/ 746 747=item California 748 749 http://cpan.develooper.com/ 750 http://www.cpan.org/ 751 ftp://cpan.valueclick.com/pub/CPAN/ 752 http://www.mednor.net/ftp/pub/mirrors/CPAN/ 753 ftp://ftp.mednor.net/pub/mirrors/CPAN/ 754 http://mirrors.gossamer-threads.com/CPAN 755 ftp://cpan.nas.nasa.gov/pub/perl/CPAN/ 756 http://mirrors.kernel.org/cpan/ 757 ftp://mirrors.kernel.org/pub/CPAN 758 http://cpan-sj.viaverio.com/ 759 ftp://cpan-sj.viaverio.com/pub/CPAN/ 760 http://cpan.digisle.net/ 761 ftp://cpan.digisle.net/pub/CPAN 762 http://www.perl.com/CPAN/ 763 http://www.uberlan.net/CPAN 764 765=item Colorado 766 767 ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ 768 http://cpan.four10.com 769 770=item Delaware 771 772 http://ftp.lug.udel.edu/pub/CPAN 773 ftp://ftp.lug.udel.edu/pub/CPAN 774 775=item District of Columbia 776 777 ftp://ftp.dc.aleron.net/pub/CPAN/ 778 779=item Florida 780 781 ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/ 782 http://mirror.csit.fsu.edu/pub/CPAN/ 783 ftp://mirror.csit.fsu.edu/pub/CPAN/ 784 http://cpan.mirrors.nks.net/ 785 786=item Indiana 787 788 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/ 789 http://cpan.netnitco.net/ 790 ftp://cpan.netnitco.net/pub/mirrors/CPAN/ 791 http://archive.progeny.com/CPAN/ 792 ftp://archive.progeny.com/CPAN/ 793 http://fx.saintjoe.edu/pub/CPAN 794 ftp://ftp.saintjoe.edu/pub/CPAN 795 http://csociety-ftp.ecn.purdue.edu/pub/CPAN 796 ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN 797 798=item Kentucky 799 800 http://cpan.uky.edu/ 801 ftp://cpan.uky.edu/pub/CPAN/ 802 http://slugsite.louisville.edu/cpan 803 ftp://slugsite.louisville.edu/CPAN 804 805=item Massachusetts 806 807 http://mirrors.towardex.com/CPAN 808 ftp://mirrors.towardex.com/pub/CPAN 809 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ 810 811=item Michigan 812 813 ftp://cpan.cse.msu.edu/ 814 http://cpan.calvin.edu/pub/CPAN 815 ftp://cpan.calvin.edu/pub/CPAN 816 817=item Nevada 818 819 http://www.oss.redundant.com/pub/CPAN 820 ftp://www.oss.redundant.com/pub/CPAN 821 822=item New Jersey 823 824 http://ftp.cpanel.net/pub/CPAN/ 825 ftp://ftp.cpanel.net/pub/CPAN/ 826 http://cpan.teleglobe.net/ 827 ftp://cpan.teleglobe.net/pub/CPAN 828 829=item New York 830 831 http://cpan.belfry.net/ 832 http://cpan.erlbaum.net/ 833 ftp://cpan.erlbaum.net/ 834 http://cpan.thepirtgroup.com/ 835 ftp://cpan.thepirtgroup.com/ 836 ftp://ftp.stealth.net/pub/CPAN/ 837 http://www.rge.com/pub/languages/perl/ 838 ftp://ftp.rge.com/pub/languages/perl/ 839 840=item North Carolina 841 842 http://www.ibiblio.org/pub/languages/perl/CPAN 843 ftp://ftp.ibiblio.org/pub/languages/perl/CPAN 844 ftp://ftp.duke.edu/pub/perl/ 845 ftp://ftp.ncsu.edu/pub/mirror/CPAN/ 846 847=item Oklahoma 848 849 ftp://ftp.ou.edu/mirrors/CPAN/ 850 851=item Oregon 852 853 ftp://ftp.orst.edu/pub/CPAN 854 855=item Pennsylvania 856 857 http://ftp.epix.net/CPAN/ 858 ftp://ftp.epix.net/pub/languages/perl/ 859 http://mirrors.phenominet.com/pub/CPAN/ 860 ftp://mirrors.phenominet.com/pub/CPAN/ 861 http://cpan.pair.com/ 862 ftp://cpan.pair.com/pub/CPAN/ 863 ftp://carroll.cac.psu.edu/pub/CPAN/ 864 865=item Tennessee 866 867 ftp://ftp.sunsite.utk.edu/pub/CPAN/ 868 869=item Texas 870 871 http://ftp.sedl.org/pub/mirrors/CPAN/ 872 http://www.binarycode.org/cpan 873 ftp://mirror.telentente.com/pub/CPAN 874 http://mirrors.theonlinerecordstore.com/CPAN 875 876=item Utah 877 878 ftp://mirror.xmission.com/CPAN/ 879 880=item Virginia 881 882 http://cpan-du.viaverio.com/ 883 ftp://cpan-du.viaverio.com/pub/CPAN/ 884 http://mirrors.rcn.net/pub/lang/CPAN/ 885 ftp://mirrors.rcn.net/pub/lang/CPAN/ 886 http://perl.secsup.org/ 887 ftp://perl.secsup.org/pub/perl/ 888 http://noc.cvaix.com/mirrors/CPAN/ 889 890=item Washington 891 892 http://cpan.llarian.net/ 893 ftp://cpan.llarian.net/pub/CPAN/ 894 http://cpan.mirrorcentral.com/ 895 ftp://ftp.mirrorcentral.com/pub/CPAN/ 896 ftp://ftp-mirror.internap.com/pub/CPAN/ 897 898=item Wisconsin 899 900 http://mirror.sit.wisc.edu/pub/CPAN/ 901 ftp://mirror.sit.wisc.edu/pub/CPAN/ 902 http://mirror.aphix.com/CPAN 903 ftp://mirror.aphix.com/pub/CPAN 904 905=back 906 907=back 908 909=head2 Oceania 910 911=over 4 912 913=item Australia 914 915 http://ftp.planetmirror.com/pub/CPAN/ 916 ftp://ftp.planetmirror.com/pub/CPAN/ 917 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/ 918 ftp://cpan.topend.com.au/pub/CPAN/ 919 http://cpan.mirrors.ilisys.com.au 920 921=item New Zealand 922 923 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ 924 925=item United States 926 927 http://aniani.ifa.hawaii.edu/CPAN/ 928 ftp://aniani.ifa.hawaii.edu/CPAN/ 929 930=back 931 932=head2 South America 933 934=over 4 935 936=item Argentina 937 938 ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/ 939 http://www.linux.org.ar/mirrors/cpan 940 ftp://ftp.linux.org.ar/mirrors/cpan 941 942=item Brazil 943 944 ftp://cpan.pop-mg.com.br/pub/CPAN/ 945 ftp://ftp.matrix.com.br/pub/perl/CPAN/ 946 http://cpan.hostsul.com.br/ 947 ftp://cpan.hostsul.com.br/ 948 949=item Chile 950 951 http://cpan.netglobalis.net/ 952 ftp://cpan.netglobalis.net/pub/CPAN/ 953 954=back 955 956=head2 RSYNC Mirrors 957 958 www.linux.org.ar::cpan 959 theoryx5.uwinnipeg.ca::CPAN 960 ftp.shellhung.org::CPAN 961 rsync.nic.funet.fi::CPAN 962 ftp.u-paris10.fr::CPAN 963 mir1.ovh.net::CPAN 964 rsync://ftp.crihan.fr::CPAN 965 ftp.gwdg.de::FTP/languages/perl/CPAN/ 966 ftp.leo.org::CPAN 967 ftp.cbn.net.id::CPAN 968 rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN 969 ftp.iglu.org.il::CPAN 970 gusp.dyndns.org::cpan 971 ftp.kddlabs.co.jp::cpan 972 ftp.ayamura.org::pub/CPAN/ 973 mirror.leafbug.org::CPAN 974 rsync.en.com.sg::CPAN 975 mirror.averse.net::cpan 976 rsync.oss.eznetsols.org 977 ftp.kr.FreeBSD.org::CPAN 978 ftp.solnet.ch::CPAN 979 cpan.cdpa.nsysu.edu.tw::CPAN 980 cpan.teleglobe.net::CPAN 981 rsync://rsync.mirror.anlx.net::CPAN 982 ftp.sedl.org::cpan 983 ibiblio.org::CPAN 984 cpan-du.viaverio.com::CPAN 985 aniani.ifa.hawaii.edu::CPAN 986 archive.progeny.com::CPAN 987 rsync://slugsite.louisville.edu::CPAN 988 mirror.aphix.com::CPAN 989 cpan.teleglobe.net::CPAN 990 ftp.lug.udel.edu::cpan 991 mirrors.kernel.org::mirrors/CPAN 992 mirrors.phenominet.com::CPAN 993 cpan.pair.com::CPAN 994 cpan-sj.viaverio.com::CPAN 995 mirror.csit.fsu.edu::CPAN 996 csociety-ftp.ecn.purdue.edu::CPAN 997 998For an up-to-date listing of CPAN sites, 999see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES . 1000
1001=head1 Modules: Creation, Use, and Abuse 1002 1003(The following section is borrowed directly from Tim Bunce's modules 1004file, available at your nearest CPAN site.) 1005 1006Perl implements a class using a package, but the presence of a 1007package doesn't imply the presence of a class. A package is just a 1008namespace. A class is a package that provides subroutines that can be 1009used as methods. A method is just a subroutine that expects, as its 1010first argument, either the name of a package (for "static" methods), 1011or a reference to something (for "virtual" methods). 1012 1013A module is a file that (by convention) provides a class of the same 1014name (sans the .pm), plus an import method in that class that can be 1015called to fetch exported symbols. This module may implement some of 1016its methods by loading dynamic C or C++ objects, but that should be 1017totally transparent to the user of the module. Likewise, the module 1018might set up an AUTOLOAD function to slurp in subroutine definitions on 1019demand, but this is also transparent. Only the F<.pm> file is required to 1020exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about 1021the AUTOLOAD mechanism. 1022 1023=head2 Guidelines for Module Creation 1024 1025=over 4 1026 1027=item * 1028 1029Do similar modules already exist in some form? 1030 1031If so, please try to reuse the existing modules either in whole or 1032by inheriting useful features into a new class. If this is not 1033practical try to get together with the module authors to work on 1034extending or enhancing the functionality of the existing modules. 1035A perfect example is the plethora of packages in perl4 for dealing 1036with command line options. 1037 1038If you are writing a module to expand an already existing set of 1039modules, please coordinate with the author of the package. It 1040helps if you follow the same naming scheme and module interaction 1041scheme as the original author. 1042 1043=item * 1044 1045Try to design the new module to be easy to extend and reuse. 1046 1047Try to C<use warnings;> (or C<use warnings qw(...);>). 1048Remember that you can add C<no warnings qw(...);> to individual blocks 1049of code that need less warnings. 1050 1051Use blessed references. Use the two argument form of bless to bless 1052into the class name given as the first parameter of the constructor, 1053e.g.,: 1054 1055 sub new { 1056 my $class = shift; 1057 return bless {}, $class; 1058 } 1059 1060or even this if you'd like it to be used as either a static 1061or a virtual method. 1062 1063 sub new { 1064 my $self = shift; 1065 my $class = ref($self) || $self; 1066 return bless {}, $class; 1067 } 1068 1069Pass arrays as references so more parameters can be added later 1070(it's also faster). Convert functions into methods where 1071appropriate. Split large methods into smaller more flexible ones. 1072Inherit methods from other modules if appropriate. 1073 1074Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>. 1075Generally you can delete the C<eq 'FOO'> part with no harm at all. 1076Let the objects look after themselves! Generally, avoid hard-wired 1077class names as far as possible. 1078 1079Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and 1080C<< $r->func() >> would work (see L<perlbot> for more details). 1081 1082Use autosplit so little used or newly added functions won't be a 1083burden to programs that don't use them. Add test functions to 1084the module after __END__ either using AutoSplit or by saying: 1085 1086 eval join('',<main::DATA>) || die $@ unless caller(); 1087 1088Does your module pass the 'empty subclass' test? If you say 1089C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able 1090to use SUBCLASS in exactly the same way as YOURCLASS. For example, 1091does your application still work if you change: C<< $obj = YOURCLASS->new(); >> 1092into: C<< $obj = SUBCLASS->new(); >> ? 1093 1094Avoid keeping any state information in your packages. It makes it 1095difficult for multiple other packages to use yours. Keep state 1096information in objects. 1097 1098Always use B<-w>. 1099 1100Try to C<use strict;> (or C<use strict qw(...);>). 1101Remember that you can add C<no strict qw(...);> to individual blocks 1102of code that need less strictness. 1103 1104Always use B<-w>. 1105 1106Follow the guidelines in the perlstyle(1) manual. 1107 1108Always use B<-w>. 1109 1110=item * 1111 1112Some simple style guidelines 1113 1114The perlstyle manual supplied with Perl has many helpful points. 1115 1116Coding style is a matter of personal taste. Many people evolve their 1117style over several years as they learn what helps them write and 1118maintain good code. Here's one set of assorted suggestions that 1119seem to be widely used by experienced developers: 1120 1121Use underscores to separate words. It is generally easier to read 1122$var_names_like_this than $VarNamesLikeThis, especially for 1123non-native speakers of English. It's also a simple rule that works 1124consistently with VAR_NAMES_LIKE_THIS. 1125 1126Package/Module names are an exception to this rule. Perl informally 1127reserves lowercase module names for 'pragma' modules like integer 1128and strict. Other modules normally begin with a capital letter and 1129use mixed case with no underscores (need to be short and portable). 1130 1131You may find it helpful to use letter case to indicate the scope 1132or nature of a variable. For example: 1133 1134 $ALL_CAPS_HERE constants only (beware clashes with Perl vars) 1135 $Some_Caps_Here package-wide global/static 1136 $no_caps_here function scope my() or local() variables 1137 1138Function and method names seem to work best as all lowercase. 1139e.g., C<< $obj->as_string() >>. 1140 1141You can use a leading underscore to indicate that a variable or 1142function should not be used outside the package that defined it. 1143 1144=item * 1145 1146Select what to export. 1147 1148Do NOT export method names! 1149 1150Do NOT export anything else by default without a good reason! 1151 1152Exports pollute the namespace of the module user. If you must 1153export try to use @EXPORT_OK in preference to @EXPORT and avoid 1154short or common names to reduce the risk of name clashes. 1155 1156Generally anything not exported is still accessible from outside the 1157module using the ModuleName::item_name (or C<< $blessed_ref->method >>) 1158syntax. By convention you can use a leading underscore on names to 1159indicate informally that they are 'internal' and not for public use. 1160 1161(It is actually possible to get private functions by saying: 1162C<my $subref = sub { ... }; &$subref;>. But there's no way to call that 1163directly as a method, because a method must have a name in the symbol 1164table.) 1165 1166As a general rule, if the module is trying to be object oriented 1167then export nothing. If it's just a collection of functions then 1168@EXPORT_OK anything but use @EXPORT with caution. 1169 1170=item * 1171 1172Select a name for the module. 1173 1174This name should be as descriptive, accurate, and complete as 1175possible. Avoid any risk of ambiguity. Always try to use two or 1176more whole words. Generally the name should reflect what is special 1177about what the module does rather than how it does it. Please use 1178nested module names to group informally or categorize a module. 1179There should be a very good reason for a module not to have a nested name. 1180Module names should begin with a capital letter. 1181 1182Having 57 modules all called Sort will not make life easy for anyone 1183(though having 23 called Sort::Quick is only marginally better :-). 1184Imagine someone trying to install your module alongside many others. 1185If in any doubt ask for suggestions in comp.lang.perl.misc. 1186 1187If you are developing a suite of related modules/classes it's good 1188practice to use nested classes with a common prefix as this will 1189avoid namespace clashes. For example: Xyz::Control, Xyz::View, 1190Xyz::Model etc. Use the modules in this list as a naming guide. 1191 1192If adding a new module to a set, follow the original author's 1193standards for naming modules and the interface to methods in 1194those modules. 1195 1196If developing modules for private internal or project specific use, 1197that will never be released to the public, then you should ensure 1198that their names will not clash with any future public module. You 1199can do this either by using the reserved Local::* category or by 1200using a category name that includes an underscore like Foo_Corp::*. 1201 1202To be portable each component of a module name should be limited to 120311 characters. If it might be used on MS-DOS then try to ensure each is 1204unique in the first 8 characters. Nested modules make this easier. 1205 1206=item * 1207 1208Have you got it right? 1209 1210How do you know that you've made the right decisions? Have you 1211picked an interface design that will cause problems later? Have 1212you picked the most appropriate name? Do you have any questions? 1213 1214The best way to know for sure, and pick up many helpful suggestions, 1215is to ask someone who knows. Comp.lang.perl.misc is read by just about 1216all the people who develop modules and it's the best place to ask. 1217 1218All you need to do is post a short summary of the module, its 1219purpose and interfaces. A few lines on each of the main methods is 1220probably enough. (If you post the whole module it might be ignored 1221by busy people - generally the very people you want to read it!) 1222 1223Don't worry about posting if you can't say when the module will be 1224ready - just say so in the message. It might be worth inviting 1225others to help you, they may be able to complete it for you! 1226 1227=item * 1228 1229README and other Additional Files. 1230 1231It's well known that software developers usually fully document the 1232software they write. If, however, the world is in urgent need of 1233your software and there is not enough time to write the full 1234documentation please at least provide a README file containing: 1235 1236=over 10 1237 1238=item * 1239 1240A description of the module/package/extension etc. 1241 1242=item * 1243 1244A copyright notice - see below. 1245 1246=item * 1247 1248Prerequisites - what else you may need to have. 1249 1250=item * 1251 1252How to build it - possible changes to Makefile.PL etc. 1253 1254=item * 1255 1256How to install it. 1257 1258=item * 1259 1260Recent changes in this release, especially incompatibilities 1261 1262=item * 1263 1264Changes / enhancements you plan to make in the future. 1265 1266=back 1267 1268If the README file seems to be getting too large you may wish to 1269split out some of the sections into separate files: INSTALL, 1270Copying, ToDo etc. 1271 1272=over 4 1273 1274=item * 1275 1276Adding a Copyright Notice. 1277 1278How you choose to license your work is a personal decision. 1279The general mechanism is to assert your Copyright and then make 1280a declaration of how others may copy/use/modify your work. 1281 1282Perl, for example, is supplied with two types of licence: The GNU GPL 1283and The Artistic Licence (see the files README, Copying, and Artistic, 1284or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT 1285just using the GNU GPL. 1286 1287My personal recommendation, out of respect for Larry, Perl, and the 1288Perl community at large is to state something simply like: 1289 1290 Copyright (c) 1995 Your Name. All rights reserved. 1291 This program is free software; you can redistribute it and/or 1292 modify it under the same terms as Perl itself. 1293 1294This statement should at least appear in the README file. You may 1295also wish to include it in a Copying file and your source files. 1296Remember to include the other words in addition to the Copyright. 1297 1298=item * 1299 1300Give the module a version/issue/release number. 1301 1302To be fully compatible with the Exporter and MakeMaker modules you 1303should store your module's version number in a non-my package 1304variable called $VERSION. This should be a floating point 1305number with at least two digits after the decimal (i.e., hundredths, 1306e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version. 1307See L<Exporter> for details. 1308 1309It may be handy to add a function or method to retrieve the number. 1310Use the number in announcements and archive file names when 1311releasing the module (ModuleName-1.02.tar.Z). 1312See perldoc ExtUtils::MakeMaker.pm for details. 1313 1314=item * 1315 1316How to release and distribute a module. 1317 1318It's good idea to post an announcement of the availability of your 1319module (or the module itself if small) to the comp.lang.perl.announce 1320Usenet newsgroup. This will at least ensure very wide once-off 1321distribution. 1322 1323If possible, register the module with CPAN. You should 1324include details of its location in your announcement. 1325 1326Some notes about ftp archives: Please use a long descriptive file 1327name that includes the version number. Most incoming directories 1328will not be readable/listable, i.e., you won't be able to see your 1329file after uploading it. Remember to send your email notification 1330message as soon as possible after uploading else your file may get 1331deleted automatically. Allow time for the file to be processed 1332and/or check the file has been processed before announcing its 1333location. 1334 1335FTP Archives for Perl Modules: 1336 1337Follow the instructions and links on: 1338 1339 http://www.cpan.org/modules/00modlist.long.html 1340 http://www.cpan.org/modules/04pause.html 1341 1342or upload to one of these sites: 1343 1344 https://pause.kbx.de/pause/ 1345 http://pause.perl.org/pause/ 1346 1347and notify <modules@perl.org>. 1348 1349By using the WWW interface you can ask the Upload Server to mirror 1350your modules from your ftp or WWW site into your own directory on 1351CPAN! 1352 1353Please remember to send me an updated entry for the Module list! 1354 1355=item * 1356 1357Take care when changing a released module. 1358 1359Always strive to remain compatible with previous released versions. 1360Otherwise try to add a mechanism to revert to the 1361old behavior if people rely on it. Document incompatible changes. 1362 1363=back 1364 1365=back 1366 1367=head2 Guidelines for Converting Perl 4 Library Scripts into Modules 1368 1369=over 4 1370 1371=item * 1372 1373There is no requirement to convert anything. 1374 1375If it ain't broke, don't fix it! Perl 4 library scripts should 1376continue to work with no problems. You may need to make some minor 1377changes (like escaping non-array @'s in double quoted strings) but 1378there is no need to convert a .pl file into a Module for just that. 1379 1380=item * 1381 1382Consider the implications. 1383 1384All Perl applications that make use of the script will need to 1385be changed (slightly) if the script is converted into a module. Is 1386it worth it unless you plan to make other changes at the same time? 1387 1388=item * 1389 1390Make the most of the opportunity. 1391 1392If you are going to convert the script to a module you can use the 1393opportunity to redesign the interface. The guidelines for module 1394creation above include many of the issues you should consider. 1395 1396=item * 1397 1398The pl2pm utility will get you started. 1399 1400This utility will read *.pl files (given as parameters) and write 1401corresponding *.pm files. The pl2pm utilities does the following: 1402 1403=over 10 1404 1405=item * 1406 1407Adds the standard Module prologue lines 1408 1409=item * 1410 1411Converts package specifiers from ' to :: 1412 1413=item * 1414 1415Converts die(...) to croak(...) 1416 1417=item * 1418 1419Several other minor changes 1420 1421=back 1422 1423Being a mechanical process pl2pm is not bullet proof. The converted 1424code will need careful checking, especially any package statements. 1425Don't delete the original .pl file till the new .pm one works! 1426 1427=back 1428 1429=head2 Guidelines for Reusing Application Code 1430 1431=over 4 1432 1433=item * 1434 1435Complete applications rarely belong in the Perl Module Library. 1436 1437=item * 1438 1439Many applications contain some Perl code that could be reused. 1440 1441Help save the world! Share your code in a form that makes it easy 1442to reuse. 1443 1444=item * 1445 1446Break-out the reusable code into one or more separate module files. 1447 1448=item * 1449 1450Take the opportunity to reconsider and redesign the interfaces. 1451 1452=item * 1453 1454In some cases the 'application' can then be reduced to a small 1455 1456fragment of code built on top of the reusable modules. In these cases 1457the application could invoked as: 1458 1459 % perl -e 'use Module::Name; method(@ARGV)' ... 1460or 1461 % perl -mModule::Name ... (in perl5.002 or higher) 1462 1463=back 1464 1465=head1 NOTE 1466 1467Perl does not enforce private and public parts of its modules as you may 1468have been used to in other languages like C++, Ada, or Modula-17. Perl 1469doesn't have an infatuation with enforced privacy. It would prefer 1470that you stayed out of its living room because you weren't invited, not 1471because it has a shotgun. 1472 1473The module and its user have a contract, part of which is common law, 1474and part of which is "written". Part of the common law contract is 1475that a module doesn't pollute any namespace it wasn't asked to. The 1476written contract for the module (A.K.A. documentation) may make other 1477provisions. But then you know when you C<use RedefineTheWorld> that 1478you're redefining the world and willing to take the consequences. 1479EOF 1480 1481close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!"; 1482close OUT or warn "$0: failed to close OUT (perlmodlib.pod): $!"; 1483 1484