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