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