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