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