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