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