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