Document Storable problems on Crays. (Will have
[p5sagit/p5-mst-13.2.git] / pod / perlmodlib.pod
CommitLineData
f102b883 1=head1 NAME
2
3perlmodlib - constructing new Perl modules and finding existing ones
4
5=head1 DESCRIPTION
6
7=head1 THE PERL MODULE LIBRARY
8
19799a22 9Many modules are included the Perl distribution. These are described
10below, and all end in F<.pm>. You may discover compiled library
11file (usually ending in F<.so>) or small pieces of modules to be
12autoloaded (ending in F<.al>); these were automatically generated
13by the installation process. You may also discover files in the
14library directory that end in either F<.pl> or F<.ph>. These are
15old libraries supplied so that old programs that use them still
16run. The F<.pl> files will all eventually be converted into standard
17modules, and the F<.ph> files made by B<h2ph> will probably end up
18as extension modules made by B<h2xs>. (Some F<.ph> values may
19already be available through the POSIX, Errno, or Fcntl modules.)
20The B<pl2pm> file in the distribution may help in your conversion,
21but it's just a mechanical process and therefore far from bulletproof.
f102b883 22
23=head2 Pragmatic Modules
24
19799a22 25They work somewhat like compiler directives (pragmata) in that they
26tend to affect the compilation of your program, and thus will usually
27work well only when used within a C<use>, or C<no>. Most of these
28are lexically scoped, so an inner BLOCK may countermand them
29by saying:
f102b883 30
31 no integer;
32 no strict 'refs';
4438c4b7 33 no warnings;
f102b883 34
35which lasts until the end of that BLOCK.
36
19799a22 37Some pragmas are lexically scoped--typically those that affect the
38C<$^H> hints variable. Others affect the current package instead,
77ca0c92 39like C<use vars> and C<use subs>, which allow you to predeclare a
19799a22 40variables or subroutines within a particular I<file> rather than
41just a block. Such declarations are effective for the entire file
42for which they were declared. You cannot rescind them with C<no
43vars> or C<no subs>.
f102b883 44
45The following pragmas are defined (and have their own documentation).
46
47=over 12
48
09bef843 49=item attributes
50
9e107c59 51Get/set subroutine or variable attributes
09bef843 52
19799a22 53=item attrs
f102b883 54
9e107c59 55Set/get attributes of a subroutine (deprecated)
19799a22 56
57=item autouse
58
9e107c59 59Postpone load of modules until a function is used
19799a22 60
61=item base
62
63Establish IS-A relationship with base class at compile time
f102b883 64
65=item blib
66
19799a22 67Use MakeMaker's uninstalled version of a package
68
2e1d04bc 69=item bytes
9e107c59 70
2e1d04bc 71Force byte semantics rather than character semantics
9e107c59 72
73=item charnames
74
75Define character names for C<\N{named}> string literal escape.
76
19799a22 77=item constant
78
9e107c59 79Declare constants
f102b883 80
81=item diagnostics
82
2e1d04bc 83Perl compiler pragma to force verbose warning diagnostics
19799a22 84
85=item fields
86
2e1d04bc 87Compile-time class fields
19799a22 88
89=item filetest
90
2e1d04bc 91Control the filetest permission operators
f102b883 92
93=item integer
94
9e107c59 95Compute arithmetic in integer instead of double
f102b883 96
97=item less
98
2e1d04bc 99Request less of something from the compiler
f102b883 100
101=item lib
102
9e107c59 103Manipulate @INC at compile time
f102b883 104
105=item locale
106
2e1d04bc 107Use and avoid POSIX locales for built-in operations
108
109=item open
110
111Set default disciplines for input and output
f102b883 112
113=item ops
114
9e107c59 115Restrict unsafe operations when compiling
f102b883 116
117=item overload
118
2e1d04bc 119Package for overloading perl operations
f102b883 120
b3eb6a9b 121=item re
122
2e1d04bc 123Alter regular expression behaviour
b3eb6a9b 124
f102b883 125=item sigtrap
126
9e107c59 127Enable simple signal handling
f102b883 128
129=item strict
130
9e107c59 131Restrict unsafe constructs
f102b883 132
133=item subs
134
2e1d04bc 135Predeclare sub names
f102b883 136
19799a22 137=item utf8
f102b883 138
2e1d04bc 139Enable/disable UTF-8 in source code
f102b883 140
141=item vars
142
2e1d04bc 143Predeclare global variable names (obsolete)
f102b883 144
4438c4b7 145=item warnings
0453d815 146
9e107c59 147Control optional warnings
19799a22 148
f102b883 149=back
150
151=head2 Standard Modules
152
153Standard, bundled modules are all expected to behave in a well-defined
154manner with respect to namespace pollution because they use the
155Exporter module. See their own documentation for details.
156
157=over 12
158
159=item AnyDBM_File
160
2e1d04bc 161Provide framework for multiple DBMs
f102b883 162
163=item AutoLoader
164
9e107c59 165Load subroutines only on demand
f102b883 166
167=item AutoSplit
168
9e107c59 169Split a package for autoloading
f102b883 170
19799a22 171=item B
172
2e1d04bc 173The Perl Compiler
19799a22 174
175=item B::Asmdata
176
177Autogenerated data about Perl ops, used to generate bytecode
178
179=item B::Assembler
180
181Assemble Perl bytecode
182
183=item B::Bblock
184
185Walk basic blocks
186
187=item B::Bytecode
188
189Perl compiler's bytecode backend
190
191=item B::C
192
193Perl compiler's C backend
194
195=item B::CC
196
197Perl compiler's optimized C translation backend
198
199=item B::Debug
200
201Walk Perl syntax tree, printing debug info about ops
202
203=item B::Deparse
204
2e1d04bc 205Perl compiler backend to produce perl code
19799a22 206
207=item B::Disassembler
208
209Disassemble Perl bytecode
210
211=item B::Lint
212
2e1d04bc 213Perl lint
19799a22 214
215=item B::Showlex
216
217Show lexical variables used in functions or files
218
219=item B::Stackobj
220
221Helper module for CC backend
222
223=item B::Terse
224
225Walk Perl syntax tree, printing terse info about ops
226
227=item B::Xref
228
229Generates cross reference reports for Perl programs
230
f102b883 231=item Benchmark
232
2e1d04bc 233Benchmark running times of Perl code
9e107c59 234
235=item ByteLoader
236
2e1d04bc 237Load byte compiled perl code
f102b883 238
19799a22 239=item CGI
240
2e1d04bc 241Simple Common Gateway Interface Class
19799a22 242
243=item CGI::Apache
244
2e1d04bc 245Backward compatibility module for CGI.pm
19799a22 246
247=item CGI::Carp
248
249CGI routines for writing to the HTTPD (or other) error log
250
251=item CGI::Cookie
252
253Interface to Netscape Cookies
254
255=item CGI::Fast
256
257CGI Interface for Fast CGI
258
9e107c59 259=item CGI::Pretty
260
261Module to produce nicely formatted HTML code
262
19799a22 263=item CGI::Push
264
265Simple Interface to Server Push
266
267=item CGI::Switch
268
2e1d04bc 269Backward compatibility module for defunct CGI::Switch
19799a22 270
f102b883 271=item CPAN
272
2e1d04bc 273Query, download and build perl modules from CPAN sites
f102b883 274
275=item CPAN::FirstTime
276
2e1d04bc 277Utility for CPAN::Config file Initialization
f102b883 278
279=item CPAN::Nox
280
19799a22 281Wrapper around CPAN.pm without using any XS module
f102b883 282
283=item Carp
284
2e1d04bc 285Warn of errors (from perspective of caller)
9e107c59 286
287=item Carp::Heavy
288
289Carp guts
f102b883 290
291=item Class::Struct
292
9e107c59 293Declare struct-like datatypes as Perl classes
f102b883 294
f102b883 295=item Cwd
296
9e107c59 297Get pathname of current working directory
f102b883 298
19799a22 299=item DB
300
2e1d04bc 301Programmatic interface to the Perl debugging API (draft, subject to
19799a22 302
f102b883 303=item DB_File
304
19799a22 305Perl5 access to Berkeley DB version 1.x
306
f102b883 307=item Devel::SelfStubber
308
9e107c59 309Generate stubs for a SelfLoading module
f102b883 310
311=item DirHandle
312
9e107c59 313Supply object methods for directory handles
f102b883 314
19799a22 315=item Dumpvalue
316
2e1d04bc 317Provides screen dump of Perl data.
f102b883 318
319=item English
320
2e1d04bc 321Use nice English (or awk) names for ugly punctuation variables
f102b883 322
323=item Env
324
2e1d04bc 325Perl module that imports environment variables as scalars or arrays
f102b883 326
327=item Exporter
328
2e1d04bc 329Implements default import method for modules
9e107c59 330
331=item Exporter::Heavy
332
333Exporter guts
19799a22 334
335=item ExtUtils::Command
336
2e1d04bc 337Utilities to replace common UNIX commands in Makefiles etc.
f102b883 338
339=item ExtUtils::Embed
340
2e1d04bc 341Utilities for embedding Perl in C/C++ applications
f102b883 342
343=item ExtUtils::Install
344
9e107c59 345Install files from here to there
f102b883 346
19799a22 347=item ExtUtils::Installed
348
349Inventory management of installed modules
350
f102b883 351=item ExtUtils::Liblist
352
9e107c59 353Determine libraries to use and how to use them
354
355=item ExtUtils::MM_Cygwin
356
2e1d04bc 357Methods to override UN*X behaviour in ExtUtils::MakeMaker
f102b883 358
359=item ExtUtils::MM_OS2
360
2e1d04bc 361Methods to override UN*X behaviour in ExtUtils::MakeMaker
f102b883 362
363=item ExtUtils::MM_Unix
364
9e107c59 365Methods used by ExtUtils::MakeMaker
f102b883 366
367=item ExtUtils::MM_VMS
368
2e1d04bc 369Methods to override UN*X behaviour in ExtUtils::MakeMaker
19799a22 370
371=item ExtUtils::MM_Win32
372
2e1d04bc 373Methods to override UN*X behaviour in ExtUtils::MakeMaker
f102b883 374
375=item ExtUtils::MakeMaker
376
9e107c59 377Create an extension Makefile
f102b883 378
379=item ExtUtils::Manifest
380
9e107c59 381Utilities to write and check a MANIFEST file
f102b883 382
383=item ExtUtils::Mkbootstrap
384
9e107c59 385Make a bootstrap file for use by DynaLoader
f102b883 386
387=item ExtUtils::Mksymlists
388
9e107c59 389Write linker options files for dynamic extension
f102b883 390
19799a22 391=item ExtUtils::Packlist
392
9e107c59 393Manage .packlist files
19799a22 394
f102b883 395=item ExtUtils::testlib
396
9e107c59 397Add blib/* directories to @INC
f102b883 398
b6c543e3 399=item Fatal
400
9e107c59 401Replace functions with equivalents which succeed or die
b6c543e3 402
f102b883 403=item Fcntl
404
2e1d04bc 405Load the C Fcntl.h defines
f102b883 406
407=item File::Basename
408
9e107c59 409Split a pathname into pieces
410
411=item File::CheckTree
412
413Run many filetest checks on a tree
f102b883 414
f102b883 415=item File::Compare
416
19799a22 417Compare files or filehandles
f102b883 418
419=item File::Copy
420
19799a22 421Copy files or filehandles
422
423=item File::DosGlob
424
2e1d04bc 425DOS like globbing and then some
f102b883 426
427=item File::Find
428
2e1d04bc 429Traverse a file tree
f102b883 430
431=item File::Path
432
2e1d04bc 433Create or remove directory trees
f102b883 434
f505c983 435=item File::Spec
436
9e107c59 437Portably perform operations on file names
f505c983 438
439=item File::Spec::Functions
440
9e107c59 441Portably perform operations on file names
19799a22 442
443=item File::Spec::Mac
444
445File::Spec for MacOS
446
447=item File::Spec::OS2
448
9e107c59 449Methods for OS/2 file specs
19799a22 450
451=item File::Spec::Unix
452
9e107c59 453Methods used by File::Spec
19799a22 454
455=item File::Spec::VMS
456
9e107c59 457Methods for VMS file specs
19799a22 458
459=item File::Spec::Win32
460
9e107c59 461Methods for Win32 file specs
f505c983 462
2e1d04bc 463=item File::Temp
464
465Return name and handle of a temporary file safely
466
f102b883 467=item File::stat
468
9e107c59 469By-name interface to Perl's built-in stat() functions
f102b883 470
471=item FileCache
472
9e107c59 473Keep more files open than the system permits
f102b883 474
475=item FileHandle
476
9e107c59 477Supply object methods for filehandles
f102b883 478
479=item FindBin
480
2e1d04bc 481Locate directory of original perl script
f102b883 482
483=item Getopt::Long
484
9e107c59 485Extended processing of command line options
f102b883 486
487=item Getopt::Std
488
19799a22 489Process single-character switches with switch clustering
f102b883 490
491=item I18N::Collate
492
2e1d04bc 493Compare 8-bit scalar data according to the current locale
f102b883 494
495=item IO
496
2e1d04bc 497Load various IO modules
f102b883 498
499=item IPC::Open2
500
9e107c59 501Open a process for both reading and writing
f102b883 502
503=item IPC::Open3
504
9e107c59 505Open a process for reading, writing, and error handling
f102b883 506
507=item Math::BigFloat
508
19799a22 509Arbitrary length float math package
f102b883 510
511=item Math::BigInt
512
19799a22 513Arbitrary size integer math package
f102b883 514
515=item Math::Complex
516
9e107c59 517Complex numbers and associated mathematical functions
f102b883 518
404b15a1 519=item Math::Trig
520
9e107c59 521Trigonometric functions
f102b883 522
2e1d04bc 523=item NDBM_File
524
525Tied access to ndbm files
526
f102b883 527=item Net::Ping
528
9e107c59 529Check a remote host for reachability
f102b883 530
531=item Net::hostent
532
9e107c59 533By-name interface to Perl's built-in gethost*() functions
f102b883 534
535=item Net::netent
536
9e107c59 537By-name interface to Perl's built-in getnet*() functions
f102b883 538
539=item Net::protoent
540
9e107c59 541By-name interface to Perl's built-in getproto*() functions
f102b883 542
543=item Net::servent
544
9e107c59 545By-name interface to Perl's built-in getserv*() functions
f102b883 546
19799a22 547=item O
f102b883 548
19799a22 549Generic interface to Perl Compiler backends
f102b883 550
2e1d04bc 551=item ODBM_File
f102b883 552
2e1d04bc 553Tied access to odbm files
f102b883 554
2e1d04bc 555=item Opcode
f102b883 556
2e1d04bc 557Disable named opcodes when compiling perl code
19799a22 558
9e107c59 559=item Pod::Checker
560
561Check pod documents for syntax errors
562
2e1d04bc 563=item Pod::Find
564
565Find POD documents in directory trees
566
19799a22 567=item Pod::Html
568
9e107c59 569Module to convert pod files to HTML
570
571=item Pod::InputObjects
572
2e1d04bc 573Objects representing POD input paragraphs, commands, etc.
9e107c59 574
575=item Pod::Man
576
577Convert POD data to formatted *roff input
578
2e1d04bc 579=item Pod::ParseUtils
580
581Helpers for POD parsing and conversion
582
9e107c59 583=item Pod::Parser
584
585Base class for creating POD filters and translators
586
2e1d04bc 587=item Pod::Plainer
588
589Perl extension for converting Pod to old style Pod.
590
9e107c59 591=item Pod::Select
592
593Extract selected sections of POD from input
19799a22 594
595=item Pod::Text
596
9e107c59 597Convert POD data to formatted ASCII text
598
599=item Pod::Text::Color
600
601Convert POD data to formatted color ASCII text
602
2e1d04bc 603=item Pod::Text::Termcap
604
605Convert POD data to ASCII text with format escapes
606
9e107c59 607=item Pod::Usage
608
609Print a usage message from embedded pod documentation
f102b883 610
611=item SDBM_File
612
19799a22 613Tied access to sdbm files
f102b883 614
615=item Safe
616
19799a22 617Compile and execute code in restricted compartments
f102b883 618
619=item Search::Dict
620
9e107c59 621Search for key in dictionary file
f102b883 622
623=item SelectSaver
624
9e107c59 625Save and restore selected file handle
f102b883 626
627=item SelfLoader
628
9e107c59 629Load functions only on demand
f102b883 630
631=item Shell
632
2e1d04bc 633Run shell commands transparently within perl
f102b883 634
635=item Socket
636
2e1d04bc 637Load the C socket.h defines and structure manipulators
f102b883 638
639=item Symbol
640
9e107c59 641Manipulate Perl symbols and their names
f102b883 642
2e1d04bc 643=item Term::ANSIColor
f102b883 644
2e1d04bc 645Color screen output using ANSI escape sequences
f102b883 646
647=item Term::Cap
648
2e1d04bc 649Perl termcap interface
f102b883 650
651=item Term::Complete
652
2e1d04bc 653Perl word completion module
f102b883 654
655=item Term::ReadLine
656
2e1d04bc 657Perl interface to various C<readline> packages. If
19799a22 658
659=item Test
660
9e107c59 661Provides a simple framework for writing test scripts
f102b883 662
663=item Test::Harness
664
2e1d04bc 665Run perl standard test scripts with statistics
f102b883 666
667=item Text::Abbrev
668
9e107c59 669Create an abbreviation table from a list
f102b883 670
671=item Text::ParseWords
672
2e1d04bc 673Parse text into an array of tokens or array of arrays
f102b883 674
675=item Text::Soundex
676
2e1d04bc 677Implementation of the Soundex Algorithm as Described by Knuth
f102b883 678
679=item Text::Wrap
680
9e107c59 681Line wrapping to form simple paragraphs
19799a22 682
683=item Tie::Array
684
9e107c59 685Base class for tied arrays
19799a22 686
687=item Tie::Handle
688
9e107c59 689Base class definitions for tied handles
19799a22 690
9e107c59 691=item Tie::Hash
f102b883 692
9e107c59 693Base class definitions for tied hashes
f102b883 694
695=item Tie::RefHash
696
9e107c59 697Use references as hash keys
f102b883 698
9e107c59 699=item Tie::Scalar
f102b883 700
9e107c59 701Base class definitions for tied scalars
f102b883 702
703=item Tie::SubstrHash
704
19799a22 705Fixed-table-size, fixed-key-length hashing
f102b883 706
707=item Time::Local
708
9e107c59 709Efficiently compute time from local and GMT time
f102b883 710
711=item Time::gmtime
712
9e107c59 713By-name interface to Perl's built-in gmtime() function
f102b883 714
715=item Time::localtime
716
9e107c59 717By-name interface to Perl's built-in localtime() function
f102b883 718
719=item Time::tm
720
9e107c59 721Internal object used by Time::gmtime and Time::localtime
f102b883 722
723=item UNIVERSAL
724
9e107c59 725Base class for ALL classes (blessed references)
f102b883 726
727=item User::grent
728
9e107c59 729By-name interface to Perl's built-in getgr*() functions
f102b883 730
731=item User::pwent
732
9e107c59 733By-name interface to Perl's built-in getpw*() functions
f102b883 734
735=back
736
19799a22 737To find out I<all> modules installed on your system, including
2e1d04bc 738those without documentation or outside the standard release,
739jus tdo this:
f102b883 740
5a964f20 741 % find `perl -e 'print "@INC"'` -name '*.pm' -print
f102b883 742
2e1d04bc 743They should all have their own documentation installed and accessible
744via your system man(1) command. If you do not have a B<find>
19799a22 745program, you can use the Perl B<find2perl> program instead, which
746generates Perl code as output you can run through perl. If you
747have a B<man> program but it doesn't find your modules, you'll have
2e1d04bc 748to fix your manpath. See L<perl> for details. If you have no
749system B<man> command, you might try the B<perldoc> program.
f102b883 750
751=head2 Extension Modules
752
19799a22 753Extension modules are written in C (or a mix of Perl and C). They
754are usually dynamically loaded into Perl if and when you need them,
2e1d04bc 755but may also be be linked in statically. Supported extension modules
19799a22 756include Socket, Fcntl, and POSIX.
f102b883 757
758Many popular C extension modules do not come bundled (at least, not
19799a22 759completely) due to their sizes, volatility, or simply lack of time
760for adequate testing and configuration across the multitude of
761platforms on which Perl was beta-tested. You are encouraged to
762look for them on CPAN (described below), or using web search engines
763like Alta Vista or Deja News.
f102b883 764
765=head1 CPAN
766
19799a22 767CPAN stands for Comprehensive Perl Archive Network; it's a globally
768replicated trove of Perl materials, including documentation, style
2e1d04bc 769guides, tricks and traps, alternate ports to non-Unix systems and
19799a22 770occasional binary distributions for these. Search engines for
771CPAN can be found at http://cpan.perl.com/ and at
772http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
773
774Most importantly, CPAN includes around a thousand unbundled modules,
775some of which require a C compiler to build. Major categories of
776modules are:
f102b883 777
778=over
779
780=item *
781Language Extensions and Documentation Tools
782
783=item *
784Development Support
785
786=item *
787Operating System Interfaces
788
789=item *
790Networking, Device Control (modems) and InterProcess Communication
791
792=item *
793Data Types and Data Type Utilities
794
795=item *
796Database Interfaces
797
798=item *
799User Interfaces
800
801=item *
802Interfaces to / Emulations of Other Programming Languages
803
804=item *
805File Names, File Systems and File Locking (see also File Handles)
806
807=item *
808String Processing, Language Text Processing, Parsing, and Searching
809
810=item *
811Option, Argument, Parameter, and Configuration File Processing
812
813=item *
814Internationalization and Locale
815
816=item *
817Authentication, Security, and Encryption
818
819=item *
820World Wide Web, HTML, HTTP, CGI, MIME
821
822=item *
823Server and Daemon Utilities
824
825=item *
826Archiving and Compression
827
828=item *
829Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
830
831=item *
832Mail and Usenet News
833
834=item *
835Control Flow Utilities (callbacks and exceptions etc)
836
837=item *
838File Handle and Input/Output Stream Utilities
839
840=item *
841Miscellaneous Modules
842
843=back
844
19799a22 845Registered CPAN sites as of this writing include the following.
f102b883 846You should try to choose one close to you:
847
848=over
849
19799a22 850=item Africa
f102b883 851
0974df93 852 South Africa ftp://ftp.is.co.za/programming/perl/CPAN/
853 ftp://ftp.saix.net/pub/CPAN/
854 ftp://ftp.sun.ac.za/CPAN/
be94a901 855 ftp://ftpza.co.za/pub/mirrors/cpan/
f102b883 856
6cecdcac 857
19799a22 858=item Asia
f102b883 859
0974df93 860 China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
6cecdcac 861 Hong Kong ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
0974df93 862 Indonesia ftp://malone.piksi.itb.ac.id/pub/CPAN/
863 Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
864 Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/
be94a901 865 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
866 ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
867 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
19799a22 868 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
be94a901 869 ftp://mirror.nucba.ac.jp/mirror/Perl/
6cecdcac 870 Saudi-Arabia ftp://ftp.isu.net.sa/pub/CPAN/
0974df93 871 Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
872 South Korea ftp://ftp.bora.net/pub/CPAN/
873 ftp://ftp.kornet.net/pub/CPAN/
be94a901 874 ftp://ftp.nuri.net/pub/CPAN/
0974df93 875 Taiwan ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
876 ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/
be94a901 877 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
6cecdcac 878 Thailand ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
879
f102b883 880
19799a22 881=item Australasia
f102b883 882
0974df93 883 Australia ftp://cpan.topend.com.au/pub/CPAN/
6cecdcac 884 ftp://ftp.labyrinth.net.au/pub/perl-CPAN/
be94a901 885 ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
886 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
0974df93 887 New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
be94a901 888 ftp://sunsite.net.nz/pub/languages/perl/CPAN/
889
6cecdcac 890
0974df93 891=item Central America
be94a901 892
0974df93 893 Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
f102b883 894
6cecdcac 895
19799a22 896=item Europe
f102b883 897
0974df93 898 Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
899 Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
900 Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/
901 Croatia ftp://ftp.linux.hr/pub/CPAN/
902 Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
be94a901 903 ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
0974df93 904 Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
905 Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/
906 Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/
6cecdcac 907 France ftp://ftp.grolier.fr/pub/perl/CPAN/
908 ftp://ftp.lip6.fr/pub/perl/CPAN/
be94a901 909 ftp://ftp.oleane.net/pub/mirrors/CPAN/
910 ftp://ftp.pasteur.fr/pub/computing/CPAN/
0974df93 911 ftp://ftp.uvsq.fr/pub/perl/CPAN/
6cecdcac 912 German ftp://ftp.gigabell.net/pub/CPAN/
913 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
914 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
915 ftp://ftp.gmd.de/packages/CPAN/
916 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
2e1d04bc 917
918ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
6cecdcac 919 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
920 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
921 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
922 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
0974df93 923 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
6cecdcac 924 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
be94a901 925 ftp://ftp.gmd.de/packages/CPAN/
926 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
2e1d04bc 927
928ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
be94a901 929 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
930 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
931 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
932 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
0974df93 933 Greece ftp://ftp.ntua.gr/pub/lang/perl/
934 Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
935 Iceland ftp://ftp.gm.is/pub/CPAN/
936 Ireland ftp://cpan.indigo.ie/pub/CPAN/
937 ftp://sunsite.compapp.dcu.ie/pub/perl/
938 Italy ftp://cis.uniRoma2.it/CPAN/
be94a901 939 ftp://ftp.flashnet.it/pub/CPAN/
19799a22 940 ftp://ftp.unina.it/pub/Other/CPAN/
be94a901 941 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
0974df93 942 Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/
be94a901 943 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
0974df93 944 Norway ftp://ftp.uit.no/pub/languages/perl/cpan/
be94a901 945 ftp://sunsite.uio.no/pub/languages/perl/CPAN/
6cecdcac 946 Poland ftp://ftp.man.torun.pl/pub/CPAN/
be94a901 947 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
948 ftp://sunsite.icm.edu.pl/pub/CPAN/
0974df93 949 Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
19799a22 950 ftp://ftp.ist.utl.pt/pub/CPAN/
be94a901 951 ftp://ftp.ua.pt/pub/CPAN/
6cecdcac 952 Romania ftp://ftp.dnttm.ro/pub/CPAN/
19799a22 953 Russia ftp://ftp.chg.ru/pub/lang/perl/CPAN/
be94a901 954 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
0974df93 955 Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/
956 Slovenia ftp://ftp.arnes.si/software/perl/CPAN/
957 Spain ftp://ftp.etse.urv.es/pub/perl/
be94a901 958 ftp://ftp.rediris.es/mirror/CPAN/
0974df93 959 Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/
960 Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
961 Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
962 United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
be94a901 963 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
2e1d04bc 964
965ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
be94a901 966 ftp://ftp.plig.org/pub/CPAN/
967 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
f102b883 968
6cecdcac 969
19799a22 970=item North America
f102b883 971
0974df93 972 Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
19799a22 973 California ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
0974df93 974 ftp://cpan.valueclick.com/CPAN/
19799a22 975 ftp://ftp.cdrom.com/pub/perl/CPAN/
6cecdcac 976 http://download.sourceforge.net/mirrors/CPAN/
0974df93 977 Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
978 Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
6cecdcac 979 Georgia ftp://ftp.twoguys.org/CPAN/
0974df93 980 Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
981 Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
be94a901 982 ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
0974df93 983 Kentucky ftp://ftp.uky.edu/CPAN/
984 Manitoba ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
2e1d04bc 985 Massachusetts
986ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
be94a901 987 ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
19799a22 988 Mexico ftp://ftp.msg.com.mx/pub/CPAN/
0974df93 989 New York ftp://ftp.deao.net/pub/CPAN/
990 ftp://ftp.rge.com/pub/languages/perl/
0974df93 991 North Carolina ftp://ftp.duke.edu/pub/perl/
6cecdcac 992 Nova Scotia ftp://cpan.chebucto.ns.ca/pub/CPAN/
0974df93 993 Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/
19799a22 994 Ontario ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
0974df93 995 Oregon ftp://ftp.orst.edu/pub/packages/CPAN/
996 Pennsylvania ftp://ftp.epix.net/pub/languages/perl/
997 Tennessee ftp://ftp.sunsite.utk.edu/pub/CPAN/
998 Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/
6cecdcac 999 ftp://jhcloos.com/pub/mirror/CPAN/
0974df93 1000 Utah ftp://mirror.xmission.com/CPAN/
1001 Virginia ftp://ftp.perl.org/pub/perl/CPAN/
be94a901 1002 ftp://ruff.cs.jmu.edu/pub/CPAN/
19799a22 1003 Washington ftp://ftp-mirror.internap.com/pub/CPAN/
6cecdcac 1004 ftp://ftp.llarian.net/pub/CPAN/
19799a22 1005 ftp://ftp.spu.edu/pub/CPAN/
f102b883 1006
6cecdcac 1007
19799a22 1008=item South America
f102b883 1009
0974df93 1010 Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/
1011 ftp://ftp.matrix.com.br/pub/perl/
6cecdcac 1012 Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/
f102b883 1013
1014=back
1015
1016For an up-to-date listing of CPAN sites,
6cecdcac 1017see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
f102b883 1018
1019=head1 Modules: Creation, Use, and Abuse
1020
1021(The following section is borrowed directly from Tim Bunce's modules
1022file, available at your nearest CPAN site.)
1023
1024Perl implements a class using a package, but the presence of a
1025package doesn't imply the presence of a class. A package is just a
1026namespace. A class is a package that provides subroutines that can be
1027used as methods. A method is just a subroutine that expects, as its
1028first argument, either the name of a package (for "static" methods),
1029or a reference to something (for "virtual" methods).
1030
1031A module is a file that (by convention) provides a class of the same
1032name (sans the .pm), plus an import method in that class that can be
1033called to fetch exported symbols. This module may implement some of
1034its methods by loading dynamic C or C++ objects, but that should be
1035totally transparent to the user of the module. Likewise, the module
1036might set up an AUTOLOAD function to slurp in subroutine definitions on
1037demand, but this is also transparent. Only the F<.pm> file is required to
2e1d04bc 1038exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
f102b883 1039the AUTOLOAD mechanism.
1040
1041=head2 Guidelines for Module Creation
1042
1043=over 4
1044
1045=item Do similar modules already exist in some form?
1046
1047If so, please try to reuse the existing modules either in whole or
1048by inheriting useful features into a new class. If this is not
1049practical try to get together with the module authors to work on
1050extending or enhancing the functionality of the existing modules.
1051A perfect example is the plethora of packages in perl4 for dealing
1052with command line options.
1053
1054If you are writing a module to expand an already existing set of
1055modules, please coordinate with the author of the package. It
1056helps if you follow the same naming scheme and module interaction
1057scheme as the original author.
1058
1059=item Try to design the new module to be easy to extend and reuse.
1060
9f1b1f2d 1061Try to C<use warnings;> (or C<use warnings qw(...);>).
1062Remember that you can add C<no warnings qw(...);> to individual blocks
2e1d04bc 1063of code that need less warnings.
19799a22 1064
f102b883 1065Use blessed references. Use the two argument form of bless to bless
1066into the class name given as the first parameter of the constructor,
1067e.g.,:
1068
1069 sub new {
2e1d04bc 1070 my $class = shift;
1071 return bless {}, $class;
f102b883 1072 }
1073
1074or even this if you'd like it to be used as either a static
1075or a virtual method.
1076
1077 sub new {
2e1d04bc 1078 my $self = shift;
1079 my $class = ref($self) || $self;
1080 return bless {}, $class;
f102b883 1081 }
1082
1083Pass arrays as references so more parameters can be added later
1084(it's also faster). Convert functions into methods where
1085appropriate. Split large methods into smaller more flexible ones.
1086Inherit methods from other modules if appropriate.
1087
1088Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
19799a22 1089Generally you can delete the C<eq 'FOO'> part with no harm at all.
f102b883 1090Let the objects look after themselves! Generally, avoid hard-wired
1091class names as far as possible.
1092
c47ff5f1 1093Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1094C<< $r->func() >> would work (see L<perlbot> for more details).
f102b883 1095
1096Use autosplit so little used or newly added functions won't be a
5a964f20 1097burden to programs that don't use them. Add test functions to
f102b883 1098the module after __END__ either using AutoSplit or by saying:
1099
1100 eval join('',<main::DATA>) || die $@ unless caller();
1101
1102Does your module pass the 'empty subclass' test? If you say
19799a22 1103C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
f102b883 1104to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1105does your application still work if you change: C<$obj = new YOURCLASS;>
1106into: C<$obj = new SUBCLASS;> ?
1107
1108Avoid keeping any state information in your packages. It makes it
1109difficult for multiple other packages to use yours. Keep state
1110information in objects.
1111
2e1d04bc 1112Always use B<-w>.
19799a22 1113
1114Try to C<use strict;> (or C<use strict qw(...);>).
f102b883 1115Remember that you can add C<no strict qw(...);> to individual blocks
2e1d04bc 1116of code that need less strictness.
19799a22 1117
2e1d04bc 1118Always use B<-w>.
19799a22 1119
f102b883 1120Follow the guidelines in the perlstyle(1) manual.
1121
19799a22 1122Always use B<-w>.
1123
f102b883 1124=item Some simple style guidelines
1125
5a964f20 1126The perlstyle manual supplied with Perl has many helpful points.
f102b883 1127
1128Coding style is a matter of personal taste. Many people evolve their
1129style over several years as they learn what helps them write and
1130maintain good code. Here's one set of assorted suggestions that
1131seem to be widely used by experienced developers:
1132
1133Use underscores to separate words. It is generally easier to read
1134$var_names_like_this than $VarNamesLikeThis, especially for
1135non-native speakers of English. It's also a simple rule that works
1136consistently with VAR_NAMES_LIKE_THIS.
1137
1138Package/Module names are an exception to this rule. Perl informally
1139reserves lowercase module names for 'pragma' modules like integer
1140and strict. Other modules normally begin with a capital letter and
1141use mixed case with no underscores (need to be short and portable).
1142
1143You may find it helpful to use letter case to indicate the scope
1144or nature of a variable. For example:
1145
5a964f20 1146 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
f102b883 1147 $Some_Caps_Here package-wide global/static
1148 $no_caps_here function scope my() or local() variables
1149
1150Function and method names seem to work best as all lowercase.
c47ff5f1 1151e.g., C<< $obj->as_string() >>.
f102b883 1152
1153You can use a leading underscore to indicate that a variable or
1154function should not be used outside the package that defined it.
1155
1156=item Select what to export.
1157
1158Do NOT export method names!
1159
1160Do NOT export anything else by default without a good reason!
1161
1162Exports pollute the namespace of the module user. If you must
1163export try to use @EXPORT_OK in preference to @EXPORT and avoid
1164short or common names to reduce the risk of name clashes.
1165
1166Generally anything not exported is still accessible from outside the
c47ff5f1 1167module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
f102b883 1168syntax. By convention you can use a leading underscore on names to
1169indicate informally that they are 'internal' and not for public use.
1170
1171(It is actually possible to get private functions by saying:
1172C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1173directly as a method, because a method must have a name in the symbol
1174table.)
1175
1176As a general rule, if the module is trying to be object oriented
1177then export nothing. If it's just a collection of functions then
1178@EXPORT_OK anything but use @EXPORT with caution.
1179
1180=item Select a name for the module.
1181
1182This name should be as descriptive, accurate, and complete as
1183possible. Avoid any risk of ambiguity. Always try to use two or
1184more whole words. Generally the name should reflect what is special
1185about what the module does rather than how it does it. Please use
1186nested module names to group informally or categorize a module.
1187There should be a very good reason for a module not to have a nested name.
1188Module names should begin with a capital letter.
1189
1190Having 57 modules all called Sort will not make life easy for anyone
1191(though having 23 called Sort::Quick is only marginally better :-).
1192Imagine someone trying to install your module alongside many others.
1193If in any doubt ask for suggestions in comp.lang.perl.misc.
1194
1195If you are developing a suite of related modules/classes it's good
1196practice to use nested classes with a common prefix as this will
1197avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1198Xyz::Model etc. Use the modules in this list as a naming guide.
1199
1200If adding a new module to a set, follow the original author's
1201standards for naming modules and the interface to methods in
1202those modules.
1203
1204To be portable each component of a module name should be limited to
120511 characters. If it might be used on MS-DOS then try to ensure each is
1206unique in the first 8 characters. Nested modules make this easier.
1207
1208=item Have you got it right?
1209
1210How do you know that you've made the right decisions? Have you
1211picked an interface design that will cause problems later? Have
1212you picked the most appropriate name? Do you have any questions?
1213
1214The best way to know for sure, and pick up many helpful suggestions,
1215is to ask someone who knows. Comp.lang.perl.misc is read by just about
1216all the people who develop modules and it's the best place to ask.
1217
1218All you need to do is post a short summary of the module, its
1219purpose and interfaces. A few lines on each of the main methods is
1220probably enough. (If you post the whole module it might be ignored
1221by busy people - generally the very people you want to read it!)
1222
1223Don't worry about posting if you can't say when the module will be
1224ready - just say so in the message. It might be worth inviting
1225others to help you, they may be able to complete it for you!
1226
1227=item README and other Additional Files.
1228
1229It's well known that software developers usually fully document the
1230software they write. If, however, the world is in urgent need of
1231your software and there is not enough time to write the full
1232documentation please at least provide a README file containing:
1233
1234=over 10
1235
1236=item *
1237A description of the module/package/extension etc.
1238
1239=item *
1240A copyright notice - see below.
1241
1242=item *
1243Prerequisites - what else you may need to have.
1244
1245=item *
1246How to build it - possible changes to Makefile.PL etc.
1247
1248=item *
1249How to install it.
1250
1251=item *
1252Recent changes in this release, especially incompatibilities
1253
1254=item *
1255Changes / enhancements you plan to make in the future.
1256
1257=back
1258
1259If the README file seems to be getting too large you may wish to
1260split out some of the sections into separate files: INSTALL,
1261Copying, ToDo etc.
1262
1263=over 4
1264
1265=item Adding a Copyright Notice.
1266
1267How you choose to license your work is a personal decision.
1268The general mechanism is to assert your Copyright and then make
1269a declaration of how others may copy/use/modify your work.
1270
1271Perl, for example, is supplied with two types of licence: The GNU
1272GPL and The Artistic Licence (see the files README, Copying, and
1273Artistic). Larry has good reasons for NOT just using the GNU GPL.
1274
1275My personal recommendation, out of respect for Larry, Perl, and the
5a964f20 1276Perl community at large is to state something simply like:
f102b883 1277
1278 Copyright (c) 1995 Your Name. All rights reserved.
1279 This program is free software; you can redistribute it and/or
1280 modify it under the same terms as Perl itself.
1281
1282This statement should at least appear in the README file. You may
1283also wish to include it in a Copying file and your source files.
1284Remember to include the other words in addition to the Copyright.
1285
1286=item Give the module a version/issue/release number.
1287
1288To be fully compatible with the Exporter and MakeMaker modules you
1289should store your module's version number in a non-my package
1290variable called $VERSION. This should be a floating point
1291number with at least two digits after the decimal (i.e., hundredths,
1292e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
19799a22 1293See L<Exporter> for details.
f102b883 1294
1295It may be handy to add a function or method to retrieve the number.
1296Use the number in announcements and archive file names when
1297releasing the module (ModuleName-1.02.tar.Z).
1298See perldoc ExtUtils::MakeMaker.pm for details.
1299
1300=item How to release and distribute a module.
1301
1302It's good idea to post an announcement of the availability of your
1303module (or the module itself if small) to the comp.lang.perl.announce
1304Usenet newsgroup. This will at least ensure very wide once-off
1305distribution.
1306
2e1d04bc 1307If possible, register the module with CPAN. You should
f102b883 1308include details of its location in your announcement.
1309
1310Some notes about ftp archives: Please use a long descriptive file
5a964f20 1311name that includes the version number. Most incoming directories
f102b883 1312will not be readable/listable, i.e., you won't be able to see your
1313file after uploading it. Remember to send your email notification
1314message as soon as possible after uploading else your file may get
1315deleted automatically. Allow time for the file to be processed
1316and/or check the file has been processed before announcing its
1317location.
1318
1319FTP Archives for Perl Modules:
1320
6cecdcac 1321Follow the instructions and links on:
f102b883 1322
6cecdcac 1323 http://www.perl.com/CPAN/modules/00modlist.long.html
1324 http://www.perl.com/CPAN/modules/04pause.html
f102b883 1325
1326or upload to one of these sites:
1327
6cecdcac 1328 https://pause.kbx.de/pause/
1329 http://pause.perl.org/pause/
f102b883 1330
6cecdcac 1331and notify <modules@perl.org>.
f102b883 1332
1333By using the WWW interface you can ask the Upload Server to mirror
1334your modules from your ftp or WWW site into your own directory on
1335CPAN!
1336
1337Please remember to send me an updated entry for the Module list!
1338
1339=item Take care when changing a released module.
1340
7b8d334a 1341Always strive to remain compatible with previous released versions.
1342Otherwise try to add a mechanism to revert to the
19799a22 1343old behavior if people rely on it. Document incompatible changes.
f102b883 1344
1345=back
1346
1347=back
1348
1349=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1350
1351=over 4
1352
1353=item There is no requirement to convert anything.
1354
1355If it ain't broke, don't fix it! Perl 4 library scripts should
1356continue to work with no problems. You may need to make some minor
1357changes (like escaping non-array @'s in double quoted strings) but
1358there is no need to convert a .pl file into a Module for just that.
1359
1360=item Consider the implications.
1361
5a964f20 1362All Perl applications that make use of the script will need to
f102b883 1363be changed (slightly) if the script is converted into a module. Is
1364it worth it unless you plan to make other changes at the same time?
1365
1366=item Make the most of the opportunity.
1367
1368If you are going to convert the script to a module you can use the
19799a22 1369opportunity to redesign the interface. The guidelines for module
1370creation above include many of the issues you should consider.
f102b883 1371
1372=item The pl2pm utility will get you started.
1373
1374This utility will read *.pl files (given as parameters) and write
1375corresponding *.pm files. The pl2pm utilities does the following:
1376
1377=over 10
1378
1379=item *
1380Adds the standard Module prologue lines
1381
1382=item *
1383Converts package specifiers from ' to ::
1384
1385=item *
1386Converts die(...) to croak(...)
1387
1388=item *
1389Several other minor changes
1390
1391=back
1392
1393Being a mechanical process pl2pm is not bullet proof. The converted
1394code will need careful checking, especially any package statements.
1395Don't delete the original .pl file till the new .pm one works!
1396
1397=back
1398
1399=head2 Guidelines for Reusing Application Code
1400
1401=over 4
1402
1403=item Complete applications rarely belong in the Perl Module Library.
1404
5a964f20 1405=item Many applications contain some Perl code that could be reused.
f102b883 1406
1407Help save the world! Share your code in a form that makes it easy
1408to reuse.
1409
1410=item Break-out the reusable code into one or more separate module files.
1411
1412=item Take the opportunity to reconsider and redesign the interfaces.
1413
1414=item In some cases the 'application' can then be reduced to a small
1415
1416fragment of code built on top of the reusable modules. In these cases
1417the application could invoked as:
1418
5a964f20 1419 % perl -e 'use Module::Name; method(@ARGV)' ...
f102b883 1420or
5a964f20 1421 % perl -mModule::Name ... (in perl5.002 or higher)
f102b883 1422
1423=back
1424
1425=head1 NOTE
1426
1427Perl does not enforce private and public parts of its modules as you may
1428have been used to in other languages like C++, Ada, or Modula-17. Perl
1429doesn't have an infatuation with enforced privacy. It would prefer
1430that you stayed out of its living room because you weren't invited, not
1431because it has a shotgun.
1432
1433The module and its user have a contract, part of which is common law,
1434and part of which is "written". Part of the common law contract is
1435that a module doesn't pollute any namespace it wasn't asked to. The
1436written contract for the module (A.K.A. documentation) may make other
1437provisions. But then you know when you C<use RedefineTheWorld> that
1438you're redefining the world and willing to take the consequences.