5 open (OUT, ">perlmodlib.tmp") or die $!;
6 my (@pragma, @mod, @MANIFEST);
8 open (MANIFEST, "../MANIFEST") or die $!;
9 @MANIFEST = grep !m</(?:t|demo)/>, <MANIFEST>;
10 push @MANIFEST, 'lib/Config.pod', 'lib/Errno.pm', 'lib/lib.pm',
11 'lib/DynaLoader.pm', 'lib/XSLoader.pm';
15 next unless s|^lib/|| or m|^ext/|;
16 my ($origfilename) = ($filename) = m|^(\S+)|;
17 $filename =~ s|^[^/]+/|| if $filename =~ s|^ext/||;
18 next unless $filename =~ m!\.p(m|od)$!;
19 unless (open (MOD, "../lib/$filename")) {
20 unless (open (MOD, "../$origfilename")) {
21 warn "Couldn't open ../$origfilename: $!";
24 $filename = $origfilename;
33 next unless /^=head1 NAME/;
39 warn "$filename missing =head1 NAME (okay if there is respective .pod)\n";
46 my $perlname = $filename;
47 $perlname =~ s!^.*\b(ext|lib)/!!;
48 $perlname =~ s!\.p(m|od)$!!;
49 $perlname =~ s!\b(\w+)/\1\b!$1!;
50 $perlname =~ s!/!::!g;
52 ($name, $thing) = split / --? /, $title, 2;
54 unless ($name and $thing) {
55 warn "$filename missing name\n" unless $name;
56 warn "$filename missing thing\n" unless $thing;
61 $thing =~ s/^perl pragma to //i;
62 $thing = ucfirst($thing);
63 $title = "=item $perlname\n\n$thing\n\n";
65 if ($filename =~ /[A-Z]/) {
74 Generated by perlmodlib.PL -- DO NOT EDIT!
78 perlmodlib - constructing new Perl modules and finding existing ones
80 =head1 THE PERL MODULE LIBRARY
82 Many modules are included in the Perl distribution. These are described
83 below, and all end in F<.pm>. You may discover compiled library
84 files (usually ending in F<.so>) or small pieces of modules to be
85 autoloaded (ending in F<.al>); these were automatically generated
86 by the installation process. You may also discover files in the
87 library directory that end in either F<.pl> or F<.ph>. These are
88 old libraries supplied so that old programs that use them still
89 run. The F<.pl> files will all eventually be converted into standard
90 modules, and the F<.ph> files made by B<h2ph> will probably end up
91 as extension modules made by B<h2xs>. (Some F<.ph> values may
92 already be available through the POSIX, Errno, or Fcntl modules.)
93 The B<pl2pm> file in the distribution may help in your conversion,
94 but it's just a mechanical process and therefore far from bulletproof.
96 =head2 Pragmatic Modules
98 They work somewhat like compiler directives (pragmata) in that they
99 tend to affect the compilation of your program, and thus will usually
100 work well only when used within a C<use>, or C<no>. Most of these
101 are lexically scoped, so an inner BLOCK may countermand them
108 which lasts until the end of that BLOCK.
110 Some pragmas are lexically scoped--typically those that affect the
111 C<$^H> hints variable. Others affect the current package instead,
112 like C<use vars> and C<use subs>, which allow you to predeclare a
113 variables or subroutines within a particular I<file> rather than
114 just a block. Such declarations are effective for the entire file
115 for which they were declared. You cannot rescind them with C<no
118 The following pragmas are defined (and have their own documentation).
124 print OUT $_ for (sort @pragma);
129 =head2 Standard Modules
131 Standard, bundled modules are all expected to behave in a well-defined
132 manner with respect to namespace pollution because they use the
133 Exporter module. See their own documentation for details.
135 It's possible that not all modules listed below are installed on your
136 system. For example, the GDBM_File module will not be installed if you
137 don't have the gdbm library.
143 print OUT $_ for (sort @mod);
148 To find out I<all> modules installed on your system, including
149 those without documentation or outside the standard release,
152 % find `perl -Te 'print "@INC"'` -name '*.pm' -print
154 (The -T is here to prevent '.' from being listed in @INC.)
155 They should all have their own documentation installed and accessible
156 via your system man(1) command. If you do not have a B<find>
157 program, you can use the Perl B<find2perl> program instead, which
158 generates Perl code as output you can run through perl. If you
159 have a B<man> program but it doesn't find your modules, you'll have
160 to fix your manpath. See L<perl> for details. If you have no
161 system B<man> command, you might try the B<perldoc> program.
163 Note also that the command C<perldoc perllocal> gives you a (possibly
164 incomplete) list of the modules that have been further installed on
165 your system. (The perllocal.pod file is updated by the standard MakeMaker
168 =head2 Extension Modules
170 Extension modules are written in C (or a mix of Perl and C). They
171 are usually dynamically loaded into Perl if and when you need them,
172 but may also be linked in statically. Supported extension modules
173 include Socket, Fcntl, and POSIX.
175 Many popular C extension modules do not come bundled (at least, not
176 completely) due to their sizes, volatility, or simply lack of time
177 for adequate testing and configuration across the multitude of
178 platforms on which Perl was beta-tested. You are encouraged to
179 look for them on CPAN (described below), or using web search engines
180 like Alta Vista or Google.
184 CPAN stands for Comprehensive Perl Archive Network; it's a globally
185 replicated trove of Perl materials, including documentation, style
186 guides, tricks and traps, alternate ports to non-Unix systems and
187 occasional binary distributions for these. Search engines for
188 CPAN can be found at http://www.cpan.org/
190 Most importantly, CPAN includes around a thousand unbundled modules,
191 some of which require a C compiler to build. Major categories of
198 Language Extensions and Documentation Tools
206 Operating System Interfaces
210 Networking, Device Control (modems) and InterProcess Communication
214 Data Types and Data Type Utilities
226 Interfaces to / Emulations of Other Programming Languages
230 File Names, File Systems and File Locking (see also File Handles)
234 String Processing, Language Text Processing, Parsing, and Searching
238 Option, Argument, Parameter, and Configuration File Processing
242 Internationalization and Locale
246 Authentication, Security, and Encryption
250 World Wide Web, HTML, HTTP, CGI, MIME
254 Server and Daemon Utilities
258 Archiving and Compression
262 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
270 Control Flow Utilities (callbacks and exceptions etc)
274 File Handle and Input/Output Stream Utilities
278 Miscellaneous Modules
282 The list of the registered CPAN sites as of this writing follows.
283 Please note that the sorting order is alphabetical on fields:
295 and thus the North American servers happen to be listed between the
296 European and the South American sites.
298 You should try to choose one close to you.
306 ftp://ftp.is.co.za/programming/perl/CPAN/
307 ftp://ftp.mweb.co.za/pub/mirrors/cpan/
308 ftp://ftp.saix.net/pub/CPAN/
309 ftp://ftp.sun.ac.za/CPAN/CPAN/
319 ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
320 http://www2.linuxforum.net/mirror/CPAN/
321 http://cpan.shellhung.org/
322 ftp://ftp.shellhung.org/pub/CPAN
326 http://cpan.in.freeos.com
327 ftp://cpan.in.freeos.com/pub/CPAN/
331 http://cpan.itb.web.id/
332 ftp://mirrors.piksi.itb.ac.id/CPAN/
333 http://cpan.cbn.net.id/
334 ftp://ftp.cbn.net.id/mirror/CPAN
335 http://CPAN.mweb.co.id/
336 ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
340 http://www.iglu.org.il:/pub/CPAN/
341 ftp://ftp.iglu.org.il/pub/CPAN/
342 http://cpan.lerner.co.il/
343 http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
344 ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
348 ftp://ftp.u-aizu.ac.jp/pub/CPAN
349 ftp://ftp.kddlabs.co.jp/CPAN/
350 http://mirror.nucba.ac.jp/mirror/Perl/
351 ftp://mirror.nucba.ac.jp/mirror/Perl/
352 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
353 ftp://ftp.ayamura.org/pub/CPAN/
354 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
355 ftp://ftp.dti.ad.jp/pub/lang/CPAN/
356 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
360 http://mirror.Mazic.org/pub/CPAN
361 ftp://mirror.Mazic.org/pub/CPAN
365 http://www.adzu.edu.ph/CPAN
367 =item Russian Federation
370 ftp://cpan.tomsk.ru/pub/CPAN
374 ftp://ftp.isu.net.sa/pub/CPAN/
378 http://cpan.hjc.edu.sg
379 http://mirror.averse.net/pub/CPAN
380 ftp://mirror.averse.net/pub/CPAN
384 http://CPAN.bora.net/
385 ftp://ftp.bora.net/pub/CPAN/
386 http://ftp.kornet.net/pub/CPAN/
387 ftp://ftp.kornet.net/pub/CPAN/
388 ftp://ftp.nuri.net/pub/CPAN/
389 http://ftp.xgate.co.kr/cpan/
390 ftp://ftp.xgate.co.kr/pub/mirror/CPAN
394 ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN
395 ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
396 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
397 http://ftp.tku.edu.tw/pub/CPAN/
398 ftp://ftp.tku.edu.tw/pub/CPAN/
402 ftp://ftp.loxinfo.co.th/pub/cpan/
403 ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
407 =head2 Central America
413 ftp://ftp.linux.co.cr/mirrors/CPAN/
414 http://ftp.ucr.ac.cr/Unix/CPAN/
415 ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
425 ftp://ftp.tuwien.ac.at/pub/CPAN/
429 http://ftp.easynet.be/pub/CPAN/
430 ftp://ftp.easynet.be/pub/CPAN/
431 http://cpan.skynet.be
432 ftp://ftp.skynet.be/pub/CPAN
433 ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
437 http://cpan.lirex.net/
438 ftp://ftp.lirex.net/pub/mirrors/CPAN
442 http://ftp.linux.hr/pub/CPAN/
443 ftp://ftp.linux.hr/pub/CPAN/
447 http://ftp.fi.muni.cz/pub/CPAN/
448 ftp://ftp.fi.muni.cz/pub/CPAN/
449 ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
453 http://mirrors.sunsite.dk/cpan/
454 ftp://sunsite.dk/mirrors/cpan/
455 http://cpan.cybercity.dk
456 http://www.cpan.dk/CPAN/
457 ftp://www.cpan.dk/ftp.cpan.org/CPAN/
461 ftp://ftp.ut.ee/pub/languages/perl/CPAN/
465 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
466 http://cpan.kpnqwest.fi/
470 http://ftp.u-paris10.fr/perl/CPAN
471 ftp://ftp.u-paris10.fr/perl/CPAN
472 http://cpan.mirrors.easynet.fr/
473 ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
474 ftp://ftp.club-internet.fr/pub/perl/CPAN/
476 ftp://ftp.lip6.fr/pub/perl/CPAN/
477 ftp://ftp.oleane.net/pub/mirrors/CPAN/
478 ftp://ftp.pasteur.fr/pub/computing/CPAN/
479 http://mir2.ovh.net/ftp.cpan.org
480 ftp://mir1.ovh.net/ftp.cpan.org
481 http://ftp.u-strasbg.fr/CPAN
482 ftp://ftp.u-strasbg.fr/CPAN
484 ftp://cpan.cict.fr/pub/CPAN/
485 ftp://ftp.uvsq.fr/pub/perl/CPAN/
489 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
490 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
491 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
492 ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
493 http://pandemonium.tiscali.de/pub/CPAN/
494 ftp://pandemonium.tiscali.de/pub/CPAN/
495 http://ftp.gwdg.de/pub/languages/perl/CPAN/
496 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
497 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
498 ftp://ftp.leo.org/pub/CPAN/
499 http://cpan.noris.de/
500 ftp://cpan.noris.de/pub/CPAN/
501 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
502 ftp://ftp.gmd.de/mirrors/CPAN/
506 ftp://ftp.acn.gr/pub/lang/perl/CPAN
507 ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
508 ftp://ftp.ntua.gr/pub/lang/perl/
512 http://cpan.artifact.hu/
513 ftp://cpan.artifact.hu/CPAN/
514 http://ftp.kfki.hu/packages/perl/CPAN/
515 ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
519 http://ftp.rhnet.is/pub/CPAN/
520 ftp://ftp.rhnet.is/pub/CPAN/
524 http://cpan.indigo.ie/
525 ftp://cpan.indigo.ie/pub/CPAN/
526 http://sunsite.compapp.dcu.ie/pub/perl/
527 ftp://sunsite.compapp.dcu.ie/pub/perl/
531 http://cpan.nettuno.it/
532 http://gusp.dyndns.org/CPAN/
533 ftp://gusp.dyndns.org/pub/CPAN
534 http://softcity.iol.it/cpan
535 ftp://softcity.iol.it/pub/cpan
536 ftp://ftp.unina.it/pub/Other/CPAN/CPAN/
537 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
538 ftp://cis.uniRoma2.it/CPAN/
539 ftp://ftp.edisontel.it/pub/CPAN_Mirror/
540 ftp://ftp.flashnet.it/pub/CPAN/
544 http://kvin.lv/pub/CPAN/
548 ftp://ftp.unix.lt/pub/CPAN/
552 ftp://download.xs4all.nl/pub/mirror/CPAN/
553 ftp://ftp.nl.uu.net/pub/CPAN/
554 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
555 http://cpan.cybercomm.nl/
556 ftp://mirror.cybercomm.nl/pub/CPAN
557 ftp://ftp.cpan.nl/pub/CPAN/
558 http://ftp.easynet.nl/mirror/CPAN
559 ftp://ftp.easynet.nl/mirror/CPAN
560 http://archive.cs.uu.nl/mirror/CPAN/
561 ftp://ftp.cs.uu.nl/mirror/CPAN/
565 ftp://ftp.uninett.no/pub/languages/perl/CPAN
566 ftp://ftp.uit.no/pub/languages/perl/cpan/
570 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
571 ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
572 ftp://ftp.man.torun.pl/pub/doc/CPAN/
573 ftp://sunsite.icm.edu.pl/pub/CPAN/
577 ftp://ftp.ua.pt/pub/CPAN/
578 ftp://perl.di.uminho.pt/pub/CPAN/
579 http://cpan.dei.uc.pt/
580 ftp://ftp.dei.uc.pt/pub/CPAN
581 ftp://ftp.ist.utl.pt/pub/CPAN/
583 ftp://cpan.ip.pt/pub/cpan/
584 ftp://ftp.netc.pt/pub/CPAN/
585 ftp://ftp.up.pt/pub/CPAN
589 ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
590 ftp://ftp.dntis.ro/pub/cpan/
591 ftp://ftp.dnttm.ro/pub/CPAN/
592 ftp://ftp.lasting.ro/pub/CPAN
593 ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
597 ftp://ftp.chg.ru/pub/lang/perl/CPAN/
598 http://cpan.rinet.ru/
599 ftp://cpan.rinet.ru/pub/mirror/CPAN/
600 ftp://ftp.aha.ru/pub/CPAN/
601 http://cpan.sai.msu.ru/
602 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
606 http://ftp.cvt.stuba.sk/pub/CPAN/
607 ftp://ftp.cvt.stuba.sk/pub/CPAN/
611 ftp://ftp.arnes.si/software/perl/CPAN/
615 http://cpan.imasd.elmundo.es/
616 ftp://ftp.rediris.es/mirror/CPAN/
617 ftp://ftp.etse.urv.es/pub/perl/
621 http://ftp.du.se/CPAN/
622 ftp://ftp.du.se/pub/CPAN/
623 ftp://mirror.dataphone.se/pub/CPAN
624 ftp://ftp.sunet.se/pub/lang/perl/CPAN/
628 ftp://ftp.danyk.ch/CPAN/
629 ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
633 http://ftp.ulak.net.tr/perl/CPAN/
634 ftp://ftp.ulak.net.tr/perl/CPAN
635 ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
641 ftp://ftp.perl.org.ua/pub/CPAN/
645 http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
646 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
647 http://cpan.teleglobe.net/
648 ftp://cpan.teleglobe.net/pub/CPAN
649 http://cpan.crazygreek.co.uk
650 ftp://ftp.demon.co.uk/pub/CPAN/
651 http://cpan.m.flirble.org/
652 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
653 ftp://ftp.plig.org/pub/CPAN/
654 http://mirror.uklinux.net/CPAN/
655 ftp://mirror.uklinux.net/pub/CPAN/
656 http://cpan.mirrors.clockerz.net/
657 ftp://ftp.clockerz.net/pub/CPAN/
658 ftp://usit.shef.ac.uk/pub/packages/CPAN/
668 http://sunsite.ualberta.ca/pub/Mirror/CPAN/
669 ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
673 http://theoryx5.uwinnipeg.ca/pub/CPAN/
674 ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
678 ftp://cpan.chebucto.ns.ca/pub/CPAN/
682 ftp://ftp.crc.ca/pub/CPAN/
686 http://cpan.mirror.smartworker.org/
690 http://cpan.azc.uam.mx
691 ftp://cpan.azc.uam.mx/mirrors/CPAN
693 ftp://cpan.unam.mx/pub/CPAN
694 http://www.msg.com.mx/CPAN/
695 ftp://ftp.msg.com.mx/pub/CPAN/
705 http://mirror.hiwaay.net/CPAN/
706 ftp://mirror.hiwaay.net/CPAN/
710 http://cpan.develooper.com/
712 ftp://cpan.valueclick.com/pub/CPAN/
713 http://mirrors.gossamer-threads.com/CPAN
714 ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
715 http://mirrors.kernel.org/cpan/
716 ftp://mirrors.kernel.org/pub/CPAN
717 http://cpan.digisle.net/
718 ftp://cpan.digisle.net/pub/CPAN
719 http://www.perl.com/CPAN/
720 http://download.sourceforge.net/mirrors/CPAN/
724 ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
728 http://ftp.lug.udel.edu/pub/CPAN
729 ftp://ftp.lug.udel.edu/pub/CPAN
731 =item District of Columbia
733 ftp://ftp.dc.aleron.net/pub/CPAN/
737 ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
738 http://mirror.csit.fsu.edu/pub/CPAN/
739 ftp://mirror.csit.fsu.edu/pub/CPAN/
740 http://cpan.mirrors.nks.net/
744 http://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
745 ftp://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
749 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
750 http://cpan.netnitco.net/
751 ftp://cpan.netnitco.net/pub/mirrors/CPAN/
752 http://archive.progeny.com/CPAN/
753 ftp://archive.progeny.com/CPAN/
754 ftp://cpan.in-span.net/
755 http://csociety-ftp.ecn.purdue.edu/pub/CPAN
756 ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
761 ftp://cpan.uky.edu/pub/CPAN/
765 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
766 http://cpan.mirrors.netnumina.com/
767 ftp://mirrors.netnumina.com/cpan/
771 ftp://cpan.cse.msu.edu/
775 ftp://ftp.cpanel.net/pub/CPAN/
776 http://cpan.teleglobe.net/
777 ftp://cpan.teleglobe.net/pub/CPAN
781 ftp://ftp.exobit.org/pub/perl/CPAN
782 http://cpan.belfry.net/
783 http://cpan.thepirtgroup.com/
784 ftp://cpan.thepirtgroup.com/
785 ftp://ftp.stealth.net/pub/CPAN/
786 http://www.rge.com/pub/languages/perl/
787 ftp://ftp.rge.com/pub/languages/perl/
788 ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
792 ftp://ftp.duke.edu/pub/perl/
796 ftp://ftp.loaded.net/pub/CPAN/
800 ftp://ftp.ou.edu/mirrors/CPAN/
804 ftp://ftp.orst.edu/pub/CPAN
808 http://ftp.epix.net/CPAN/
809 ftp://ftp.epix.net/pub/languages/perl/
810 http://mirrors.phenominet.com/pub/CPAN/
811 ftp://mirrors.phenominet.com/pub/CPAN/
812 http://cpan.pair.com/
813 ftp://cpan.pair.com/pub/CPAN/
814 ftp://carroll.cac.psu.edu/pub/CPAN/
818 ftp://ftp.sunsite.utk.edu/pub/CPAN/
822 http://ftp.sedl.org/pub/mirrors/CPAN/
823 ftp://mirror.telentente.com/pub/CPAN
827 ftp://mirror.xmission.com/CPAN/
831 http://mirrors.rcn.net/pub/lang/CPAN/
832 ftp://mirrors.rcn.net/pub/lang/CPAN/
833 http://perl.secsup.org/
834 ftp://perl.secsup.org/pub/perl/
835 http://mirrors.phihost.com/CPAN/
836 ftp://mirrors.phihost.com/CPAN/
837 ftp://ruff.cs.jmu.edu/pub/CPAN/
838 http://perl.Liquidation.com/CPAN/
842 http://cpan.llarian.net/
843 ftp://cpan.llarian.net/pub/CPAN/
844 http://cpan.mirrorcentral.com/
845 ftp://ftp.mirrorcentral.com/pub/CPAN/
846 ftp://ftp-mirror.internap.com/pub/CPAN/
850 http://mirror.sit.wisc.edu/pub/CPAN/
851 ftp://mirror.sit.wisc.edu/pub/CPAN/
861 http://ftp.planetmirror.com/pub/CPAN/
862 ftp://ftp.planetmirror.com/pub/CPAN/
863 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
864 ftp://cpan.topend.com.au/pub/CPAN/
868 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
869 http://cpan.soa.co.nz/CPAN/
879 ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
880 http://ftp.fcaglp.unlp.edu.ar/pub/CPAN/
881 ftp://ftp.fcaglp.unlp.edu.ar/pub/CPAN/
885 ftp://cpan.pop-mg.com.br/pub/CPAN/
886 ftp://ftp.matrix.com.br/pub/perl/CPAN/
890 http://cpan.netglobalis.net/
891 ftp://cpan.netglobalis.net/pub/CPAN/
897 ftp.fcaglp.unlp.edu.ar::CPAN
898 cpan.mirror.smartworker.org::CPAN
899 theoryx5.uwinnipeg.ca::CPAN
900 ftp.shellhung.org::CPAN
902 ftp.u-paris10.fr::CPAN
904 ftp.gwdg.de::FTP/languages/perl/CPAN/
906 CPAN.piksi.itb.ac.id::CPAN
908 ftp.iglu.org.il::CPAN
909 gusp.dyndns.org::cpan
910 ftp.kddlabs.co.jp::cpan
911 ftp.ayamura.org::pub/CPAN/
912 mirror.averse.net::cpan
913 cpan.teleglobe.net::CPAN
915 archive.progeny.com::CPAN
916 cpan.teleglobe.net::CPAN
917 ftp.lug.udel.edu::cpan
918 mirrors.kernel.org::mirrors/CPAN
919 mirrors.phenominet.com::CPAN
920 mirror.csit.fsu.edu::CPAN
921 csociety-ftp.ecn.purdue.edu::CPAN
923 For an up-to-date listing of CPAN sites,
924 see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
926 =head1 Modules: Creation, Use, and Abuse
928 (The following section is borrowed directly from Tim Bunce's modules
929 file, available at your nearest CPAN site.)
931 Perl implements a class using a package, but the presence of a
932 package doesn't imply the presence of a class. A package is just a
933 namespace. A class is a package that provides subroutines that can be
934 used as methods. A method is just a subroutine that expects, as its
935 first argument, either the name of a package (for "static" methods),
936 or a reference to something (for "virtual" methods).
938 A module is a file that (by convention) provides a class of the same
939 name (sans the .pm), plus an import method in that class that can be
940 called to fetch exported symbols. This module may implement some of
941 its methods by loading dynamic C or C++ objects, but that should be
942 totally transparent to the user of the module. Likewise, the module
943 might set up an AUTOLOAD function to slurp in subroutine definitions on
944 demand, but this is also transparent. Only the F<.pm> file is required to
945 exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
946 the AUTOLOAD mechanism.
948 =head2 Guidelines for Module Creation
954 Do similar modules already exist in some form?
956 If so, please try to reuse the existing modules either in whole or
957 by inheriting useful features into a new class. If this is not
958 practical try to get together with the module authors to work on
959 extending or enhancing the functionality of the existing modules.
960 A perfect example is the plethora of packages in perl4 for dealing
961 with command line options.
963 If you are writing a module to expand an already existing set of
964 modules, please coordinate with the author of the package. It
965 helps if you follow the same naming scheme and module interaction
966 scheme as the original author.
970 Try to design the new module to be easy to extend and reuse.
972 Try to C<use warnings;> (or C<use warnings qw(...);>).
973 Remember that you can add C<no warnings qw(...);> to individual blocks
974 of code that need less warnings.
976 Use blessed references. Use the two argument form of bless to bless
977 into the class name given as the first parameter of the constructor,
982 return bless {}, $class;
985 or even this if you'd like it to be used as either a static
990 my $class = ref($self) || $self;
991 return bless {}, $class;
994 Pass arrays as references so more parameters can be added later
995 (it's also faster). Convert functions into methods where
996 appropriate. Split large methods into smaller more flexible ones.
997 Inherit methods from other modules if appropriate.
999 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1000 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1001 Let the objects look after themselves! Generally, avoid hard-wired
1002 class names as far as possible.
1004 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1005 C<< $r->func() >> would work (see L<perlbot> for more details).
1007 Use autosplit so little used or newly added functions won't be a
1008 burden to programs that don't use them. Add test functions to
1009 the module after __END__ either using AutoSplit or by saying:
1011 eval join('',<main::DATA>) || die $@ unless caller();
1013 Does your module pass the 'empty subclass' test? If you say
1014 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1015 to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1016 does your application still work if you change: C<$obj = new YOURCLASS;>
1017 into: C<$obj = new SUBCLASS;> ?
1019 Avoid keeping any state information in your packages. It makes it
1020 difficult for multiple other packages to use yours. Keep state
1021 information in objects.
1025 Try to C<use strict;> (or C<use strict qw(...);>).
1026 Remember that you can add C<no strict qw(...);> to individual blocks
1027 of code that need less strictness.
1031 Follow the guidelines in the perlstyle(1) manual.
1037 Some simple style guidelines
1039 The perlstyle manual supplied with Perl has many helpful points.
1041 Coding style is a matter of personal taste. Many people evolve their
1042 style over several years as they learn what helps them write and
1043 maintain good code. Here's one set of assorted suggestions that
1044 seem to be widely used by experienced developers:
1046 Use underscores to separate words. It is generally easier to read
1047 $var_names_like_this than $VarNamesLikeThis, especially for
1048 non-native speakers of English. It's also a simple rule that works
1049 consistently with VAR_NAMES_LIKE_THIS.
1051 Package/Module names are an exception to this rule. Perl informally
1052 reserves lowercase module names for 'pragma' modules like integer
1053 and strict. Other modules normally begin with a capital letter and
1054 use mixed case with no underscores (need to be short and portable).
1056 You may find it helpful to use letter case to indicate the scope
1057 or nature of a variable. For example:
1059 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
1060 $Some_Caps_Here package-wide global/static
1061 $no_caps_here function scope my() or local() variables
1063 Function and method names seem to work best as all lowercase.
1064 e.g., C<< $obj->as_string() >>.
1066 You can use a leading underscore to indicate that a variable or
1067 function should not be used outside the package that defined it.
1071 Select what to export.
1073 Do NOT export method names!
1075 Do NOT export anything else by default without a good reason!
1077 Exports pollute the namespace of the module user. If you must
1078 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1079 short or common names to reduce the risk of name clashes.
1081 Generally anything not exported is still accessible from outside the
1082 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1083 syntax. By convention you can use a leading underscore on names to
1084 indicate informally that they are 'internal' and not for public use.
1086 (It is actually possible to get private functions by saying:
1087 C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1088 directly as a method, because a method must have a name in the symbol
1091 As a general rule, if the module is trying to be object oriented
1092 then export nothing. If it's just a collection of functions then
1093 @EXPORT_OK anything but use @EXPORT with caution.
1097 Select a name for the module.
1099 This name should be as descriptive, accurate, and complete as
1100 possible. Avoid any risk of ambiguity. Always try to use two or
1101 more whole words. Generally the name should reflect what is special
1102 about what the module does rather than how it does it. Please use
1103 nested module names to group informally or categorize a module.
1104 There should be a very good reason for a module not to have a nested name.
1105 Module names should begin with a capital letter.
1107 Having 57 modules all called Sort will not make life easy for anyone
1108 (though having 23 called Sort::Quick is only marginally better :-).
1109 Imagine someone trying to install your module alongside many others.
1110 If in any doubt ask for suggestions in comp.lang.perl.misc.
1112 If you are developing a suite of related modules/classes it's good
1113 practice to use nested classes with a common prefix as this will
1114 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1115 Xyz::Model etc. Use the modules in this list as a naming guide.
1117 If adding a new module to a set, follow the original author's
1118 standards for naming modules and the interface to methods in
1121 If developing modules for private internal or project specific use,
1122 that will never be released to the public, then you should ensure
1123 that their names will not clash with any future public module. You
1124 can do this either by using the reserved Local::* category or by
1125 using a category name that includes an underscore like Foo_Corp::*.
1127 To be portable each component of a module name should be limited to
1128 11 characters. If it might be used on MS-DOS then try to ensure each is
1129 unique in the first 8 characters. Nested modules make this easier.
1133 Have you got it right?
1135 How do you know that you've made the right decisions? Have you
1136 picked an interface design that will cause problems later? Have
1137 you picked the most appropriate name? Do you have any questions?
1139 The best way to know for sure, and pick up many helpful suggestions,
1140 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1141 all the people who develop modules and it's the best place to ask.
1143 All you need to do is post a short summary of the module, its
1144 purpose and interfaces. A few lines on each of the main methods is
1145 probably enough. (If you post the whole module it might be ignored
1146 by busy people - generally the very people you want to read it!)
1148 Don't worry about posting if you can't say when the module will be
1149 ready - just say so in the message. It might be worth inviting
1150 others to help you, they may be able to complete it for you!
1154 README and other Additional Files.
1156 It's well known that software developers usually fully document the
1157 software they write. If, however, the world is in urgent need of
1158 your software and there is not enough time to write the full
1159 documentation please at least provide a README file containing:
1165 A description of the module/package/extension etc.
1169 A copyright notice - see below.
1173 Prerequisites - what else you may need to have.
1177 How to build it - possible changes to Makefile.PL etc.
1185 Recent changes in this release, especially incompatibilities
1189 Changes / enhancements you plan to make in the future.
1193 If the README file seems to be getting too large you may wish to
1194 split out some of the sections into separate files: INSTALL,
1201 Adding a Copyright Notice.
1203 How you choose to license your work is a personal decision.
1204 The general mechanism is to assert your Copyright and then make
1205 a declaration of how others may copy/use/modify your work.
1207 Perl, for example, is supplied with two types of licence: The GNU
1208 GPL and The Artistic Licence (see the files README, Copying, and
1209 Artistic). Larry has good reasons for NOT just using the GNU GPL.
1211 My personal recommendation, out of respect for Larry, Perl, and the
1212 Perl community at large is to state something simply like:
1214 Copyright (c) 1995 Your Name. All rights reserved.
1215 This program is free software; you can redistribute it and/or
1216 modify it under the same terms as Perl itself.
1218 This statement should at least appear in the README file. You may
1219 also wish to include it in a Copying file and your source files.
1220 Remember to include the other words in addition to the Copyright.
1224 Give the module a version/issue/release number.
1226 To be fully compatible with the Exporter and MakeMaker modules you
1227 should store your module's version number in a non-my package
1228 variable called $VERSION. This should be a floating point
1229 number with at least two digits after the decimal (i.e., hundredths,
1230 e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1231 See L<Exporter> for details.
1233 It may be handy to add a function or method to retrieve the number.
1234 Use the number in announcements and archive file names when
1235 releasing the module (ModuleName-1.02.tar.Z).
1236 See perldoc ExtUtils::MakeMaker.pm for details.
1240 How to release and distribute a module.
1242 It's good idea to post an announcement of the availability of your
1243 module (or the module itself if small) to the comp.lang.perl.announce
1244 Usenet newsgroup. This will at least ensure very wide once-off
1247 If possible, register the module with CPAN. You should
1248 include details of its location in your announcement.
1250 Some notes about ftp archives: Please use a long descriptive file
1251 name that includes the version number. Most incoming directories
1252 will not be readable/listable, i.e., you won't be able to see your
1253 file after uploading it. Remember to send your email notification
1254 message as soon as possible after uploading else your file may get
1255 deleted automatically. Allow time for the file to be processed
1256 and/or check the file has been processed before announcing its
1259 FTP Archives for Perl Modules:
1261 Follow the instructions and links on:
1263 http://www.cpan.org/modules/00modlist.long.html
1264 http://www.cpan.org/modules/04pause.html
1266 or upload to one of these sites:
1268 https://pause.kbx.de/pause/
1269 http://pause.perl.org/pause/
1271 and notify <modules@perl.org>.
1273 By using the WWW interface you can ask the Upload Server to mirror
1274 your modules from your ftp or WWW site into your own directory on
1277 Please remember to send me an updated entry for the Module list!
1281 Take care when changing a released module.
1283 Always strive to remain compatible with previous released versions.
1284 Otherwise try to add a mechanism to revert to the
1285 old behavior if people rely on it. Document incompatible changes.
1291 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1297 There is no requirement to convert anything.
1299 If it ain't broke, don't fix it! Perl 4 library scripts should
1300 continue to work with no problems. You may need to make some minor
1301 changes (like escaping non-array @'s in double quoted strings) but
1302 there is no need to convert a .pl file into a Module for just that.
1306 Consider the implications.
1308 All Perl applications that make use of the script will need to
1309 be changed (slightly) if the script is converted into a module. Is
1310 it worth it unless you plan to make other changes at the same time?
1314 Make the most of the opportunity.
1316 If you are going to convert the script to a module you can use the
1317 opportunity to redesign the interface. The guidelines for module
1318 creation above include many of the issues you should consider.
1322 The pl2pm utility will get you started.
1324 This utility will read *.pl files (given as parameters) and write
1325 corresponding *.pm files. The pl2pm utilities does the following:
1331 Adds the standard Module prologue lines
1335 Converts package specifiers from ' to ::
1339 Converts die(...) to croak(...)
1343 Several other minor changes
1347 Being a mechanical process pl2pm is not bullet proof. The converted
1348 code will need careful checking, especially any package statements.
1349 Don't delete the original .pl file till the new .pm one works!
1353 =head2 Guidelines for Reusing Application Code
1359 Complete applications rarely belong in the Perl Module Library.
1363 Many applications contain some Perl code that could be reused.
1365 Help save the world! Share your code in a form that makes it easy
1370 Break-out the reusable code into one or more separate module files.
1374 Take the opportunity to reconsider and redesign the interfaces.
1378 In some cases the 'application' can then be reduced to a small
1380 fragment of code built on top of the reusable modules. In these cases
1381 the application could invoked as:
1383 % perl -e 'use Module::Name; method(@ARGV)' ...
1385 % perl -mModule::Name ... (in perl5.002 or higher)
1391 Perl does not enforce private and public parts of its modules as you may
1392 have been used to in other languages like C++, Ada, or Modula-17. Perl
1393 doesn't have an infatuation with enforced privacy. It would prefer
1394 that you stayed out of its living room because you weren't invited, not
1395 because it has a shotgun.
1397 The module and its user have a contract, part of which is common law,
1398 and part of which is "written". Part of the common law contract is
1399 that a module doesn't pollute any namespace it wasn't asked to. The
1400 written contract for the module (A.K.A. documentation) may make other
1401 provisions. But then you know when you C<use RedefineTheWorld> that
1402 you're redefining the world and willing to take the consequences.
1405 close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
1406 close OUT or warn "$0: failed to close OUT (perlmodlib.tmp): $!";