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