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