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