This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
The -n32 is normally part of $cc, not $ccflags.
[perl5.git] / pod / perlmodlib.pod
CommitLineData
f102b883
TC
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
GS
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
TC
22
23=head2 Pragmatic Modules
24
19799a22
GS
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
TC
30
31 no integer;
32 no strict 'refs';
4438c4b7 33 no warnings;
f102b883
TC
34
35which lasts until the end of that BLOCK.
36
19799a22
GS
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
GS
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
TC
44
45The following pragmas are defined (and have their own documentation).
46
47=over 12
48
09bef843
SB
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
GS
56
57=item autouse
58
9e107c59 59Postpone load of modules until a function is used
19799a22
GS
60
61=item base
62
63Establish IS-A relationship with base class at compile time
f102b883
TC
64
65=item blib
66
19799a22
GS
67Use MakeMaker's uninstalled version of a package
68
9e107c59
GS
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
GS
77=item constant
78
9e107c59 79Declare constants
f102b883
TC
80
81=item diagnostics
82
9e107c59 83Force verbose warning diagnostics
19799a22
GS
84
85=item fields
86
9e107c59 87Declare a class's attribute fields at compile-time
19799a22
GS
88
89=item filetest
90
9e107c59 91Control the filetest operators like C<-r>, C<-w> for AFS, etc.
f102b883
TC
92
93=item integer
94
9e107c59 95Compute arithmetic in integer instead of double
f102b883
TC
96
97=item less
98
9e107c59 99Request less of something from the compiler (unimplemented)
f102b883
TC
100
101=item lib
102
9e107c59 103Manipulate @INC at compile time
f102b883
TC
104
105=item locale
106
9e107c59 107Use or avoid POSIX locales for built-in operations
f102b883
TC
108
109=item ops
110
9e107c59 111Restrict unsafe operations when compiling
f102b883
TC
112
113=item overload
114
9e107c59 115Overload Perl operations
f102b883 116
b3eb6a9b
GS
117=item re
118
9e107c59 119Alter regular expression behavior
b3eb6a9b 120
f102b883
TC
121=item sigtrap
122
9e107c59 123Enable simple signal handling
f102b883
TC
124
125=item strict
126
9e107c59 127Restrict unsafe constructs
f102b883
TC
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
TC
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
TC
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
TC
158
159=item AutoLoader
160
9e107c59 161Load subroutines only on demand
f102b883
TC
162
163=item AutoSplit
164
9e107c59 165Split a package for autoloading
f102b883 166
19799a22
GS
167=item B
168
9e107c59 169Guts of the Perl code generator (aka compiler)
19799a22
GS
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
GS
202
203=item B::Disassembler
204
205Disassemble Perl bytecode
206
207=item B::Lint
208
9e107c59 209Module to catch dubious constructs
19799a22
GS
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
GS
219B::Stash -- XXX NFI XXX
220
19799a22
GS
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
TC
229=item Benchmark
230
9e107c59
GS
231Benchmark running times of code
232
233=item ByteLoader
234
235Load byte-compiled Perl code
f102b883 236
19799a22
GS
237=item CGI
238
9e107c59 239Simple Common Gateway Interface class
19799a22
GS
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
GS
257=item CGI::Pretty
258
259Module to produce nicely formatted HTML code
260
19799a22
GS
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
TC
269=item CPAN
270
9e107c59 271Query, download, and build Perl modules from CPAN sites
f102b883
TC
272
273=item CPAN::FirstTime
274
9e107c59 275Utility for CPAN::Config file initialization
f102b883
TC
276
277=item CPAN::Nox
278
19799a22 279Wrapper around CPAN.pm without using any XS module
f102b883
TC
280
281=item Carp
282
9e107c59
GS
283Act like warn/die from perspective of caller
284
285=item Carp::Heavy
286
287Carp guts
f102b883
TC
288
289=item Class::Struct
290
9e107c59 291Declare struct-like datatypes as Perl classes
f102b883
TC
292
293=item Config
294
9e107c59 295Access Perl configuration information
f102b883
TC
296
297=item Cwd
298
9e107c59 299Get pathname of current working directory
f102b883 300
19799a22
GS
301=item DB
302
9e107c59 303Programmatic interface to the Perl debugging API (experimental)
19799a22 304
f102b883
TC
305=item DB_File
306
19799a22
GS
307Perl5 access to Berkeley DB version 1.x
308
309=item Data::Dumper
310
9e107c59
GS
311Serialize Perl data structures
312
313=item Devel::DProf
314
315A Perl execution profiler
f102b883 316
f505c983
GS
317=item Devel::Peek
318
19799a22 319A data debugging tool for the XS programmer
f505c983 320
f102b883
TC
321=item Devel::SelfStubber
322
9e107c59 323Generate stubs for a SelfLoading module
f102b883
TC
324
325=item DirHandle
326
9e107c59 327Supply object methods for directory handles
f102b883 328
19799a22
GS
329=item Dumpvalue
330
9e107c59 331Provide screen dump of Perl data
19799a22 332
f102b883
TC
333=item DynaLoader
334
19799a22 335Dynamically load C libraries into Perl code
f102b883
TC
336
337=item English
338
9e107c59 339Use English (or awk) names for ugly punctuation variables
f102b883
TC
340
341=item Env
342
9e107c59 343Access environment variables as regular ones
19799a22
GS
344
345=item Errno
346
9e107c59 347Load the libc errno.h defines
f102b883
TC
348
349=item Exporter
350
9e107c59
GS
351Implement default import method for modules
352
353=item Exporter::Heavy
354
355Exporter guts
19799a22
GS
356
357=item ExtUtils::Command
358
9e107c59 359Utilities to replace common Unix commands in Makefiles etc.
f102b883
TC
360
361=item ExtUtils::Embed
362
9e107c59 363Utilities for embedding Perl in C/C++ programs
f102b883
TC
364
365=item ExtUtils::Install
366
9e107c59 367Install files from here to there
f102b883 368
19799a22
GS
369=item ExtUtils::Installed
370
371Inventory management of installed modules
372
f102b883
TC
373=item ExtUtils::Liblist
374
9e107c59
GS
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
TC
380
381=item ExtUtils::MM_OS2
382
9e107c59 383Methods to override Unix behavior in ExtUtils::MakeMaker
f102b883
TC
384
385=item ExtUtils::MM_Unix
386
9e107c59 387Methods used by ExtUtils::MakeMaker
f102b883
TC
388
389=item ExtUtils::MM_VMS
390
9e107c59 391Methods to override Unix behavior in ExtUtils::MakeMaker
19799a22
GS
392
393=item ExtUtils::MM_Win32
394
9e107c59 395Methods to override Unix behavior in ExtUtils::MakeMaker
f102b883
TC
396
397=item ExtUtils::MakeMaker
398
9e107c59 399Create an extension Makefile
f102b883
TC
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
TC
407=item ExtUtils::Mkbootstrap
408
9e107c59 409Make a bootstrap file for use by DynaLoader
f102b883
TC
410
411=item ExtUtils::Mksymlists
412
9e107c59 413Write linker options files for dynamic extension
f102b883 414
19799a22
GS
415=item ExtUtils::Packlist
416
9e107c59 417Manage .packlist files
19799a22 418
f102b883
TC
419=item ExtUtils::testlib
420
9e107c59 421Add blib/* directories to @INC
f102b883 422
b6c543e3
IZ
423=item Fatal
424
9e107c59 425Replace functions with equivalents which succeed or die
b6c543e3 426
f102b883
TC
427=item Fcntl
428
9e107c59 429Load the libc fcntl.h defines
f102b883
TC
430
431=item File::Basename
432
9e107c59
GS
433Split a pathname into pieces
434
435=item File::CheckTree
436
437Run many filetest checks on a tree
f102b883 438
f102b883
TC
439=item File::Compare
440
19799a22 441Compare files or filehandles
f102b883
TC
442
443=item File::Copy
444
19799a22
GS
445Copy files or filehandles
446
447=item File::DosGlob
448
9e107c59 449DOS-like globbing and then some
f102b883
TC
450
451=item File::Find
452
9e107c59
GS
453Traverse a file tree
454
455=item File::Glob
456
457Perl extension for BSD filename globbing
f102b883
TC
458
459=item File::Path
460
9e107c59 461Create or remove a series of directories
f102b883 462
f505c983
GS
463=item File::Spec
464
9e107c59 465Portably perform operations on file names
f505c983
GS
466
467=item File::Spec::Functions
468
9e107c59 469Portably perform operations on file names
19799a22
GS
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
GS
478
479=item File::Spec::Unix
480
9e107c59 481Methods used by File::Spec
19799a22
GS
482
483=item File::Spec::VMS
484
9e107c59 485Methods for VMS file specs
19799a22
GS
486
487=item File::Spec::Win32
488
9e107c59 489Methods for Win32 file specs
f505c983 490
f102b883
TC
491=item File::stat
492
9e107c59 493By-name interface to Perl's built-in stat() functions
f102b883
TC
494
495=item FileCache
496
9e107c59 497Keep more files open than the system permits
f102b883
TC
498
499=item FileHandle
500
9e107c59 501Supply object methods for filehandles
f102b883
TC
502
503=item FindBin
504
9e107c59 505Locate installation directory of running Perl program
f102b883
TC
506
507=item GDBM_File
508
9e107c59 509Access to the gdbm library
f102b883
TC
510
511=item Getopt::Long
512
9e107c59 513Extended processing of command line options
f102b883
TC
514
515=item Getopt::Std
516
19799a22 517Process single-character switches with switch clustering
f102b883
TC
518
519=item I18N::Collate
520
9e107c59 521Compare 8-bit scalar data according to current locale
f102b883
TC
522
523=item IO
524
9e107c59 525Front-end to load various IO modules
f102b883 526
19799a22
GS
527=item IO::Dir
528
9e107c59 529Supply object methods for directory handles
19799a22 530
f102b883
TC
531=item IO::File
532
9e107c59 533Supply object methods for filehandles
f102b883
TC
534
535=item IO::Handle
536
9e107c59 537Supply object methods for I/O handles
f102b883
TC
538
539=item IO::Pipe
540
9e107c59 541Supply object methods for pipes
f102b883 542
19799a22
GS
543=item IO::Poll
544
545Object interface to system poll call
546
f102b883
TC
547=item IO::Seekable
548
9e107c59 549Supply seek based methods for I/O objects
f102b883
TC
550
551=item IO::Select
552
553OO interface to the select system call
554
555=item IO::Socket
556
19799a22
GS
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
TC
570
571=item IPC::Open2
572
9e107c59 573Open a process for both reading and writing
f102b883
TC
574
575=item IPC::Open3
576
9e107c59 577Open a process for reading, writing, and error handling
f102b883 578
19799a22
GS
579=item IPC::Semaphore
580
581SysV Semaphore IPC object class
582
583=item IPC::SysV
584
585SysV IPC constants
586
f102b883
TC
587=item Math::BigFloat
588
19799a22 589Arbitrary length float math package
f102b883
TC
590
591=item Math::BigInt
592
19799a22 593Arbitrary size integer math package
f102b883
TC
594
595=item Math::Complex
596
9e107c59 597Complex numbers and associated mathematical functions
f102b883 598
404b15a1
CS
599=item Math::Trig
600
9e107c59 601Trigonometric functions
f102b883
TC
602
603=item Net::Ping
604
9e107c59 605Check a remote host for reachability
f102b883
TC
606
607=item Net::hostent
608
9e107c59 609By-name interface to Perl's built-in gethost*() functions
f102b883
TC
610
611=item Net::netent
612
9e107c59 613By-name interface to Perl's built-in getnet*() functions
f102b883
TC
614
615=item Net::protoent
616
9e107c59 617By-name interface to Perl's built-in getproto*() functions
f102b883
TC
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
TC
630
631=item POSIX
632
19799a22
GS
633Perl interface to IEEE Std 1003.1
634
9e107c59
GS
635=item Pod::Checker
636
637Check pod documents for syntax errors
638
19799a22
GS
639=item Pod::Html
640
9e107c59
GS
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
GS
658
659=item Pod::Text
660
9e107c59
GS
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
TC
670
671=item SDBM_File
672
19799a22 673Tied access to sdbm files
f102b883
TC
674
675=item Safe
676
19799a22 677Compile and execute code in restricted compartments
f102b883
TC
678
679=item Search::Dict
680
9e107c59 681Search for key in dictionary file
f102b883
TC
682
683=item SelectSaver
684
9e107c59 685Save and restore selected file handle
f102b883
TC
686
687=item SelfLoader
688
9e107c59 689Load functions only on demand
f102b883
TC
690
691=item Shell
692
9e107c59 693Run shell commands transparently within Perl
f102b883
TC
694
695=item Socket
696
9e107c59 697Load the libc socket.h defines and structure manipulators
f102b883
TC
698
699=item Symbol
700
9e107c59 701Manipulate Perl symbols and their names
f102b883
TC
702
703=item Sys::Hostname
704
19799a22 705Try every conceivable way to get hostname
f102b883
TC
706
707=item Sys::Syslog
708
9e107c59 709Interface to the libc syslog(3) calls
f102b883
TC
710
711=item Term::Cap
712
9e107c59 713Termcap interface
f102b883
TC
714
715=item Term::Complete
716
9e107c59 717Word completion module
f102b883
TC
718
719=item Term::ReadLine
720
9e107c59 721Interface to various `readline' packages.
19799a22
GS
722
723=item Test
724
9e107c59 725Provides a simple framework for writing test scripts
f102b883
TC
726
727=item Test::Harness
728
9e107c59 729Run Perl standard test scripts with statistics
f102b883
TC
730
731=item Text::Abbrev
732
9e107c59 733Create an abbreviation table from a list
f102b883
TC
734
735=item Text::ParseWords
736
9e107c59 737Parse text into a list of tokens or array of arrays
f102b883
TC
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
TC
744
745=item Text::Wrap
746
9e107c59 747Line wrapping to form simple paragraphs
19799a22
GS
748
749=item Tie::Array
750
9e107c59 751Base class for tied arrays
19799a22
GS
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
TC
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
TC
768
769=item Tie::SubstrHash
770
19799a22 771Fixed-table-size, fixed-key-length hashing
f102b883
TC
772
773=item Time::Local
774
9e107c59 775Efficiently compute time from local and GMT time
f102b883
TC
776
777=item Time::gmtime
778
9e107c59 779By-name interface to Perl's built-in gmtime() function
f102b883
TC
780
781=item Time::localtime
782
9e107c59 783By-name interface to Perl's built-in localtime() function
f102b883
TC
784
785=item Time::tm
786
9e107c59 787Internal object used by Time::gmtime and Time::localtime
f102b883
TC
788
789=item UNIVERSAL
790
9e107c59 791Base class for ALL classes (blessed references)
f102b883
TC
792
793=item User::grent
794
9e107c59 795By-name interface to Perl's built-in getgr*() functions
f102b883
TC
796
797=item User::pwent
798
9e107c59 799By-name interface to Perl's built-in getpw*() functions
f102b883
TC
800
801=back
802
19799a22
GS
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
GS
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
TC
816
817=head2 Extension Modules
818
19799a22
GS
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
TC
823
824Many popular C extension modules do not come bundled (at least, not
19799a22
GS
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
TC
830
831=head1 CPAN
832
19799a22
GS
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
TC
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
TC
912You should try to choose one close to you:
913
914=over
915
19799a22 916=item Africa
f102b883 917
be94a901
GS
918 South Africa ftp://ftp.is.co.za/programming/perl/CPAN/
919 ftp://ftpza.co.za/pub/mirrors/cpan/
f102b883 920
19799a22 921=item Asia
f102b883 922
be94a901
GS
923 China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
924 Hong Kong ftp://ftp.hkstar.com/pub/CPAN/
925 Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
926 Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/
927 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
928 ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
929 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
19799a22 930 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
be94a901
GS
931 ftp://mirror.nucba.ac.jp/mirror/Perl/
932 Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
933 South Korea ftp://ftp.bora.net/pub/CPAN/
934 ftp://ftp.nuri.net/pub/CPAN/
935 Taiwan ftp://ftp.wownet.net/pub2/PERL/
936 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
937 Thailand ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
938 ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
f102b883 939
19799a22 940=item Australasia
f102b883 941
be94a901
GS
942 Australia ftp://cpan.topend.com.au/pub/CPAN/
943 ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
944 ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
945 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
946 New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
947 ftp://sunsite.net.nz/pub/languages/perl/CPAN/
948
be94a901
GS
949Central America
950
951 Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
f102b883 952
19799a22 953=item Europe
f102b883 954
be94a901
GS
955 Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
956 Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
957 Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/
958 Croatia ftp://ftp.linux.hr/pub/CPAN/
959 Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
960 ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
961 Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
962 Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/
963 Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/
964 France ftp://ftp.lip6.fr/pub/perl/CPAN/
965 ftp://ftp.oleane.net/pub/mirrors/CPAN/
966 ftp://ftp.pasteur.fr/pub/computing/CPAN/
967 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
968 ftp://ftp.gmd.de/packages/CPAN/
969 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
970 ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/
971 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
972 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
973 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
974 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
975 Greece ftp://ftp.ntua.gr/pub/lang/perl/
976 Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
977 Ireland ftp://sunsite.compapp.dcu.ie/pub/perl/
978 Italy ftp://cis.uniRoma2.it/CPAN/
979 ftp://ftp.flashnet.it/pub/CPAN/
19799a22 980 ftp://ftp.unina.it/pub/Other/CPAN/
be94a901
GS
981 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
982 Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/
19799a22 983 ftp://ftp.EU.net/packages/cpan/
be94a901
GS
984 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
985 Norway ftp://ftp.uit.no/pub/languages/perl/cpan/
986 ftp://sunsite.uio.no/pub/languages/perl/CPAN/
987 Poland ftp://ftp.man.szczecin.pl/pub/perl/CPAN/
988 ftp://ftp.man.torun.pl/pub/doc/CPAN/
989 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
990 ftp://sunsite.icm.edu.pl/pub/CPAN/
991 Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
19799a22 992 ftp://ftp.ist.utl.pt/pub/CPAN/
be94a901
GS
993 ftp://ftp.ua.pt/pub/CPAN/
994 Romania ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
995 ftp://ftp.dnttm.ro/pub/CPAN/
19799a22 996 Russia ftp://ftp.chg.ru/pub/lang/perl/CPAN/
be94a901
GS
997 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
998 Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/
999 Slovenia ftp://ftp.arnes.si/software/perl/CPAN/
1000 Spain ftp://ftp.etse.urv.es/pub/perl/
1001 ftp://ftp.rediris.es/mirror/CPAN/
1002 Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/
1003 Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
1004 Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
1005 United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
1006 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
1007 ftp://ftp.plig.org/pub/CPAN/
1008 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
1009 ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
f102b883 1010
19799a22 1011=item North America
f102b883 1012
be94a901 1013 Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
19799a22
GS
1014 California ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
1015 ftp://ftp.cdrom.com/pub/perl/CPAN/
be94a901
GS
1016 ftp://ftp.digital.com/pub/plan/perl/CPAN/
1017 Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
1018 Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
1019 Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
1020 Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
1021 ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
1022 Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/
1023 Massachusetts ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
1024 ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
19799a22
GS
1025 Mexico ftp://ftp.msg.com.mx/pub/CPAN/
1026 Minnesota ftp://ftp.midearthbbs.com/CPAN/
be94a901
GS
1027 New York ftp://ftp.rge.com/pub/languages/perl/
1028 North Carolina ftp://ftp.duke.edu/pub/perl/
1029 Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/
19799a22 1030 Ontario ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
be94a901
GS
1031 Oregon ftp://ftp.orst.edu/pub/packages/CPAN/
1032 Pennsylvania ftp://ftp.epix.net/pub/languages/perl/
1033 Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/
1034 Utah ftp://mirror.xmission.com/CPAN/
1035 Virginia ftp://ftp.perl.org/pub/perl/CPAN/
1036 ftp://ruff.cs.jmu.edu/pub/CPAN/
19799a22
GS
1037 Washington ftp://ftp-mirror.internap.com/pub/CPAN/
1038 ftp://ftp.spu.edu/pub/CPAN/
f102b883 1039
19799a22 1040=item South America
f102b883 1041
be94a901 1042 Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/
19799a22 1043 Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
f102b883
TC
1044
1045=back
1046
1047For an up-to-date listing of CPAN sites,
19799a22 1048see http://www.perl.com/perl/CPAN or ftp://www.perl.com/perl/ .
f102b883
TC
1049
1050=head1 Modules: Creation, Use, and Abuse
1051
1052(The following section is borrowed directly from Tim Bunce's modules
1053file, available at your nearest CPAN site.)
1054
1055Perl implements a class using a package, but the presence of a
1056package doesn't imply the presence of a class. A package is just a
1057namespace. A class is a package that provides subroutines that can be
1058used as methods. A method is just a subroutine that expects, as its
1059first argument, either the name of a package (for "static" methods),
1060or a reference to something (for "virtual" methods).
1061
1062A module is a file that (by convention) provides a class of the same
1063name (sans the .pm), plus an import method in that class that can be
1064called to fetch exported symbols. This module may implement some of
1065its methods by loading dynamic C or C++ objects, but that should be
1066totally transparent to the user of the module. Likewise, the module
1067might set up an AUTOLOAD function to slurp in subroutine definitions on
1068demand, but this is also transparent. Only the F<.pm> file is required to
1069exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1070the AUTOLOAD mechanism.
1071
1072=head2 Guidelines for Module Creation
1073
1074=over 4
1075
1076=item Do similar modules already exist in some form?
1077
1078If so, please try to reuse the existing modules either in whole or
1079by inheriting useful features into a new class. If this is not
1080practical try to get together with the module authors to work on
1081extending or enhancing the functionality of the existing modules.
1082A perfect example is the plethora of packages in perl4 for dealing
1083with command line options.
1084
1085If you are writing a module to expand an already existing set of
1086modules, please coordinate with the author of the package. It
1087helps if you follow the same naming scheme and module interaction
1088scheme as the original author.
1089
1090=item Try to design the new module to be easy to extend and reuse.
1091
19799a22
GS
1092Always use B<-w>.
1093
f102b883
TC
1094Use blessed references. Use the two argument form of bless to bless
1095into the class name given as the first parameter of the constructor,
1096e.g.,:
1097
1098 sub new {
1099 my $class = shift;
1100 return bless {}, $class;
1101 }
1102
1103or even this if you'd like it to be used as either a static
1104or a virtual method.
1105
1106 sub new {
1107 my $self = shift;
1108 my $class = ref($self) || $self;
1109 return bless {}, $class;
1110 }
1111
1112Pass arrays as references so more parameters can be added later
1113(it's also faster). Convert functions into methods where
1114appropriate. Split large methods into smaller more flexible ones.
1115Inherit methods from other modules if appropriate.
1116
1117Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
19799a22 1118Generally you can delete the C<eq 'FOO'> part with no harm at all.
f102b883
TC
1119Let the objects look after themselves! Generally, avoid hard-wired
1120class names as far as possible.
1121
1122Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
1123C<$r-E<gt>func()> would work (see L<perlbot> for more details).
1124
1125Use autosplit so little used or newly added functions won't be a
5a964f20 1126burden to programs that don't use them. Add test functions to
f102b883
TC
1127the module after __END__ either using AutoSplit or by saying:
1128
1129 eval join('',<main::DATA>) || die $@ unless caller();
1130
1131Does your module pass the 'empty subclass' test? If you say
19799a22 1132C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
f102b883
TC
1133to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1134does your application still work if you change: C<$obj = new YOURCLASS;>
1135into: C<$obj = new SUBCLASS;> ?
1136
1137Avoid keeping any state information in your packages. It makes it
1138difficult for multiple other packages to use yours. Keep state
1139information in objects.
1140
19799a22
GS
1141Always use B<-w>.
1142
1143Try to C<use strict;> (or C<use strict qw(...);>).
f102b883 1144Remember that you can add C<no strict qw(...);> to individual blocks
19799a22
GS
1145of code that need less strictness.
1146
1147Always use B<-w>.
1148
f102b883
TC
1149Follow the guidelines in the perlstyle(1) manual.
1150
19799a22
GS
1151Always use B<-w>.
1152
f102b883
TC
1153=item Some simple style guidelines
1154
5a964f20 1155The perlstyle manual supplied with Perl has many helpful points.
f102b883
TC
1156
1157Coding style is a matter of personal taste. Many people evolve their
1158style over several years as they learn what helps them write and
1159maintain good code. Here's one set of assorted suggestions that
1160seem to be widely used by experienced developers:
1161
1162Use underscores to separate words. It is generally easier to read
1163$var_names_like_this than $VarNamesLikeThis, especially for
1164non-native speakers of English. It's also a simple rule that works
1165consistently with VAR_NAMES_LIKE_THIS.
1166
1167Package/Module names are an exception to this rule. Perl informally
1168reserves lowercase module names for 'pragma' modules like integer
1169and strict. Other modules normally begin with a capital letter and
1170use mixed case with no underscores (need to be short and portable).
1171
1172You may find it helpful to use letter case to indicate the scope
1173or nature of a variable. For example:
1174
5a964f20 1175 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
f102b883
TC
1176 $Some_Caps_Here package-wide global/static
1177 $no_caps_here function scope my() or local() variables
1178
1179Function and method names seem to work best as all lowercase.
1180e.g., C<$obj-E<gt>as_string()>.
1181
1182You can use a leading underscore to indicate that a variable or
1183function should not be used outside the package that defined it.
1184
1185=item Select what to export.
1186
1187Do NOT export method names!
1188
1189Do NOT export anything else by default without a good reason!
1190
1191Exports pollute the namespace of the module user. If you must
1192export try to use @EXPORT_OK in preference to @EXPORT and avoid
1193short or common names to reduce the risk of name clashes.
1194
1195Generally anything not exported is still accessible from outside the
1196module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
1197syntax. By convention you can use a leading underscore on names to
1198indicate informally that they are 'internal' and not for public use.
1199
1200(It is actually possible to get private functions by saying:
1201C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1202directly as a method, because a method must have a name in the symbol
1203table.)
1204
1205As a general rule, if the module is trying to be object oriented
1206then export nothing. If it's just a collection of functions then
1207@EXPORT_OK anything but use @EXPORT with caution.
1208
1209=item Select a name for the module.
1210
1211This name should be as descriptive, accurate, and complete as
1212possible. Avoid any risk of ambiguity. Always try to use two or
1213more whole words. Generally the name should reflect what is special
1214about what the module does rather than how it does it. Please use
1215nested module names to group informally or categorize a module.
1216There should be a very good reason for a module not to have a nested name.
1217Module names should begin with a capital letter.
1218
1219Having 57 modules all called Sort will not make life easy for anyone
1220(though having 23 called Sort::Quick is only marginally better :-).
1221Imagine someone trying to install your module alongside many others.
1222If in any doubt ask for suggestions in comp.lang.perl.misc.
1223
1224If you are developing a suite of related modules/classes it's good
1225practice to use nested classes with a common prefix as this will
1226avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1227Xyz::Model etc. Use the modules in this list as a naming guide.
1228
1229If adding a new module to a set, follow the original author's
1230standards for naming modules and the interface to methods in
1231those modules.
1232
1233To be portable each component of a module name should be limited to
123411 characters. If it might be used on MS-DOS then try to ensure each is
1235unique in the first 8 characters. Nested modules make this easier.
1236
1237=item Have you got it right?
1238
1239How do you know that you've made the right decisions? Have you
1240picked an interface design that will cause problems later? Have
1241you picked the most appropriate name? Do you have any questions?
1242
1243The best way to know for sure, and pick up many helpful suggestions,
1244is to ask someone who knows. Comp.lang.perl.misc is read by just about
1245all the people who develop modules and it's the best place to ask.
1246
1247All you need to do is post a short summary of the module, its
1248purpose and interfaces. A few lines on each of the main methods is
1249probably enough. (If you post the whole module it might be ignored
1250by busy people - generally the very people you want to read it!)
1251
1252Don't worry about posting if you can't say when the module will be
1253ready - just say so in the message. It might be worth inviting
1254others to help you, they may be able to complete it for you!
1255
1256=item README and other Additional Files.
1257
1258It's well known that software developers usually fully document the
1259software they write. If, however, the world is in urgent need of
1260your software and there is not enough time to write the full
1261documentation please at least provide a README file containing:
1262
1263=over 10
1264
1265=item *
1266A description of the module/package/extension etc.
1267
1268=item *
1269A copyright notice - see below.
1270
1271=item *
1272Prerequisites - what else you may need to have.
1273
1274=item *
1275How to build it - possible changes to Makefile.PL etc.
1276
1277=item *
1278How to install it.
1279
1280=item *
1281Recent changes in this release, especially incompatibilities
1282
1283=item *
1284Changes / enhancements you plan to make in the future.
1285
1286=back
1287
1288If the README file seems to be getting too large you may wish to
1289split out some of the sections into separate files: INSTALL,
1290Copying, ToDo etc.
1291
1292=over 4
1293
1294=item Adding a Copyright Notice.
1295
1296How you choose to license your work is a personal decision.
1297The general mechanism is to assert your Copyright and then make
1298a declaration of how others may copy/use/modify your work.
1299
1300Perl, for example, is supplied with two types of licence: The GNU
1301GPL and The Artistic Licence (see the files README, Copying, and
1302Artistic). Larry has good reasons for NOT just using the GNU GPL.
1303
1304My personal recommendation, out of respect for Larry, Perl, and the
5a964f20 1305Perl community at large is to state something simply like:
f102b883
TC
1306
1307 Copyright (c) 1995 Your Name. All rights reserved.
1308 This program is free software; you can redistribute it and/or
1309 modify it under the same terms as Perl itself.
1310
1311This statement should at least appear in the README file. You may
1312also wish to include it in a Copying file and your source files.
1313Remember to include the other words in addition to the Copyright.
1314
1315=item Give the module a version/issue/release number.
1316
1317To be fully compatible with the Exporter and MakeMaker modules you
1318should store your module's version number in a non-my package
1319variable called $VERSION. This should be a floating point
1320number with at least two digits after the decimal (i.e., hundredths,
1321e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
19799a22 1322See L<Exporter> for details.
f102b883
TC
1323
1324It may be handy to add a function or method to retrieve the number.
1325Use the number in announcements and archive file names when
1326releasing the module (ModuleName-1.02.tar.Z).
1327See perldoc ExtUtils::MakeMaker.pm for details.
1328
1329=item How to release and distribute a module.
1330
1331It's good idea to post an announcement of the availability of your
1332module (or the module itself if small) to the comp.lang.perl.announce
1333Usenet newsgroup. This will at least ensure very wide once-off
1334distribution.
1335
19799a22 1336If possible, register the module with CPAN. You should
f102b883
TC
1337include details of its location in your announcement.
1338
1339Some notes about ftp archives: Please use a long descriptive file
5a964f20 1340name that includes the version number. Most incoming directories
f102b883
TC
1341will not be readable/listable, i.e., you won't be able to see your
1342file after uploading it. Remember to send your email notification
1343message as soon as possible after uploading else your file may get
1344deleted automatically. Allow time for the file to be processed
1345and/or check the file has been processed before announcing its
1346location.
1347
1348FTP Archives for Perl Modules:
1349
1350Follow the instructions and links on
1351
1352 http://franz.ww.tu-berlin.de/modulelist
1353
1354or upload to one of these sites:
1355
1356 ftp://franz.ww.tu-berlin.de/incoming
1357 ftp://ftp.cis.ufl.edu/incoming
1358
1359and notify <F<upload@franz.ww.tu-berlin.de>>.
1360
1361By using the WWW interface you can ask the Upload Server to mirror
1362your modules from your ftp or WWW site into your own directory on
1363CPAN!
1364
1365Please remember to send me an updated entry for the Module list!
1366
1367=item Take care when changing a released module.
1368
7b8d334a
GS
1369Always strive to remain compatible with previous released versions.
1370Otherwise try to add a mechanism to revert to the
19799a22 1371old behavior if people rely on it. Document incompatible changes.
f102b883
TC
1372
1373=back
1374
1375=back
1376
1377=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1378
1379=over 4
1380
1381=item There is no requirement to convert anything.
1382
1383If it ain't broke, don't fix it! Perl 4 library scripts should
1384continue to work with no problems. You may need to make some minor
1385changes (like escaping non-array @'s in double quoted strings) but
1386there is no need to convert a .pl file into a Module for just that.
1387
1388=item Consider the implications.
1389
5a964f20 1390All Perl applications that make use of the script will need to
f102b883
TC
1391be changed (slightly) if the script is converted into a module. Is
1392it worth it unless you plan to make other changes at the same time?
1393
1394=item Make the most of the opportunity.
1395
1396If you are going to convert the script to a module you can use the
19799a22
GS
1397opportunity to redesign the interface. The guidelines for module
1398creation above include many of the issues you should consider.
f102b883
TC
1399
1400=item The pl2pm utility will get you started.
1401
1402This utility will read *.pl files (given as parameters) and write
1403corresponding *.pm files. The pl2pm utilities does the following:
1404
1405=over 10
1406
1407=item *
1408Adds the standard Module prologue lines
1409
1410=item *
1411Converts package specifiers from ' to ::
1412
1413=item *
1414Converts die(...) to croak(...)
1415
1416=item *
1417Several other minor changes
1418
1419=back
1420
1421Being a mechanical process pl2pm is not bullet proof. The converted
1422code will need careful checking, especially any package statements.
1423Don't delete the original .pl file till the new .pm one works!
1424
1425=back
1426
1427=head2 Guidelines for Reusing Application Code
1428
1429=over 4
1430
1431=item Complete applications rarely belong in the Perl Module Library.
1432
5a964f20 1433=item Many applications contain some Perl code that could be reused.
f102b883
TC
1434
1435Help save the world! Share your code in a form that makes it easy
1436to reuse.
1437
1438=item Break-out the reusable code into one or more separate module files.
1439
1440=item Take the opportunity to reconsider and redesign the interfaces.
1441
1442=item In some cases the 'application' can then be reduced to a small
1443
1444fragment of code built on top of the reusable modules. In these cases
1445the application could invoked as:
1446
5a964f20 1447 % perl -e 'use Module::Name; method(@ARGV)' ...
f102b883 1448or
5a964f20 1449 % perl -mModule::Name ... (in perl5.002 or higher)
f102b883
TC
1450
1451=back
1452
1453=head1 NOTE
1454
1455Perl does not enforce private and public parts of its modules as you may
1456have been used to in other languages like C++, Ada, or Modula-17. Perl
1457doesn't have an infatuation with enforced privacy. It would prefer
1458that you stayed out of its living room because you weren't invited, not
1459because it has a shotgun.
1460
1461The module and its user have a contract, part of which is common law,
1462and part of which is "written". Part of the common law contract is
1463that a module doesn't pollute any namespace it wasn't asked to. The
1464written contract for the module (A.K.A. documentation) may make other
1465provisions. But then you know when you C<use RedefineTheWorld> that
1466you're redefining the world and willing to take the consequences.