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 Tags and names 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 Test::More
 874
 875 Yet another framework for writing test scripts
 876
 877 =item Test::Simple
 878
 879 Basic utilities for writing tests.
 880
 881 =item Text::Abbrev
 882
 883 Create an abbreviation table from a list
 884
 885 =item Text::Balanced
 886
 887 Extract delimited text sequences from strings.
 888
 889 =item Text::ParseWords
 890
 891 Parse text into an array of tokens or array of arrays
 892
 893 =item Text::Soundex
 894
 895 Implementation of the Soundex Algorithm as Described by Knuth
 896
 897 =item Text::Tabs
 898
 899 Expand and unexpand tabs per the unix expand(1) and unexpand(1)
 900
 901 =item Text::Wrap
 902
 903 Line wrapping to form simple paragraphs
 904
 905 =item Thread
 906
 907 Manipulate threads in Perl (EXPERIMENTAL, subject to change)
 908
 909 =item Thread::Queue
 910
 911 Thread-safe queues
 912
 913 =item Thread::Semaphore
 914
 915 Thread-safe semaphores
 916
 917 =item Thread::Signal
 918
 919 Start a thread which runs signal handlers reliably
 920
 921 =item Thread::Specific
 922
 923 Thread-specific keys
 924
 925 =item Tie::Array
 926
 927 Base class for tied arrays
 928
 929 =item Tie::Handle
 930
 931 Base class definitions for tied handles
 932
 933 =item Tie::Hash
 934
 935 Base class definitions for tied hashes
 936
 937 =item Tie::RefHash
 938
 939 Use references as hash keys
 940
 941 =item Tie::Scalar
 942
 943 Base class definitions for tied scalars
 944
 945 =item Tie::SubstrHash
 946
 947 Fixed-table-size, fixed-key-length hashing
 948
 949 =item Time::Local
 950
 951 Efficiently compute time from local and GMT time
 952
 953 =item Time::gmtime
 954
 955 By-name interface to Perl's built-in gmtime() function
 956
 957 =item Time::localtime
 958
 959 By-name interface to Perl's built-in localtime() function
 960
 961 =item Time::tm
 962
 963 Internal object used by Time::gmtime and Time::localtime
 964
 965 =item UNIVERSAL
 966
 967 Base class for ALL classes (blessed references)
 968
 969 =item User::grent
 970
 971 By-name interface to Perl's built-in getgr*() functions
 972
 973 =item User::pwent
 974
 975 By-name interface to Perl's built-in getpw*() functions
 976
 977 =item Win32
 978
 979 Interfaces to some Win32 API Functions
 980
 981 =back
 982
 983 To find out I<all> modules installed on your system, including
 984 those without documentation or outside the standard release,
 985 just do this:
 986
 987     % find `perl -e 'print "@INC"'` -name '*.pm' -print
 988
 989 They should all have their own documentation installed and accessible
 990 via your system man(1) command.  If you do not have a B<find>
 991 program, you can use the Perl B<find2perl> program instead, which
 992 generates Perl code as output you can run through perl.  If you
 993 have a B<man> program but it doesn't find your modules, you'll have
 994 to fix your manpath.  See L<perl> for details.  If you have no
 995 system B<man> command, you might try the B<perldoc> program.
 996
 997 =head2 Extension Modules
 998
 999 Extension modules are written in C (or a mix of Perl and C).  They
1000 are usually dynamically loaded into Perl if and when you need them,
1001 but may also be be linked in statically.  Supported extension modules
1002 include Socket, Fcntl, and POSIX.
1003
1004 Many popular C extension modules do not come bundled (at least, not
1005 completely) due to their sizes, volatility, or simply lack of time
1006 for adequate testing and configuration across the multitude of
1007 platforms on which Perl was beta-tested.  You are encouraged to
1008 look for them on CPAN (described below), or using web search engines
1009 like Alta Vista or Deja News.
1010
1011 =head1 CPAN
1012
1013 CPAN stands for Comprehensive Perl Archive Network; it's a globally
1014 replicated trove of Perl materials, including documentation, style
1015 guides, tricks and traps, alternate ports to non-Unix systems and
1016 occasional binary distributions for these.   Search engines for
1017 CPAN can be found at http://cpan.perl.com/ and at
1018 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
1019
1020 Most importantly, CPAN includes around a thousand unbundled modules,
1021 some of which require a C compiler to build.  Major categories of
1022 modules are:
1023
1024 =over
1025
1026 =item *
1027
1028 Language Extensions and Documentation Tools
1029
1030 =item *
1031
1032 Development Support
1033
1034 =item *
1035
1036 Operating System Interfaces
1037
1038 =item *
1039
1040 Networking, Device Control (modems) and InterProcess Communication
1041
1042 =item *
1043
1044 Data Types and Data Type Utilities
1045
1046 =item *
1047
1048 Database Interfaces
1049
1050 =item *
1051
1052 User Interfaces
1053
1054 =item *
1055
1056 Interfaces to / Emulations of Other Programming Languages
1057
1058 =item *
1059
1060 File Names, File Systems and File Locking (see also File Handles)
1061
1062 =item *
1063
1064 String Processing, Language Text Processing, Parsing, and Searching
1065
1066 =item *
1067
1068 Option, Argument, Parameter, and Configuration File Processing
1069
1070 =item *
1071
1072 Internationalization and Locale
1073
1074 =item *
1075
1076 Authentication, Security, and Encryption
1077
1078 =item *
1079
1080 World Wide Web, HTML, HTTP, CGI, MIME
1081
1082 =item *
1083
1084 Server and Daemon Utilities
1085
1086 =item *
1087
1088 Archiving and Compression
1089
1090 =item *
1091
1092 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
1093
1094 =item *
1095
1096 Mail and Usenet News
1097
1098 =item *
1099
1100 Control Flow Utilities (callbacks and exceptions etc)
1101
1102 =item *
1103
1104 File Handle and Input/Output Stream Utilities
1105
1106 =item *
1107
1108 Miscellaneous Modules
1109
1110 =back
1111
1112 Registered CPAN sites as of this writing include the following.
1113 You should try to choose one close to you:
1114
1115 =head2 Africa
1116
1117 =over 4
1118
1119 =item *
1120
1121 South Africa
1122
1123     ftp://ftp.is.co.za/programming/perl/CPAN/
1124     ftp://ftp.saix.net/pub/CPAN/
1125     ftp://ftpza.co.za/pub/mirrors/cpan/
1126     ftp://ftp.sun.ac.za/CPAN/
1127
1128 =back
1129
1130 =head2 Asia
1131
1132 =over 4
1133
1134 =item *
1135
1136 China
1137
1138     ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
1139     http://www2.linuxforum.net/mirror/CPAN/
1140     http://cpan.shellhung.org/
1141     ftp://ftp.shellhung.org/pub/CPAN
1142
1143 =item *
1144
1145 Hong Kong
1146
1147     http://CPAN.pacific.net.hk/
1148     ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
1149
1150 =item *
1151
1152 Indonesia
1153
1154     http://piksi.itb.ac.id/CPAN/
1155     ftp://mirrors.piksi.itb.ac.id/CPAN/
1156     http://CPAN.mweb.co.id/
1157     ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
1158
1159 =item *
1160
1161 Israel
1162
1163     http://www.iglu.org.il:/pub/CPAN/
1164     ftp://ftp.iglu.org.il/pub/CPAN/
1165     http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1166     ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
1167
1168 =item *
1169
1170 Japan
1171
1172     ftp://ftp.u-aizu.ac.jp/pub/lang/perl/CPAN/
1173     ftp://ftp.kddlabs.co.jp/CPAN/
1174     http://mirror.nucba.ac.jp/mirror/Perl/
1175     ftp://mirror.nucba.ac.jp/mirror/Perl/
1176     ftp://ftp.meisei-u.ac.jp/pub/CPAN/
1177     ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
1178     ftp://ftp.dti.ad.jp/pub/lang/CPAN/
1179     ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
1180
1181 =item *
1182
1183 Saudi Arabia
1184
1185     ftp://ftp.isu.net.sa/pub/CPAN/
1186
1187 =item *
1188
1189 Singapore
1190
1191     http://cpan.hjc.edu.sg
1192     http://ftp.nus.edu.sg/unix/perl/CPAN/
1193     ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
1194
1195 =item *
1196
1197 South Korea
1198
1199     http://CPAN.bora.net/
1200     ftp://ftp.bora.net/pub/CPAN/
1201     http://ftp.kornet.net/CPAN/
1202     ftp://ftp.kornet.net/pub/CPAN/
1203     ftp://ftp.nuri.net/pub/CPAN/
1204
1205 =item *
1206
1207 Taiwan
1208
1209     ftp://coda.nctu.edu.tw/UNIX/perl/CPAN
1210     ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
1211     ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
1212
1213 =item *
1214
1215 Thailand
1216
1217     http://download.nectec.or.th/CPAN/
1218     ftp://ftp.nectec.or.th/pub/languages/CPAN/
1219     ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
1220
1221 =back
1222
1223 =head2 Central America
1224
1225 =over 4
1226
1227 =item *
1228
1229 Costa Rica
1230
1231     ftp://ftp.linux.co.cr/mirrors/CPAN/
1232     http://ftp.ucr.ac.cr/Unix/CPAN/
1233     ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
1234
1235 =back
1236
1237 =head2 Europe
1238
1239 =over 4
1240
1241 =item *
1242
1243 Austria
1244
1245     ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
1246
1247 =item *
1248
1249 Belgium
1250
1251     http://ftp.easynet.be/CPAN/
1252     ftp://ftp.easynet.be/CPAN/
1253     ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
1254
1255 =item *
1256
1257 Bulgaria
1258
1259     ftp://ftp.ntrl.net/pub/mirrors/CPAN/
1260
1261 =item *
1262
1263 Croatia
1264
1265     ftp://ftp.linux.hr/pub/CPAN/
1266
1267 =item *
1268
1269 Czech Republic
1270
1271     http://www.fi.muni.cz/pub/perl/
1272     ftp://ftp.fi.muni.cz/pub/perl/
1273     ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
1274
1275 =item *
1276
1277 Denmark
1278
1279     ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
1280     http://www.cpan.dk/CPAN/
1281     ftp://www.cpan.dk/ftp.cpan.org/CPAN/
1282
1283 =item *
1284
1285 England
1286
1287     http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
1288     ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
1289     ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
1290     ftp://ftp.flirble.org/pub/languages/perl/CPAN/
1291     ftp://ftp.plig.org/pub/CPAN/
1292     ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
1293     http://mirror.uklinux.net/CPAN/
1294     ftp://mirror.uklinux.net/pub/CPAN/
1295     ftp://usit.shef.ac.uk/pub/packages/CPAN/
1296
1297 =item *
1298
1299 Estonia
1300
1301     ftp://ftp.ut.ee/pub/languages/perl/CPAN/
1302
1303 =item *
1304
1305 Finland
1306
1307     ftp://ftp.funet.fi/pub/languages/perl/CPAN/
1308
1309 =item *
1310
1311 France
1312
1313     ftp://cpan.ftp.worldonline.fr/pub/CPAN/
1314     ftp://ftp.club-internet.fr/pub/perl/CPAN/
1315     ftp://ftp.lip6.fr/pub/perl/CPAN/
1316     ftp://ftp.oleane.net/pub/mirrors/CPAN/
1317     ftp://ftp.pasteur.fr/pub/computing/CPAN/
1318     ftp://cpan.cict.fr/pub/CPAN/
1319     ftp://ftp.uvsq.fr/pub/perl/CPAN/
1320
1321 =item *
1322
1323 Germany
1324
1325     ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
1326     ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
1327     ftp://ftp.uni-erlangen.de/pub/source/CPAN/
1328     ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
1329     ftp://ftp.gigabell.net/pub/CPAN/
1330     http://ftp.gwdg.de/pub/languages/perl/CPAN/
1331     ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
1332     ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
1333     ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
1334     ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
1335     ftp://ftp.gmd.de/mirrors/CPAN/
1336
1337 =item *
1338
1339 Greece
1340
1341     ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
1342     ftp://ftp.ntua.gr/pub/lang/perl/
1343
1344 =item *
1345
1346 Hungary
1347
1348     http://cpan.artifact.hu/
1349     ftp://cpan.artifact.hu/CPAN/
1350     ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
1351
1352 =item *
1353
1354 Iceland
1355
1356     http://cpan.gm.is/
1357     ftp://ftp.gm.is/pub/CPAN/
1358
1359 =item *
1360
1361 Ireland
1362
1363     http://cpan.indigo.ie/
1364     ftp://cpan.indigo.ie/pub/CPAN/
1365     http://sunsite.compapp.dcu.ie/pub/perl/
1366     ftp://sunsite.compapp.dcu.ie/pub/perl/
1367
1368 =item *
1369
1370 Italy
1371
1372     http://cpan.nettuno.it/
1373     http://gusp.dyndns.org/CPAN/
1374     ftp://gusp.dyndns.org/pub/CPAN
1375     http://softcity.iol.it/cpan
1376     ftp://softcity.iol.it/pub/cpan
1377     ftp://ftp.unina.it/pub/Other/CPAN/
1378     ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
1379     ftp://cis.uniRoma2.it/CPAN/
1380     ftp://ftp.edisontel.it/pub/CPAN_Mirror/
1381     ftp://ftp.flashnet.it/pub/CPAN/
1382
1383 =item *
1384
1385 Latvia
1386
1387     http://kvin.lv/pub/CPAN/
1388
1389 =item *
1390
1391 Netherlands
1392
1393     ftp://download.xs4all.nl/pub/mirror/CPAN/
1394     ftp://ftp.nl.uu.net/pub/CPAN/
1395     ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
1396     ftp://ftp.cpan.nl/pub/CPAN/
1397     http://www.cs.uu.nl/mirror/CPAN/
1398     ftp://ftp.cs.uu.nl/mirror/CPAN/
1399
1400 =item *
1401
1402 Norway
1403
1404     ftp://sunsite.uio.no/pub/languages/perl/CPAN/
1405     ftp://ftp.uit.no/pub/languages/perl/cpan/
1406
1407 =item *
1408
1409 Poland
1410
1411     ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
1412     ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
1413     ftp://ftp.man.torun.pl/pub/doc/CPAN/
1414     ftp://sunsite.icm.edu.pl/pub/CPAN/
1415
1416 =item *
1417
1418 Portugal
1419
1420     ftp://ftp.ua.pt/pub/CPAN/
1421     ftp://perl.di.uminho.pt/pub/CPAN/
1422     ftp://ftp.ist.utl.pt/pub/CPAN/
1423     ftp://ftp.netc.pt/pub/CPAN/
1424
1425 =item *
1426
1427 Romania
1428
1429     ftp://archive.logicnet.ro/mirrors/ftp.cpan.org/CPAN/
1430     ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
1431     ftp://ftp.dntis.ro/pub/cpan/
1432     ftp://ftp.opsynet.com/cpan/
1433     ftp://ftp.dnttm.ro/pub/CPAN/
1434     ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
1435
1436 =item *
1437
1438 Russia
1439
1440     ftp://ftp.chg.ru/pub/lang/perl/CPAN/
1441     http://cpan.rinet.ru/
1442     ftp://cpan.rinet.ru/pub/mirror/CPAN/
1443     ftp://ftp.aha.ru/pub/CPAN/
1444     ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
1445
1446 =item *
1447
1448 Slovakia
1449
1450     ftp://ftp.entry.sk/pub/languages/perl/CPAN/
1451
1452 =item *
1453
1454 Slovenia
1455
1456     ftp://ftp.arnes.si/software/perl/CPAN/
1457
1458 =item *
1459
1460 Spain
1461
1462     ftp://ftp.rediris.es/mirror/CPAN/
1463     ftp://ftp.etse.urv.es/pub/perl/
1464
1465 =item *
1466
1467 Sweden
1468
1469     http://ftp.du.se/CPAN/
1470     ftp://ftp.du.se/pub/CPAN/
1471     ftp://ftp.sunet.se/pub/lang/perl/CPAN/
1472
1473 =item *
1474
1475 Switzerland
1476
1477     ftp://ftp.danyk.ch/CPAN/
1478     ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
1479
1480 =item *
1481
1482 Turkey
1483
1484     ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
1485
1486 =back
1487
1488 =head2 North America
1489
1490 =over 4
1491
1492 =item *
1493
1494 Canada
1495
1496 =over 8
1497
1498 =item *
1499
1500 Alberta
1501
1502     http://sunsite.ualberta.ca/pub/Mirror/CPAN/
1503     ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
1504
1505 =item *
1506
1507 Manitoba
1508
1509     http://theoryx5.uwinnipeg.ca/pub/CPAN/
1510     ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
1511
1512 =item *
1513
1514 Nova Scotia
1515
1516     ftp://cpan.chebucto.ns.ca/pub/CPAN/
1517
1518 =item *
1519
1520 Ontario
1521
1522     ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
1523
1524 =item *
1525
1526 Mexico
1527
1528     http://www.msg.com.mx/CPAN/
1529     ftp://ftp.msg.com.mx/pub/CPAN/
1530
1531 =back
1532
1533 =item *
1534
1535 United States
1536
1537 =over 8
1538
1539 =item *
1540
1541 Alabama
1542
1543     http://mirror.hiwaay.net/CPAN/
1544     ftp://mirror.hiwaay.net/CPAN/
1545
1546 =item *
1547
1548 California
1549
1550     http://www.cpan.org/
1551     ftp://ftp.cpan.org/CPAN/
1552     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
1553     ftp://ftp.digital.com/pub/plan/perl/CPAN/
1554     http://www.kernel.org/pub/mirrors/cpan/
1555     ftp://ftp.kernel.org/pub/mirrors/cpan/
1556     http://www.perl.com/CPAN/
1557     http://download.sourceforge.net/mirrors/CPAN/
1558
1559 =item *
1560
1561 Colorado
1562
1563     ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
1564
1565 =item *
1566
1567 Florida
1568
1569     ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
1570
1571 =item *
1572
1573 Georgia
1574
1575     ftp://ftp.twoguys.org/CPAN/
1576
1577 =item *
1578
1579 Illinois
1580
1581     http://www.neurogames.com/mirrors/CPAN
1582     http://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/
1583     ftp://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/
1584
1585 =item *
1586
1587 Indiana
1588
1589     ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
1590     http://cpan.nitco.com/
1591     ftp://cpan.nitco.com/pub/CPAN/
1592     ftp://cpan.in-span.net/
1593     http://csociety-ftp.ecn.purdue.edu/pub/CPAN
1594     ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
1595
1596 =item *
1597
1598 Kentucky
1599
1600     http://cpan.uky.edu/
1601     ftp://cpan.uky.edu/pub/CPAN/
1602
1603 =item *
1604
1605 Massachusetts
1606
1607     ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
1608     ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
1609
1610 =item *
1611
1612 New Jersey
1613
1614     ftp://ftp.cpanel.net/pub/CPAN/
1615
1616 =item *
1617
1618 New York
1619
1620     ftp://ftp.freesoftware.com/pub/perl/CPAN/
1621     http://www.deao.net/mirrors/CPAN/
1622     ftp://ftp.deao.net/pub/CPAN/
1623     ftp://ftp.stealth.net/pub/mirrors/ftp.cpan.org/pub/CPAN/
1624     http://mirror.nyc.anidea.com/CPAN/
1625     ftp://mirror.nyc.anidea.com/pub/CPAN/
1626     http://www.rge.com/pub/languages/perl/
1627     ftp://ftp.rge.com/pub/languages/perl/
1628     ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
1629
1630 =item *
1631
1632 North Carolina
1633
1634     ftp://ftp.duke.edu/pub/perl/
1635
1636 =item *
1637
1638 Ohio
1639
1640     ftp://ftp.loaded.net/pub/CPAN/
1641
1642 =item *
1643
1644 Oklahoma
1645
1646     ftp://ftp.ou.edu/mirrors/CPAN/
1647
1648 =item *
1649
1650 Oregon
1651
1652     ftp://ftp.orst.edu/pub/packages/CPAN/
1653
1654 =item *
1655
1656 Pennsylvania
1657
1658     http://ftp.epix.net/CPAN/
1659     ftp://ftp.epix.net/pub/languages/perl/
1660     ftp://carroll.cac.psu.edu/pub/CPAN/
1661
1662 =item *
1663
1664 Tennessee
1665
1666     ftp://ftp.sunsite.utk.edu/pub/CPAN/
1667
1668 =item *
1669
1670 Texas
1671
1672     http://ftp.sedl.org/pub/mirrors/CPAN/
1673     http://jhcloos.com/pub/mirror/CPAN/
1674     ftp://jhcloos.com/pub/mirror/CPAN/
1675
1676 =item *
1677
1678 Utah
1679
1680     ftp://mirror.xmission.com/CPAN/
1681
1682 =item *
1683
1684 Virginia
1685
1686     http://mirrors.rcn.net/pub/lang/CPAN/
1687     ftp://mirrors.rcn.net/pub/lang/CPAN/
1688     ftp://ruff.cs.jmu.edu/pub/CPAN/
1689     http://perl.Liquidation.com/CPAN/
1690
1691 =item *
1692
1693 Washington
1694
1695     http://cpan.llarian.net/
1696     ftp://cpan.llarian.net/pub/CPAN/
1697     ftp://ftp-mirror.internap.com/pub/CPAN/
1698     ftp://ftp.spu.edu/pub/CPAN/
1699
1700 =back
1701
1702 =back
1703
1704 =head2 Oceania
1705
1706 =over 4
1707
1708 =item *
1709
1710 Australia
1711
1712     http://ftp.planetmirror.com/pub/CPAN/
1713     ftp://ftp.planetmirror.com/pub/CPAN/
1714     ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
1715     ftp://cpan.topend.com.au/pub/CPAN/
1716
1717 =item *
1718
1719 New Zealand
1720
1721     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
1722
1723 =back
1724
1725 =head2 South America
1726
1727 =over 4
1728
1729 =item *
1730
1731 Argentina
1732
1733     ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
1734
1735 =item *
1736
1737 Brazil
1738
1739     ftp://cpan.pop-mg.com.br/pub/CPAN/
1740     ftp://ftp.matrix.com.br/pub/perl/
1741     ftp://cpan.if.usp.br/pub/mirror/CPAN/
1742
1743 =item *
1744
1745 Chile
1746
1747     ftp://ftp.psinet.cl/pub/programming/perl/CPAN/
1748     ftp://sunsite.dcc.uchile.cl/pub/lang/perl/
1749
1750 =back
1751
1752 For an up-to-date listing of CPAN sites,
1753 see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
1754
1755 =head1 Modules: Creation, Use, and Abuse
1756
1757 (The following section is borrowed directly from Tim Bunce's modules
1758 file, available at your nearest CPAN site.)
1759
1760 Perl implements a class using a package, but the presence of a
1761 package doesn't imply the presence of a class.  A package is just a
1762 namespace.  A class is a package that provides subroutines that can be
1763 used as methods.  A method is just a subroutine that expects, as its
1764 first argument, either the name of a package (for "static" methods),
1765 or a reference to something (for "virtual" methods).
1766
1767 A module is a file that (by convention) provides a class of the same
1768 name (sans the .pm), plus an import method in that class that can be
1769 called to fetch exported symbols.  This module may implement some of
1770 its methods by loading dynamic C or C++ objects, but that should be
1771 totally transparent to the user of the module.  Likewise, the module
1772 might set up an AUTOLOAD function to slurp in subroutine definitions on
1773 demand, but this is also transparent.  Only the F<.pm> file is required to
1774 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1775 the AUTOLOAD mechanism.
1776
1777 =head2 Guidelines for Module Creation
1778
1779 =over 4
1780
1781 =item  *
1782
1783 Do similar modules already exist in some form?
1784
1785 If so, please try to reuse the existing modules either in whole or
1786 by inheriting useful features into a new class.  If this is not
1787 practical try to get together with the module authors to work on
1788 extending or enhancing the functionality of the existing modules.
1789 A perfect example is the plethora of packages in perl4 for dealing
1790 with command line options.
1791
1792 If you are writing a module to expand an already existing set of
1793 modules, please coordinate with the author of the package.  It
1794 helps if you follow the same naming scheme and module interaction
1795 scheme as the original author.
1796
1797 =item  *
1798
1799 Try to design the new module to be easy to extend and reuse.
1800
1801 Try to C<use warnings;> (or C<use warnings qw(...);>).
1802 Remember that you can add C<no warnings qw(...);> to individual blocks
1803 of code that need less warnings.
1804
1805 Use blessed references.  Use the two argument form of bless to bless
1806 into the class name given as the first parameter of the constructor,
1807 e.g.,:
1808
1809  sub new {
1810      my $class = shift;
1811      return bless {}, $class;
1812  }
1813
1814 or even this if you'd like it to be used as either a static
1815 or a virtual method.
1816
1817  sub new {
1818      my $self  = shift;
1819      my $class = ref($self) || $self;
1820      return bless {}, $class;
1821  }
1822
1823 Pass arrays as references so more parameters can be added later
1824 (it's also faster).  Convert functions into methods where
1825 appropriate.  Split large methods into smaller more flexible ones.
1826 Inherit methods from other modules if appropriate.
1827
1828 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1829 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1830 Let the objects look after themselves! Generally, avoid hard-wired
1831 class names as far as possible.
1832
1833 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1834 C<< $r->func() >> would work (see L<perlbot> for more details).
1835
1836 Use autosplit so little used or newly added functions won't be a
1837 burden to programs that don't use them. Add test functions to
1838 the module after __END__ either using AutoSplit or by saying:
1839
1840  eval join('',<main::DATA>) || die $@ unless caller();
1841
1842 Does your module pass the 'empty subclass' test? If you say
1843 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1844 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1845 does your application still work if you change:  C<$obj = new YOURCLASS;>
1846 into: C<$obj = new SUBCLASS;> ?
1847
1848 Avoid keeping any state information in your packages. It makes it
1849 difficult for multiple other packages to use yours. Keep state
1850 information in objects.
1851
1852 Always use B<-w>.
1853
1854 Try to C<use strict;> (or C<use strict qw(...);>).
1855 Remember that you can add C<no strict qw(...);> to individual blocks
1856 of code that need less strictness.
1857
1858 Always use B<-w>.
1859
1860 Follow the guidelines in the perlstyle(1) manual.
1861
1862 Always use B<-w>.
1863
1864 =item  *
1865
1866 Some simple style guidelines
1867
1868 The perlstyle manual supplied with Perl has many helpful points.
1869
1870 Coding style is a matter of personal taste. Many people evolve their
1871 style over several years as they learn what helps them write and
1872 maintain good code.  Here's one set of assorted suggestions that
1873 seem to be widely used by experienced developers:
1874
1875 Use underscores to separate words.  It is generally easier to read
1876 $var_names_like_this than $VarNamesLikeThis, especially for
1877 non-native speakers of English. It's also a simple rule that works
1878 consistently with VAR_NAMES_LIKE_THIS.
1879
1880 Package/Module names are an exception to this rule. Perl informally
1881 reserves lowercase module names for 'pragma' modules like integer
1882 and strict. Other modules normally begin with a capital letter and
1883 use mixed case with no underscores (need to be short and portable).
1884
1885 You may find it helpful to use letter case to indicate the scope
1886 or nature of a variable. For example:
1887
1888  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1889  $Some_Caps_Here  package-wide global/static
1890  $no_caps_here    function scope my() or local() variables
1891
1892 Function and method names seem to work best as all lowercase.
1893 e.g., C<< $obj->as_string() >>.
1894
1895 You can use a leading underscore to indicate that a variable or
1896 function should not be used outside the package that defined it.
1897
1898 =item  *
1899
1900 Select what to export.
1901
1902 Do NOT export method names!
1903
1904 Do NOT export anything else by default without a good reason!
1905
1906 Exports pollute the namespace of the module user.  If you must
1907 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1908 short or common names to reduce the risk of name clashes.
1909
1910 Generally anything not exported is still accessible from outside the
1911 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1912 syntax.  By convention you can use a leading underscore on names to
1913 indicate informally that they are 'internal' and not for public use.
1914
1915 (It is actually possible to get private functions by saying:
1916 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
1917 directly as a method, because a method must have a name in the symbol
1918 table.)
1919
1920 As a general rule, if the module is trying to be object oriented
1921 then export nothing. If it's just a collection of functions then
1922 @EXPORT_OK anything but use @EXPORT with caution.
1923
1924 =item  *
1925
1926 Select a name for the module.
1927
1928 This name should be as descriptive, accurate, and complete as
1929 possible.  Avoid any risk of ambiguity. Always try to use two or
1930 more whole words.  Generally the name should reflect what is special
1931 about what the module does rather than how it does it.  Please use
1932 nested module names to group informally or categorize a module.
1933 There should be a very good reason for a module not to have a nested name.
1934 Module names should begin with a capital letter.
1935
1936 Having 57 modules all called Sort will not make life easy for anyone
1937 (though having 23 called Sort::Quick is only marginally better :-).
1938 Imagine someone trying to install your module alongside many others.
1939 If in any doubt ask for suggestions in comp.lang.perl.misc.
1940
1941 If you are developing a suite of related modules/classes it's good
1942 practice to use nested classes with a common prefix as this will
1943 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1944 Xyz::Model etc. Use the modules in this list as a naming guide.
1945
1946 If adding a new module to a set, follow the original author's
1947 standards for naming modules and the interface to methods in
1948 those modules.
1949
1950 If developing modules for private internal or project specific use,
1951 that will never be released to the public, then you should ensure
1952 that their names will not clash with any future public module. You
1953 can do this either by using the reserved Local::* category or by
1954 using a category name that includes an underscore like Foo_Corp::*.
1955
1956 To be portable each component of a module name should be limited to
1957 11 characters. If it might be used on MS-DOS then try to ensure each is
1958 unique in the first 8 characters. Nested modules make this easier.
1959
1960 =item  *
1961
1962 Have you got it right?
1963
1964 How do you know that you've made the right decisions? Have you
1965 picked an interface design that will cause problems later? Have
1966 you picked the most appropriate name? Do you have any questions?
1967
1968 The best way to know for sure, and pick up many helpful suggestions,
1969 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1970 all the people who develop modules and it's the best place to ask.
1971
1972 All you need to do is post a short summary of the module, its
1973 purpose and interfaces. A few lines on each of the main methods is
1974 probably enough. (If you post the whole module it might be ignored
1975 by busy people - generally the very people you want to read it!)
1976
1977 Don't worry about posting if you can't say when the module will be
1978 ready - just say so in the message. It might be worth inviting
1979 others to help you, they may be able to complete it for you!
1980
1981 =item  *
1982
1983 README and other Additional Files.
1984
1985 It's well known that software developers usually fully document the
1986 software they write. If, however, the world is in urgent need of
1987 your software and there is not enough time to write the full
1988 documentation please at least provide a README file containing:
1989
1990 =over 10
1991
1992 =item *
1993
1994 A description of the module/package/extension etc.
1995
1996 =item *
1997
1998 A copyright notice - see below.
1999
2000 =item *
2001
2002 Prerequisites - what else you may need to have.
2003
2004 =item *
2005
2006 How to build it - possible changes to Makefile.PL etc.
2007
2008 =item *
2009
2010 How to install it.
2011
2012 =item *
2013
2014 Recent changes in this release, especially incompatibilities
2015
2016 =item *
2017
2018 Changes / enhancements you plan to make in the future.
2019
2020 =back
2021
2022 If the README file seems to be getting too large you may wish to
2023 split out some of the sections into separate files: INSTALL,
2024 Copying, ToDo etc.
2025
2026 =over 4
2027
2028 =item Adding a Copyright Notice.
2029
2030
2031 How you choose to license your work is a personal decision.
2032 The general mechanism is to assert your Copyright and then make
2033 a declaration of how others may copy/use/modify your work.
2034
2035 Perl, for example, is supplied with two types of licence: The GNU
2036 GPL and The Artistic Licence (see the files README, Copying, and
2037 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
2038
2039 My personal recommendation, out of respect for Larry, Perl, and the
2040 Perl community at large is to state something simply like:
2041
2042  Copyright (c) 1995 Your Name. All rights reserved.
2043  This program is free software; you can redistribute it and/or
2044  modify it under the same terms as Perl itself.
2045
2046 This statement should at least appear in the README file. You may
2047 also wish to include it in a Copying file and your source files.
2048 Remember to include the other words in addition to the Copyright.
2049
2050 =item  *
2051
2052 Give the module a version/issue/release number.
2053
2054 To be fully compatible with the Exporter and MakeMaker modules you
2055 should store your module's version number in a non-my package
2056 variable called $VERSION.  This should be a floating point
2057 number with at least two digits after the decimal (i.e., hundredths,
2058 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
2059 See L<Exporter> for details.
2060
2061 It may be handy to add a function or method to retrieve the number.
2062 Use the number in announcements and archive file names when
2063 releasing the module (ModuleName-1.02.tar.Z).
2064 See perldoc ExtUtils::MakeMaker.pm for details.
2065
2066 =item  *
2067
2068 How to release and distribute a module.
2069
2070 It's good idea to post an announcement of the availability of your
2071 module (or the module itself if small) to the comp.lang.perl.announce
2072 Usenet newsgroup.  This will at least ensure very wide once-off
2073 distribution.
2074
2075 If possible, register the module with CPAN.  You should
2076 include details of its location in your announcement.
2077
2078 Some notes about ftp archives: Please use a long descriptive file
2079 name that includes the version number. Most incoming directories
2080 will not be readable/listable, i.e., you won't be able to see your
2081 file after uploading it. Remember to send your email notification
2082 message as soon as possible after uploading else your file may get
2083 deleted automatically. Allow time for the file to be processed
2084 and/or check the file has been processed before announcing its
2085 location.
2086
2087 FTP Archives for Perl Modules:
2088
2089 Follow the instructions and links on:
2090
2091    http://www.cpan.org/modules/00modlist.long.html
2092    http://www.cpan.org/modules/04pause.html
2093
2094 or upload to one of these sites:
2095
2096    https://pause.kbx.de/pause/
2097    http://pause.perl.org/pause/
2098
2099 and notify <modules@perl.org>.
2100
2101 By using the WWW interface you can ask the Upload Server to mirror
2102 your modules from your ftp or WWW site into your own directory on
2103 CPAN!
2104
2105 Please remember to send me an updated entry for the Module list!
2106
2107 =item  *
2108
2109 Take care when changing a released module.
2110
2111 Always strive to remain compatible with previous released versions.
2112 Otherwise try to add a mechanism to revert to the
2113 old behavior if people rely on it.  Document incompatible changes.
2114
2115 =back
2116
2117 =back
2118
2119 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
2120
2121 =over 4
2122
2123 =item  *
2124
2125 There is no requirement to convert anything.
2126
2127 If it ain't broke, don't fix it! Perl 4 library scripts should
2128 continue to work with no problems. You may need to make some minor
2129 changes (like escaping non-array @'s in double quoted strings) but
2130 there is no need to convert a .pl file into a Module for just that.
2131
2132 =item  *
2133
2134 Consider the implications.
2135
2136 All Perl applications that make use of the script will need to
2137 be changed (slightly) if the script is converted into a module.  Is
2138 it worth it unless you plan to make other changes at the same time?
2139
2140 =item  *
2141
2142 Make the most of the opportunity.
2143
2144 If you are going to convert the script to a module you can use the
2145 opportunity to redesign the interface.  The guidelines for module
2146 creation above include many of the issues you should consider.
2147
2148 =item  *
2149
2150 The pl2pm utility will get you started.
2151
2152 This utility will read *.pl files (given as parameters) and write
2153 corresponding *.pm files. The pl2pm utilities does the following:
2154
2155 =over 10
2156
2157 =item *
2158
2159 Adds the standard Module prologue lines
2160
2161 =item *
2162
2163 Converts package specifiers from ' to ::
2164
2165 =item *
2166
2167 Converts die(...) to croak(...)
2168
2169 =item *
2170
2171 Several other minor changes
2172
2173 =back
2174
2175 Being a mechanical process pl2pm is not bullet proof. The converted
2176 code will need careful checking, especially any package statements.
2177 Don't delete the original .pl file till the new .pm one works!
2178
2179 =back
2180
2181 =head2 Guidelines for Reusing Application Code
2182
2183 =over 4
2184
2185 =item  *
2186
2187 Complete applications rarely belong in the Perl Module Library.
2188
2189 =item  *
2190
2191 Many applications contain some Perl code that could be reused.
2192
2193 Help save the world! Share your code in a form that makes it easy
2194 to reuse.
2195
2196 =item  *
2197
2198 Break-out the reusable code into one or more separate module files.
2199
2200 =item  *
2201
2202 Take the opportunity to reconsider and redesign the interfaces.
2203
2204 =item  *
2205
2206 In some cases the 'application' can then be reduced to a small
2207
2208 fragment of code built on top of the reusable modules. In these cases
2209 the application could invoked as:
2210
2211      % perl -e 'use Module::Name; method(@ARGV)' ...
2212 or
2213      % perl -mModule::Name ...    (in perl5.002 or higher)
2214
2215 =back
2216
2217 =head1 NOTE
2218
2219 Perl does not enforce private and public parts of its modules as you may
2220 have been used to in other languages like C++, Ada, or Modula-17.  Perl
2221 doesn't have an infatuation with enforced privacy.  It would prefer
2222 that you stayed out of its living room because you weren't invited, not
2223 because it has a shotgun.
2224
2225 The module and its user have a contract, part of which is common law,
2226 and part of which is "written".  Part of the common law contract is
2227 that a module doesn't pollute any namespace it wasn't asked to.  The
2228 written contract for the module (A.K.A. documentation) may make other
2229 provisions.  But then you know when you C<use RedefineTheWorld> that
2230 you're redefining the world and willing to take the consequences.