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