pod/perlmodlib.pod

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