Provide defined value for $TODO only where test is still failing.
[perl.git] / pod / perlmodlib.PL
1 #!../miniperl
2
3 use strict;
4 use warnings;
5
6 local $ENV{LC_ALL} = 'C';
7
8 my $Quiet;
9 @ARGV = grep { not($_ eq '-q' and $Quiet = 1) } @ARGV;
10
11 if (@ARGV) {
12     my $workdir = shift;
13     chdir $workdir
14         or die "Couldn't chdir to '$workdir': $!";
15 }
16 require './regen/regen_lib.pl';
17
18 # MANIFEST itself is Unix style filenames, so we have to assume that Unix style
19 # filenames will work.
20
21 open MANIFEST, '<', 'MANIFEST'
22     or die "Can't open MANIFEST: $!";
23 my @files =
24     grep !m#/perl.*\.pod#,
25     grep m#(?:\.pm|\.pod|_pm\.PL)#,
26     map {s/\s.*//s; $_}
27     grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo|corpus)/# }
28     <MANIFEST>;
29 close MANIFEST
30     or die "$0: failed to close MANIFEST: $!";
31
32 my $out = open_new('pod/perlmodlib.pod', undef,
33                    {by => "$0 extracting documentation",
34                     from => 'the Perl source files'}, 1);
35
36 my %exceptions = (
37     'abbrev' => 'Text::Abbrev',
38     'carp' => 'Carp',
39     'getopt' => 'Getopt::Std',
40     'Encode::MIME::NAME' => 'Encode::MIME::Name',
41     'libnetFAQ' => 'Net::libnetFAQ',
42 );
43
44 my (@pragma, @mod);
45
46 for my $filename (@files) {
47     unless (open MOD, '<', $filename) {
48         warn "Couldn't open $filename: $!";
49         next;
50     }
51
52     my ($name, $thing);
53     my $foundit = 0;
54     {
55         local $/ = "";
56         while (<MOD>) {
57             next unless /^=head1 NAME/;
58             $foundit++;
59             last;
60         }
61     }
62     unless ($foundit) {
63         next if pod_for_module_has_head1_NAME($filename);
64         die "p5p-controlled module $filename missing =head1 NAME\n"
65             if $filename !~ m{^(dist/|cpan/)}n # under our direct control
66             && $filename !~ m{/_[^/]+\z}       # not private
67             && $filename ne 'lib/meta_notation.pm'      # no pod
68             && $filename ne 'lib/overload/numbers.pm';  # no pod
69         warn "$filename missing =head1 NAME\n" unless $Quiet;
70         next;
71     }
72     my $title = <MOD>;
73     chomp $title;
74     close MOD
75         or die "Error closing $filename: $!";
76
77     ($name, $thing) = split /\s+--?\s+/, $title, 2;
78
79     unless ($name and $thing) {
80         warn "$filename missing name\n"  unless $name;
81         warn "$filename missing thing\n" unless $thing or $Quiet;
82         next;
83     }
84
85     $name =~ s/[^A-Za-z0-9_:\$<>].*//;
86     $name = $exceptions{$name} || $name;
87     $thing =~ s/^perl pragma to //i;
88     $thing = ucfirst $thing;
89     $title = "=item $name\n\n$thing\n\n";
90
91     if ($name =~ /[A-Z]/) {
92         push @mod, $title;
93     } else {
94         push @pragma, $title;
95     }
96 }
97
98 sub pod_for_module_has_head1_NAME {
99     my ($filename) = @_;
100     (my $pod_file = $filename) =~ s/\.pm\z/.pod/ or return 0;
101     return 0 if !-e $pod_file;
102     open my $fh, '<', $pod_file
103         or die "Can't open $pod_file for reading: $!\n";
104     local $/ = '';
105     while (my $para = <$fh>) {
106         return 1 if $para =~ /\A=head1 NAME$/m;
107     }
108     return 0;
109 }
110
111 # Much easier to special case it like this than special case the depending on
112 # and parsing lib/Config.pod, or special case opening configpm and finding its
113 # =head1 (which is not found with the $/="" above)
114 push @mod, "=item Config\n\nAccess Perl configuration information\n\n";
115
116
117 # The intent of using =cut as the heredoc terminator is to make the whole file
118 # parse as (reasonably) sane Pod as-is to anything that attempts to
119 # brute-force treat it as such. The content is already useful - this just
120 # makes it tidier, by stopping anything doing this mistaking the rest of the
121 # Perl code for Pod. eg http://search.cpan.org/dist/perl/pod/perlmodlib.PL
122
123 print $out <<'=cut';
124 =head1 NAME
125
126 perlmodlib - constructing new Perl modules and finding existing ones
127
128 =head1 THE PERL MODULE LIBRARY
129
130 Many modules are included in the Perl distribution.  These are described
131 below, and all end in F<.pm>.  You may discover compiled library
132 files (usually ending in F<.so>) or small pieces of modules to be
133 autoloaded (ending in F<.al>); these were automatically generated
134 by the installation process.  You may also discover files in the
135 library directory that end in either F<.pl> or F<.ph>.  These are
136 old libraries supplied so that old programs that use them still
137 run.  The F<.pl> files will all eventually be converted into standard
138 modules, and the F<.ph> files made by B<h2ph> will probably end up
139 as extension modules made by B<h2xs>.  (Some F<.ph> values may
140 already be available through the POSIX, Errno, or Fcntl modules.)
141 The B<pl2pm> file in the distribution may help in your conversion,
142 but it's just a mechanical process and therefore far from bulletproof.
143
144 =head2 Pragmatic Modules
145
146 They work somewhat like compiler directives (pragmata) in that they
147 tend to affect the compilation of your program, and thus will usually
148 work well only when used within a C<use>, or C<no>.  Most of these
149 are lexically scoped, so an inner BLOCK may countermand them
150 by saying:
151
152     no integer;
153     no strict 'refs';
154     no warnings;
155
156 which lasts until the end of that BLOCK.
157
158 Some pragmas are lexically scoped--typically those that affect the
159 C<$^H> hints variable.  Others affect the current package instead,
160 like C<use vars> and C<use subs>, which allow you to predeclare a
161 variables or subroutines within a particular I<file> rather than
162 just a block.  Such declarations are effective for the entire file
163 for which they were declared.  You cannot rescind them with C<no
164 vars> or C<no subs>.
165
166 The following pragmas are defined (and have their own documentation).
167
168 =over 12
169
170 =cut
171
172 print $out $_ for sort @pragma;
173
174 print $out <<'=cut';
175
176 =back
177
178 =head2 Standard Modules
179
180 Standard, bundled modules are all expected to behave in a well-defined
181 manner with respect to namespace pollution because they use the
182 Exporter module.  See their own documentation for details.
183
184 It's possible that not all modules listed below are installed on your
185 system. For example, the GDBM_File module will not be installed if you
186 don't have the gdbm library.
187
188 =over 12
189
190 =cut
191
192 print $out $_ for sort @mod;
193
194 print $out <<'=cut', "=cut\n";
195
196 =back
197
198 To find out I<all> modules installed on your system, including
199 those without documentation or outside the standard release,
200 just use the following command (under the default win32 shell,
201 double quotes should be used instead of single quotes).
202
203     % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
204       'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
205       no_chdir => 1 }, @INC'
206
207 (The -T is here to prevent '.' from being listed in @INC.)
208 They should all have their own documentation installed and accessible
209 via your system man(1) command.  If you do not have a B<find>
210 program, you can use the Perl B<find2perl> program instead, which
211 generates Perl code as output you can run through perl.  If you
212 have a B<man> program but it doesn't find your modules, you'll have
213 to fix your manpath.  See L<perl> for details.  If you have no
214 system B<man> command, you might try the B<perldoc> program.
215
216 Note also that the command C<perldoc perllocal> gives you a (possibly
217 incomplete) list of the modules that have been further installed on
218 your system. (The perllocal.pod file is updated by the standard MakeMaker
219 install process.)
220
221 =head2 Extension Modules
222
223 Extension modules are written in C (or a mix of Perl and C).  They
224 are usually dynamically loaded into Perl if and when you need them,
225 but may also be linked in statically.  Supported extension modules
226 include Socket, Fcntl, and POSIX.
227
228 Many popular C extension modules do not come bundled (at least, not
229 completely) due to their sizes, volatility, or simply lack of time
230 for adequate testing and configuration across the multitude of
231 platforms on which Perl was beta-tested.  You are encouraged to
232 look for them on CPAN (described below), or using web search engines
233 like Google or DuckDuckGo.
234
235 =head1 CPAN
236
237 CPAN stands for Comprehensive Perl Archive Network; it's a globally
238 replicated trove of Perl materials, including documentation, style
239 guides, tricks and traps, alternate ports to non-Unix systems and
240 occasional binary distributions for these.   Search engines for
241 CPAN can be found at http://www.cpan.org/
242
243 Most importantly, CPAN includes around a thousand unbundled modules,
244 some of which require a C compiler to build.  Major categories of
245 modules are:
246
247 =over
248
249 =item *
250
251 Language Extensions and Documentation Tools
252
253 =item *
254
255 Development Support
256
257 =item *
258
259 Operating System Interfaces
260
261 =item *
262
263 Networking, Device Control (modems) and InterProcess Communication
264
265 =item *
266
267 Data Types and Data Type Utilities
268
269 =item *
270
271 Database Interfaces
272
273 =item *
274
275 User Interfaces
276
277 =item *
278
279 Interfaces to / Emulations of Other Programming Languages
280
281 =item *
282
283 File Names, File Systems and File Locking (see also File Handles)
284
285 =item *
286
287 String Processing, Language Text Processing, Parsing, and Searching
288
289 =item *
290
291 Option, Argument, Parameter, and Configuration File Processing
292
293 =item *
294
295 Internationalization and Locale
296
297 =item *
298
299 Authentication, Security, and Encryption
300
301 =item *
302
303 World Wide Web, HTML, HTTP, CGI, MIME
304
305 =item *
306
307 Server and Daemon Utilities
308
309 =item *
310
311 Archiving and Compression
312
313 =item *
314
315 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
316
317 =item *
318
319 Mail and Usenet News
320
321 =item *
322
323 Control Flow Utilities (callbacks and exceptions etc)
324
325 =item *
326
327 File Handle and Input/Output Stream Utilities
328
329 =item *
330
331 Miscellaneous Modules
332
333 =back
334
335 The list of the registered CPAN sites follows.
336 Please note that the sorting order is alphabetical on fields:
337
338 Continent
339    |
340    |-->Country
341          |
342          |-->[state/province]
343                    |
344                    |-->ftp
345                    |
346                    |-->[http]
347
348 and thus the North American servers happen to be listed between the
349 European and the South American sites.
350
351 Registered CPAN sites
352
353 =for maintainers
354 Generated by Porting/make_modlib_cpan.pl
355
356 =head2 Africa
357
358 =over 4
359
360 =item South Africa
361
362   http://mirror.is.co.za/pub/cpan/
363   ftp://ftp.is.co.za/pub/cpan/
364   http://cpan.mirror.ac.za/
365   ftp://cpan.mirror.ac.za/
366   http://cpan.saix.net/
367   ftp://ftp.saix.net/pub/CPAN/
368   http://ftp.wa.co.za/pub/CPAN/
369   ftp://ftp.wa.co.za/pub/CPAN/
370
371 =item Uganda
372
373   http://mirror.ucu.ac.ug/cpan/
374
375 =item Zimbabwe
376
377   http://mirror.zol.co.zw/CPAN/
378   ftp://mirror.zol.co.zw/CPAN/
379
380 =back
381
382 =head2 Asia
383
384 =over 4
385
386 =item Bangladesh
387
388   http://mirror.dhakacom.com/CPAN/
389   ftp://mirror.dhakacom.com/CPAN/
390
391 =item China
392
393   http://cpan.communilink.net/
394   http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
395   ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
396   http://mirrors.hust.edu.cn/CPAN/
397   http://mirrors.neusoft.edu.cn/cpan/
398   http://mirror.lzu.edu.cn/CPAN/
399   http://mirrors.163.com/cpan/
400   http://mirrors.sohu.com/CPAN/
401   http://mirrors.ustc.edu.cn/CPAN/
402   ftp://mirrors.ustc.edu.cn/CPAN/
403   http://mirrors.xmu.edu.cn/CPAN/
404   ftp://mirrors.xmu.edu.cn/CPAN/
405   http://mirrors.zju.edu.cn/CPAN/
406
407 =item India
408
409   http://cpan.excellmedia.net/
410   http://perlmirror.indialinks.com/
411
412 =item Indonesia
413
414   http://kambing.ui.ac.id/cpan/
415   http://cpan.pesat.net.id/
416   http://mirror.poliwangi.ac.id/CPAN/
417   http://kartolo.sby.datautama.net.id/CPAN/
418   http://mirror.wanxp.id/cpan/
419
420 =item Iran
421
422   http://mirror.yazd.ac.ir/cpan/
423
424 =item Israel
425
426   http://biocourse.weizmann.ac.il/CPAN/
427
428 =item Japan
429
430   http://ftp.jaist.ac.jp/pub/CPAN/
431   ftp://ftp.jaist.ac.jp/pub/CPAN/
432   http://mirror.jre655.com/CPAN/
433   ftp://mirror.jre655.com/CPAN/
434   ftp://ftp.kddilabs.jp/CPAN/
435   http://ftp.nara.wide.ad.jp/pub/CPAN/
436   ftp://ftp.nara.wide.ad.jp/pub/CPAN/
437   http://ftp.riken.jp/lang/CPAN/
438   ftp://ftp.riken.jp/lang/CPAN/
439   ftp://ftp.u-aizu.ac.jp/pub/CPAN/
440   http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
441   ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
442
443 =item Kazakhstan
444
445   http://mirror.neolabs.kz/CPAN/
446   ftp://mirror.neolabs.kz/CPAN/
447
448 =item Philippines
449
450   http://mirror.pregi.net/CPAN/
451   ftp://mirror.pregi.net/CPAN/
452   http://mirror.rise.ph/cpan/
453   ftp://mirror.rise.ph/cpan/
454
455 =item Qatar
456
457   http://mirror.qnren.qa/CPAN/
458   ftp://mirror.qnren.qa/CPAN/
459
460 =item Republic of Korea
461
462   http://cpan.mirror.cdnetworks.com/
463   ftp://cpan.mirror.cdnetworks.com/CPAN/
464   http://ftp.kaist.ac.kr/pub/CPAN/
465   ftp://ftp.kaist.ac.kr/CPAN/
466   http://ftp.kr.freebsd.org/pub/CPAN/
467   ftp://ftp.kr.freebsd.org/pub/CPAN/
468   http://mirror.navercorp.com/CPAN/
469   http://ftp.neowiz.com/CPAN/
470   ftp://ftp.neowiz.com/CPAN/
471
472 =item Singapore
473
474   http://cpan.mirror.choon.net/
475   http://mirror.0x.sg/CPAN/
476   ftp://mirror.0x.sg/CPAN/
477
478 =item Taiwan
479
480   http://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
481   ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
482   http://cpan.stu.edu.tw/
483   ftp://ftp.stu.edu.tw/CPAN/
484   http://ftp.yzu.edu.tw/CPAN/
485   ftp://ftp.yzu.edu.tw/CPAN/
486   http://cpan.nctu.edu.tw/
487   ftp://cpan.nctu.edu.tw/
488   http://ftp.ubuntu-tw.org/mirror/CPAN/
489   ftp://ftp.ubuntu-tw.org/mirror/CPAN/
490
491 =item Turkey
492
493   http://cpan.ulak.net.tr/
494   ftp://ftp.ulak.net.tr/pub/perl/CPAN/
495   http://mirror.vit.com.tr/mirror/CPAN/
496   ftp://mirror.vit.com.tr/CPAN/
497
498 =item Viet Nam
499
500   http://mirrors.digipower.vn/CPAN/
501   http://mirror.downloadvn.com/cpan/
502   http://mirrors.vinahost.vn/CPAN/
503
504 =back
505
506 =head2 Europe
507
508 =over 4
509
510 =item Austria
511
512   http://cpan.inode.at/
513   ftp://cpan.inode.at/
514   http://mirror.easyname.at/cpan/
515   ftp://mirror.easyname.at/cpan/
516   http://gd.tuwien.ac.at/languages/perl/CPAN/
517   ftp://gd.tuwien.ac.at/pub/CPAN/
518
519 =item Belarus
520
521   http://ftp.byfly.by/pub/CPAN/
522   ftp://ftp.byfly.by/pub/CPAN/
523   http://mirror.datacenter.by/pub/CPAN/
524   ftp://mirror.datacenter.by/pub/CPAN/
525
526 =item Belgium
527
528   http://ftp.belnet.be/ftp.cpan.org/
529   ftp://ftp.belnet.be/mirror/ftp.cpan.org/
530   http://cpan.cu.be/
531   http://lib.ugent.be/CPAN/
532   http://cpan.weepeetelecom.be/
533
534 =item Bosnia and Herzegovina
535
536   http://cpan.mirror.ba/
537   ftp://ftp.mirror.ba/CPAN/
538
539 =item Bulgaria
540
541   http://mirrors.neterra.net/CPAN/
542   ftp://mirrors.neterra.net/CPAN/
543   http://mirrors.netix.net/CPAN/
544   ftp://mirrors.netix.net/CPAN/
545
546 =item Croatia
547
548   http://ftp.carnet.hr/pub/CPAN/
549   ftp://ftp.carnet.hr/pub/CPAN/
550
551 =item Czech Republic
552
553   http://mirror.dkm.cz/cpan/
554   ftp://mirror.dkm.cz/cpan/
555   ftp://ftp.fi.muni.cz/pub/CPAN/
556   http://mirrors.nic.cz/CPAN/
557   ftp://mirrors.nic.cz/pub/CPAN/
558   http://cpan.mirror.vutbr.cz/
559   ftp://mirror.vutbr.cz/cpan/
560
561 =item Denmark
562
563   http://www.cpan.dk/
564   http://mirrors.dotsrc.org/cpan/
565   ftp://mirrors.dotsrc.org/cpan/
566
567 =item Finland
568
569   ftp://ftp.funet.fi/pub/languages/perl/CPAN/
570
571 =item France
572
573   http://ftp.ciril.fr/pub/cpan/
574   ftp://ftp.ciril.fr/pub/cpan/
575   http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
576   ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
577   http://ftp.lip6.fr/pub/perl/CPAN/
578   ftp://ftp.lip6.fr/pub/perl/CPAN/
579   http://mirror.ibcp.fr/pub/CPAN/
580   ftp://ftp.oleane.net/pub/CPAN/
581   http://cpan.mirrors.ovh.net/ftp.cpan.org/
582   ftp://cpan.mirrors.ovh.net/ftp.cpan.org/
583   http://cpan.enstimac.fr/
584
585 =item Germany
586
587   http://mirror.23media.de/cpan/
588   ftp://mirror.23media.de/cpan/
589   http://artfiles.org/cpan.org/
590   ftp://artfiles.org/cpan.org/
591   http://mirror.bibleonline.ru/cpan/
592   http://mirror.checkdomain.de/CPAN/
593   ftp://mirror.checkdomain.de/CPAN/
594   http://cpan.noris.de/
595   http://mirror.de.leaseweb.net/CPAN/
596   ftp://mirror.de.leaseweb.net/CPAN/
597   http://cpan.mirror.euserv.net/
598   ftp://mirror.euserv.net/cpan/
599   http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
600   ftp://mirror.fraunhofer.de/CPAN/
601   ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
602   http://ftp.hosteurope.de/pub/CPAN/
603   ftp://ftp.hosteurope.de/pub/CPAN/
604   ftp://ftp.fu-berlin.de/unix/languages/perl/
605   http://ftp.gwdg.de/pub/languages/perl/CPAN/
606   ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
607   http://ftp.hawo.stw.uni-erlangen.de/CPAN/
608   ftp://ftp.hawo.stw.uni-erlangen.de/CPAN/
609   http://cpan.mirror.iphh.net/
610   ftp://cpan.mirror.iphh.net/pub/CPAN/
611   ftp://ftp.mpi-inf.mpg.de/pub/perl/CPAN/
612   http://cpan.netbet.org/
613   http://mirror.netcologne.de/cpan/
614   ftp://mirror.netcologne.de/cpan/
615   ftp://mirror.petamem.com/CPAN/
616   http://www.planet-elektronik.de/CPAN/
617   http://ftp.halifax.rwth-aachen.de/cpan/
618   ftp://ftp.halifax.rwth-aachen.de/cpan/
619   http://mirror.softaculous.com/cpan/
620   http://ftp.u-tx.net/CPAN/
621   ftp://ftp.u-tx.net/CPAN/
622   http://mirror.reismil.ch/CPAN/
623
624 =item Greece
625
626   http://cpan.cc.uoc.gr/mirrors/CPAN/
627   ftp://ftp.cc.uoc.gr/mirrors/CPAN/
628   http://ftp.ntua.gr/pub/lang/perl/
629   ftp://ftp.ntua.gr/pub/lang/perl/
630
631 =item Hungary
632
633   http://mirror.met.hu/CPAN/
634
635 =item Ireland
636
637   http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
638   ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
639
640 =item Italy
641
642   http://bo.mirror.garr.it/mirrors/CPAN/
643   ftp://ftp.eutelia.it/CPAN_Mirror/
644   http://cpan.panu.it/
645   ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
646   http://cpan.muzzy.it/
647
648 =item Latvia
649
650   http://kvin.lv/pub/CPAN/
651
652 =item Lithuania
653
654   http://ftp.litnet.lt/pub/CPAN/
655   ftp://ftp.litnet.lt/pub/CPAN/
656
657 =item Moldova
658
659   http://mirror.as43289.net/pub/CPAN/
660   ftp://mirror.as43289.net/pub/CPAN/
661
662 =item Netherlands
663
664   http://cpan.cs.uu.nl/
665   ftp://ftp.cs.uu.nl/pub/CPAN/
666   http://mirror.nl.leaseweb.net/CPAN/
667   ftp://mirror.nl.leaseweb.net/CPAN/
668   http://ftp.nluug.nl/languages/perl/CPAN/
669   ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
670   http://mirror.transip.net/CPAN/
671   ftp://mirror.transip.net/CPAN/
672   http://cpan.mirror.triple-it.nl/
673   http://ftp.tudelft.nl/cpan/
674   ftp://ftp.tudelft.nl/pub/CPAN/
675   ftp://download.xs4all.nl/pub/mirror/CPAN/
676
677 =item Norway
678
679   http://cpan.uib.no/
680   ftp://cpan.uib.no/pub/CPAN/
681   ftp://ftp.uninett.no/pub/languages/perl/CPAN/
682   http://cpan.vianett.no/
683
684 =item Poland
685
686   http://ftp.agh.edu.pl/CPAN/
687   ftp://ftp.agh.edu.pl/CPAN/
688   http://ftp.piotrkosoft.net/pub/mirrors/CPAN/
689   ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
690   ftp://ftp.ps.pl/pub/CPAN/
691   http://sunsite.icm.edu.pl/pub/CPAN/
692   ftp://sunsite.icm.edu.pl/pub/CPAN/
693
694 =item Portugal
695
696   http://cpan.dcc.fc.up.pt/
697   http://mirrors.fe.up.pt/pub/CPAN/
698   http://cpan.perl-hackers.net/
699   http://cpan.perl.pt/
700
701 =item Romania
702
703   http://mirrors.hostingromania.ro/cpan.org/
704   ftp://ftp.lug.ro/CPAN/
705   http://mirrors.m247.ro/CPAN/
706   http://mirrors.evowise.com/CPAN/
707   http://mirrors.teentelecom.net/CPAN/
708   ftp://mirrors.teentelecom.net/CPAN/
709   http://mirrors.xservers.ro/CPAN/
710
711 =item Russian Federation
712
713   ftp://ftp.aha.ru/CPAN/
714   http://cpan.rinet.ru/
715   ftp://cpan.rinet.ru/pub/mirror/CPAN/
716   http://cpan-mirror.rbc.ru/pub/CPAN/
717   http://mirror.rol.ru/CPAN/
718   http://cpan.uni-altai.ru/
719   http://cpan.webdesk.ru/
720   ftp://cpan.webdesk.ru/cpan/
721   http://mirror.yandex.ru/mirrors/cpan/
722   ftp://mirror.yandex.ru/mirrors/cpan/
723
724 =item Serbia
725
726   http://mirror.sbb.rs/CPAN/
727   ftp://mirror.sbb.rs/CPAN/
728
729 =item Slovakia
730
731   http://cpan.lnx.sk/
732   http://tux.rainside.sk/CPAN/
733   ftp://tux.rainside.sk/CPAN/
734
735 =item Slovenia
736
737   http://ftp.arnes.si/software/perl/CPAN/
738   ftp://ftp.arnes.si/software/perl/CPAN/
739
740 =item Spain
741
742   http://mirrors.evowise.com/CPAN/
743   http://osl.ugr.es/CPAN/
744   http://ftp.rediris.es/mirror/CPAN/
745   ftp://ftp.rediris.es/mirror/CPAN/
746
747 =item Sweden
748
749   http://ftp.acc.umu.se/mirror/CPAN/
750   ftp://ftp.acc.umu.se/mirror/CPAN/
751
752 =item Switzerland
753
754   http://www.pirbot.com/mirrors/cpan/
755   http://mirror.switch.ch/ftp/mirror/CPAN/
756   ftp://mirror.switch.ch/mirror/CPAN/
757
758 =item Ukraine
759
760   http://cpan.ip-connect.vn.ua/
761   ftp://cpan.ip-connect.vn.ua/mirror/cpan/
762
763 =item United Kingdom
764
765   http://cpan.mirror.anlx.net/
766   ftp://ftp.mirror.anlx.net/CPAN/
767   http://mirror.bytemark.co.uk/CPAN/
768   ftp://mirror.bytemark.co.uk/CPAN/
769   http://mirrors.coreix.net/CPAN/
770   http://cpan.etla.org/
771   ftp://cpan.etla.org/pub/CPAN/
772   http://cpan.cpantesters.org/
773   http://mirror.sax.uk.as61049.net/CPAN/
774   http://mirror.sov.uk.goscomb.net/CPAN/
775   http://www.mirrorservice.org/sites/cpan.perl.org/CPAN/
776   ftp://ftp.mirrorservice.org/sites/cpan.perl.org/CPAN/
777   http://mirror.ox.ac.uk/sites/www.cpan.org/
778   ftp://mirror.ox.ac.uk/sites/www.cpan.org/
779   http://ftp.ticklers.org/pub/CPAN/
780   ftp://ftp.ticklers.org/pub/CPAN/
781   http://cpan.mirrors.uk2.net/
782   ftp://mirrors.uk2.net/pub/CPAN/
783   http://mirror.ukhost4u.com/CPAN/
784
785 =back
786
787 =head2 North America
788
789 =over 4
790
791 =item Canada
792
793   http://CPAN.mirror.rafal.ca/
794   ftp://CPAN.mirror.rafal.ca/pub/CPAN/
795   http://mirror.csclub.uwaterloo.ca/CPAN/
796   ftp://mirror.csclub.uwaterloo.ca/CPAN/
797   http://mirrors.gossamer-threads.com/CPAN/
798   http://mirror.its.dal.ca/cpan/
799   ftp://mirror.its.dal.ca/cpan/
800   ftp://ftp.ottix.net/pub/CPAN/
801
802 =item Costa Rica
803
804   http://mirrors.ucr.ac.cr/CPAN/
805
806 =item Mexico
807
808   http://www.msg.com.mx/CPAN/
809   ftp://ftp.msg.com.mx/pub/CPAN/
810
811 =item United States
812
813 =over 8
814
815 =item Alabama
816
817   http://mirror.teklinks.com/CPAN/
818
819 =item Arizona
820
821   http://mirror.n5tech.com/CPAN/
822   http://mirrors.namecheap.com/CPAN/
823   ftp://mirrors.namecheap.com/CPAN/
824
825 =item California
826
827   http://cpan.develooper.com/
828   http://httpupdate127.cpanel.net/CPAN/
829   http://mirrors.sonic.net/cpan/
830   ftp://mirrors.sonic.net/cpan/
831   http://www.perl.com/CPAN/
832   http://cpan.yimg.com/
833
834 =item Idaho
835
836   http://mirrors.syringanetworks.net/CPAN/
837   ftp://mirrors.syringanetworks.net/CPAN/
838
839 =item Illinois
840
841   http://cpan.mirrors.hoobly.com/
842   http://mirror.team-cymru.org/CPAN/
843   ftp://mirror.team-cymru.org/CPAN/
844
845 =item Indiana
846
847   http://cpan.netnitco.net/
848   ftp://cpan.netnitco.net/pub/mirrors/CPAN/
849   ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
850
851 =item Kansas
852
853   http://mirrors.concertpass.com/cpan/
854
855 =item Massachusetts
856
857   http://mirrors.ccs.neu.edu/CPAN/
858
859 =item Michigan
860
861   http://cpan.cse.msu.edu/
862   ftp://cpan.cse.msu.edu/
863   http://httpupdate118.cpanel.net/CPAN/
864   http://mirrors-usa.go-parts.com/cpan/
865   http://ftp.wayne.edu/CPAN/
866   ftp://ftp.wayne.edu/CPAN/
867
868 =item New Hampshire
869
870   http://mirror.metrocast.net/cpan/
871
872 =item New Jersey
873
874   http://mirror.datapipe.net/CPAN/
875   ftp://mirror.datapipe.net/pub/CPAN/
876   http://www.hoovism.com/CPAN/
877   ftp://ftp.hoovism.com/CPAN/
878   http://cpan.mirror.nac.net/
879
880 =item New York
881
882   http://mirror.cc.columbia.edu/pub/software/cpan/
883   ftp://mirror.cc.columbia.edu/pub/software/cpan/
884   http://cpan.belfry.net/
885   http://cpan.erlbaum.net/
886   ftp://cpan.erlbaum.net/CPAN/
887   http://cpan.hexten.net/
888   ftp://cpan.hexten.net/
889   http://mirror.nyi.net/CPAN/
890   ftp://mirror.nyi.net/pub/CPAN/
891   http://noodle.portalus.net/CPAN/
892   ftp://noodle.portalus.net/CPAN/
893   http://mirrors.rit.edu/CPAN/
894   ftp://mirrors.rit.edu/CPAN/
895
896 =item North Carolina
897
898   http://httpupdate140.cpanel.net/CPAN/
899   http://mirrors.ibiblio.org/CPAN/
900
901 =item Oregon
902
903   http://ftp.osuosl.org/pub/CPAN/
904   ftp://ftp.osuosl.org/pub/CPAN/
905   http://mirror.uoregon.edu/CPAN/
906
907 =item Pennsylvania
908
909   http://cpan.pair.com/
910   ftp://cpan.pair.com/pub/CPAN/
911   http://cpan.mirrors.ionfish.org/
912
913 =item South Carolina
914
915   http://cpan.mirror.clemson.edu/
916
917 =item Texas
918
919   http://mirror.uta.edu/CPAN/
920
921 =item Utah
922
923   http://cpan.cs.utah.edu/
924   ftp://cpan.cs.utah.edu/CPAN/
925   ftp://mirror.xmission.com/CPAN/
926
927 =item Virginia
928
929   http://mirror.cogentco.com/pub/CPAN/
930   ftp://mirror.cogentco.com/pub/CPAN/
931   http://mirror.jmu.edu/pub/CPAN/
932   ftp://mirror.jmu.edu/pub/CPAN/
933   http://mirror.us.leaseweb.net/CPAN/
934   ftp://mirror.us.leaseweb.net/CPAN/
935
936 =item Washington
937
938   http://cpan.llarian.net/
939   ftp://cpan.llarian.net/pub/CPAN/
940
941 =item Wisconsin
942
943   http://cpan.mirrors.tds.net/
944   ftp://cpan.mirrors.tds.net/pub/CPAN/
945
946 =back
947
948 =back
949
950 =head2 Oceania
951
952 =over 4
953
954 =item Australia
955
956   http://mirror.as24220.net/pub/cpan/
957   ftp://mirror.as24220.net/pub/cpan/
958   http://cpan.mirrors.ilisys.com.au/
959   http://cpan.mirror.digitalpacific.com.au/
960   ftp://mirror.internode.on.net/pub/cpan/
961   http://mirror.optusnet.com.au/CPAN/
962   http://cpan.mirror.serversaustralia.com.au/
963   http://cpan.uberglobalmirror.com/
964   http://mirror.waia.asn.au/pub/cpan/
965
966 =item New Caledonia
967
968   http://cpan.lagoon.nc/pub/CPAN/
969   ftp://cpan.lagoon.nc/pub/CPAN/
970   http://cpan.nautile.nc/CPAN/
971   ftp://cpan.nautile.nc/CPAN/
972
973 =item New Zealand
974
975   ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
976   http://cpan.catalyst.net.nz/CPAN/
977   ftp://cpan.catalyst.net.nz/pub/CPAN/
978   http://cpan.inspire.net.nz/
979   ftp://cpan.inspire.net.nz/cpan/
980   http://mirror.webtastix.net/CPAN/
981   ftp://mirror.webtastix.net/CPAN/
982
983 =back
984
985 =head2 South America
986
987 =over 4
988
989 =item Argentina
990
991   http://cpan.mmgdesigns.com.ar/
992
993 =item Brazil
994
995   http://cpan.kinghost.net/
996   http://linorg.usp.br/CPAN/
997   http://mirror.nbtelecom.com.br/CPAN/
998
999 =item Chile
1000
1001   http://cpan.dcc.uchile.cl/
1002   ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
1003
1004 =back
1005
1006 =head2 RSYNC Mirrors
1007
1008                 rsync://ftp.is.co.za/IS-Mirror/ftp.cpan.org/
1009                 rsync://mirror.ac.za/CPAN/
1010                 rsync://mirror.zol.co.zw/CPAN/
1011                 rsync://mirror.dhakacom.com/CPAN/
1012                 rsync://mirrors.ustc.edu.cn/CPAN/
1013                 rsync://mirrors.xmu.edu.cn/CPAN/
1014                 rsync://kambing.ui.ac.id/CPAN/
1015                 rsync://ftp.jaist.ac.jp/pub/CPAN/
1016                 rsync://mirror.jre655.com/CPAN/
1017                 rsync://ftp.kddilabs.jp/cpan/
1018                 rsync://ftp.nara.wide.ad.jp/cpan/
1019                 rsync://ftp.riken.jp/cpan/
1020                 rsync://mirror.neolabs.kz/CPAN/
1021                 rsync://mirror.qnren.qa/CPAN/
1022                 rsync://ftp.neowiz.com/CPAN/
1023                 rsync://mirror.0x.sg/CPAN/
1024                 rsync://ftp.yzu.edu.tw/pub/CPAN/
1025                 rsync://ftp.ubuntu-tw.org/CPAN/
1026                 rsync://mirrors.digipower.vn/CPAN/
1027                 rsync://cpan.inode.at/CPAN/
1028                 rsync://ftp.byfly.by/CPAN/
1029                 rsync://mirror.datacenter.by/CPAN/
1030                 rsync://ftp.belnet.be/cpan/
1031                 rsync://cpan.mirror.ba/CPAN/
1032                 rsync://mirrors.neterra.net/CPAN/
1033                 rsync://mirrors.netix.net/CPAN/
1034                 rsync://mirror.dkm.cz/cpan/
1035                 rsync://mirrors.nic.cz/CPAN/
1036                 rsync://cpan.mirror.vutbr.cz/cpan/
1037                 rsync://rsync.nic.funet.fi/CPAN/
1038                 rsync://ftp.ciril.fr/pub/cpan/
1039                 rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
1040                 rsync://cpan.mirrors.ovh.net/CPAN/
1041                 rsync://mirror.de.leaseweb.net/CPAN/
1042                 rsync://mirror.euserv.net/cpan/
1043                 rsync://ftp-stud.hs-esslingen.de/CPAN/
1044                 rsync://ftp.gwdg.de/pub/languages/perl/CPAN/
1045                 rsync://ftp.hawo.stw.uni-erlangen.de/CPAN/
1046                 rsync://cpan.mirror.iphh.net/CPAN/
1047                 rsync://mirror.netcologne.de/cpan/
1048                 rsync://ftp.halifax.rwth-aachen.de/cpan/
1049                 rsync://ftp.ntua.gr/CPAN/
1050                 rsync://mirror.met.hu/CPAN/
1051                 rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN/
1052                 rsync://rsync.panu.it/CPAN/
1053                 rsync://mirror.as43289.net/CPAN/
1054                 rsync://rsync.cs.uu.nl/CPAN/
1055                 rsync://mirror.nl.leaseweb.net/CPAN/
1056                 rsync://ftp.nluug.nl/CPAN/
1057                 rsync://mirror.transip.net/CPAN/
1058                 rsync://cpan.uib.no/cpan/
1059                 rsync://cpan.vianett.no/CPAN/
1060                 rsync://cpan.perl-hackers.net/CPAN/
1061                 rsync://cpan.perl.pt/cpan/
1062                 rsync://mirrors.m247.ro/CPAN/
1063                 rsync://mirrors.teentelecom.net/CPAN/
1064                 rsync://cpan.webdesk.ru/CPAN/
1065                 rsync://mirror.yandex.ru/mirrors/cpan/
1066                 rsync://mirror.sbb.rs/CPAN/
1067                 rsync://ftp.acc.umu.se/mirror/CPAN/
1068                 rsync://rsync.pirbot.com/ftp/cpan/
1069                 rsync://cpan.ip-connect.vn.ua/CPAN/
1070                 rsync://rsync.mirror.anlx.net/CPAN/
1071                 rsync://mirror.bytemark.co.uk/CPAN/
1072                 rsync://mirror.sax.uk.as61049.net/CPAN/
1073                 rsync://rsync.mirrorservice.org/cpan.perl.org/CPAN/
1074                 rsync://ftp.ticklers.org/CPAN/
1075                 rsync://mirrors.uk2.net/CPAN/
1076                 rsync://CPAN.mirror.rafal.ca/CPAN/
1077                 rsync://mirror.csclub.uwaterloo.ca/CPAN/
1078                 rsync://mirrors.namecheap.com/CPAN/
1079                 rsync://mirrors.syringanetworks.net/CPAN/
1080                 rsync://mirror.team-cymru.org/CPAN/
1081                 rsync://debian.cse.msu.edu/cpan/
1082                 rsync://mirrors-usa.go-parts.com/mirrors/cpan/
1083                 rsync://rsync.hoovism.com/CPAN/
1084                 rsync://mirror.cc.columbia.edu/cpan/
1085                 rsync://noodle.portalus.net/CPAN/
1086                 rsync://mirrors.rit.edu/cpan/
1087                 rsync://mirrors.ibiblio.org/CPAN/
1088                 rsync://cpan.pair.com/CPAN/
1089                 rsync://cpan.cs.utah.edu/CPAN/
1090                 rsync://mirror.cogentco.com/CPAN/
1091                 rsync://mirror.jmu.edu/CPAN/
1092                 rsync://mirror.us.leaseweb.net/CPAN/
1093                 rsync://cpan.mirror.digitalpacific.com.au/cpan/
1094                 rsync://mirror.internode.on.net/cpan/
1095                 rsync://uberglobalmirror.com/cpan/
1096                 rsync://cpan.lagoon.nc/cpan/
1097                 rsync://mirrors.mmgdesigns.com.ar/CPAN/
1098
1099
1100 For an up-to-date listing of CPAN sites,
1101 see L<http://www.cpan.org/SITES> or L<ftp://www.cpan.org/SITES>.
1102
1103 =head1 Modules: Creation, Use, and Abuse
1104
1105 (The following section is borrowed directly from Tim Bunce's modules
1106 file, available at your nearest CPAN site.)
1107
1108 Perl implements a class using a package, but the presence of a
1109 package doesn't imply the presence of a class.  A package is just a
1110 namespace.  A class is a package that provides subroutines that can be
1111 used as methods.  A method is just a subroutine that expects, as its
1112 first argument, either the name of a package (for "static" methods),
1113 or a reference to something (for "virtual" methods).
1114
1115 A module is a file that (by convention) provides a class of the same
1116 name (sans the .pm), plus an import method in that class that can be
1117 called to fetch exported symbols.  This module may implement some of
1118 its methods by loading dynamic C or C++ objects, but that should be
1119 totally transparent to the user of the module.  Likewise, the module
1120 might set up an AUTOLOAD function to slurp in subroutine definitions on
1121 demand, but this is also transparent.  Only the F<.pm> file is required to
1122 exist.  See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
1123 the AUTOLOAD mechanism.
1124
1125 =head2 Guidelines for Module Creation
1126
1127 =over 4
1128
1129 =item  *
1130
1131 Do similar modules already exist in some form?
1132
1133 If so, please try to reuse the existing modules either in whole or
1134 by inheriting useful features into a new class.  If this is not
1135 practical try to get together with the module authors to work on
1136 extending or enhancing the functionality of the existing modules.
1137 A perfect example is the plethora of packages in perl4 for dealing
1138 with command line options.
1139
1140 If you are writing a module to expand an already existing set of
1141 modules, please coordinate with the author of the package.  It
1142 helps if you follow the same naming scheme and module interaction
1143 scheme as the original author.
1144
1145 =item  *
1146
1147 Try to design the new module to be easy to extend and reuse.
1148
1149 Try to C<use warnings;> (or C<use warnings qw(...);>).
1150 Remember that you can add C<no warnings qw(...);> to individual blocks
1151 of code that need less warnings.
1152
1153 Use blessed references.  Use the two argument form of bless to bless
1154 into the class name given as the first parameter of the constructor,
1155 e.g.,:
1156
1157  sub new {
1158      my $class = shift;
1159      return bless {}, $class;
1160  }
1161
1162 or even this if you'd like it to be used as either a static
1163 or a virtual method.
1164
1165  sub new {
1166      my $self  = shift;
1167      my $class = ref($self) || $self;
1168      return bless {}, $class;
1169  }
1170
1171 Pass arrays as references so more parameters can be added later
1172 (it's also faster).  Convert functions into methods where
1173 appropriate.  Split large methods into smaller more flexible ones.
1174 Inherit methods from other modules if appropriate.
1175
1176 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1177 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1178 Let the objects look after themselves! Generally, avoid hard-wired
1179 class names as far as possible.
1180
1181 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1182 C<< $r->func() >> would work.
1183
1184 Use autosplit so little used or newly added functions won't be a
1185 burden to programs that don't use them. Add test functions to
1186 the module after __END__ either using AutoSplit or by saying:
1187
1188  eval join('',<main::DATA>) || die $@ unless caller();
1189
1190 Does your module pass the 'empty subclass' test? If you say
1191 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1192 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1193 does your application still work if you change:  C<< $obj = YOURCLASS->new(); >>
1194 into: C<< $obj = SUBCLASS->new(); >> ?
1195
1196 Avoid keeping any state information in your packages. It makes it
1197 difficult for multiple other packages to use yours. Keep state
1198 information in objects.
1199
1200 Always use B<-w>.
1201
1202 Try to C<use strict;> (or C<use strict qw(...);>).
1203 Remember that you can add C<no strict qw(...);> to individual blocks
1204 of code that need less strictness.
1205
1206 Always use B<-w>.
1207
1208 Follow the guidelines in L<perlstyle>.
1209
1210 Always use B<-w>.
1211
1212 =item  *
1213
1214 Some simple style guidelines
1215
1216 The perlstyle manual supplied with Perl has many helpful points.
1217
1218 Coding style is a matter of personal taste. Many people evolve their
1219 style over several years as they learn what helps them write and
1220 maintain good code.  Here's one set of assorted suggestions that
1221 seem to be widely used by experienced developers:
1222
1223 Use underscores to separate words.  It is generally easier to read
1224 $var_names_like_this than $VarNamesLikeThis, especially for
1225 non-native speakers of English. It's also a simple rule that works
1226 consistently with VAR_NAMES_LIKE_THIS.
1227
1228 Package/Module names are an exception to this rule. Perl informally
1229 reserves lowercase module names for 'pragma' modules like integer
1230 and strict. Other modules normally begin with a capital letter and
1231 use mixed case with no underscores (need to be short and portable).
1232
1233 You may find it helpful to use letter case to indicate the scope
1234 or nature of a variable. For example:
1235
1236  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1237  $Some_Caps_Here  package-wide global/static
1238  $no_caps_here    function scope my() or local() variables
1239
1240 Function and method names seem to work best as all lowercase.
1241 e.g., C<< $obj->as_string() >>.
1242
1243 You can use a leading underscore to indicate that a variable or
1244 function should not be used outside the package that defined it.
1245
1246 =item  *
1247
1248 Select what to export.
1249
1250 Do NOT export method names!
1251
1252 Do NOT export anything else by default without a good reason!
1253
1254 Exports pollute the namespace of the module user.  If you must
1255 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1256 short or common names to reduce the risk of name clashes.
1257
1258 Generally anything not exported is still accessible from outside the
1259 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1260 syntax.  By convention you can use a leading underscore on names to
1261 indicate informally that they are 'internal' and not for public use.
1262
1263 (It is actually possible to get private functions by saying:
1264 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
1265 directly as a method, because a method must have a name in the symbol
1266 table.)
1267
1268 As a general rule, if the module is trying to be object oriented
1269 then export nothing. If it's just a collection of functions then
1270 @EXPORT_OK anything but use @EXPORT with caution.
1271
1272 =item  *
1273
1274 Select a name for the module.
1275
1276 This name should be as descriptive, accurate, and complete as
1277 possible.  Avoid any risk of ambiguity. Always try to use two or
1278 more whole words.  Generally the name should reflect what is special
1279 about what the module does rather than how it does it.  Please use
1280 nested module names to group informally or categorize a module.
1281 There should be a very good reason for a module not to have a nested name.
1282 Module names should begin with a capital letter.
1283
1284 Having 57 modules all called Sort will not make life easy for anyone
1285 (though having 23 called Sort::Quick is only marginally better :-).
1286 Imagine someone trying to install your module alongside many others.
1287
1288 If you are developing a suite of related modules/classes it's good
1289 practice to use nested classes with a common prefix as this will
1290 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1291 Xyz::Model etc. Use the modules in this list as a naming guide.
1292
1293 If adding a new module to a set, follow the original author's
1294 standards for naming modules and the interface to methods in
1295 those modules.
1296
1297 If developing modules for private internal or project specific use,
1298 that will never be released to the public, then you should ensure
1299 that their names will not clash with any future public module. You
1300 can do this either by using the reserved Local::* category or by
1301 using a category name that includes an underscore like Foo_Corp::*.
1302
1303 To be portable each component of a module name should be limited to
1304 11 characters. If it might be used on MS-DOS then try to ensure each is
1305 unique in the first 8 characters. Nested modules make this easier.
1306
1307 For additional guidance on the naming of modules, please consult:
1308
1309     http://pause.perl.org/pause/query?ACTION=pause_namingmodules
1310
1311 or send mail to the <module-authors@perl.org> mailing list.
1312
1313 =item  *
1314
1315 Have you got it right?
1316
1317 How do you know that you've made the right decisions? Have you
1318 picked an interface design that will cause problems later? Have
1319 you picked the most appropriate name? Do you have any questions?
1320
1321 The best way to know for sure, and pick up many helpful suggestions,
1322 is to ask someone who knows. The <module-authors@perl.org> mailing list
1323 is useful for this purpose; it's also accessible via news interface as
1324 perl.module-authors at nntp.perl.org.
1325
1326 All you need to do is post a short summary of the module, its
1327 purpose and interfaces. A few lines on each of the main methods is
1328 probably enough. (If you post the whole module it might be ignored
1329 by busy people - generally the very people you want to read it!)
1330
1331 Don't worry about posting if you can't say when the module will be
1332 ready - just say so in the message. It might be worth inviting
1333 others to help you, they may be able to complete it for you!
1334
1335 =item  *
1336
1337 README and other Additional Files.
1338
1339 It's well known that software developers usually fully document the
1340 software they write. If, however, the world is in urgent need of
1341 your software and there is not enough time to write the full
1342 documentation please at least provide a README file containing:
1343
1344 =over 10
1345
1346 =item *
1347
1348 A description of the module/package/extension etc.
1349
1350 =item *
1351
1352 A copyright notice - see below.
1353
1354 =item *
1355
1356 Prerequisites - what else you may need to have.
1357
1358 =item *
1359
1360 How to build it - possible changes to Makefile.PL etc.
1361
1362 =item *
1363
1364 How to install it.
1365
1366 =item *
1367
1368 Recent changes in this release, especially incompatibilities
1369
1370 =item *
1371
1372 Changes / enhancements you plan to make in the future.
1373
1374 =back
1375
1376 If the README file seems to be getting too large you may wish to
1377 split out some of the sections into separate files: INSTALL,
1378 Copying, ToDo etc.
1379
1380 =over 4
1381
1382 =item *
1383
1384 Adding a Copyright Notice.
1385
1386 How you choose to license your work is a personal decision.
1387 The general mechanism is to assert your Copyright and then make
1388 a declaration of how others may copy/use/modify your work.
1389
1390 Perl, for example, is supplied with two types of licence: The GNU GPL
1391 and The Artistic Licence (see the files README, Copying, and Artistic,
1392 or L<perlgpl> and L<perlartistic>).  Larry has good reasons for NOT
1393 just using the GNU GPL.
1394
1395 My personal recommendation, out of respect for Larry, Perl, and the
1396 Perl community at large is to state something simply like:
1397
1398  Copyright (c) 1995 Your Name. All rights reserved.
1399  This program is free software; you can redistribute it and/or
1400  modify it under the same terms as Perl itself.
1401
1402 This statement should at least appear in the README file. You may
1403 also wish to include it in a Copying file and your source files.
1404 Remember to include the other words in addition to the Copyright.
1405
1406 =item  *
1407
1408 Give the module a version/issue/release number.
1409
1410 To be fully compatible with the Exporter and MakeMaker modules you
1411 should store your module's version number in a non-my package
1412 variable called $VERSION.  This should be a positive floating point
1413 number with at least two digits after the decimal (i.e., hundredths,
1414 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
1415 See L<Exporter> for details.
1416
1417 It may be handy to add a function or method to retrieve the number.
1418 Use the number in announcements and archive file names when
1419 releasing the module (ModuleName-1.02.tar.Z).
1420 See perldoc ExtUtils::MakeMaker.pm for details.
1421
1422 =item  *
1423
1424 How to release and distribute a module.
1425
1426 If possible, register the module with CPAN. Follow the instructions
1427 and links on:
1428
1429    http://www.cpan.org/modules/04pause.html
1430
1431 and upload to:
1432
1433    http://pause.perl.org/
1434
1435 and notify <modules@perl.org>. This will allow anyone to install
1436 your module using the C<cpan> tool distributed with Perl.
1437
1438 By using the WWW interface you can ask the Upload Server to mirror
1439 your modules from your ftp or WWW site into your own directory on
1440 CPAN!
1441
1442 =item  *
1443
1444 Take care when changing a released module.
1445
1446 Always strive to remain compatible with previous released versions.
1447 Otherwise try to add a mechanism to revert to the
1448 old behavior if people rely on it.  Document incompatible changes.
1449
1450 =back
1451
1452 =back
1453
1454 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1455
1456 =over 4
1457
1458 =item  *
1459
1460 There is no requirement to convert anything.
1461
1462 If it ain't broke, don't fix it! Perl 4 library scripts should
1463 continue to work with no problems. You may need to make some minor
1464 changes (like escaping non-array @'s in double quoted strings) but
1465 there is no need to convert a .pl file into a Module for just that.
1466
1467 =item  *
1468
1469 Consider the implications.
1470
1471 All Perl applications that make use of the script will need to
1472 be changed (slightly) if the script is converted into a module.  Is
1473 it worth it unless you plan to make other changes at the same time?
1474
1475 =item  *
1476
1477 Make the most of the opportunity.
1478
1479 If you are going to convert the script to a module you can use the
1480 opportunity to redesign the interface.  The guidelines for module
1481 creation above include many of the issues you should consider.
1482
1483 =item  *
1484
1485 The pl2pm utility will get you started.
1486
1487 This utility will read *.pl files (given as parameters) and write
1488 corresponding *.pm files. The pl2pm utilities does the following:
1489
1490 =over 10
1491
1492 =item *
1493
1494 Adds the standard Module prologue lines
1495
1496 =item *
1497
1498 Converts package specifiers from ' to ::
1499
1500 =item *
1501
1502 Converts die(...) to croak(...)
1503
1504 =item *
1505
1506 Several other minor changes
1507
1508 =back
1509
1510 Being a mechanical process pl2pm is not bullet proof. The converted
1511 code will need careful checking, especially any package statements.
1512 Don't delete the original .pl file till the new .pm one works!
1513
1514 =back
1515
1516 =head2 Guidelines for Reusing Application Code
1517
1518 =over 4
1519
1520 =item  *
1521
1522 Complete applications rarely belong in the Perl Module Library.
1523
1524 =item  *
1525
1526 Many applications contain some Perl code that could be reused.
1527
1528 Help save the world! Share your code in a form that makes it easy
1529 to reuse.
1530
1531 =item  *
1532
1533 Break-out the reusable code into one or more separate module files.
1534
1535 =item  *
1536
1537 Take the opportunity to reconsider and redesign the interfaces.
1538
1539 =item  *
1540
1541 In some cases the 'application' can then be reduced to a small
1542
1543 fragment of code built on top of the reusable modules. In these cases
1544 the application could invoked as:
1545
1546      % perl -e 'use Module::Name; method(@ARGV)' ...
1547 or
1548      % perl -mModule::Name ...    (in perl5.002 or higher)
1549
1550 =back
1551
1552 =head1 NOTE
1553
1554 Perl does not enforce private and public parts of its modules as you may
1555 have been used to in other languages like C++, Ada, or Modula-17.  Perl
1556 doesn't have an infatuation with enforced privacy.  It would prefer
1557 that you stayed out of its living room because you weren't invited, not
1558 because it has a shotgun.
1559
1560 The module and its user have a contract, part of which is common law,
1561 and part of which is "written".  Part of the common law contract is
1562 that a module doesn't pollute any namespace it wasn't asked to.  The
1563 written contract for the module (A.K.A. documentation) may make other
1564 provisions.  But then you know when you C<use RedefineTheWorld> that
1565 you're redefining the world and willing to take the consequences.
1566
1567 =cut
1568
1569 read_only_bottom_close_and_rename($out);