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