pod/perlmodlib.pod

   1 # Generated by perlmodlib.PL  DO NOT EDIT!
   2
   3 =head1 NAME
   4
   5 perlmodlib - constructing new Perl modules and finding existing ones
   6
   7 =head1 DESCRIPTION
   8
   9 =head1 THE PERL MODULE LIBRARY
  10
  11 Many modules are included the Perl distribution.  These are described
  12 below, and all end in F<.pm>.  You may discover compiled library
  13 file (usually ending in F<.so>) or small pieces of modules to be
  14 autoloaded (ending in F<.al>); these were automatically generated
  15 by the installation process.  You may also discover files in the
  16 library directory that end in either F<.pl> or F<.ph>.  These are
  17 old libraries supplied so that old programs that use them still
  18 run.  The F<.pl> files will all eventually be converted into standard
  19 modules, and the F<.ph> files made by B<h2ph> will probably end up
  20 as extension modules made by B<h2xs>.  (Some F<.ph> values may
  21 already be available through the POSIX, Errno, or Fcntl modules.)
  22 The B<pl2pm> file in the distribution may help in your conversion,
  23 but it's just a mechanical process and therefore far from bulletproof.
  24
  25 =head2 Pragmatic Modules
  26
  27 They work somewhat like compiler directives (pragmata) in that they
  28 tend to affect the compilation of your program, and thus will usually
  29 work well only when used within a C<use>, or C<no>.  Most of these
  30 are lexically scoped, so an inner BLOCK may countermand them
  31 by saying:
  32
  33     no integer;
  34     no strict 'refs';
  35     no warnings;
  36
  37 which lasts until the end of that BLOCK.
  38
  39 Some pragmas are lexically scoped--typically those that affect the
  40 C<$^H> hints variable.  Others affect the current package instead,
  41 like C<use vars> and C<use subs>, which allow you to predeclare a
  42 variables or subroutines within a particular I<file> rather than
  43 just a block.  Such declarations are effective for the entire file
  44 for which they were declared.  You cannot rescind them with C<no
  45 vars> or C<no subs>.
  46
  47 The following pragmas are defined (and have their own documentation).
  48
  49 =over 12
  50
  51 =item attributes
  52
  53 Get/set subroutine or variable attributes
  54
  55 =item attrs
  56
  57 Set/get attributes of a subroutine (deprecated)
  58
  59 =item autouse
  60
  61 Postpone load of modules until a function is used
  62
  63 =item base
  64
  65 Establish IS-A relationship with base class at compile time
  66
  67 =item blib
  68
  69 Use MakeMaker's uninstalled version of a package
  70
  71 =item bytes
  72
  73 Force byte semantics rather than character semantics
  74
  75 =item charnames
  76
  77 Define character names for C<\N{named}> string literal escape.
  78
  79 =item constant
  80
  81 Declare constants
  82
  83 =item diagnostics
  84
  85 Perl compiler pragma to force verbose warning diagnostics
  86
  87 =item fields
  88
  89 Compile-time class fields
  90
  91 =item filetest
  92
  93 Control the filetest permission operators
  94
  95 =item integer
  96
  97 Use integer arithmetic instead of floating point
  98
  99 =item less
 100
 101 Request less of something from the compiler
 102
 103 =item locale
 104
 105 Use and avoid POSIX locales for built-in operations
 106
 107 =item open
 108
 109 Set default disciplines for input and output
 110
 111 =item ops
 112
 113 Restrict unsafe operations when compiling
 114
 115 =item overload
 116
 117 Package for overloading perl operations
 118
 119 =item re
 120
 121 Alter regular expression behaviour
 122
 123 =item sigtrap
 124
 125 Enable simple signal handling
 126
 127 =item strict
 128
 129 Restrict unsafe constructs
 130
 131 =item subs
 132
 133 Predeclare sub names
 134
 135 =item unicode::distinct
 136
 137 Strictly distinguish UTF8 data and non-UTF data.
 138
 139 =item utf8
 140
 141 Enable/disable UTF-8 (or UTF-EBCDIC) in source code
 142
 143 =item vars
 144
 145 Predeclare global variable names (obsolete)
 146
 147 =item warnings
 148
 149 Control optional warnings
 150
 151 =item warnings::register
 152
 153 Warnings import function
 154
 155 =back
 156
 157 =head2 Standard Modules
 158
 159 Standard, bundled modules are all expected to behave in a well-defined
 160 manner with respect to namespace pollution because they use the
 161 Exporter module.  See their own documentation for details.
 162
 163 =over 12
 164
 165 =item AnyDBM_File
 166
 167 Provide framework for multiple DBMs
 168
 169 =item Attribute::Handlers
 170
 171 Simpler definition of attribute handlers
 172
 173 =item AutoLoader
 174
 175 Load subroutines only on demand
 176
 177 =item AutoSplit
 178
 179 Split a package for autoloading
 180
 181 =item B
 182
 183 The Perl Compiler
 184
 185 =item B::Asmdata
 186
 187 Autogenerated data about Perl ops, used to generate bytecode
 188
 189 =item B::Assembler
 190
 191 Assemble Perl bytecode
 192
 193 =item B::Bblock
 194
 195 Walk basic blocks
 196
 197 =item B::Bytecode
 198
 199 Perl compiler's bytecode backend
 200
 201 =item B::C
 202
 203 Perl compiler's C backend
 204
 205 =item B::CC
 206
 207 Perl compiler's optimized C translation backend
 208
 209 =item B::Concise
 210
 211 Walk Perl syntax tree, printing concise info about ops
 212
 213 =item B::Debug
 214
 215 Walk Perl syntax tree, printing debug info about ops
 216
 217 =item B::Deparse
 218
 219 Perl compiler backend to produce perl code
 220
 221 =item B::Disassembler
 222
 223 Disassemble Perl bytecode
 224
 225 =item B::Lint
 226
 227 Perl lint
 228
 229 =item B::Showlex
 230
 231 Show lexical variables used in functions or files
 232
 233 =item B::Stackobj
 234
 235 Helper module for CC backend
 236
 237 =item B::Stash
 238
 239 Show what stashes are loaded
 240
 241 =item B::Terse
 242
 243 Walk Perl syntax tree, printing terse info about ops
 244
 245 =item B::Xref
 246
 247 Generates cross reference reports for Perl programs
 248
 249 =item Benchmark
 250
 251 Benchmark running times of Perl code
 252
 253 =item ByteLoader
 254
 255 Load byte compiled perl code
 256
 257 =item CGI
 258
 259 Simple Common Gateway Interface Class
 260
 261 =item CGI::Apache
 262
 263 Backward compatibility module for CGI.pm
 264
 265 =item CGI::Carp
 266
 267 CGI routines for writing to the HTTPD (or other) error log
 268
 269 =item CGI::Cookie
 270
 271 Interface to Netscape Cookies
 272
 273 =item CGI::Fast
 274
 275 CGI Interface for Fast CGI
 276
 277 =item CGI::Pretty
 278
 279 Module to produce nicely formatted HTML code
 280
 281 =item CGI::Push
 282
 283 Simple Interface to Server Push
 284
 285 =item CGI::Switch
 286
 287 Backward compatibility module for defunct CGI::Switch
 288
 289 =item CGI::Util
 290
 291 Internal utilities used by CGI module
 292
 293 =item CPAN
 294
 295 Query, download and build perl modules from CPAN sites
 296
 297 =item CPAN::FirstTime
 298
 299 Utility for CPAN::Config file Initialization
 300
 301 =item CPAN::Nox
 302
 303 Wrapper around CPAN.pm without using any XS module
 304
 305 =item Carp
 306
 307 Warn of errors (from perspective of caller)
 308
 309 =item Carp::Heavy
 310
 311 No user serviceable parts inside
 312
 313 =item Class::ISA
 314
 315 Report the search path for a class's ISA tree
 316
 317 =item Class::Struct
 318
 319 Declare struct-like datatypes as Perl classes
 320
 321 =item Cwd
 322
 323 Get pathname of current working directory
 324
 325 =item DB
 326
 327 Programmatic interface to the Perl debugging API (draft, subject to
 328
 329 =item DB_File
 330
 331 Perl5 access to Berkeley DB version 1.x
 332
 333 =item Devel::SelfStubber
 334
 335 Generate stubs for a SelfLoading module
 336
 337 =item Digest
 338
 339 Modules that calculate message digests
 340
 341 =item DirHandle
 342
 343 Supply object methods for directory handles
 344
 345 =item Dumpvalue
 346
 347 Provides screen dump of Perl data.
 348
 349 =item Encode
 350
 351 Character encodings
 352
 353 =item Encode::EncodeFormat
 354
 355 The format of encoding tables of the Encode extension
 356
 357 =item Encode::Tcl
 358
 359 Tcl encodings
 360
 361 =item English
 362
 363 Use nice English (or awk) names for ugly punctuation variables
 364
 365 =item Env
 366
 367 Perl module that imports environment variables as scalars or arrays
 368
 369 =item Exporter
 370
 371 Implements default import method for modules
 372
 373 =item Exporter::Heavy
 374
 375 Exporter guts
 376
 377 =item ExtUtils::Command
 378
 379 Utilities to replace common UNIX commands in Makefiles etc.
 380
 381 =item ExtUtils::Constant
 382
 383 Generate XS code to import C header constants
 384
 385 =item ExtUtils::Embed
 386
 387 Utilities for embedding Perl in C/C++ applications
 388
 389 =item ExtUtils::Install
 390
 391 Install files from here to there
 392
 393 =item ExtUtils::Installed
 394
 395 Inventory management of installed modules
 396
 397 =item ExtUtils::Liblist
 398
 399 Determine libraries to use and how to use them
 400
 401 =item ExtUtils::MM_Cygwin
 402
 403 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 404
 405 =item ExtUtils::MM_NW5
 406
 407 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 408
 409 =item ExtUtils::MM_OS2
 410
 411 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 412
 413 =item ExtUtils::MM_Unix
 414
 415 Methods used by ExtUtils::MakeMaker
 416
 417 =item ExtUtils::MM_VMS
 418
 419 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 420
 421 =item ExtUtils::MM_Win32
 422
 423 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 424
 425 =item ExtUtils::MakeMaker
 426
 427 Create an extension Makefile
 428
 429 =item ExtUtils::Manifest
 430
 431 Utilities to write and check a MANIFEST file
 432
 433 =item ExtUtils::Mkbootstrap
 434
 435 Make a bootstrap file for use by DynaLoader
 436
 437 =item ExtUtils::Mksymlists
 438
 439 Write linker options files for dynamic extension
 440
 441 =item ExtUtils::Packlist
 442
 443 Manage .packlist files
 444
 445 =item ExtUtils::testlib
 446
 447 Add blib/* directories to @INC
 448
 449 =item Fatal
 450
 451 Replace functions with equivalents which succeed or die
 452
 453 =item Fcntl
 454
 455 Load the C Fcntl.h defines
 456
 457 =item File::Basename
 458
 459 Split a pathname into pieces
 460
 461 =item File::CheckTree
 462
 463 Run many filetest checks on a tree
 464
 465 =item File::Compare
 466
 467 Compare files or filehandles
 468
 469 =item File::Copy
 470
 471 Copy files or filehandles
 472
 473 =item File::DosGlob
 474
 475 DOS like globbing and then some
 476
 477 =item File::Find
 478
 479 Traverse a file tree
 480
 481 =item File::Path
 482
 483 Create or remove directory trees
 484
 485 =item File::Spec
 486
 487 Portably perform operations on file names
 488
 489 =item File::Spec::Epoc
 490
 491 Methods for Epoc file specs
 492
 493 =item File::Spec::Functions
 494
 495 Portably perform operations on file names
 496
 497 =item File::Spec::Mac
 498
 499 File::Spec for MacOS
 500
 501 =item File::Spec::OS2
 502
 503 Methods for OS/2 file specs
 504
 505 =item File::Spec::Unix
 506
 507 Methods used by File::Spec
 508
 509 =item File::Spec::VMS
 510
 511 Methods for VMS file specs
 512
 513 =item File::Spec::Win32
 514
 515 Methods for Win32 file specs
 516
 517 =item File::Temp
 518
 519 Return name and handle of a temporary file safely
 520
 521 =item File::stat
 522
 523 By-name interface to Perl's built-in stat() functions
 524
 525 =item FileCache
 526
 527 Keep more files open than the system permits
 528
 529 =item FileHandle
 530
 531 Supply object methods for filehandles
 532
 533 =item Filter::Simple
 534
 535 Simplified source filtering
 536
 537 =item FindBin
 538
 539 Locate directory of original perl script
 540
 541 =item Getopt::Long
 542
 543 Extended processing of command line options
 544
 545 =item Getopt::Std
 546
 547 Process single-character switches with switch clustering
 548
 549 =item I18N::Collate
 550
 551 Compare 8-bit scalar data according to the current locale
 552
 553 =item I18N::LangTags
 554
 555 Functions for dealing with RFC3066-style language tags
 556
 557 =item I18N::LangTags::List
 558
 559 List of tags for human languages
 560
 561 =item IO
 562
 563 Load various IO modules
 564
 565 =item IPC::Open2
 566
 567 Open a process for both reading and writing
 568
 569 =item IPC::Open3
 570
 571 Open a process for reading, writing, and error handling
 572
 573 =item Locale::Constants
 574
 575 Constants for Locale codes
 576
 577 =item Locale::Country
 578
 579 ISO codes for country identification (ISO 3166)
 580
 581 =item Locale::Currency
 582
 583 ISO three letter codes for currency identification (ISO 4217)
 584
 585 =item Locale::Language
 586
 587 ISO two letter codes for language identification (ISO 639)
 588
 589 =item Locale::Maketext
 590
 591 Framework for localization
 592
 593 =item Locale::Maketext::TPJ13
 594
 595 Article about software localization
 596
 597 =item Math::BigFloat
 598
 599 Arbitrary size floating point math package
 600
 601 =item Math::BigInt
 602
 603 Arbitrary size integer math package
 604
 605 =item Math::Complex
 606
 607 Complex numbers and associated mathematical functions
 608
 609 =item Math::Trig
 610
 611 Trigonometric functions
 612
 613 =item Memoize
 614
 615 Make your functions faster by trading space for time
 616
 617 =item Memoize::AnyDBM_File
 618
 619 Glue to provide EXISTS for AnyDBM_File for Storable use
 620
 621 =item Memoize::Expire
 622
 623 Plug-in module for automatic expiration of memoized values
 624
 625 =item Memoize::ExpireFile
 626
 627 Test for Memoize expiration semantics
 628
 629 =item Memoize::ExpireTest
 630
 631 Test for Memoize expiration semantics
 632
 633 =item Memoize::NDBM_File
 634
 635 Glue to provide EXISTS for NDBM_File for Storable use
 636
 637 =item Memoize::SDBM_File
 638
 639 Glue to provide EXISTS for SDBM_File for Storable use
 640
 641 =item Memoize::Saves
 642
 643 Plug-in module to specify which return values should be memoized
 644
 645 =item Memoize::Storable
 646
 647 Store Memoized data in Storable database
 648
 649 =item NDBM_File
 650
 651 Tied access to ndbm files
 652
 653 =item NEXT
 654
 655 Provide a pseudo-class NEXT that allows method redispatch
 656
 657 =item Net::Cmd
 658
 659 Network Command class (as used by FTP, SMTP etc)
 660
 661 =item Net::Config
 662
 663 Local configuration data for libnet
 664
 665 =item Net::Domain
 666
 667 Attempt to evaluate the current host's internet name and domain
 668
 669 =item Net::DummyInetd
 670
 671 A dummy Inetd server
 672
 673 =item Net::FTP
 674
 675 FTP Client class
 676
 677 =item Net::NNTP
 678
 679 NNTP Client class
 680
 681 =item Net::Netrc
 682
 683 OO interface to users netrc file
 684
 685 =item Net::PH
 686
 687 CCSO Nameserver Client class
 688
 689 =item Net::POP3
 690
 691 Post Office Protocol 3 Client class (RFC1081)
 692
 693 =item Net::Ping
 694
 695 Check a remote host for reachability
 696
 697 =item Net::SMTP
 698
 699 Simple Mail Transfer Protocol Client
 700
 701 =item Net::SNPP
 702
 703 Simple Network Pager Protocol Client
 704
 705 =item Net::Time
 706
 707 Time and daytime network client interface
 708
 709 =item Net::hostent
 710
 711 By-name interface to Perl's built-in gethost*() functions
 712
 713 =item Net::libnetFAQ
 714
 715 Libnet Frequently Asked Questions
 716
 717 =item Net::netent
 718
 719 By-name interface to Perl's built-in getnet*() functions
 720
 721 =item Net::protoent
 722
 723 By-name interface to Perl's built-in getproto*() functions
 724
 725 =item Net::servent
 726
 727 By-name interface to Perl's built-in getserv*() functions
 728
 729 =item O
 730
 731 Generic interface to Perl Compiler backends
 732
 733 =item ODBM_File
 734
 735 Tied access to odbm files
 736
 737 =item Opcode
 738
 739 Disable named opcodes when compiling perl code
 740
 741 =item POSIX
 742
 743 Perl interface to IEEE Std 1003.1
 744
 745 =item PerlIO
 746
 747 On demand loader for PerlIO layers and root of PerlIO::* name space
 748
 749 =item Pod::Checker
 750
 751 Check pod documents for syntax errors
 752
 753 =item Pod::Find
 754
 755 Find POD documents in directory trees
 756
 757 =item Pod::Html
 758
 759 Module to convert pod files to HTML
 760
 761 =item Pod::InputObjects
 762
 763 Objects representing POD input paragraphs, commands, etc.
 764
 765 =item Pod::LaTeX
 766
 767 Convert Pod data to formatted Latex
 768
 769 =item Pod::Man
 770
 771 Convert POD data to formatted *roff input
 772
 773 =item Pod::ParseUtils
 774
 775 Helpers for POD parsing and conversion
 776
 777 =item Pod::Parser
 778
 779 Base class for creating POD filters and translators
 780
 781 =item Pod::Plainer
 782
 783 Perl extension for converting Pod to old style Pod.
 784
 785 =item Pod::Select
 786
 787 Extract selected sections of POD from input
 788
 789 =item Pod::Text
 790
 791 Convert POD data to formatted ASCII text
 792
 793 =item Pod::Text::Color
 794
 795 Convert POD data to formatted color ASCII text
 796
 797 =item Pod::Text::Overstrike
 798
 799 Convert POD data to formatted overstrike text
 800
 801 =item Pod::Text::Termcap
 802
 803 Convert POD data to ASCII text with format escapes
 804
 805 =item Pod::Usage
 806
 807 Print a usage message from embedded pod documentation
 808
 809 =item SDBM_File
 810
 811 Tied access to sdbm files
 812
 813 =item Safe
 814
 815 Compile and execute code in restricted compartments
 816
 817 =item Search::Dict
 818
 819 Search for key in dictionary file
 820
 821 =item SelectSaver
 822
 823 Save and restore selected file handle
 824
 825 =item SelfLoader
 826
 827 Load functions only on demand
 828
 829 =item Shell
 830
 831 Run shell commands transparently within perl
 832
 833 =item Socket
 834
 835 Load the C socket.h defines and structure manipulators
 836
 837 =item Storable
 838
 839 Persistency for perl data structures
 840
 841 =item Switch
 842
 843 A switch statement for Perl
 844
 845 =item Symbol
 846
 847 Manipulate Perl symbols and their names
 848
 849 =item Term::ANSIColor
 850
 851 Color screen output using ANSI escape sequences
 852
 853 =item Term::Cap
 854
 855 Perl termcap interface
 856
 857 =item Term::Complete
 858
 859 Perl word completion module
 860
 861 =item Term::ReadLine
 862
 863 Perl interface to various C<readline> packages. If
 864
 865 =item Test
 866
 867 Provides a simple framework for writing test scripts
 868
 869 =item Test::Harness
 870
 871 Run perl standard test scripts with statistics
 872
 873 =item Text::Abbrev
 874
 875 Create an abbreviation table from a list
 876
 877 =item Text::Balanced
 878
 879 Extract delimited text sequences from strings.
 880
 881 =item Text::ParseWords
 882
 883 Parse text into an array of tokens or array of arrays
 884
 885 =item Text::Soundex
 886
 887 Implementation of the Soundex Algorithm as Described by Knuth
 888
 889 =item Text::Tabs
 890
 891 Expand and unexpand tabs per the unix expand(1) and unexpand(1)
 892
 893 =item Text::Wrap
 894
 895 Line wrapping to form simple paragraphs
 896
 897 =item Tie::Array
 898
 899 Base class for tied arrays
 900
 901 =item Tie::Handle
 902
 903 Base class definitions for tied handles
 904
 905 =item Tie::Hash
 906
 907 Base class definitions for tied hashes
 908
 909 =item Tie::RefHash
 910
 911 Use references as hash keys
 912
 913 =item Tie::Scalar
 914
 915 Base class definitions for tied scalars
 916
 917 =item Tie::SubstrHash
 918
 919 Fixed-table-size, fixed-key-length hashing
 920
 921 =item Time::Local
 922
 923 Efficiently compute time from local and GMT time
 924
 925 =item Time::gmtime
 926
 927 By-name interface to Perl's built-in gmtime() function
 928
 929 =item Time::localtime
 930
 931 By-name interface to Perl's built-in localtime() function
 932
 933 =item Time::tm
 934
 935 Internal object used by Time::gmtime and Time::localtime
 936
 937 =item UNIVERSAL
 938
 939 Base class for ALL classes (blessed references)
 940
 941 =item User::grent
 942
 943 By-name interface to Perl's built-in getgr*() functions
 944
 945 =item User::pwent
 946
 947 By-name interface to Perl's built-in getpw*() functions
 948
 949 =item Win32
 950
 951 Interfaces to some Win32 API Functions
 952
 953 =back
 954
 955 To find out I<all> modules installed on your system, including
 956 those without documentation or outside the standard release,
 957 just do this:
 958
 959     % find `perl -e 'print "@INC"'` -name '*.pm' -print
 960
 961 They should all have their own documentation installed and accessible
 962 via your system man(1) command.  If you do not have a B<find>
 963 program, you can use the Perl B<find2perl> program instead, which
 964 generates Perl code as output you can run through perl.  If you
 965 have a B<man> program but it doesn't find your modules, you'll have
 966 to fix your manpath.  See L<perl> for details.  If you have no
 967 system B<man> command, you might try the B<perldoc> program.
 968
 969 =head2 Extension Modules
 970
 971 Extension modules are written in C (or a mix of Perl and C).  They
 972 are usually dynamically loaded into Perl if and when you need them,
 973 but may also be be linked in statically.  Supported extension modules
 974 include Socket, Fcntl, and POSIX.
 975
 976 Many popular C extension modules do not come bundled (at least, not
 977 completely) due to their sizes, volatility, or simply lack of time
 978 for adequate testing and configuration across the multitude of
 979 platforms on which Perl was beta-tested.  You are encouraged to
 980 look for them on CPAN (described below), or using web search engines
 981 like Alta Vista or Deja News.
 982
 983 =head1 CPAN
 984
 985 CPAN stands for Comprehensive Perl Archive Network; it's a globally
 986 replicated trove of Perl materials, including documentation, style
 987 guides, tricks and traps, alternate ports to non-Unix systems and
 988 occasional binary distributions for these.   Search engines for
 989 CPAN can be found at http://cpan.perl.com/ and at
 990 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
 991
 992 Most importantly, CPAN includes around a thousand unbundled modules,
 993 some of which require a C compiler to build.  Major categories of
 994 modules are:
 995
 996 =over
 997
 998 =item *
 999
1000 Language Extensions and Documentation Tools
1001
1002 =item *
1003
1004 Development Support
1005
1006 =item *
1007
1008 Operating System Interfaces
1009
1010 =item *
1011
1012 Networking, Device Control (modems) and InterProcess Communication
1013
1014 =item *
1015
1016 Data Types and Data Type Utilities
1017
1018 =item *
1019
1020 Database Interfaces
1021
1022 =item *
1023
1024 User Interfaces
1025
1026 =item *
1027
1028 Interfaces to / Emulations of Other Programming Languages
1029
1030 =item *
1031
1032 File Names, File Systems and File Locking (see also File Handles)
1033
1034 =item *
1035
1036 String Processing, Language Text Processing, Parsing, and Searching
1037
1038 =item *
1039
1040 Option, Argument, Parameter, and Configuration File Processing
1041
1042 =item *
1043
1044 Internationalization and Locale
1045
1046 =item *
1047
1048 Authentication, Security, and Encryption
1049
1050 =item *
1051
1052 World Wide Web, HTML, HTTP, CGI, MIME
1053
1054 =item *
1055
1056 Server and Daemon Utilities
1057
1058 =item *
1059
1060 Archiving and Compression
1061
1062 =item *
1063
1064 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
1065
1066 =item *
1067
1068 Mail and Usenet News
1069
1070 =item *
1071
1072 Control Flow Utilities (callbacks and exceptions etc)
1073
1074 =item *
1075
1076 File Handle and Input/Output Stream Utilities
1077
1078 =item *
1079
1080 Miscellaneous Modules
1081
1082 =back
1083
1084 Registered CPAN sites as of this writing include the following.
1085 You should try to choose one close to you:
1086
1087 =head2 Africa
1088
1089 =over 4
1090
1091 =item *
1092
1093 South Africa
1094
1095     ftp://ftp.is.co.za/programming/perl/CPAN/
1096     ftp://ftp.saix.net/pub/CPAN/
1097     ftp://ftpza.co.za/pub/mirrors/cpan/
1098     ftp://ftp.sun.ac.za/CPAN/
1099
1100 =back
1101
1102 =head2 Asia
1103
1104 =over 4
1105
1106 =item *
1107
1108 China
1109
1110     ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
1111     http://www2.linuxforum.net/mirror/CPAN/
1112     http://cpan.shellhung.org/
1113     ftp://ftp.shellhung.org/pub/CPAN
1114
1115 =item *
1116
1117 Hong Kong
1118
1119     http://CPAN.pacific.net.hk/
1120     ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
1121
1122 =item *
1123
1124 Indonesia
1125
1126     http://piksi.itb.ac.id/CPAN/
1127     ftp://mirrors.piksi.itb.ac.id/CPAN/
1128     http://CPAN.mweb.co.id/
1129     ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
1130
1131 =item *
1132
1133 Israel
1134
1135     http://www.iglu.org.il:/pub/CPAN/
1136     ftp://ftp.iglu.org.il/pub/CPAN/
1137     http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1138     ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1139
1140 =item *
1141
1142 Japan
1143
1144     ftp://ftp.u-aizu.ac.jp/pub/lang/perl/CPAN/
1145     ftp://ftp.kddlabs.co.jp/CPAN/
1146     http://mirror.nucba.ac.jp/mirror/Perl/
1147     ftp://mirror.nucba.ac.jp/mirror/Perl/
1148     ftp://ftp.meisei-u.ac.jp/pub/CPAN/
1149     ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
1150     ftp://ftp.dti.ad.jp/pub/lang/CPAN/
1151     ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
1152
1153 =item *
1154
1155 Saudi Arabia
1156
1157     ftp://ftp.isu.net.sa/pub/CPAN/
1158
1159 =item *
1160
1161 Singapore
1162
1163     http://cpan.hjc.edu.sg
1164     http://ftp.nus.edu.sg/unix/perl/CPAN/
1165     ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
1166
1167 =item *
1168
1169 South Korea
1170
1171     http://CPAN.bora.net/
1172     ftp://ftp.bora.net/pub/CPAN/
1173     http://ftp.kornet.net/CPAN/
1174     ftp://ftp.kornet.net/pub/CPAN/
1175     ftp://ftp.nuri.net/pub/CPAN/
1176
1177 =item *
1178
1179 Taiwan
1180
1181     ftp://coda.nctu.edu.tw/UNIX/perl/CPAN
1182     ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
1183     ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
1184
1185 =item *
1186
1187 Thailand
1188
1189     http://download.nectec.or.th/CPAN/
1190     ftp://ftp.nectec.or.th/pub/languages/CPAN/
1191     ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
1192
1193 =back
1194
1195 =head2 Central America
1196
1197 =over 4
1198
1199 =item *
1200
1201 Costa Rica
1202
1203     ftp://ftp.linux.co.cr/mirrors/CPAN/
1204     http://ftp.ucr.ac.cr/Unix/CPAN/
1205     ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
1206
1207 =back
1208
1209 =head2 Europe
1210
1211 =over 4
1212
1213 =item *
1214
1215 Austria
1216
1217     ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
1218
1219 =item *
1220
1221 Belgium
1222
1223     http://ftp.easynet.be/CPAN/
1224     ftp://ftp.easynet.be/CPAN/
1225     ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
1226
1227 =item *
1228
1229 Bulgaria
1230
1231     ftp://ftp.ntrl.net/pub/mirrors/CPAN/
1232
1233 =item *
1234
1235 Croatia
1236
1237     ftp://ftp.linux.hr/pub/CPAN/
1238
1239 =item *
1240
1241 Czech Republic
1242
1243     http://www.fi.muni.cz/pub/perl/
1244     ftp://ftp.fi.muni.cz/pub/perl/
1245     ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
1246
1247 =item *
1248
1249 Denmark
1250
1251     ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
1252     http://www.cpan.dk/CPAN/
1253     ftp://www.cpan.dk/ftp.cpan.org/CPAN/
1254
1255 =item *
1256
1257 England
1258
1259     http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
1260     ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
1261     ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
1262     ftp://ftp.flirble.org/pub/languages/perl/CPAN/
1263     ftp://ftp.plig.org/pub/CPAN/
1264     ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
1265     http://mirror.uklinux.net/CPAN/
1266     ftp://mirror.uklinux.net/pub/CPAN/
1267     ftp://usit.shef.ac.uk/pub/packages/CPAN/
1268
1269 =item *
1270
1271 Estonia
1272
1273     ftp://ftp.ut.ee/pub/languages/perl/CPAN/
1274
1275 =item *
1276
1277 Finland
1278
1279     ftp://ftp.funet.fi/pub/languages/perl/CPAN/
1280
1281 =item *
1282
1283 France
1284
1285     ftp://cpan.ftp.worldonline.fr/pub/CPAN/
1286     ftp://ftp.club-internet.fr/pub/perl/CPAN/
1287     ftp://ftp.lip6.fr/pub/perl/CPAN/
1288     ftp://ftp.oleane.net/pub/mirrors/CPAN/
1289     ftp://ftp.pasteur.fr/pub/computing/CPAN/
1290     ftp://cpan.cict.fr/pub/CPAN/
1291     ftp://ftp.uvsq.fr/pub/perl/CPAN/
1292
1293 =item *
1294
1295 Germany
1296
1297     ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
1298     ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
1299     ftp://ftp.uni-erlangen.de/pub/source/CPAN/
1300     ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
1301     ftp://ftp.gigabell.net/pub/CPAN/
1302     http://ftp.gwdg.de/pub/languages/perl/CPAN/
1303     ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
1304     ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
1305     ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
1306     ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
1307     ftp://ftp.gmd.de/mirrors/CPAN/
1308
1309 =item *
1310
1311 Greece
1312
1313     ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
1314     ftp://ftp.ntua.gr/pub/lang/perl/
1315
1316 =item *
1317
1318 Hungary
1319
1320     http://cpan.artifact.hu/
1321     ftp://cpan.artifact.hu/CPAN/
1322     ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
1323
1324 =item *
1325
1326 Iceland
1327
1328     http://cpan.gm.is/
1329     ftp://ftp.gm.is/pub/CPAN/
1330
1331 =item *
1332
1333 Ireland
1334
1335     http://cpan.indigo.ie/
1336     ftp://cpan.indigo.ie/pub/CPAN/
1337     http://sunsite.compapp.dcu.ie/pub/perl/
1338     ftp://sunsite.compapp.dcu.ie/pub/perl/
1339
1340 =item *
1341
1342 Italy
1343
1344     http://cpan.nettuno.it/
1345     http://gusp.dyndns.org/CPAN/
1346     ftp://gusp.dyndns.org/pub/CPAN
1347     http://softcity.iol.it/cpan
1348     ftp://softcity.iol.it/pub/cpan
1349     ftp://ftp.unina.it/pub/Other/CPAN/
1350     ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
1351     ftp://cis.uniRoma2.it/CPAN/
1352     ftp://ftp.edisontel.it/pub/CPAN_Mirror/
1353     ftp://ftp.flashnet.it/pub/CPAN/
1354
1355 =item *
1356
1357 Latvia
1358
1359     http://kvin.lv/pub/CPAN/
1360
1361 =item *
1362
1363 Netherlands
1364
1365     ftp://download.xs4all.nl/pub/mirror/CPAN/
1366     ftp://ftp.nl.uu.net/pub/CPAN/
1367     ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
1368     ftp://ftp.cpan.nl/pub/CPAN/
1369     http://www.cs.uu.nl/mirror/CPAN/
1370     ftp://ftp.cs.uu.nl/mirror/CPAN/
1371
1372 =item *
1373
1374 Norway
1375
1376     ftp://sunsite.uio.no/pub/languages/perl/CPAN/
1377     ftp://ftp.uit.no/pub/languages/perl/cpan/
1378
1379 =item *
1380
1381 Poland
1382
1383     ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
1384     ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
1385     ftp://ftp.man.torun.pl/pub/doc/CPAN/
1386     ftp://sunsite.icm.edu.pl/pub/CPAN/
1387
1388 =item *
1389
1390 Portugal
1391
1392     ftp://ftp.ua.pt/pub/CPAN/
1393     ftp://perl.di.uminho.pt/pub/CPAN/
1394     ftp://ftp.ist.utl.pt/pub/CPAN/
1395     ftp://ftp.netc.pt/pub/CPAN/
1396
1397 =item *
1398
1399 Romania
1400
1401     ftp://archive.logicnet.ro/mirrors/ftp.cpan.org/CPAN/
1402     ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
1403     ftp://ftp.dntis.ro/pub/cpan/
1404     ftp://ftp.opsynet.com/cpan/
1405     ftp://ftp.dnttm.ro/pub/CPAN/
1406     ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
1407
1408 =item *
1409
1410 Russia
1411
1412     ftp://ftp.chg.ru/pub/lang/perl/CPAN/
1413     http://cpan.rinet.ru/
1414     ftp://cpan.rinet.ru/pub/mirror/CPAN/
1415     ftp://ftp.aha.ru/pub/CPAN/
1416     ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
1417
1418 =item *
1419
1420 Slovakia
1421
1422     ftp://ftp.entry.sk/pub/languages/perl/CPAN/
1423
1424 =item *
1425
1426 Slovenia
1427
1428     ftp://ftp.arnes.si/software/perl/CPAN/
1429
1430 =item *
1431
1432 Spain
1433
1434     ftp://ftp.rediris.es/mirror/CPAN/
1435     ftp://ftp.etse.urv.es/pub/perl/
1436
1437 =item *
1438
1439 Sweden
1440
1441     http://ftp.du.se/CPAN/
1442     ftp://ftp.du.se/pub/CPAN/
1443     ftp://ftp.sunet.se/pub/lang/perl/CPAN/
1444
1445 =item *
1446
1447 Switzerland
1448
1449     ftp://ftp.danyk.ch/CPAN/
1450     ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
1451
1452 =item *
1453
1454 Turkey
1455
1456     ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
1457
1458 =back
1459
1460 =head2 North America
1461
1462 =over 4
1463
1464 =item *
1465
1466 Canada
1467
1468 =over 8
1469
1470 =item *
1471
1472 Alberta
1473
1474     http://sunsite.ualberta.ca/pub/Mirror/CPAN/
1475     ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
1476
1477 =item *
1478
1479 Manitoba
1480
1481     http://theoryx5.uwinnipeg.ca/pub/CPAN/
1482     ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
1483
1484 =item *
1485
1486 Nova Scotia
1487
1488     ftp://cpan.chebucto.ns.ca/pub/CPAN/
1489
1490 =item *
1491
1492 Ontario
1493
1494     ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
1495
1496 =item *
1497
1498 Mexico
1499
1500     http://www.msg.com.mx/CPAN/
1501     ftp://ftp.msg.com.mx/pub/CPAN/
1502
1503 =back
1504
1505 =item *
1506
1507 United States
1508
1509 =over 8
1510
1511 =item *
1512
1513 Alabama
1514
1515     http://mirror.hiwaay.net/CPAN/
1516     ftp://mirror.hiwaay.net/CPAN/
1517
1518 =item *
1519
1520 California
1521
1522     http://www.cpan.org/
1523     ftp://ftp.cpan.org/CPAN/
1524     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
1525     ftp://ftp.digital.com/pub/plan/perl/CPAN/
1526     http://www.kernel.org/pub/mirrors/cpan/
1527     ftp://ftp.kernel.org/pub/mirrors/cpan/
1528     http://www.perl.com/CPAN/
1529     http://download.sourceforge.net/mirrors/CPAN/
1530
1531 =item *
1532
1533 Colorado
1534
1535     ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
1536
1537 =item *
1538
1539 Florida
1540
1541     ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
1542
1543 =item *
1544
1545 Georgia
1546
1547     ftp://ftp.twoguys.org/CPAN/
1548
1549 =item *
1550
1551 Illinois
1552
1553     http://www.neurogames.com/mirrors/CPAN
1554     http://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/
1555     ftp://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/
1556
1557 =item *
1558
1559 Indiana
1560
1561     ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
1562     http://cpan.nitco.com/
1563     ftp://cpan.nitco.com/pub/CPAN/
1564     ftp://cpan.in-span.net/
1565     http://csociety-ftp.ecn.purdue.edu/pub/CPAN
1566     ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
1567
1568 =item *
1569
1570 Kentucky
1571
1572     http://cpan.uky.edu/
1573     ftp://cpan.uky.edu/pub/CPAN/
1574
1575 =item *
1576
1577 Massachusetts
1578
1579     ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
1580     ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
1581
1582 =item *
1583
1584 New Jersey
1585
1586     ftp://ftp.cpanel.net/pub/CPAN/
1587
1588 =item *
1589
1590 New York
1591
1592     ftp://ftp.freesoftware.com/pub/perl/CPAN/
1593     http://www.deao.net/mirrors/CPAN/
1594     ftp://ftp.deao.net/pub/CPAN/
1595     ftp://ftp.stealth.net/pub/mirrors/ftp.cpan.org/pub/CPAN/
1596     http://mirror.nyc.anidea.com/CPAN/
1597     ftp://mirror.nyc.anidea.com/pub/CPAN/
1598     http://www.rge.com/pub/languages/perl/
1599     ftp://ftp.rge.com/pub/languages/perl/
1600     ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
1601
1602 =item *
1603
1604 North Carolina
1605
1606     ftp://ftp.duke.edu/pub/perl/
1607
1608 =item *
1609
1610 Ohio
1611
1612     ftp://ftp.loaded.net/pub/CPAN/
1613
1614 =item *
1615
1616 Oklahoma
1617
1618     ftp://ftp.ou.edu/mirrors/CPAN/
1619
1620 =item *
1621
1622 Oregon
1623
1624     ftp://ftp.orst.edu/pub/packages/CPAN/
1625
1626 =item *
1627
1628 Pennsylvania
1629
1630     http://ftp.epix.net/CPAN/
1631     ftp://ftp.epix.net/pub/languages/perl/
1632     ftp://carroll.cac.psu.edu/pub/CPAN/
1633
1634 =item *
1635
1636 Tennessee
1637
1638     ftp://ftp.sunsite.utk.edu/pub/CPAN/
1639
1640 =item *
1641
1642 Texas
1643
1644     http://ftp.sedl.org/pub/mirrors/CPAN/
1645     http://jhcloos.com/pub/mirror/CPAN/
1646     ftp://jhcloos.com/pub/mirror/CPAN/
1647
1648 =item *
1649
1650 Utah
1651
1652     ftp://mirror.xmission.com/CPAN/
1653
1654 =item *
1655
1656 Virginia
1657
1658     http://mirrors.rcn.net/pub/lang/CPAN/
1659     ftp://mirrors.rcn.net/pub/lang/CPAN/
1660     ftp://ruff.cs.jmu.edu/pub/CPAN/
1661     http://perl.Liquidation.com/CPAN/
1662
1663 =item *
1664
1665 Washington
1666
1667     http://cpan.llarian.net/
1668     ftp://cpan.llarian.net/pub/CPAN/
1669     ftp://ftp-mirror.internap.com/pub/CPAN/
1670     ftp://ftp.spu.edu/pub/CPAN/
1671
1672 =back
1673
1674 =back
1675
1676 =head2 Oceania
1677
1678 =over 4
1679
1680 =item *
1681
1682 Australia
1683
1684     http://ftp.planetmirror.com/pub/CPAN/
1685     ftp://ftp.planetmirror.com/pub/CPAN/
1686     ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
1687     ftp://cpan.topend.com.au/pub/CPAN/
1688
1689 =item *
1690
1691 New Zealand
1692
1693     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
1694
1695 =back
1696
1697 =head2 South America
1698
1699 =over 4
1700
1701 =item *
1702
1703 Argentina
1704
1705     ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
1706
1707 =item *
1708
1709 Brazil
1710
1711     ftp://cpan.pop-mg.com.br/pub/CPAN/
1712     ftp://ftp.matrix.com.br/pub/perl/
1713     ftp://cpan.if.usp.br/pub/mirror/CPAN/
1714
1715 =item *
1716
1717 Chile
1718
1719     ftp://ftp.psinet.cl/pub/programming/perl/CPAN/
1720     ftp://sunsite.dcc.uchile.cl/pub/lang/perl/
1721
1722 =back
1723
1724 For an up-to-date listing of CPAN sites,
1725 see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
1726
1727 =head1 Modules: Creation, Use, and Abuse
1728
1729 (The following section is borrowed directly from Tim Bunce's modules
1730 file, available at your nearest CPAN site.)
1731
1732 Perl implements a class using a package, but the presence of a
1733 package doesn't imply the presence of a class.  A package is just a
1734 namespace.  A class is a package that provides subroutines that can be
1735 used as methods.  A method is just a subroutine that expects, as its
1736 first argument, either the name of a package (for "static" methods),
1737 or a reference to something (for "virtual" methods).
1738
1739 A module is a file that (by convention) provides a class of the same
1740 name (sans the .pm), plus an import method in that class that can be
1741 called to fetch exported symbols.  This module may implement some of
1742 its methods by loading dynamic C or C++ objects, but that should be
1743 totally transparent to the user of the module.  Likewise, the module
1744 might set up an AUTOLOAD function to slurp in subroutine definitions on
1745 demand, but this is also transparent.  Only the F<.pm> file is required to
1746 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1747 the AUTOLOAD mechanism.
1748
1749 =head2 Guidelines for Module Creation
1750
1751 =over 4
1752
1753 =item  *
1754
1755 Do similar modules already exist in some form?
1756
1757 If so, please try to reuse the existing modules either in whole or
1758 by inheriting useful features into a new class.  If this is not
1759 practical try to get together with the module authors to work on
1760 extending or enhancing the functionality of the existing modules.
1761 A perfect example is the plethora of packages in perl4 for dealing
1762 with command line options.
1763
1764 If you are writing a module to expand an already existing set of
1765 modules, please coordinate with the author of the package.  It
1766 helps if you follow the same naming scheme and module interaction
1767 scheme as the original author.
1768
1769 =item  *
1770
1771 Try to design the new module to be easy to extend and reuse.
1772
1773 Try to C<use warnings;> (or C<use warnings qw(...);>).
1774 Remember that you can add C<no warnings qw(...);> to individual blocks
1775 of code that need less warnings.
1776
1777 Use blessed references.  Use the two argument form of bless to bless
1778 into the class name given as the first parameter of the constructor,
1779 e.g.,:
1780
1781  sub new {
1782      my $class = shift;
1783      return bless {}, $class;
1784  }
1785
1786 or even this if you'd like it to be used as either a static
1787 or a virtual method.
1788
1789  sub new {
1790      my $self  = shift;
1791      my $class = ref($self) || $self;
1792      return bless {}, $class;
1793  }
1794
1795 Pass arrays as references so more parameters can be added later
1796 (it's also faster).  Convert functions into methods where
1797 appropriate.  Split large methods into smaller more flexible ones.
1798 Inherit methods from other modules if appropriate.
1799
1800 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1801 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1802 Let the objects look after themselves! Generally, avoid hard-wired
1803 class names as far as possible.
1804
1805 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1806 C<< $r->func() >> would work (see L<perlbot> for more details).
1807
1808 Use autosplit so little used or newly added functions won't be a
1809 burden to programs that don't use them. Add test functions to
1810 the module after __END__ either using AutoSplit or by saying:
1811
1812  eval join('',<main::DATA>) || die $@ unless caller();
1813
1814 Does your module pass the 'empty subclass' test? If you say
1815 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1816 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1817 does your application still work if you change:  C<$obj = new YOURCLASS;>
1818 into: C<$obj = new SUBCLASS;> ?
1819
1820 Avoid keeping any state information in your packages. It makes it
1821 difficult for multiple other packages to use yours. Keep state
1822 information in objects.
1823
1824 Always use B<-w>.
1825
1826 Try to C<use strict;> (or C<use strict qw(...);>).
1827 Remember that you can add C<no strict qw(...);> to individual blocks
1828 of code that need less strictness.
1829
1830 Always use B<-w>.
1831
1832 Follow the guidelines in the perlstyle(1) manual.
1833
1834 Always use B<-w>.
1835
1836 =item  *
1837
1838 Some simple style guidelines
1839
1840 The perlstyle manual supplied with Perl has many helpful points.
1841
1842 Coding style is a matter of personal taste. Many people evolve their
1843 style over several years as they learn what helps them write and
1844 maintain good code.  Here's one set of assorted suggestions that
1845 seem to be widely used by experienced developers:
1846
1847 Use underscores to separate words.  It is generally easier to read
1848 $var_names_like_this than $VarNamesLikeThis, especially for
1849 non-native speakers of English. It's also a simple rule that works
1850 consistently with VAR_NAMES_LIKE_THIS.
1851
1852 Package/Module names are an exception to this rule. Perl informally
1853 reserves lowercase module names for 'pragma' modules like integer
1854 and strict. Other modules normally begin with a capital letter and
1855 use mixed case with no underscores (need to be short and portable).
1856
1857 You may find it helpful to use letter case to indicate the scope
1858 or nature of a variable. For example:
1859
1860  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1861  $Some_Caps_Here  package-wide global/static
1862  $no_caps_here    function scope my() or local() variables
1863
1864 Function and method names seem to work best as all lowercase.
1865 e.g., C<< $obj->as_string() >>.
1866
1867 You can use a leading underscore to indicate that a variable or
1868 function should not be used outside the package that defined it.
1869
1870 =item  *
1871
1872 Select what to export.
1873
1874 Do NOT export method names!
1875
1876 Do NOT export anything else by default without a good reason!
1877
1878 Exports pollute the namespace of the module user.  If you must
1879 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1880 short or common names to reduce the risk of name clashes.
1881
1882 Generally anything not exported is still accessible from outside the
1883 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1884 syntax.  By convention you can use a leading underscore on names to
1885 indicate informally that they are 'internal' and not for public use.
1886
1887 (It is actually possible to get private functions by saying:
1888 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
1889 directly as a method, because a method must have a name in the symbol
1890 table.)
1891
1892 As a general rule, if the module is trying to be object oriented
1893 then export nothing. If it's just a collection of functions then
1894 @EXPORT_OK anything but use @EXPORT with caution.
1895
1896 =item  *
1897
1898 Select a name for the module.
1899
1900 This name should be as descriptive, accurate, and complete as
1901 possible.  Avoid any risk of ambiguity. Always try to use two or
1902 more whole words.  Generally the name should reflect what is special
1903 about what the module does rather than how it does it.  Please use
1904 nested module names to group informally or categorize a module.
1905 There should be a very good reason for a module not to have a nested name.
1906 Module names should begin with a capital letter.
1907
1908 Having 57 modules all called Sort will not make life easy for anyone
1909 (though having 23 called Sort::Quick is only marginally better :-).
1910 Imagine someone trying to install your module alongside many others.
1911 If in any doubt ask for suggestions in comp.lang.perl.misc.
1912
1913 If you are developing a suite of related modules/classes it's good
1914 practice to use nested classes with a common prefix as this will
1915 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1916 Xyz::Model etc. Use the modules in this list as a naming guide.
1917
1918 If adding a new module to a set, follow the original author's
1919 standards for naming modules and the interface to methods in
1920 those modules.
1921
1922 If developing modules for private internal or project specific use,
1923 that will never be released to the public, then you should ensure
1924 that their names will not clash with any future public module. You
1925 can do this either by using the reserved Local::* category or by
1926 using a category name that includes an underscore like Foo_Corp::*.
1927
1928 To be portable each component of a module name should be limited to
1929 11 characters. If it might be used on MS-DOS then try to ensure each is
1930 unique in the first 8 characters. Nested modules make this easier.
1931
1932 =item  *
1933
1934 Have you got it right?
1935
1936 How do you know that you've made the right decisions? Have you
1937 picked an interface design that will cause problems later? Have
1938 you picked the most appropriate name? Do you have any questions?
1939
1940 The best way to know for sure, and pick up many helpful suggestions,
1941 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1942 all the people who develop modules and it's the best place to ask.
1943
1944 All you need to do is post a short summary of the module, its
1945 purpose and interfaces. A few lines on each of the main methods is
1946 probably enough. (If you post the whole module it might be ignored
1947 by busy people - generally the very people you want to read it!)
1948
1949 Don't worry about posting if you can't say when the module will be
1950 ready - just say so in the message. It might be worth inviting
1951 others to help you, they may be able to complete it for you!
1952
1953 =item  *
1954
1955 README and other Additional Files.
1956
1957 It's well known that software developers usually fully document the
1958 software they write. If, however, the world is in urgent need of
1959 your software and there is not enough time to write the full
1960 documentation please at least provide a README file containing:
1961
1962 =over 10
1963
1964 =item *
1965
1966 A description of the module/package/extension etc.
1967
1968 =item *
1969
1970 A copyright notice - see below.
1971
1972 =item *
1973
1974 Prerequisites - what else you may need to have.
1975
1976 =item *
1977
1978 How to build it - possible changes to Makefile.PL etc.
1979
1980 =item *
1981
1982 How to install it.
1983
1984 =item *
1985
1986 Recent changes in this release, especially incompatibilities
1987
1988 =item *
1989
1990 Changes / enhancements you plan to make in the future.
1991
1992 =back
1993
1994 If the README file seems to be getting too large you may wish to
1995 split out some of the sections into separate files: INSTALL,
1996 Copying, ToDo etc.
1997
1998 =over 4
1999
2000 =item Adding a Copyright Notice.
2001
2002
2003 How you choose to license your work is a personal decision.
2004 The general mechanism is to assert your Copyright and then make
2005 a declaration of how others may copy/use/modify your work.
2006
2007 Perl, for example, is supplied with two types of licence: The GNU
2008 GPL and The Artistic Licence (see the files README, Copying, and
2009 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
2010
2011 My personal recommendation, out of respect for Larry, Perl, and the
2012 Perl community at large is to state something simply like:
2013
2014  Copyright (c) 1995 Your Name. All rights reserved.
2015  This program is free software; you can redistribute it and/or
2016  modify it under the same terms as Perl itself.
2017
2018 This statement should at least appear in the README file. You may
2019 also wish to include it in a Copying file and your source files.
2020 Remember to include the other words in addition to the Copyright.
2021
2022 =item  *
2023
2024 Give the module a version/issue/release number.
2025
2026 To be fully compatible with the Exporter and MakeMaker modules you
2027 should store your module's version number in a non-my package
2028 variable called $VERSION.  This should be a floating point
2029 number with at least two digits after the decimal (i.e., hundredths,
2030 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
2031 See L<Exporter> for details.
2032
2033 It may be handy to add a function or method to retrieve the number.
2034 Use the number in announcements and archive file names when
2035 releasing the module (ModuleName-1.02.tar.Z).
2036 See perldoc ExtUtils::MakeMaker.pm for details.
2037
2038 =item  *
2039
2040 How to release and distribute a module.
2041
2042 It's good idea to post an announcement of the availability of your
2043 module (or the module itself if small) to the comp.lang.perl.announce
2044 Usenet newsgroup.  This will at least ensure very wide once-off
2045 distribution.
2046
2047 If possible, register the module with CPAN.  You should
2048 include details of its location in your announcement.
2049
2050 Some notes about ftp archives: Please use a long descriptive file
2051 name that includes the version number. Most incoming directories
2052 will not be readable/listable, i.e., you won't be able to see your
2053 file after uploading it. Remember to send your email notification
2054 message as soon as possible after uploading else your file may get
2055 deleted automatically. Allow time for the file to be processed
2056 and/or check the file has been processed before announcing its
2057 location.
2058
2059 FTP Archives for Perl Modules:
2060
2061 Follow the instructions and links on:
2062
2063    http://www.cpan.org/modules/00modlist.long.html
2064    http://www.cpan.org/modules/04pause.html
2065
2066 or upload to one of these sites:
2067
2068    https://pause.kbx.de/pause/
2069    http://pause.perl.org/pause/
2070
2071 and notify <modules@perl.org>.
2072
2073 By using the WWW interface you can ask the Upload Server to mirror
2074 your modules from your ftp or WWW site into your own directory on
2075 CPAN!
2076
2077 Please remember to send me an updated entry for the Module list!
2078
2079 =item  *
2080
2081 Take care when changing a released module.
2082
2083 Always strive to remain compatible with previous released versions.
2084 Otherwise try to add a mechanism to revert to the
2085 old behavior if people rely on it.  Document incompatible changes.
2086
2087 =back
2088
2089 =back
2090
2091 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
2092
2093 =over 4
2094
2095 =item  *
2096
2097 There is no requirement to convert anything.
2098
2099 If it ain't broke, don't fix it! Perl 4 library scripts should
2100 continue to work with no problems. You may need to make some minor
2101 changes (like escaping non-array @'s in double quoted strings) but
2102 there is no need to convert a .pl file into a Module for just that.
2103
2104 =item  *
2105
2106 Consider the implications.
2107
2108 All Perl applications that make use of the script will need to
2109 be changed (slightly) if the script is converted into a module.  Is
2110 it worth it unless you plan to make other changes at the same time?
2111
2112 =item  *
2113
2114 Make the most of the opportunity.
2115
2116 If you are going to convert the script to a module you can use the
2117 opportunity to redesign the interface.  The guidelines for module
2118 creation above include many of the issues you should consider.
2119
2120 =item  *
2121
2122 The pl2pm utility will get you started.
2123
2124 This utility will read *.pl files (given as parameters) and write
2125 corresponding *.pm files. The pl2pm utilities does the following:
2126
2127 =over 10
2128
2129 =item *
2130
2131 Adds the standard Module prologue lines
2132
2133 =item *
2134
2135 Converts package specifiers from ' to ::
2136
2137 =item *
2138
2139 Converts die(...) to croak(...)
2140
2141 =item *
2142
2143 Several other minor changes
2144
2145 =back
2146
2147 Being a mechanical process pl2pm is not bullet proof. The converted
2148 code will need careful checking, especially any package statements.
2149 Don't delete the original .pl file till the new .pm one works!
2150
2151 =back
2152
2153 =head2 Guidelines for Reusing Application Code
2154
2155 =over 4
2156
2157 =item  *
2158
2159 Complete applications rarely belong in the Perl Module Library.
2160
2161 =item  *
2162
2163 Many applications contain some Perl code that could be reused.
2164
2165 Help save the world! Share your code in a form that makes it easy
2166 to reuse.
2167
2168 =item  *
2169
2170 Break-out the reusable code into one or more separate module files.
2171
2172 =item  *
2173
2174 Take the opportunity to reconsider and redesign the interfaces.
2175
2176 =item  *
2177
2178 In some cases the 'application' can then be reduced to a small
2179
2180 fragment of code built on top of the reusable modules. In these cases
2181 the application could invoked as:
2182
2183      % perl -e 'use Module::Name; method(@ARGV)' ...
2184 or
2185      % perl -mModule::Name ...    (in perl5.002 or higher)
2186
2187 =back
2188
2189 =head1 NOTE
2190
2191 Perl does not enforce private and public parts of its modules as you may
2192 have been used to in other languages like C++, Ada, or Modula-17.  Perl
2193 doesn't have an infatuation with enforced privacy.  It would prefer
2194 that you stayed out of its living room because you weren't invited, not
2195 because it has a shotgun.
2196
2197 The module and its user have a contract, part of which is common law,
2198 and part of which is "written".  Part of the common law contract is
2199 that a module doesn't pollute any namespace it wasn't asked to.  The
2200 written contract for the module (A.K.A. documentation) may make other
2201 provisions.  But then you know when you C<use RedefineTheWorld> that
2202 you're redefining the world and willing to take the consequences.