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