This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
URL fixups from Michael Schwern.
[perl5.git] / pod / perlmodlib.pod
1 # Generated by perlmodlib.PL  DO NOT EDIT!
2
3 =head1 NAME
4
5 perlmodlib - constructing new Perl modules and finding existing ones
6
7 =head1 DESCRIPTION
8
9 =head1 THE PERL MODULE LIBRARY
10
11 Many modules are included the Perl distribution.  These are described
12 below, and all end in F<.pm>.  You may discover compiled library
13 file (usually ending in F<.so>) or small pieces of modules to be
14 autoloaded (ending in F<.al>); these were automatically generated
15 by the installation process.  You may also discover files in the
16 library directory that end in either F<.pl> or F<.ph>.  These are
17 old libraries supplied so that old programs that use them still
18 run.  The F<.pl> files will all eventually be converted into standard
19 modules, and the F<.ph> files made by B<h2ph> will probably end up
20 as extension modules made by B<h2xs>.  (Some F<.ph> values may
21 already be available through the POSIX, Errno, or Fcntl modules.)
22 The B<pl2pm> file in the distribution may help in your conversion,
23 but it's just a mechanical process and therefore far from bulletproof.
24
25 =head2 Pragmatic Modules
26
27 They work somewhat like compiler directives (pragmata) in that they
28 tend to affect the compilation of your program, and thus will usually
29 work well only when used within a C<use>, or C<no>.  Most of these
30 are lexically scoped, so an inner BLOCK may countermand them
31 by saying:
32
33     no integer;
34     no strict 'refs';
35     no warnings;
36
37 which lasts until the end of that BLOCK.
38
39 Some pragmas are lexically scoped--typically those that affect the
40 C<$^H> hints variable.  Others affect the current package instead,
41 like C<use vars> and C<use subs>, which allow you to predeclare a
42 variables or subroutines within a particular I<file> rather than
43 just a block.  Such declarations are effective for the entire file
44 for which they were declared.  You cannot rescind them with C<no
45 vars> or C<no subs>.
46
47 The following pragmas are defined (and have their own documentation).
48
49 =over 12
50
51 =item attributes
52
53 Get/set subroutine or variable attributes
54
55 =item attrs
56
57 Set/get attributes of a subroutine (deprecated)
58
59 =item autouse
60
61 Postpone load of modules until a function is used
62
63 =item base
64
65 Establish IS-A relationship with base class at compile time
66
67 =item blib
68
69 Use MakeMaker's uninstalled version of a package
70
71 =item bytes
72
73 Force byte semantics rather than character semantics
74
75 =item charnames
76
77 Define character names for C<\N{named}> string literal escapes.
78
79 =item constant
80
81 Declare constants
82
83 =item diagnostics
84
85 Perl compiler pragma to force verbose warning diagnostics
86
87 =item encoding
88
89 Pragma to control the conversion of legacy data into Unicode
90
91 =item fields
92
93 Compile-time class fields
94
95 =item filetest
96
97 Control the filetest permission operators
98
99 =item integer
100
101 Use integer arithmetic instead of floating point
102
103 =item less
104
105 Request less of something from the compiler
106
107 =item locale
108
109 Use and avoid POSIX locales for built-in operations
110
111 =item open
112
113 Set default disciplines for input and output
114
115 =item ops
116
117 Restrict unsafe operations when compiling
118
119 =item overload
120
121 Package for overloading perl operations
122
123 =item re
124
125 Alter regular expression behaviour
126
127 =item sigtrap
128
129 Enable simple signal handling
130
131 =item sort
132
133 Control sort() behaviour
134
135 =item strict
136
137 Restrict unsafe constructs
138
139 =item subs
140
141 Predeclare sub names
142
143 =item threads
144
145 Perl extension allowing use of interpreter based threads from perl
146
147 =item utf8
148
149 Enable/disable UTF-8 (or UTF-EBCDIC) in source code
150
151 =item vars
152
153 Predeclare global variable names (obsolete)
154
155 =item vmsish
156
157 Control VMS-specific language features
158
159 =item warnings
160
161 Control optional warnings
162
163 =item warnings::register
164
165 Warnings import function
166
167 =back
168
169 =head2 Standard Modules
170
171 Standard, bundled modules are all expected to behave in a well-defined
172 manner with respect to namespace pollution because they use the
173 Exporter module.  See their own documentation for details.
174
175 =over 12
176
177 =item AnyDBM_File
178
179 Provide framework for multiple DBMs
180
181 =item Attribute::Handlers
182
183 Simpler definition of attribute handlers
184
185 =item AutoLoader
186
187 Load subroutines only on demand
188
189 =item AutoSplit
190
191 Split a package for autoloading
192
193 =item B
194
195 The Perl Compiler
196
197 =item B::Asmdata
198
199 Autogenerated data about Perl ops, used to generate bytecode
200
201 =item B::Assembler
202
203 Assemble Perl bytecode
204
205 =item B::Bblock
206
207 Walk basic blocks
208
209 =item B::Bytecode
210
211 Perl compiler's bytecode backend
212
213 =item B::C
214
215 Perl compiler's C backend
216
217 =item B::CC
218
219 Perl compiler's optimized C translation backend
220
221 =item B::Concise
222
223 Walk Perl syntax tree, printing concise info about ops
224
225 =item B::Debug
226
227 Walk Perl syntax tree, printing debug info about ops
228
229 =item B::Deparse
230
231 Perl compiler backend to produce perl code
232
233 =item B::Disassembler
234
235 Disassemble Perl bytecode
236
237 =item B::Lint
238
239 Perl lint
240
241 =item B::Showlex
242
243 Show lexical variables used in functions or files
244
245 =item B::Stackobj
246
247 Helper module for CC backend
248
249 =item B::Stash
250
251 Show what stashes are loaded
252
253 =item B::Terse
254
255 Walk Perl syntax tree, printing terse info about ops
256
257 =item B::Xref
258
259 Generates cross reference reports for Perl programs
260
261 =item Benchmark
262
263 Benchmark running times of Perl code
264
265 =item ByteLoader
266
267 Load byte compiled perl code
268
269 =item CGI
270
271 Simple Common Gateway Interface Class
272
273 =item CGI::Apache
274
275 Backward compatibility module for CGI.pm
276
277 =item CGI::Carp
278
279 CGI routines for writing to the HTTPD (or other) error log
280
281 =item CGI::Cookie
282
283 Interface to Netscape Cookies
284
285 =item CGI::Fast
286
287 CGI Interface for Fast CGI
288
289 =item CGI::Pretty
290
291 Module to produce nicely formatted HTML code
292
293 =item CGI::Push
294
295 Simple Interface to Server Push
296
297 =item CGI::Switch
298
299 Backward compatibility module for defunct CGI::Switch
300
301 =item CGI::Util
302
303 Internal utilities used by CGI module
304
305 =item CPAN
306
307 Query, download and build perl modules from CPAN sites
308
309 =item CPAN::FirstTime
310
311 Utility for CPAN::Config file Initialization
312
313 =item CPAN::Nox
314
315 Wrapper around CPAN.pm without using any XS module
316
317 =item Carp
318
319 Warn of errors (from perspective of caller)
320
321 =item Carp::Heavy
322
323 No user serviceable parts inside
324
325 =item Class::ISA
326
327 Report the search path for a class's ISA tree
328
329 =item Class::Struct
330
331 Declare struct-like datatypes as Perl classes
332
333 =item Cwd
334
335 Get pathname of current working directory
336
337 =item DB
338
339 Programmatic interface to the Perl debugging API (draft, subject to
340
341 =item DB_File
342
343 Perl5 access to Berkeley DB version 1.x
344
345 =item Devel::SelfStubber
346
347 Generate stubs for a SelfLoading module
348
349 =item Digest
350
351 Modules that calculate message digests
352
353 =item DirHandle
354
355 Supply object methods for directory handles
356
357 =item Dumpvalue
358
359 Provides screen dump of Perl data.
360
361 =item Encode
362
363 Character encodings
364
365 =item Encode::EncodeFormat
366
367 The format of encoding tables of the Encode extension
368
369 =item Encode::Tcl
370
371 Tcl encodings
372
373 =item English
374
375 Use nice English (or awk) names for ugly punctuation variables
376
377 =item Env
378
379 Perl module that imports environment variables as scalars or arrays
380
381 =item Exporter
382
383 Implements default import method for modules
384
385 =item Exporter::Heavy
386
387 Exporter guts
388
389 =item ExtUtils::Command
390
391 Utilities to replace common UNIX commands in Makefiles etc.
392
393 =item ExtUtils::Constant
394
395 Generate XS code to import C header constants
396
397 =item ExtUtils::Embed
398
399 Utilities for embedding Perl in C/C++ applications
400
401 =item ExtUtils::Install
402
403 Install files from here to there
404
405 =item ExtUtils::Installed
406
407 Inventory management of installed modules
408
409 =item ExtUtils::Liblist
410
411 Determine libraries to use and how to use them
412
413 =item ExtUtils::MM_Cygwin
414
415 Methods to override UN*X behaviour in ExtUtils::MakeMaker
416
417 =item ExtUtils::MM_NW5
418
419 Methods to override UN*X behaviour in ExtUtils::MakeMaker
420
421 =item ExtUtils::MM_OS2
422
423 Methods to override UN*X behaviour in ExtUtils::MakeMaker
424
425 =item ExtUtils::MM_Unix
426
427 Methods used by ExtUtils::MakeMaker
428
429 =item ExtUtils::MM_VMS
430
431 Methods to override UN*X behaviour in ExtUtils::MakeMaker
432
433 =item ExtUtils::MM_Win32
434
435 Methods to override UN*X behaviour in ExtUtils::MakeMaker
436
437 =item ExtUtils::MakeMaker
438
439 Create an extension Makefile
440
441 =item ExtUtils::Manifest
442
443 Utilities to write and check a MANIFEST file
444
445 =item ExtUtils::Mkbootstrap
446
447 Make a bootstrap file for use by DynaLoader
448
449 =item ExtUtils::Mksymlists
450
451 Write linker options files for dynamic extension
452
453 =item ExtUtils::Packlist
454
455 Manage .packlist files
456
457 =item ExtUtils::testlib
458
459 Add blib/* directories to @INC
460
461 =item Fatal
462
463 Replace functions with equivalents which succeed or die
464
465 =item Fcntl
466
467 Load the C Fcntl.h defines
468
469 =item File::Basename
470
471 Split a pathname into pieces
472
473 =item File::CheckTree
474
475 Run many filetest checks on a tree
476
477 =item File::Compare
478
479 Compare files or filehandles
480
481 =item File::Copy
482
483 Copy files or filehandles
484
485 =item File::DosGlob
486
487 DOS like globbing and then some
488
489 =item File::Find
490
491 Traverse a file tree
492
493 =item File::Path
494
495 Create or remove directory trees
496
497 =item File::Spec
498
499 Portably perform operations on file names
500
501 =item File::Spec::Epoc
502
503 Methods for Epoc file specs
504
505 =item File::Spec::Functions
506
507 Portably perform operations on file names
508
509 =item File::Spec::Mac
510
511 File::Spec for Mac OS (Classic)
512
513 =item File::Spec::OS2
514
515 Methods for OS/2 file specs
516
517 =item File::Spec::Unix
518
519 File::Spec for Unix, base for other File::Spec modules
520
521 =item File::Spec::VMS
522
523 Methods for VMS file specs
524
525 =item File::Spec::Win32
526
527 Methods for Win32 file specs
528
529 =item File::Temp
530
531 Return name and handle of a temporary file safely
532
533 =item File::stat
534
535 By-name interface to Perl's built-in stat() functions
536
537 =item FileCache
538
539 Keep more files open than the system permits
540
541 =item FileHandle
542
543 Supply object methods for filehandles
544
545 =item Filter::Simple
546
547 Simplified source filtering
548
549 =item FindBin
550
551 Locate directory of original perl script
552
553 =item Getopt::Long
554
555 Extended processing of command line options
556
557 =item Getopt::Std
558
559 Process single-character switches with switch clustering
560
561 =item I18N::Collate
562
563 Compare 8-bit scalar data according to the current locale
564
565 =item I18N::LangTags
566
567 Functions for dealing with RFC3066-style language tags
568
569 =item I18N::LangTags::List
570
571 Tags and names for human languages
572
573 =item IO
574
575 Load various IO modules
576
577 =item IPC::Open2
578
579 Open a process for both reading and writing
580
581 =item IPC::Open3
582
583 Open a process for reading, writing, and error handling
584
585 =item Locale::Constants
586
587 Constants for Locale codes
588
589 =item Locale::Country
590
591 ISO codes for country identification (ISO 3166)
592
593 =item Locale::Currency
594
595 ISO three letter codes for currency identification (ISO 4217)
596
597 =item Locale::Language
598
599 ISO two letter codes for language identification (ISO 639)
600
601 =item Locale::Maketext
602
603 Framework for localization
604
605 =item Locale::Maketext::TPJ13
606
607 Article about software localization
608
609 =item Math::BigFloat
610
611 Arbitrary size floating point math package
612
613 =item Math::BigInt
614
615 Arbitrary size integer math package
616
617 =item Math::BigInt::Calc
618
619 Pure Perl module to support Math::BigInt
620
621 =item Math::Complex
622
623 Complex numbers and associated mathematical functions
624
625 =item Math::Trig
626
627 Trigonometric functions
628
629 =item Memoize
630
631 Make your functions faster by trading space for time
632
633 =item Memoize::AnyDBM_File
634
635 Glue to provide EXISTS for AnyDBM_File for Storable use
636
637 =item Memoize::Expire
638
639 Plug-in module for automatic expiration of memoized values
640
641 =item Memoize::ExpireFile
642
643 Test for Memoize expiration semantics
644
645 =item Memoize::ExpireTest
646
647 Test for Memoize expiration semantics
648
649 =item Memoize::NDBM_File
650
651 Glue to provide EXISTS for NDBM_File for Storable use
652
653 =item Memoize::SDBM_File
654
655 Glue to provide EXISTS for SDBM_File for Storable use
656
657 =item Memoize::Saves
658
659 Plug-in module to specify which return values should be memoized
660
661 =item Memoize::Storable
662
663 Store Memoized data in Storable database
664
665 =item NDBM_File
666
667 Tied access to ndbm files
668
669 =item NEXT
670
671 Provide a pseudo-class NEXT that allows method redispatch
672
673 =item Net::Cmd
674
675 Network Command class (as used by FTP, SMTP etc)
676
677 =item Net::Config
678
679 Local configuration data for libnet
680
681 =item Net::Domain
682
683 Attempt to evaluate the current host's internet name and domain
684
685 =item Net::FTP
686
687 FTP Client class
688
689 =item Net::NNTP
690
691 NNTP Client class
692
693 =item Net::Netrc
694
695 OO interface to users netrc file
696
697 =item Net::POP3
698
699 Post Office Protocol 3 Client class (RFC1081)
700
701 =item Net::Ping
702
703 Check a remote host for reachability
704
705 =item Net::SMTP
706
707 Simple Mail Transfer Protocol Client
708
709 =item Net::Time
710
711 Time and daytime network client interface
712
713 =item Net::hostent
714
715 By-name interface to Perl's built-in gethost*() functions
716
717 =item Net::libnetFAQ
718
719 Libnet Frequently Asked Questions
720
721 =item Net::netent
722
723 By-name interface to Perl's built-in getnet*() functions
724
725 =item Net::protoent
726
727 By-name interface to Perl's built-in getproto*() functions
728
729 =item Net::servent
730
731 By-name interface to Perl's built-in getserv*() functions
732
733 =item O
734
735 Generic interface to Perl Compiler backends
736
737 =item ODBM_File
738
739 Tied access to odbm files
740
741 =item Opcode
742
743 Disable named opcodes when compiling perl code
744
745 =item POSIX
746
747 Perl interface to IEEE Std 1003.1
748
749 =item PerlIO
750
751 On demand loader for PerlIO layers and root of PerlIO::* name space
752
753 =item Pod::Checker
754
755 Check pod documents for syntax errors
756
757 =item Pod::Find
758
759 Find POD documents in directory trees
760
761 =item Pod::Html
762
763 Module to convert pod files to HTML
764
765 =item Pod::InputObjects
766
767 Objects representing POD input paragraphs, commands, etc.
768
769 =item Pod::LaTeX
770
771 Convert Pod data to formatted Latex
772
773 =item Pod::Man
774
775 Convert POD data to formatted *roff input
776
777 =item Pod::ParseLink
778
779 Parse an LE<lt>E<gt> formatting code in POD text
780
781 =item Pod::ParseUtils
782
783 Helpers for POD parsing and conversion
784
785 =item Pod::Parser
786
787 Base class for creating POD filters and translators
788
789 =item Pod::Plainer
790
791 Perl extension for converting Pod to old style Pod.
792
793 =item Pod::Select
794
795 Extract selected sections of POD from input
796
797 =item Pod::Text
798
799 Convert POD data to formatted ASCII text
800
801 =item Pod::Text::Color
802
803 Convert POD data to formatted color ASCII text
804
805 =item Pod::Text::Overstrike
806
807 Convert POD data to formatted overstrike text
808
809 =item Pod::Text::Termcap
810
811 Convert POD data to ASCII text with format escapes
812
813 =item Pod::Usage
814
815 Print a usage message from embedded pod documentation
816
817 =item Pod::t::basic
818
819 Test of various basic POD features in translators.
820
821 =item SDBM_File
822
823 Tied access to sdbm files
824
825 =item Safe
826
827 Compile and execute code in restricted compartments
828
829 =item Search::Dict
830
831 Search for key in dictionary file
832
833 =item SelectSaver
834
835 Save and restore selected file handle
836
837 =item SelfLoader
838
839 Load functions only on demand
840
841 =item Shell
842
843 Run shell commands transparently within perl
844
845 =item Socket
846
847 Load the C socket.h defines and structure manipulators 
848
849 =item Storable
850
851 Persistency for perl data structures
852
853 =item Switch
854
855 A switch statement for Perl
856
857 =item Symbol
858
859 Manipulate Perl symbols and their names
860
861 =item Term::ANSIColor
862
863 Color screen output using ANSI escape sequences
864
865 =item Term::Cap
866
867 Perl termcap interface
868
869 =item Term::Complete
870
871 Perl word completion module
872
873 =item Term::ReadLine
874
875 Perl interface to various C<readline> packages. If
876
877 =item Test
878
879 Provides a simple framework for writing test scripts
880
881 =item Test::Builder
882
883 Backend for building test libraries
884
885 =item Test::Harness
886
887 Run perl standard test scripts with statistics
888
889 =item Test::More
890
891 Yet another framework for writing test scripts
892
893 =item Test::Simple
894
895 Basic utilities for writing tests.
896
897 =item Test::Tutorial
898
899 A tutorial about writing really basic tests
900
901 =item Text::Abbrev
902
903 Create an abbreviation table from a list
904
905 =item Text::Balanced
906
907 Extract delimited text sequences from strings.
908
909 =item Text::ParseWords
910
911 Parse text into an array of tokens or array of arrays
912
913 =item Text::Soundex
914
915 Implementation of the Soundex Algorithm as Described by Knuth
916
917 =item Text::Tabs
918
919 Expand and unexpand tabs per the unix expand(1) and unexpand(1)
920
921 =item Text::Wrap
922
923 Line wrapping to form simple paragraphs
924
925 =item Thread
926
927 Manipulate threads in Perl
928
929 =item Tie::Array
930
931 Base class for tied arrays
932
933 =item Tie::Handle
934
935 Base class definitions for tied handles
936
937 =item Tie::Hash
938
939 Base class definitions for tied hashes
940
941 =item Tie::RefHash
942
943 Use references as hash keys
944
945 =item Tie::Scalar
946
947 Base class definitions for tied scalars
948
949 =item Tie::SubstrHash
950
951 Fixed-table-size, fixed-key-length hashing
952
953 =item Time::Local
954
955 Efficiently compute time from local and GMT time
956
957 =item Time::gmtime
958
959 By-name interface to Perl's built-in gmtime() function
960
961 =item Time::localtime
962
963 By-name interface to Perl's built-in localtime() function
964
965 =item Time::tm
966
967 Internal object used by Time::gmtime and Time::localtime
968
969 =item UNIVERSAL
970
971 Base class for ALL classes (blessed references)
972
973 =item Unicode::Collate
974
975 Use UCA (Unicode Collation Algorithm)
976
977 =item Unicode::UCD
978
979 Unicode character database
980
981 =item User::grent
982
983 By-name interface to Perl's built-in getgr*() functions
984
985 =item User::pwent
986
987 By-name interface to Perl's built-in getpw*() functions
988
989 =item Win32
990
991 Interfaces to some Win32 API Functions
992
993 =back
994
995 To find out I<all> modules installed on your system, including
996 those without documentation or outside the standard release,
997 just do this:
998
999     % find `perl -e 'print "@INC"'` -name '*.pm' -print
1000
1001 They should all have their own documentation installed and accessible
1002 via your system man(1) command.  If you do not have a B<find>
1003 program, you can use the Perl B<find2perl> program instead, which
1004 generates Perl code as output you can run through perl.  If you
1005 have a B<man> program but it doesn't find your modules, you'll have
1006 to fix your manpath.  See L<perl> for details.  If you have no
1007 system B<man> command, you might try the B<perldoc> program.
1008
1009 =head2 Extension Modules
1010
1011 Extension modules are written in C (or a mix of Perl and C).  They
1012 are usually dynamically loaded into Perl if and when you need them,
1013 but may also be linked in statically.  Supported extension modules
1014 include Socket, Fcntl, and POSIX.
1015
1016 Many popular C extension modules do not come bundled (at least, not
1017 completely) due to their sizes, volatility, or simply lack of time
1018 for adequate testing and configuration across the multitude of
1019 platforms on which Perl was beta-tested.  You are encouraged to
1020 look for them on CPAN (described below), or using web search engines
1021 like Alta Vista or Deja News.
1022
1023 =head1 CPAN
1024
1025 CPAN stands for Comprehensive Perl Archive Network; it's a globally
1026 replicated trove of Perl materials, including documentation, style
1027 guides, tricks and traps, alternate ports to non-Unix systems and
1028 occasional binary distributions for these.   Search engines for
1029 CPAN can be found at http://cpan.perl.com/ and at
1030 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
1031
1032 Most importantly, CPAN includes around a thousand unbundled modules,
1033 some of which require a C compiler to build.  Major categories of
1034 modules are:
1035
1036 =over
1037
1038 =item *
1039
1040 Language Extensions and Documentation Tools
1041
1042 =item *
1043
1044 Development Support
1045
1046 =item *
1047
1048 Operating System Interfaces
1049
1050 =item *
1051
1052 Networking, Device Control (modems) and InterProcess Communication
1053
1054 =item *
1055
1056 Data Types and Data Type Utilities
1057
1058 =item *
1059
1060 Database Interfaces
1061
1062 =item *
1063
1064 User Interfaces
1065
1066 =item *
1067
1068 Interfaces to / Emulations of Other Programming Languages
1069
1070 =item *
1071
1072 File Names, File Systems and File Locking (see also File Handles)
1073
1074 =item *
1075
1076 String Processing, Language Text Processing, Parsing, and Searching
1077
1078 =item *
1079
1080 Option, Argument, Parameter, and Configuration File Processing
1081
1082 =item *
1083
1084 Internationalization and Locale
1085
1086 =item *
1087
1088 Authentication, Security, and Encryption
1089
1090 =item *
1091
1092 World Wide Web, HTML, HTTP, CGI, MIME
1093
1094 =item *
1095
1096 Server and Daemon Utilities
1097
1098 =item *
1099
1100 Archiving and Compression
1101
1102 =item *
1103
1104 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
1105
1106 =item *
1107
1108 Mail and Usenet News
1109
1110 =item *
1111
1112 Control Flow Utilities (callbacks and exceptions etc)
1113
1114 =item *
1115
1116 File Handle and Input/Output Stream Utilities
1117
1118 =item *
1119
1120 Miscellaneous Modules
1121
1122 =back
1123
1124 Registered CPAN sites as of this writing include the following.
1125 You should try to choose one close to you:
1126
1127 =head2 Africa
1128
1129 =over 4
1130
1131 =item *
1132
1133 South Africa
1134
1135     ftp://ftp.is.co.za/programming/perl/CPAN/
1136     ftp://ftp.mweb.co.za/pub/mirrors/cpan/
1137     ftp://ftp.saix.net/pub/CPAN/
1138     ftp://ftp.sun.ac.za/CPAN/
1139
1140 =back
1141
1142 =head2 Asia
1143
1144 =over 4
1145
1146 =item *
1147
1148 China
1149
1150     ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
1151     http://www2.linuxforum.net/mirror/CPAN/
1152     http://CPAN.pacific.net.hk/
1153     ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
1154     http://cpan.shellhung.org/
1155     ftp://ftp.shellhung.org/pub/CPAN
1156
1157 =item *
1158
1159 India
1160
1161     http://cpan.in.freeos.com
1162     ftp://cpan.in.freeos.com/pub/CPAN/
1163
1164 =item *
1165
1166 Indonesia
1167
1168     http://cpan.itb.web.id/
1169     ftp://mirrors.piksi.itb.ac.id/CPAN/
1170     http://CPAN.mweb.co.id/
1171     ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
1172
1173 =item *
1174
1175 Israel
1176
1177     http://www.iglu.org.il:/pub/CPAN/
1178     ftp://ftp.iglu.org.il/pub/CPAN/
1179     http://cpan.lerner.co.il/
1180     http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1181     ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1182
1183 =item *
1184
1185 Japan
1186
1187     ftp://ftp.u-aizu.ac.jp/pub/CPAN
1188     ftp://ftp.kddlabs.co.jp/CPAN/
1189     http://mirror.nucba.ac.jp/mirror/Perl/
1190     ftp://mirror.nucba.ac.jp/mirror/Perl/
1191     ftp://ftp.meisei-u.ac.jp/pub/CPAN/
1192     ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
1193     ftp://ftp.dti.ad.jp/pub/lang/CPAN/
1194     ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
1195
1196 =item *
1197
1198 Korea
1199
1200     http://mirror.Mazic.org/pub/CPAN
1201     ftp://mirror.Mazic.org/pub/CPAN
1202
1203 =item *
1204
1205 Philippines
1206
1207     http://www.adzu.edu.ph/CPAN
1208
1209 =item *
1210
1211 Russian Federation
1212
1213     http://cpan.tomsk.ru
1214     ftp://cpan.tomsk.ru/pub/CPAN
1215
1216 =item *
1217
1218 Saudi Arabia
1219
1220     ftp://ftp.isu.net.sa/pub/CPAN/
1221
1222 =item *
1223
1224 Singapore
1225
1226     http://cpan.hjc.edu.sg
1227
1228 =item *
1229
1230 South Korea
1231
1232     http://CPAN.bora.net/
1233     ftp://ftp.bora.net/pub/CPAN/
1234     http://ftp.kornet.net/pub/CPAN/
1235     ftp://ftp.kornet.net/pub/CPAN/
1236     ftp://ftp.nuri.net/pub/CPAN/
1237
1238 =item *
1239
1240 Taiwan
1241
1242     ftp://coda.nctu.edu.tw/UNIX/perl/CPAN
1243     ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
1244     ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
1245     http://ftp.tku.edu.tw/pub/CPAN/
1246     ftp://ftp.tku.edu.tw/pub/CPAN/
1247
1248 =item *
1249
1250 Thailand
1251
1252     http://download.nectec.or.th/CPAN/
1253     ftp://ftp.nectec.or.th/pub/languages/CPAN/
1254     ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
1255
1256 =back
1257
1258 =head2 Central America
1259
1260 =over 4
1261
1262 =item *
1263
1264 Costa Rica
1265
1266     ftp://ftp.linux.co.cr/mirrors/CPAN/
1267     http://ftp.ucr.ac.cr/Unix/CPAN/
1268     ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
1269
1270 =back
1271
1272 =head2 Europe
1273
1274 =over 4
1275
1276 =item *
1277
1278 Austria
1279
1280     ftp://ftp.tuwien.ac.at/pub/CPAN/
1281
1282 =item *
1283
1284 Belgium
1285
1286     http://ftp.easynet.be/pub/CPAN/
1287     ftp://ftp.easynet.be/pub/CPAN/
1288     http://cpan.skynet.be
1289     ftp://ftp.skynet.be/pub/CPAN
1290     ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
1291
1292 =item *
1293
1294 Bulgaria
1295
1296     ftp://ftp.ntrl.net/pub/mirrors/CPAN/
1297
1298 =item *
1299
1300 Croatia
1301
1302     ftp://ftp.linux.hr/pub/CPAN/
1303
1304 =item *
1305
1306 Czech Republic
1307
1308     http://ftp.fi.muni.cz/pub/CPAN/
1309     ftp://ftp.fi.muni.cz/pub/CPAN/
1310     ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
1311
1312 =item *
1313
1314 Denmark
1315
1316     http://mirrors.sunsite.dk/cpan/
1317     ftp://sunsite.dk/mirrors/cpan/
1318     http://www.cpan.dk/CPAN/
1319     ftp://www.cpan.dk/ftp.cpan.org/CPAN/
1320
1321 =item *
1322
1323 England
1324
1325     http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
1326     ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
1327     http://cpan.crazygreek.co.uk
1328     ftp://ftp.demon.co.uk/pub/CPAN/
1329     ftp://ftp.flirble.org/pub/languages/perl/CPAN/
1330     ftp://ftp.plig.org/pub/CPAN/
1331     ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
1332     http://mirror.uklinux.net/CPAN/
1333     ftp://mirror.uklinux.net/pub/CPAN/
1334     ftp://usit.shef.ac.uk/pub/packages/CPAN/
1335
1336 =item *
1337
1338 Estonia
1339
1340     ftp://ftp.ut.ee/pub/languages/perl/CPAN/
1341
1342 =item *
1343
1344 Finland
1345
1346     ftp://ftp.funet.fi/pub/languages/perl/CPAN/
1347     http://cpan.kpnqwest.fi/
1348
1349 =item *
1350
1351 France
1352
1353     ftp://cpan.ftp.worldonline.fr/pub/CPAN/
1354     http://cpan.mirrors.easynet.fr/
1355     ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
1356     ftp://ftp.club-internet.fr/pub/perl/CPAN/
1357     http://fr.cpan.org/
1358     ftp://ftp.lip6.fr/pub/perl/CPAN/
1359     ftp://ftp.oleane.net/pub/mirrors/CPAN/
1360     ftp://ftp.pasteur.fr/pub/computing/CPAN/
1361     http://cpan.cict.fr/
1362     ftp://cpan.cict.fr/pub/CPAN/
1363     ftp://ftp.uvsq.fr/pub/perl/CPAN/
1364
1365 =item *
1366
1367 Germany
1368
1369     ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
1370     ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
1371     ftp://ftp.uni-erlangen.de/pub/source/CPAN/
1372     ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
1373     ftp://ftp.gigabell.net/pub/CPAN/
1374     http://ftp.gwdg.de/pub/languages/perl/CPAN/
1375     ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
1376     ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
1377     ftp://ftp.leo.org/pub/CPAN/
1378     http://cpan.noris.de/
1379     ftp://cpan.noris.de/pub/CPAN/
1380     ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
1381     ftp://ftp.gmd.de/mirrors/CPAN/
1382
1383 =item *
1384
1385 Greece
1386
1387     ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
1388     ftp://ftp.ntua.gr/pub/lang/perl/
1389
1390 =item *
1391
1392 Hungary
1393
1394     http://cpan.artifact.hu/
1395     ftp://cpan.artifact.hu/CPAN/
1396     http://ftp.kfki.hu/pub/CPAN/
1397     ftp://ftp.kfki.hu/pub/CPAN/
1398
1399 =item *
1400
1401 Iceland
1402
1403     http://ftp.rhnet.is/pub/CPAN/
1404     ftp://ftp.rhnet.is/pub/CPAN/
1405
1406 =item *
1407
1408 Ireland
1409
1410     http://cpan.indigo.ie/
1411     ftp://cpan.indigo.ie/pub/CPAN/
1412     http://sunsite.compapp.dcu.ie/pub/perl/
1413     ftp://sunsite.compapp.dcu.ie/pub/perl/
1414
1415 =item *
1416
1417 Italy
1418
1419     http://cpan.nettuno.it/
1420     http://gusp.dyndns.org/CPAN/
1421     ftp://gusp.dyndns.org/pub/CPAN
1422     http://softcity.iol.it/cpan
1423     ftp://softcity.iol.it/pub/cpan
1424     ftp://ftp.unina.it/pub/Other/CPAN/
1425     ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
1426     ftp://cis.uniRoma2.it/CPAN/
1427     ftp://ftp.edisontel.it/pub/CPAN_Mirror/
1428     ftp://ftp.flashnet.it/pub/CPAN/
1429
1430 =item *
1431
1432 Latvia
1433
1434     http://kvin.lv/pub/CPAN/
1435
1436 =item *
1437
1438 Lithuania
1439
1440     ftp://ftp.unix.lt/pub/CPAN/
1441
1442 =item *
1443
1444 Netherlands
1445
1446     ftp://download.xs4all.nl/pub/mirror/CPAN/
1447     ftp://ftp.nl.uu.net/pub/CPAN/
1448     ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
1449     http://cpan.cybercomm.nl/
1450     ftp://mirror.cybercomm.nl/pub/cpan/
1451     ftp://ftp.cpan.nl/pub/CPAN/
1452     http://www.cs.uu.nl/mirror/CPAN/
1453     ftp://ftp.cs.uu.nl/mirror/CPAN/
1454
1455 =item *
1456
1457 Norway
1458
1459     ftp://ftp.uninett.no/pub/languages/perl/CPAN
1460     ftp://ftp.uit.no/pub/languages/perl/cpan/
1461
1462 =item *
1463
1464 Poland
1465
1466     ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
1467     http://www.fic.uni.lodz.pl/pub/CPAN
1468     ftp://ftp.fic.uni.lodz.pl/pub/CPAN
1469     ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
1470     ftp://ftp.man.torun.pl/pub/doc/CPAN/
1471     ftp://sunsite.icm.edu.pl/pub/CPAN/
1472
1473 =item *
1474
1475 Portugal
1476
1477     ftp://ftp.ua.pt/pub/CPAN/
1478     ftp://perl.di.uminho.pt/pub/CPAN/
1479     http://cpan.ip.pt/
1480     ftp://cpan.ip.pt/pub/perl/
1481     ftp://ftp.ist.utl.pt/pub/CPAN/
1482     http://cpan.ip.pt/
1483     ftp://cpan.ip.pt/pub/cpan/
1484     ftp://ftp.netc.pt/pub/CPAN/
1485     ftp://ftp.up.pt/pub/CPAN
1486
1487 =item *
1488
1489 Romania
1490
1491     ftp://archive.logicnet.ro/mirrors/ftp.cpan.org/CPAN/
1492     ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
1493     ftp://ftp.dntis.ro/pub/cpan/
1494     ftp://ftp.opsynet.com/cpan/
1495     ftp://ftp.dnttm.ro/pub/CPAN/
1496     ftp://ftp.lasting.ro/pub/CPAN
1497     ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
1498
1499 =item *
1500
1501 Russia
1502
1503     ftp://ftp.chg.ru/pub/lang/perl/CPAN/
1504     http://cpan.rinet.ru/
1505     ftp://cpan.rinet.ru/pub/mirror/CPAN/
1506     ftp://ftp.aha.ru/pub/CPAN/
1507     http://cpan.sai.msu.ru/
1508     ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
1509
1510 =item *
1511
1512 Slovakia
1513
1514     ftp://ftp.entry.sk/pub/languages/perl/CPAN/
1515
1516 =item *
1517
1518 Slovenia
1519
1520     ftp://ftp.arnes.si/software/perl/CPAN/
1521
1522 =item *
1523
1524 Spain
1525
1526     ftp://ftp.rediris.es/mirror/CPAN/
1527     ftp://ftp.etse.urv.es/pub/perl/
1528
1529 =item *
1530
1531 Sweden
1532
1533     http://ftp.du.se/CPAN/
1534     ftp://ftp.du.se/pub/CPAN/
1535     ftp://mirror.dataphone.se/pub/CPAN
1536     ftp://ftp.sunet.se/pub/lang/perl/CPAN/
1537
1538 =item *
1539
1540 Switzerland
1541
1542     ftp://ftp.danyk.ch/CPAN/
1543     ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
1544
1545 =item *
1546
1547 Turkey
1548
1549     ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
1550
1551 =item *
1552
1553 Ukraine
1554
1555     http://cpan.org.ua/
1556     ftp://cpan.org.ua/
1557     ftp://ftp.perl.org.ua/pub/CPAN/
1558
1559 =back
1560
1561 =head2 North America
1562
1563 =over 4
1564
1565 =item *
1566
1567 Canada
1568
1569 =over 8
1570
1571 =item *
1572
1573 Alberta
1574
1575     http://sunsite.ualberta.ca/pub/Mirror/CPAN/
1576     ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
1577
1578 =item *
1579
1580 Manitoba
1581
1582     http://theoryx5.uwinnipeg.ca/pub/CPAN/
1583     ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
1584
1585 =item *
1586
1587 Nova Scotia
1588
1589     ftp://cpan.chebucto.ns.ca/pub/CPAN/
1590
1591 =item *
1592
1593 Ontario
1594
1595     ftp://ftp.crc.ca/pub/CPAN/
1596
1597 =item *
1598
1599 Quebec
1600
1601     http://cpan.mirror.smartworker.org/
1602     ftp://cpan.mirror.smartworker.org/pub/CPAN
1603
1604 =back
1605
1606 =item *
1607
1608 Mexico
1609
1610     http://cpan.azc.uam.mx
1611     ftp://cpan.azc.uam.mx/mirrors/CPAN
1612     http://cpan.unam.mx/
1613     ftp://cpan.unam.mx/pub/CPAN
1614     http://www.msg.com.mx/CPAN/
1615     ftp://ftp.msg.com.mx/pub/CPAN/
1616
1617 =item *
1618
1619 United States
1620
1621 =over 8
1622
1623 =item *
1624
1625 Alabama
1626
1627     http://mirror.hiwaay.net/CPAN/
1628     ftp://mirror.hiwaay.net/CPAN/
1629
1630 =item *
1631
1632 California
1633
1634     http://www.cpan.org/
1635     ftp://cpan.valueclick.com/pub/CPAN/
1636     http://mirrors.gossamer-threads.com/CPAN
1637     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
1638     ftp://ftp.digital.com/pub/plan/perl/CPAN/
1639     http://mirrors.kernel.org/cpan/
1640     ftp://mirrors.kernel.org/pub/CPAN
1641     http://cpan.digisle.net/
1642     ftp://cpan.digisle.net/pub/CPAN
1643     http://www.linuxjar.com/CPAN
1644     ftp://linuxjar.com/pub/CPAN
1645     http://www.perl.com/CPAN/
1646     http://download.sourceforge.net/mirrors/CPAN/
1647
1648 =item *
1649
1650 Colorado
1651
1652     ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
1653
1654 =item *
1655
1656 District of Columbia
1657
1658     ftp://ftp.dc.us.telia.net/pub/cpan/
1659
1660 =item *
1661
1662 Florida
1663
1664     ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
1665     http://mirror.csit.fsu.edu/pub/CPAN/
1666     ftp://mirror.csit.fsu.edu/pub/CPAN/
1667
1668 =item *
1669
1670 Illinois
1671
1672     http://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
1673     ftp://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
1674
1675 =item *
1676
1677 Indiana
1678
1679     ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
1680     http://cpan.nitco.com/
1681     ftp://cpan.nitco.com/pub/CPAN/
1682     http://archive.progeny.com/CPAN/
1683     ftp://archive.progeny.com/CPAN/
1684     ftp://cpan.in-span.net/
1685     http://csociety-ftp.ecn.purdue.edu/pub/CPAN
1686     ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
1687
1688 =item *
1689
1690 Kentucky
1691
1692     http://cpan.uky.edu/
1693     ftp://cpan.uky.edu/pub/CPAN/
1694
1695 =item *
1696
1697 Massachusetts
1698
1699     ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
1700     http://cpan.mirrors.netnumina.com/
1701     ftp://mirrors.netnumina.com/cpan/
1702     ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
1703
1704 =item *
1705
1706 Michigan
1707
1708     ftp://cpan.cse.msu.edu/
1709
1710 =item *
1711
1712 New Jersey
1713
1714     ftp://ftp.cpanel.net/pub/CPAN/
1715
1716 =item *
1717
1718 New York
1719
1720     ftp://ftp.freesoftware.com/pub/perl/CPAN/
1721     ftp://ftp.stealth.net/pub/CPAN/
1722     http://www.rge.com/pub/languages/perl/
1723     ftp://ftp.rge.com/pub/languages/perl/
1724     ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
1725
1726 =item *
1727
1728 North Carolina
1729
1730     ftp://ftp.duke.edu/pub/perl/
1731
1732 =item *
1733
1734 Ohio
1735
1736     ftp://ftp.loaded.net/pub/CPAN/
1737
1738 =item *
1739
1740 Oklahoma
1741
1742     ftp://ftp.ou.edu/mirrors/CPAN/
1743
1744 =item *
1745
1746 Oregon
1747
1748     ftp://ftp.orst.edu/pub/CPAN
1749
1750 =item *
1751
1752 Pennsylvania
1753
1754     http://ftp.epix.net/CPAN/
1755     ftp://ftp.epix.net/pub/languages/perl/
1756     http://mirrors.phenominet.com/pub/CPAN/
1757     ftp://mirrors.phenominet.com/pub/CPAN/
1758     ftp://carroll.cac.psu.edu/pub/CPAN/
1759
1760 =item *
1761
1762 Tennessee
1763
1764     ftp://ftp.sunsite.utk.edu/pub/CPAN/
1765
1766 =item *
1767
1768 Texas
1769
1770     http://ftp.sedl.org/pub/mirrors/CPAN/
1771
1772 =item *
1773
1774 Utah
1775
1776     ftp://mirror.xmission.com/CPAN/
1777
1778 =item *
1779
1780 Virginia
1781
1782     http://mirrors.rcn.net/pub/lang/CPAN/
1783     ftp://mirrors.rcn.net/pub/lang/CPAN/
1784     ftp://ruff.cs.jmu.edu/pub/CPAN/
1785     http://perl.Liquidation.com/CPAN/
1786
1787 =item *
1788
1789 Washington
1790
1791     http://cpan.llarian.net/
1792     ftp://cpan.llarian.net/pub/CPAN/
1793     http://cpan.mirrorcentral.com/
1794     ftp://ftp.mirrorcentral.com/pub/CPAN/
1795     ftp://ftp-mirror.internap.com/pub/CPAN/
1796
1797 =back
1798
1799 =back
1800
1801 =head2 Oceania
1802
1803 =over 4
1804
1805 =item *
1806
1807 Australia
1808
1809     http://ftp.planetmirror.com/pub/CPAN/
1810     ftp://ftp.planetmirror.com/pub/CPAN/
1811     ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
1812     ftp://cpan.topend.com.au/pub/CPAN/
1813
1814 =item *
1815
1816 New Zealand
1817     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
1818
1819 =back
1820
1821 =head2 South America
1822
1823 =over 4
1824
1825 =item *
1826
1827 Argentina
1828
1829     ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
1830
1831 =item *
1832
1833 Brazil
1834
1835     ftp://cpan.pop-mg.com.br/pub/CPAN/
1836     ftp://ftp.matrix.com.br/pub/perl/CPAN/
1837
1838 =item *
1839
1840 Chile
1841
1842     ftp://ftp.psinet.cl/pub/programming/perl/CPAN/
1843     ftp://sunsite.dcc.uchile.cl/pub/lang/perl/
1844
1845 =back
1846
1847
1848 For an up-to-date listing of CPAN sites,
1849 see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
1850
1851 =head1 Modules: Creation, Use, and Abuse
1852
1853 (The following section is borrowed directly from Tim Bunce's modules
1854 file, available at your nearest CPAN site.)
1855
1856 Perl implements a class using a package, but the presence of a
1857 package doesn't imply the presence of a class.  A package is just a
1858 namespace.  A class is a package that provides subroutines that can be
1859 used as methods.  A method is just a subroutine that expects, as its
1860 first argument, either the name of a package (for "static" methods),
1861 or a reference to something (for "virtual" methods).
1862
1863 A module is a file that (by convention) provides a class of the same
1864 name (sans the .pm), plus an import method in that class that can be
1865 called to fetch exported symbols.  This module may implement some of
1866 its methods by loading dynamic C or C++ objects, but that should be
1867 totally transparent to the user of the module.  Likewise, the module
1868 might set up an AUTOLOAD function to slurp in subroutine definitions on
1869 demand, but this is also transparent.  Only the F<.pm> file is required to
1870 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1871 the AUTOLOAD mechanism.
1872
1873 =head2 Guidelines for Module Creation
1874
1875 =over 4
1876
1877 =item  *
1878
1879 Do similar modules already exist in some form?
1880
1881 If so, please try to reuse the existing modules either in whole or
1882 by inheriting useful features into a new class.  If this is not
1883 practical try to get together with the module authors to work on
1884 extending or enhancing the functionality of the existing modules.
1885 A perfect example is the plethora of packages in perl4 for dealing
1886 with command line options.
1887
1888 If you are writing a module to expand an already existing set of
1889 modules, please coordinate with the author of the package.  It
1890 helps if you follow the same naming scheme and module interaction
1891 scheme as the original author.
1892
1893 =item  *
1894
1895 Try to design the new module to be easy to extend and reuse.
1896
1897 Try to C<use warnings;> (or C<use warnings qw(...);>).
1898 Remember that you can add C<no warnings qw(...);> to individual blocks
1899 of code that need less warnings.
1900
1901 Use blessed references.  Use the two argument form of bless to bless
1902 into the class name given as the first parameter of the constructor,
1903 e.g.,:
1904
1905  sub new {
1906      my $class = shift;
1907      return bless {}, $class;
1908  }
1909
1910 or even this if you'd like it to be used as either a static
1911 or a virtual method.
1912
1913  sub new {
1914      my $self  = shift;
1915      my $class = ref($self) || $self;
1916      return bless {}, $class;
1917  }
1918
1919 Pass arrays as references so more parameters can be added later
1920 (it's also faster).  Convert functions into methods where
1921 appropriate.  Split large methods into smaller more flexible ones.
1922 Inherit methods from other modules if appropriate.
1923
1924 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1925 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1926 Let the objects look after themselves! Generally, avoid hard-wired
1927 class names as far as possible.
1928
1929 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1930 C<< $r->func() >> would work (see L<perlbot> for more details).
1931
1932 Use autosplit so little used or newly added functions won't be a
1933 burden to programs that don't use them. Add test functions to
1934 the module after __END__ either using AutoSplit or by saying:
1935
1936  eval join('',<main::DATA>) || die $@ unless caller();
1937
1938 Does your module pass the 'empty subclass' test? If you say
1939 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1940 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1941 does your application still work if you change:  C<$obj = new YOURCLASS;>
1942 into: C<$obj = new SUBCLASS;> ?
1943
1944 Avoid keeping any state information in your packages. It makes it
1945 difficult for multiple other packages to use yours. Keep state
1946 information in objects.
1947
1948 Always use B<-w>.
1949
1950 Try to C<use strict;> (or C<use strict qw(...);>).
1951 Remember that you can add C<no strict qw(...);> to individual blocks
1952 of code that need less strictness.
1953
1954 Always use B<-w>.
1955
1956 Follow the guidelines in the perlstyle(1) manual.
1957
1958 Always use B<-w>.
1959
1960 =item  *
1961
1962 Some simple style guidelines
1963
1964 The perlstyle manual supplied with Perl has many helpful points.
1965
1966 Coding style is a matter of personal taste. Many people evolve their
1967 style over several years as they learn what helps them write and
1968 maintain good code.  Here's one set of assorted suggestions that
1969 seem to be widely used by experienced developers:
1970
1971 Use underscores to separate words.  It is generally easier to read
1972 $var_names_like_this than $VarNamesLikeThis, especially for
1973 non-native speakers of English. It's also a simple rule that works
1974 consistently with VAR_NAMES_LIKE_THIS.
1975
1976 Package/Module names are an exception to this rule. Perl informally
1977 reserves lowercase module names for 'pragma' modules like integer
1978 and strict. Other modules normally begin with a capital letter and
1979 use mixed case with no underscores (need to be short and portable).
1980
1981 You may find it helpful to use letter case to indicate the scope
1982 or nature of a variable. For example:
1983
1984  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1985  $Some_Caps_Here  package-wide global/static
1986  $no_caps_here    function scope my() or local() variables
1987
1988 Function and method names seem to work best as all lowercase.
1989 e.g., C<< $obj->as_string() >>.
1990
1991 You can use a leading underscore to indicate that a variable or
1992 function should not be used outside the package that defined it.
1993
1994 =item  *
1995
1996 Select what to export.
1997
1998 Do NOT export method names!
1999
2000 Do NOT export anything else by default without a good reason!
2001
2002 Exports pollute the namespace of the module user.  If you must
2003 export try to use @EXPORT_OK in preference to @EXPORT and avoid
2004 short or common names to reduce the risk of name clashes.
2005
2006 Generally anything not exported is still accessible from outside the
2007 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
2008 syntax.  By convention you can use a leading underscore on names to
2009 indicate informally that they are 'internal' and not for public use.
2010
2011 (It is actually possible to get private functions by saying:
2012 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
2013 directly as a method, because a method must have a name in the symbol
2014 table.)
2015
2016 As a general rule, if the module is trying to be object oriented
2017 then export nothing. If it's just a collection of functions then
2018 @EXPORT_OK anything but use @EXPORT with caution.
2019
2020 =item  *
2021
2022 Select a name for the module.
2023
2024 This name should be as descriptive, accurate, and complete as
2025 possible.  Avoid any risk of ambiguity. Always try to use two or
2026 more whole words.  Generally the name should reflect what is special
2027 about what the module does rather than how it does it.  Please use
2028 nested module names to group informally or categorize a module.
2029 There should be a very good reason for a module not to have a nested name.
2030 Module names should begin with a capital letter.
2031
2032 Having 57 modules all called Sort will not make life easy for anyone
2033 (though having 23 called Sort::Quick is only marginally better :-).
2034 Imagine someone trying to install your module alongside many others.
2035 If in any doubt ask for suggestions in comp.lang.perl.misc.
2036
2037 If you are developing a suite of related modules/classes it's good
2038 practice to use nested classes with a common prefix as this will
2039 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
2040 Xyz::Model etc. Use the modules in this list as a naming guide.
2041
2042 If adding a new module to a set, follow the original author's
2043 standards for naming modules and the interface to methods in
2044 those modules.
2045
2046 If developing modules for private internal or project specific use,
2047 that will never be released to the public, then you should ensure
2048 that their names will not clash with any future public module. You
2049 can do this either by using the reserved Local::* category or by
2050 using a category name that includes an underscore like Foo_Corp::*.
2051
2052 To be portable each component of a module name should be limited to
2053 11 characters. If it might be used on MS-DOS then try to ensure each is
2054 unique in the first 8 characters. Nested modules make this easier.
2055
2056 =item  *
2057
2058 Have you got it right?
2059
2060 How do you know that you've made the right decisions? Have you
2061 picked an interface design that will cause problems later? Have
2062 you picked the most appropriate name? Do you have any questions?
2063
2064 The best way to know for sure, and pick up many helpful suggestions,
2065 is to ask someone who knows. Comp.lang.perl.misc is read by just about
2066 all the people who develop modules and it's the best place to ask.
2067
2068 All you need to do is post a short summary of the module, its
2069 purpose and interfaces. A few lines on each of the main methods is
2070 probably enough. (If you post the whole module it might be ignored
2071 by busy people - generally the very people you want to read it!)
2072
2073 Don't worry about posting if you can't say when the module will be
2074 ready - just say so in the message. It might be worth inviting
2075 others to help you, they may be able to complete it for you!
2076
2077 =item  *
2078
2079 README and other Additional Files.
2080
2081 It's well known that software developers usually fully document the
2082 software they write. If, however, the world is in urgent need of
2083 your software and there is not enough time to write the full
2084 documentation please at least provide a README file containing:
2085
2086 =over 10
2087
2088 =item *
2089
2090 A description of the module/package/extension etc.
2091
2092 =item *
2093
2094 A copyright notice - see below.
2095
2096 =item *
2097
2098 Prerequisites - what else you may need to have.
2099
2100 =item *
2101
2102 How to build it - possible changes to Makefile.PL etc.
2103
2104 =item *
2105
2106 How to install it.
2107
2108 =item *
2109
2110 Recent changes in this release, especially incompatibilities
2111
2112 =item *
2113
2114 Changes / enhancements you plan to make in the future.
2115
2116 =back
2117
2118 If the README file seems to be getting too large you may wish to
2119 split out some of the sections into separate files: INSTALL,
2120 Copying, ToDo etc.
2121
2122 =over 4
2123
2124 =item *
2125
2126 Adding a Copyright Notice.
2127
2128 How you choose to license your work is a personal decision.
2129 The general mechanism is to assert your Copyright and then make
2130 a declaration of how others may copy/use/modify your work.
2131
2132 Perl, for example, is supplied with two types of licence: The GNU
2133 GPL and The Artistic Licence (see the files README, Copying, and
2134 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
2135
2136 My personal recommendation, out of respect for Larry, Perl, and the
2137 Perl community at large is to state something simply like:
2138
2139  Copyright (c) 1995 Your Name. All rights reserved.
2140  This program is free software; you can redistribute it and/or
2141  modify it under the same terms as Perl itself.
2142
2143 This statement should at least appear in the README file. You may
2144 also wish to include it in a Copying file and your source files.
2145 Remember to include the other words in addition to the Copyright.
2146
2147 =item  *
2148
2149 Give the module a version/issue/release number.
2150
2151 To be fully compatible with the Exporter and MakeMaker modules you
2152 should store your module's version number in a non-my package
2153 variable called $VERSION.  This should be a floating point
2154 number with at least two digits after the decimal (i.e., hundredths,
2155 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
2156 See L<Exporter> for details.
2157
2158 It may be handy to add a function or method to retrieve the number.
2159 Use the number in announcements and archive file names when
2160 releasing the module (ModuleName-1.02.tar.Z).
2161 See perldoc ExtUtils::MakeMaker.pm for details.
2162
2163 =item  *
2164
2165 How to release and distribute a module.
2166
2167 It's good idea to post an announcement of the availability of your
2168 module (or the module itself if small) to the comp.lang.perl.announce
2169 Usenet newsgroup.  This will at least ensure very wide once-off
2170 distribution.
2171
2172 If possible, register the module with CPAN.  You should
2173 include details of its location in your announcement.
2174
2175 Some notes about ftp archives: Please use a long descriptive file
2176 name that includes the version number. Most incoming directories
2177 will not be readable/listable, i.e., you won't be able to see your
2178 file after uploading it. Remember to send your email notification
2179 message as soon as possible after uploading else your file may get
2180 deleted automatically. Allow time for the file to be processed
2181 and/or check the file has been processed before announcing its
2182 location.
2183
2184 FTP Archives for Perl Modules:
2185
2186 Follow the instructions and links on:
2187
2188    http://www.cpan.org/modules/00modlist.long.html
2189    http://www.cpan.org/modules/04pause.html
2190
2191 or upload to one of these sites:
2192
2193    https://pause.kbx.de/pause/
2194    http://pause.perl.org/pause/
2195
2196 and notify <modules@perl.org>.
2197
2198 By using the WWW interface you can ask the Upload Server to mirror
2199 your modules from your ftp or WWW site into your own directory on
2200 CPAN!
2201
2202 Please remember to send me an updated entry for the Module list!
2203
2204 =item  *
2205
2206 Take care when changing a released module.
2207
2208 Always strive to remain compatible with previous released versions.
2209 Otherwise try to add a mechanism to revert to the
2210 old behavior if people rely on it.  Document incompatible changes.
2211
2212 =back
2213
2214 =back
2215
2216 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
2217
2218 =over 4
2219
2220 =item  *
2221
2222 There is no requirement to convert anything.
2223
2224 If it ain't broke, don't fix it! Perl 4 library scripts should
2225 continue to work with no problems. You may need to make some minor
2226 changes (like escaping non-array @'s in double quoted strings) but
2227 there is no need to convert a .pl file into a Module for just that.
2228
2229 =item  *
2230
2231 Consider the implications.
2232
2233 All Perl applications that make use of the script will need to
2234 be changed (slightly) if the script is converted into a module.  Is
2235 it worth it unless you plan to make other changes at the same time?
2236
2237 =item  *
2238
2239 Make the most of the opportunity.
2240
2241 If you are going to convert the script to a module you can use the
2242 opportunity to redesign the interface.  The guidelines for module
2243 creation above include many of the issues you should consider.
2244
2245 =item  *
2246
2247 The pl2pm utility will get you started.
2248
2249 This utility will read *.pl files (given as parameters) and write
2250 corresponding *.pm files. The pl2pm utilities does the following:
2251
2252 =over 10
2253
2254 =item *
2255
2256 Adds the standard Module prologue lines
2257
2258 =item *
2259
2260 Converts package specifiers from ' to ::
2261
2262 =item *
2263
2264 Converts die(...) to croak(...)
2265
2266 =item *
2267
2268 Several other minor changes
2269
2270 =back
2271
2272 Being a mechanical process pl2pm is not bullet proof. The converted
2273 code will need careful checking, especially any package statements.
2274 Don't delete the original .pl file till the new .pm one works!
2275
2276 =back
2277
2278 =head2 Guidelines for Reusing Application Code
2279
2280 =over 4
2281
2282 =item  *
2283
2284 Complete applications rarely belong in the Perl Module Library.
2285
2286 =item  *
2287
2288 Many applications contain some Perl code that could be reused.
2289
2290 Help save the world! Share your code in a form that makes it easy
2291 to reuse.
2292
2293 =item  *
2294
2295 Break-out the reusable code into one or more separate module files.
2296
2297 =item  *
2298
2299 Take the opportunity to reconsider and redesign the interfaces.
2300
2301 =item  *
2302
2303 In some cases the 'application' can then be reduced to a small
2304
2305 fragment of code built on top of the reusable modules. In these cases
2306 the application could invoked as:
2307
2308      % perl -e 'use Module::Name; method(@ARGV)' ...
2309 or
2310      % perl -mModule::Name ...    (in perl5.002 or higher)
2311
2312 =back
2313
2314 =head1 NOTE
2315
2316 Perl does not enforce private and public parts of its modules as you may
2317 have been used to in other languages like C++, Ada, or Modula-17.  Perl
2318 doesn't have an infatuation with enforced privacy.  It would prefer
2319 that you stayed out of its living room because you weren't invited, not
2320 because it has a shotgun.
2321
2322 The module and its user have a contract, part of which is common law,
2323 and part of which is "written".  Part of the common law contract is
2324 that a module doesn't pollute any namespace it wasn't asked to.  The
2325 written contract for the module (A.K.A. documentation) may make other
2326 provisions.  But then you know when you C<use RedefineTheWorld> that
2327 you're redefining the world and willing to take the consequences.