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