pod/perlmodlib.pod

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