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