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