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