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