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