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