pod/perlmodlib.pod

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