pod/perlmodlib.pod

   1 =head1 NAME
   2
   3 perlmodlib - constructing new Perl modules and finding existing ones
   4
   5 =head1 DESCRIPTION
   6
   7 =head1 THE PERL MODULE LIBRARY
   8
   9 Many modules are included the Perl distribution.  These are described
  10 below, and all end in F<.pm>.  You may discover compiled library
  11 file (usually ending in F<.so>) or small pieces of modules to be
  12 autoloaded (ending in F<.al>); these were automatically generated
  13 by the installation process.  You may also discover files in the
  14 library directory that end in either F<.pl> or F<.ph>.  These are
  15 old libraries supplied so that old programs that use them still
  16 run.  The F<.pl> files will all eventually be converted into standard
  17 modules, and the F<.ph> files made by B<h2ph> will probably end up
  18 as extension modules made by B<h2xs>.  (Some F<.ph> values may
  19 already be available through the POSIX, Errno, or Fcntl modules.)
  20 The B<pl2pm> file in the distribution may help in your conversion,
  21 but it's just a mechanical process and therefore far from bulletproof.
  22
  23 =head2 Pragmatic Modules
  24
  25 They work somewhat like compiler directives (pragmata) in that they
  26 tend to affect the compilation of your program, and thus will usually
  27 work well only when used within a C<use>, or C<no>.  Most of these
  28 are lexically scoped, so an inner BLOCK may countermand them
  29 by saying:
  30
  31     no integer;
  32     no strict 'refs';
  33     no warnings;
  34
  35 which lasts until the end of that BLOCK.
  36
  37 Some pragmas are lexically scoped--typically those that affect the
  38 C<$^H> hints variable.  Others affect the current package instead,
  39 like C<use vars> and C<use subs>, which allow you to predeclare a
  40 variables or subroutines within a particular I<file> rather than
  41 just a block.  Such declarations are effective for the entire file
  42 for which they were declared.  You cannot rescind them with C<no
  43 vars> or C<no subs>.
  44
  45 The following pragmas are defined (and have their own documentation).
  46
  47 =over 12
  48
  49 =item attributes
  50
  51 Get/set subroutine or variable attributes
  52
  53 =item attrs
  54
  55 Set/get attributes of a subroutine (deprecated)
  56
  57 =item autouse
  58
  59 Postpone load of modules until a function is used
  60
  61 =item base
  62
  63 Establish IS-A relationship with base class at compile time
  64
  65 =item blib
  66
  67 Use MakeMaker's uninstalled version of a package
  68
  69 =item bytes
  70
  71 Force byte semantics rather than character semantics
  72
  73 =item charnames
  74
  75 Define character names for C<\N{named}> string literal escape.
  76
  77 =item constant
  78
  79 Declare constants
  80
  81 =item diagnostics
  82
  83 Perl compiler pragma to force verbose warning diagnostics
  84
  85 =item fields
  86
  87 Compile-time class fields
  88
  89 =item filetest
  90
  91 Control the filetest permission operators
  92
  93 =item integer
  94
  95 Compute arithmetic in integer instead of double
  96
  97 =item less
  98
  99 Request less of something from the compiler
 100
 101 =item lib
 102
 103 Manipulate @INC at compile time
 104
 105 =item locale
 106
 107 Use and avoid POSIX locales for built-in operations
 108
 109 =item open
 110
 111 Set default disciplines for input and output
 112
 113 =item ops
 114
 115 Restrict unsafe operations when compiling
 116
 117 =item overload
 118
 119 Package for overloading perl operations
 120
 121 =item re
 122
 123 Alter regular expression behaviour
 124
 125 =item sigtrap
 126
 127 Enable simple signal handling
 128
 129 =item strict
 130
 131 Restrict unsafe constructs
 132
 133 =item subs
 134
 135 Predeclare sub names
 136
 137 =item utf8
 138
 139 Enable/disable UTF-8 in source code
 140
 141 =item vars
 142
 143 Predeclare global variable names (obsolete)
 144
 145 =item warnings
 146
 147 Control optional warnings
 148
 149 =back
 150
 151 =head2 Standard Modules
 152
 153 Standard, bundled modules are all expected to behave in a well-defined
 154 manner with respect to namespace pollution because they use the
 155 Exporter module.  See their own documentation for details.
 156
 157 =over 12
 158
 159 =item AnyDBM_File
 160
 161 Provide framework for multiple DBMs
 162
 163 =item AutoLoader
 164
 165 Load subroutines only on demand
 166
 167 =item AutoSplit
 168
 169 Split a package for autoloading
 170
 171 =item B
 172
 173 The Perl Compiler
 174
 175 =item B::Asmdata
 176
 177 Autogenerated data about Perl ops, used to generate bytecode
 178
 179 =item B::Assembler
 180
 181 Assemble Perl bytecode
 182
 183 =item B::Bblock
 184
 185 Walk basic blocks
 186
 187 =item B::Bytecode
 188
 189 Perl compiler's bytecode backend
 190
 191 =item B::C
 192
 193 Perl compiler's C backend
 194
 195 =item B::CC
 196
 197 Perl compiler's optimized C translation backend
 198
 199 =item B::Debug
 200
 201 Walk Perl syntax tree, printing debug info about ops
 202
 203 =item B::Deparse
 204
 205 Perl compiler backend to produce perl code
 206
 207 =item B::Disassembler
 208
 209 Disassemble Perl bytecode
 210
 211 =item B::Lint
 212
 213 Perl lint
 214
 215 =item B::Showlex
 216
 217 Show lexical variables used in functions or files
 218
 219 =item B::Stackobj
 220
 221 Helper module for CC backend
 222
 223 =item B::Terse
 224
 225 Walk Perl syntax tree, printing terse info about ops
 226
 227 =item B::Xref
 228
 229 Generates cross reference reports for Perl programs
 230
 231 =item Benchmark
 232
 233 Benchmark running times of Perl code
 234
 235 =item ByteLoader
 236
 237 Load byte compiled perl code
 238
 239 =item CGI
 240
 241 Simple Common Gateway Interface Class
 242
 243 =item CGI::Apache
 244
 245 Backward compatibility module for CGI.pm
 246
 247 =item CGI::Carp
 248
 249 CGI routines for writing to the HTTPD (or other) error log
 250
 251 =item CGI::Cookie
 252
 253 Interface to Netscape Cookies
 254
 255 =item CGI::Fast
 256
 257 CGI Interface for Fast CGI
 258
 259 =item CGI::Pretty
 260
 261 Module to produce nicely formatted HTML code
 262
 263 =item CGI::Push
 264
 265 Simple Interface to Server Push
 266
 267 =item CGI::Switch
 268
 269 Backward compatibility module for defunct CGI::Switch
 270
 271 =item CPAN
 272
 273 Query, download and build perl modules from CPAN sites
 274
 275 =item CPAN::FirstTime
 276
 277 Utility for CPAN::Config file Initialization
 278
 279 =item CPAN::Nox
 280
 281 Wrapper around CPAN.pm without using any XS module
 282
 283 =item Carp
 284
 285 Warn of errors (from perspective of caller)
 286
 287 =item Carp::Heavy
 288
 289 Carp guts
 290
 291 =item Class::Struct
 292
 293 Declare struct-like datatypes as Perl classes
 294
 295 =item Cwd
 296
 297 Get pathname of current working directory
 298
 299 =item DB
 300
 301 Programmatic interface to the Perl debugging API (draft, subject to
 302
 303 =item DB_File
 304
 305 Perl5 access to Berkeley DB version 1.x
 306
 307 =item Devel::SelfStubber
 308
 309 Generate stubs for a SelfLoading module
 310
 311 =item DirHandle
 312
 313 Supply object methods for directory handles
 314
 315 =item Dumpvalue
 316
 317 Provides screen dump of Perl data.
 318
 319 =item English
 320
 321 Use nice English (or awk) names for ugly punctuation variables
 322
 323 =item Env
 324
 325 Perl module that imports environment variables as scalars or arrays
 326
 327 =item Exporter
 328
 329 Implements default import method for modules
 330
 331 =item Exporter::Heavy
 332
 333 Exporter guts
 334
 335 =item ExtUtils::Command
 336
 337 Utilities to replace common UNIX commands in Makefiles etc.
 338
 339 =item ExtUtils::Embed
 340
 341 Utilities for embedding Perl in C/C++ applications
 342
 343 =item ExtUtils::Install
 344
 345 Install files from here to there
 346
 347 =item ExtUtils::Installed
 348
 349 Inventory management of installed modules
 350
 351 =item ExtUtils::Liblist
 352
 353 Determine libraries to use and how to use them
 354
 355 =item ExtUtils::MM_Cygwin
 356
 357 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 358
 359 =item ExtUtils::MM_OS2
 360
 361 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 362
 363 =item ExtUtils::MM_Unix
 364
 365 Methods used by ExtUtils::MakeMaker
 366
 367 =item ExtUtils::MM_VMS
 368
 369 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 370
 371 =item ExtUtils::MM_Win32
 372
 373 Methods to override UN*X behaviour in ExtUtils::MakeMaker
 374
 375 =item ExtUtils::MakeMaker
 376
 377 Create an extension Makefile
 378
 379 =item ExtUtils::Manifest
 380
 381 Utilities to write and check a MANIFEST file
 382
 383 =item ExtUtils::Mkbootstrap
 384
 385 Make a bootstrap file for use by DynaLoader
 386
 387 =item ExtUtils::Mksymlists
 388
 389 Write linker options files for dynamic extension
 390
 391 =item ExtUtils::Packlist
 392
 393 Manage .packlist files
 394
 395 =item ExtUtils::testlib
 396
 397 Add blib/* directories to @INC
 398
 399 =item Fatal
 400
 401 Replace functions with equivalents which succeed or die
 402
 403 =item Fcntl
 404
 405 Load the C Fcntl.h defines
 406
 407 =item File::Basename
 408
 409 Split a pathname into pieces
 410
 411 =item File::CheckTree
 412
 413 Run many filetest checks on a tree
 414
 415 =item File::Compare
 416
 417 Compare files or filehandles
 418
 419 =item File::Copy
 420
 421 Copy files or filehandles
 422
 423 =item File::DosGlob
 424
 425 DOS like globbing and then some
 426
 427 =item File::Find
 428
 429 Traverse a file tree
 430
 431 =item File::Path
 432
 433 Create or remove directory trees
 434
 435 =item File::Spec
 436
 437 Portably perform operations on file names
 438
 439 =item File::Spec::Functions
 440
 441 Portably perform operations on file names
 442
 443 =item File::Spec::Mac
 444
 445 File::Spec for MacOS
 446
 447 =item File::Spec::OS2
 448
 449 Methods for OS/2 file specs
 450
 451 =item File::Spec::Unix
 452
 453 Methods used by File::Spec
 454
 455 =item File::Spec::VMS
 456
 457 Methods for VMS file specs
 458
 459 =item File::Spec::Win32
 460
 461 Methods for Win32 file specs
 462
 463 =item File::Temp
 464
 465 Return name and handle of a temporary file safely
 466
 467 =item File::stat
 468
 469 By-name interface to Perl's built-in stat() functions
 470
 471 =item FileCache
 472
 473 Keep more files open than the system permits
 474
 475 =item FileHandle
 476
 477 Supply object methods for filehandles
 478
 479 =item FindBin
 480
 481 Locate directory of original perl script
 482
 483 =item Getopt::Long
 484
 485 Extended processing of command line options
 486
 487 =item Getopt::Std
 488
 489 Process single-character switches with switch clustering
 490
 491 =item I18N::Collate
 492
 493 Compare 8-bit scalar data according to the current locale
 494
 495 =item IO
 496
 497 Load various IO modules
 498
 499 =item IPC::Open2
 500
 501 Open a process for both reading and writing
 502
 503 =item IPC::Open3
 504
 505 Open a process for reading, writing, and error handling
 506
 507 =item Math::BigFloat
 508
 509 Arbitrary length float math package
 510
 511 =item Math::BigInt
 512
 513 Arbitrary size integer math package
 514
 515 =item Math::Complex
 516
 517 Complex numbers and associated mathematical functions
 518
 519 =item Math::Trig
 520
 521 Trigonometric functions
 522
 523 =item NDBM_File
 524
 525 Tied access to ndbm files
 526
 527 =item Net::Ping
 528
 529 Check a remote host for reachability
 530
 531 =item Net::hostent
 532
 533 By-name interface to Perl's built-in gethost*() functions
 534
 535 =item Net::netent
 536
 537 By-name interface to Perl's built-in getnet*() functions
 538
 539 =item Net::protoent
 540
 541 By-name interface to Perl's built-in getproto*() functions
 542
 543 =item Net::servent
 544
 545 By-name interface to Perl's built-in getserv*() functions
 546
 547 =item O
 548
 549 Generic interface to Perl Compiler backends
 550
 551 =item ODBM_File
 552
 553 Tied access to odbm files
 554
 555 =item Opcode
 556
 557 Disable named opcodes when compiling perl code
 558
 559 =item Pod::Checker
 560
 561 Check pod documents for syntax errors
 562
 563 =item Pod::Find
 564
 565 Find POD documents in directory trees
 566
 567 =item Pod::Html
 568
 569 Module to convert pod files to HTML
 570
 571 =item Pod::InputObjects
 572
 573 Objects representing POD input paragraphs, commands, etc.
 574
 575 =item Pod::Man
 576
 577 Convert POD data to formatted *roff input
 578
 579 =item Pod::ParseUtils
 580
 581 Helpers for POD parsing and conversion
 582
 583 =item Pod::Parser
 584
 585 Base class for creating POD filters and translators
 586
 587 =item Pod::Plainer
 588
 589 Perl extension for converting Pod to old style Pod.
 590
 591 =item Pod::Select
 592
 593 Extract selected sections of POD from input
 594
 595 =item Pod::Text
 596
 597 Convert POD data to formatted ASCII text
 598
 599 =item Pod::Text::Color
 600
 601 Convert POD data to formatted color ASCII text
 602
 603 =item Pod::Text::Termcap
 604
 605 Convert POD data to ASCII text with format escapes
 606
 607 =item Pod::Usage
 608
 609 Print a usage message from embedded pod documentation
 610
 611 =item SDBM_File
 612
 613 Tied access to sdbm files
 614
 615 =item Safe
 616
 617 Compile and execute code in restricted compartments
 618
 619 =item Search::Dict
 620
 621 Search for key in dictionary file
 622
 623 =item SelectSaver
 624
 625 Save and restore selected file handle
 626
 627 =item SelfLoader
 628
 629 Load functions only on demand
 630
 631 =item Shell
 632
 633 Run shell commands transparently within perl
 634
 635 =item Socket
 636
 637 Load the C socket.h defines and structure manipulators
 638
 639 =item Symbol
 640
 641 Manipulate Perl symbols and their names
 642
 643 =item Term::ANSIColor
 644
 645 Color screen output using ANSI escape sequences
 646
 647 =item Term::Cap
 648
 649 Perl termcap interface
 650
 651 =item Term::Complete
 652
 653 Perl word completion module
 654
 655 =item Term::ReadLine
 656
 657 Perl interface to various C<readline> packages. If
 658
 659 =item Test
 660
 661 Provides a simple framework for writing test scripts
 662
 663 =item Test::Harness
 664
 665 Run perl standard test scripts with statistics
 666
 667 =item Text::Abbrev
 668
 669 Create an abbreviation table from a list
 670
 671 =item Text::ParseWords
 672
 673 Parse text into an array of tokens or array of arrays
 674
 675 =item Text::Soundex
 676
 677 Implementation of the Soundex Algorithm as Described by Knuth
 678
 679 =item Text::Wrap
 680
 681 Line wrapping to form simple paragraphs
 682
 683 =item Tie::Array
 684
 685 Base class for tied arrays
 686
 687 =item Tie::Handle
 688
 689 Base class definitions for tied handles
 690
 691 =item Tie::Hash
 692
 693 Base class definitions for tied hashes
 694
 695 =item Tie::RefHash
 696
 697 Use references as hash keys
 698
 699 =item Tie::Scalar
 700
 701 Base class definitions for tied scalars
 702
 703 =item Tie::SubstrHash
 704
 705 Fixed-table-size, fixed-key-length hashing
 706
 707 =item Time::Local
 708
 709 Efficiently compute time from local and GMT time
 710
 711 =item Time::gmtime
 712
 713 By-name interface to Perl's built-in gmtime() function
 714
 715 =item Time::localtime
 716
 717 By-name interface to Perl's built-in localtime() function
 718
 719 =item Time::tm
 720
 721 Internal object used by Time::gmtime and Time::localtime
 722
 723 =item UNIVERSAL
 724
 725 Base class for ALL classes (blessed references)
 726
 727 =item User::grent
 728
 729 By-name interface to Perl's built-in getgr*() functions
 730
 731 =item User::pwent
 732
 733 By-name interface to Perl's built-in getpw*() functions
 734
 735 =back
 736
 737 To find out I<all> modules installed on your system, including
 738 those without documentation or outside the standard release,
 739 just do this:
 740
 741     % find `perl -e 'print "@INC"'` -name '*.pm' -print
 742
 743 They should all have their own documentation installed and accessible
 744 via your system man(1) command.  If you do not have a B<find>
 745 program, you can use the Perl B<find2perl> program instead, which
 746 generates Perl code as output you can run through perl.  If you
 747 have a B<man> program but it doesn't find your modules, you'll have
 748 to fix your manpath.  See L<perl> for details.  If you have no
 749 system B<man> command, you might try the B<perldoc> program.
 750
 751 =head2 Extension Modules
 752
 753 Extension modules are written in C (or a mix of Perl and C).  They
 754 are usually dynamically loaded into Perl if and when you need them,
 755 but may also be be linked in statically.  Supported extension modules
 756 include Socket, Fcntl, and POSIX.
 757
 758 Many popular C extension modules do not come bundled (at least, not
 759 completely) due to their sizes, volatility, or simply lack of time
 760 for adequate testing and configuration across the multitude of
 761 platforms on which Perl was beta-tested.  You are encouraged to
 762 look for them on CPAN (described below), or using web search engines
 763 like Alta Vista or Deja News.
 764
 765 =head1 CPAN
 766
 767 CPAN stands for Comprehensive Perl Archive Network; it's a globally
 768 replicated trove of Perl materials, including documentation, style
 769 guides, tricks and traps, alternate ports to non-Unix systems and
 770 occasional binary distributions for these.   Search engines for
 771 CPAN can be found at http://cpan.perl.com/ and at
 772 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
 773
 774 Most importantly, CPAN includes around a thousand unbundled modules,
 775 some of which require a C compiler to build.  Major categories of
 776 modules are:
 777
 778 =over
 779
 780 =item *
 781 Language Extensions and Documentation Tools
 782
 783 =item *
 784 Development Support
 785
 786 =item *
 787 Operating System Interfaces
 788
 789 =item *
 790 Networking, Device Control (modems) and InterProcess Communication
 791
 792 =item *
 793 Data Types and Data Type Utilities
 794
 795 =item *
 796 Database Interfaces
 797
 798 =item *
 799 User Interfaces
 800
 801 =item *
 802 Interfaces to / Emulations of Other Programming Languages
 803
 804 =item *
 805 File Names, File Systems and File Locking (see also File Handles)
 806
 807 =item *
 808 String Processing, Language Text Processing, Parsing, and Searching
 809
 810 =item *
 811 Option, Argument, Parameter, and Configuration File Processing
 812
 813 =item *
 814 Internationalization and Locale
 815
 816 =item *
 817 Authentication, Security, and Encryption
 818
 819 =item *
 820 World Wide Web, HTML, HTTP, CGI, MIME
 821
 822 =item *
 823 Server and Daemon Utilities
 824
 825 =item *
 826 Archiving and Compression
 827
 828 =item *
 829 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
 830
 831 =item *
 832 Mail and Usenet News
 833
 834 =item *
 835 Control Flow Utilities (callbacks and exceptions etc)
 836
 837 =item *
 838 File Handle and Input/Output Stream Utilities
 839
 840 =item *
 841 Miscellaneous Modules
 842
 843 =back
 844
 845 Registered CPAN sites as of this writing include the following.
 846 You should try to choose one close to you:
 847
 848 =over
 849
 850 =item Africa
 851
 852     South Africa   ftp://ftp.is.co.za/programming/perl/CPAN/
 853                    ftp://ftp.saix.net/pub/CPAN/
 854                    ftp://ftp.sun.ac.za/CPAN/
 855                    ftp://ftpza.co.za/pub/mirrors/cpan/
 856
 857
 858 =item Asia
 859
 860     China          ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
 861     Hong Kong      ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
 862     Indonesia      ftp://malone.piksi.itb.ac.id/pub/CPAN/
 863     Israel         ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
 864     Japan          ftp://ftp.dti.ad.jp/pub/lang/CPAN/
 865                    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
 866                    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
 867                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
 868                    ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
 869                    ftp://mirror.nucba.ac.jp/mirror/Perl/
 870     Saudi-Arabia   ftp://ftp.isu.net.sa/pub/CPAN/
 871     Singapore      ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
 872     South Korea    ftp://ftp.bora.net/pub/CPAN/
 873                    ftp://ftp.kornet.net/pub/CPAN/
 874                    ftp://ftp.nuri.net/pub/CPAN/
 875     Taiwan         ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
 876                    ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/
 877                    ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
 878     Thailand       ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
 879
 880
 881 =item Australasia
 882
 883     Australia      ftp://cpan.topend.com.au/pub/CPAN/
 884                    ftp://ftp.labyrinth.net.au/pub/perl-CPAN/
 885                    ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
 886                    ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
 887     New Zealand    ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
 888                    ftp://sunsite.net.nz/pub/languages/perl/CPAN/
 889
 890
 891 =item Central America
 892
 893     Costa Rica     ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
 894
 895
 896 =item Europe
 897
 898     Austria        ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
 899     Belgium        ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
 900     Bulgaria       ftp://ftp.ntrl.net/pub/mirrors/CPAN/
 901     Croatia        ftp://ftp.linux.hr/pub/CPAN/
 902     Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
 903                    ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
 904     Denmark        ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
 905     Estonia        ftp://ftp.ut.ee/pub/languages/perl/CPAN/
 906     Finland        ftp://ftp.funet.fi/pub/languages/perl/CPAN/
 907     France         ftp://ftp.grolier.fr/pub/perl/CPAN/
 908                    ftp://ftp.lip6.fr/pub/perl/CPAN/
 909                    ftp://ftp.oleane.net/pub/mirrors/CPAN/
 910                    ftp://ftp.pasteur.fr/pub/computing/CPAN/
 911                    ftp://ftp.uvsq.fr/pub/perl/CPAN/
 912     German         ftp://ftp.gigabell.net/pub/CPAN/
 913     Germany        ftp://ftp.archive.de.uu.net/pub/CPAN/
 914                    ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
 915                    ftp://ftp.gmd.de/packages/CPAN/
 916                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
 917
 918 ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
 919                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
 920                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
 921                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
 922                    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
 923     Germany        ftp://ftp.archive.de.uu.net/pub/CPAN/
 924                    ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
 925                    ftp://ftp.gmd.de/packages/CPAN/
 926                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
 927
 928 ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
 929                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
 930                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
 931                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
 932                    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
 933     Greece         ftp://ftp.ntua.gr/pub/lang/perl/
 934     Hungary        ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
 935     Iceland        ftp://ftp.gm.is/pub/CPAN/
 936     Ireland        ftp://cpan.indigo.ie/pub/CPAN/
 937                    ftp://sunsite.compapp.dcu.ie/pub/perl/
 938     Italy          ftp://cis.uniRoma2.it/CPAN/
 939                    ftp://ftp.flashnet.it/pub/CPAN/
 940                    ftp://ftp.unina.it/pub/Other/CPAN/
 941                    ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
 942     Netherlands    ftp://ftp.cs.uu.nl/mirror/CPAN/
 943                    ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
 944     Norway         ftp://ftp.uit.no/pub/languages/perl/cpan/
 945                    ftp://sunsite.uio.no/pub/languages/perl/CPAN/
 946     Poland         ftp://ftp.man.torun.pl/pub/CPAN/
 947                    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
 948                    ftp://sunsite.icm.edu.pl/pub/CPAN/
 949     Portugal       ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
 950                    ftp://ftp.ist.utl.pt/pub/CPAN/
 951                    ftp://ftp.ua.pt/pub/CPAN/
 952     Romania        ftp://ftp.dnttm.ro/pub/CPAN/
 953     Russia         ftp://ftp.chg.ru/pub/lang/perl/CPAN/
 954                    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
 955     Slovakia       ftp://ftp.entry.sk/pub/languages/perl/CPAN/
 956     Slovenia       ftp://ftp.arnes.si/software/perl/CPAN/
 957     Spain          ftp://ftp.etse.urv.es/pub/perl/
 958                    ftp://ftp.rediris.es/mirror/CPAN/
 959     Sweden         ftp://ftp.sunet.se/pub/lang/perl/CPAN/
 960     Switzerland    ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
 961     Turkey         ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
 962     United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
 963                    ftp://ftp.flirble.org/pub/languages/perl/CPAN/
 964
 965 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
 966                    ftp://ftp.plig.org/pub/CPAN/
 967                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
 968
 969
 970 =item North America
 971
 972     Alberta        ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
 973     California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
 974                    ftp://cpan.valueclick.com/CPAN/
 975                    ftp://ftp.cdrom.com/pub/perl/CPAN/
 976                    http://download.sourceforge.net/mirrors/CPAN/
 977     Colorado       ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
 978     Florida        ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
 979     Georgia        ftp://ftp.twoguys.org/CPAN/
 980     Illinois       ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
 981     Indiana        ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
 982                    ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
 983     Kentucky       ftp://ftp.uky.edu/CPAN/
 984     Manitoba       ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
 985     Massachusetts
 986 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
 987                    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
 988     Mexico         ftp://ftp.msg.com.mx/pub/CPAN/
 989     New York       ftp://ftp.deao.net/pub/CPAN/
 990                    ftp://ftp.rge.com/pub/languages/perl/
 991     North Carolina ftp://ftp.duke.edu/pub/perl/
 992     Nova Scotia    ftp://cpan.chebucto.ns.ca/pub/CPAN/
 993     Oklahoma       ftp://ftp.ou.edu/mirrors/CPAN/
 994     Ontario        ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
 995     Oregon         ftp://ftp.orst.edu/pub/packages/CPAN/
 996     Pennsylvania   ftp://ftp.epix.net/pub/languages/perl/
 997     Tennessee      ftp://ftp.sunsite.utk.edu/pub/CPAN/
 998     Texas          ftp://ftp.sedl.org/pub/mirrors/CPAN/
 999                    ftp://jhcloos.com/pub/mirror/CPAN/
1000     Utah           ftp://mirror.xmission.com/CPAN/
1001     Virginia       ftp://ftp.perl.org/pub/perl/CPAN/
1002                    ftp://ruff.cs.jmu.edu/pub/CPAN/
1003     Washington     ftp://ftp-mirror.internap.com/pub/CPAN/
1004                    ftp://ftp.llarian.net/pub/CPAN/
1005                    ftp://ftp.spu.edu/pub/CPAN/
1006
1007
1008 =item South America
1009
1010     Brazil         ftp://cpan.if.usp.br/pub/mirror/CPAN/
1011                    ftp://ftp.matrix.com.br/pub/perl/
1012     Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/
1013
1014 =back
1015
1016 For an up-to-date listing of CPAN sites,
1017 see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
1018
1019 =head1 Modules: Creation, Use, and Abuse
1020
1021 (The following section is borrowed directly from Tim Bunce's modules
1022 file, available at your nearest CPAN site.)
1023
1024 Perl implements a class using a package, but the presence of a
1025 package doesn't imply the presence of a class.  A package is just a
1026 namespace.  A class is a package that provides subroutines that can be
1027 used as methods.  A method is just a subroutine that expects, as its
1028 first argument, either the name of a package (for "static" methods),
1029 or a reference to something (for "virtual" methods).
1030
1031 A module is a file that (by convention) provides a class of the same
1032 name (sans the .pm), plus an import method in that class that can be
1033 called to fetch exported symbols.  This module may implement some of
1034 its methods by loading dynamic C or C++ objects, but that should be
1035 totally transparent to the user of the module.  Likewise, the module
1036 might set up an AUTOLOAD function to slurp in subroutine definitions on
1037 demand, but this is also transparent.  Only the F<.pm> file is required to
1038 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
1039 the AUTOLOAD mechanism.
1040
1041 =head2 Guidelines for Module Creation
1042
1043 =over 4
1044
1045 =item Do similar modules already exist in some form?
1046
1047 If so, please try to reuse the existing modules either in whole or
1048 by inheriting useful features into a new class.  If this is not
1049 practical try to get together with the module authors to work on
1050 extending or enhancing the functionality of the existing modules.
1051 A perfect example is the plethora of packages in perl4 for dealing
1052 with command line options.
1053
1054 If you are writing a module to expand an already existing set of
1055 modules, please coordinate with the author of the package.  It
1056 helps if you follow the same naming scheme and module interaction
1057 scheme as the original author.
1058
1059 =item Try to design the new module to be easy to extend and reuse.
1060
1061 Try to C<use warnings;> (or C<use warnings qw(...);>).
1062 Remember that you can add C<no warnings qw(...);> to individual blocks
1063 of code that need less warnings.
1064
1065 Use blessed references.  Use the two argument form of bless to bless
1066 into the class name given as the first parameter of the constructor,
1067 e.g.,:
1068
1069  sub new {
1070      my $class = shift;
1071      return bless {}, $class;
1072  }
1073
1074 or even this if you'd like it to be used as either a static
1075 or a virtual method.
1076
1077  sub new {
1078      my $self  = shift;
1079      my $class = ref($self) || $self;
1080      return bless {}, $class;
1081  }
1082
1083 Pass arrays as references so more parameters can be added later
1084 (it's also faster).  Convert functions into methods where
1085 appropriate.  Split large methods into smaller more flexible ones.
1086 Inherit methods from other modules if appropriate.
1087
1088 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1089 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1090 Let the objects look after themselves! Generally, avoid hard-wired
1091 class names as far as possible.
1092
1093 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1094 C<< $r->func() >> would work (see L<perlbot> for more details).
1095
1096 Use autosplit so little used or newly added functions won't be a
1097 burden to programs that don't use them. Add test functions to
1098 the module after __END__ either using AutoSplit or by saying:
1099
1100  eval join('',<main::DATA>) || die $@ unless caller();
1101
1102 Does your module pass the 'empty subclass' test? If you say
1103 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1104 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1105 does your application still work if you change:  C<$obj = new YOURCLASS;>
1106 into: C<$obj = new SUBCLASS;> ?
1107
1108 Avoid keeping any state information in your packages. It makes it
1109 difficult for multiple other packages to use yours. Keep state
1110 information in objects.
1111
1112 Always use B<-w>.
1113
1114 Try to C<use strict;> (or C<use strict qw(...);>).
1115 Remember that you can add C<no strict qw(...);> to individual blocks
1116 of code that need less strictness.
1117
1118 Always use B<-w>.
1119
1120 Follow the guidelines in the perlstyle(1) manual.
1121
1122 Always use B<-w>.
1123
1124 =item Some simple style guidelines
1125
1126 The perlstyle manual supplied with Perl has many helpful points.
1127
1128 Coding style is a matter of personal taste. Many people evolve their
1129 style over several years as they learn what helps them write and
1130 maintain good code.  Here's one set of assorted suggestions that
1131 seem to be widely used by experienced developers:
1132
1133 Use underscores to separate words.  It is generally easier to read
1134 $var_names_like_this than $VarNamesLikeThis, especially for
1135 non-native speakers of English. It's also a simple rule that works
1136 consistently with VAR_NAMES_LIKE_THIS.
1137
1138 Package/Module names are an exception to this rule. Perl informally
1139 reserves lowercase module names for 'pragma' modules like integer
1140 and strict. Other modules normally begin with a capital letter and
1141 use mixed case with no underscores (need to be short and portable).
1142
1143 You may find it helpful to use letter case to indicate the scope
1144 or nature of a variable. For example:
1145
1146  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1147  $Some_Caps_Here  package-wide global/static
1148  $no_caps_here    function scope my() or local() variables
1149
1150 Function and method names seem to work best as all lowercase.
1151 e.g., C<< $obj->as_string() >>.
1152
1153 You can use a leading underscore to indicate that a variable or
1154 function should not be used outside the package that defined it.
1155
1156 =item Select what to export.
1157
1158 Do NOT export method names!
1159
1160 Do NOT export anything else by default without a good reason!
1161
1162 Exports pollute the namespace of the module user.  If you must
1163 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1164 short or common names to reduce the risk of name clashes.
1165
1166 Generally anything not exported is still accessible from outside the
1167 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1168 syntax.  By convention you can use a leading underscore on names to
1169 indicate informally that they are 'internal' and not for public use.
1170
1171 (It is actually possible to get private functions by saying:
1172 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
1173 directly as a method, because a method must have a name in the symbol
1174 table.)
1175
1176 As a general rule, if the module is trying to be object oriented
1177 then export nothing. If it's just a collection of functions then
1178 @EXPORT_OK anything but use @EXPORT with caution.
1179
1180 =item Select a name for the module.
1181
1182 This name should be as descriptive, accurate, and complete as
1183 possible.  Avoid any risk of ambiguity. Always try to use two or
1184 more whole words.  Generally the name should reflect what is special
1185 about what the module does rather than how it does it.  Please use
1186 nested module names to group informally or categorize a module.
1187 There should be a very good reason for a module not to have a nested name.
1188 Module names should begin with a capital letter.
1189
1190 Having 57 modules all called Sort will not make life easy for anyone
1191 (though having 23 called Sort::Quick is only marginally better :-).
1192 Imagine someone trying to install your module alongside many others.
1193 If in any doubt ask for suggestions in comp.lang.perl.misc.
1194
1195 If you are developing a suite of related modules/classes it's good
1196 practice to use nested classes with a common prefix as this will
1197 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1198 Xyz::Model etc. Use the modules in this list as a naming guide.
1199
1200 If adding a new module to a set, follow the original author's
1201 standards for naming modules and the interface to methods in
1202 those modules.
1203
1204 To be portable each component of a module name should be limited to
1205 11 characters. If it might be used on MS-DOS then try to ensure each is
1206 unique in the first 8 characters. Nested modules make this easier.
1207
1208 =item Have you got it right?
1209
1210 How do you know that you've made the right decisions? Have you
1211 picked an interface design that will cause problems later? Have
1212 you picked the most appropriate name? Do you have any questions?
1213
1214 The best way to know for sure, and pick up many helpful suggestions,
1215 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1216 all the people who develop modules and it's the best place to ask.
1217
1218 All you need to do is post a short summary of the module, its
1219 purpose and interfaces. A few lines on each of the main methods is
1220 probably enough. (If you post the whole module it might be ignored
1221 by busy people - generally the very people you want to read it!)
1222
1223 Don't worry about posting if you can't say when the module will be
1224 ready - just say so in the message. It might be worth inviting
1225 others to help you, they may be able to complete it for you!
1226
1227 =item README and other Additional Files.
1228
1229 It's well known that software developers usually fully document the
1230 software they write. If, however, the world is in urgent need of
1231 your software and there is not enough time to write the full
1232 documentation please at least provide a README file containing:
1233
1234 =over 10
1235
1236 =item *
1237 A description of the module/package/extension etc.
1238
1239 =item *
1240 A copyright notice - see below.
1241
1242 =item *
1243 Prerequisites - what else you may need to have.
1244
1245 =item *
1246 How to build it - possible changes to Makefile.PL etc.
1247
1248 =item *
1249 How to install it.
1250
1251 =item *
1252 Recent changes in this release, especially incompatibilities
1253
1254 =item *
1255 Changes / enhancements you plan to make in the future.
1256
1257 =back
1258
1259 If the README file seems to be getting too large you may wish to
1260 split out some of the sections into separate files: INSTALL,
1261 Copying, ToDo etc.
1262
1263 =over 4
1264
1265 =item Adding a Copyright Notice.
1266
1267 How you choose to license your work is a personal decision.
1268 The general mechanism is to assert your Copyright and then make
1269 a declaration of how others may copy/use/modify your work.
1270
1271 Perl, for example, is supplied with two types of licence: The GNU
1272 GPL and The Artistic Licence (see the files README, Copying, and
1273 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
1274
1275 My personal recommendation, out of respect for Larry, Perl, and the
1276 Perl community at large is to state something simply like:
1277
1278  Copyright (c) 1995 Your Name. All rights reserved.
1279  This program is free software; you can redistribute it and/or
1280  modify it under the same terms as Perl itself.
1281
1282 This statement should at least appear in the README file. You may
1283 also wish to include it in a Copying file and your source files.
1284 Remember to include the other words in addition to the Copyright.
1285
1286 =item Give the module a version/issue/release number.
1287
1288 To be fully compatible with the Exporter and MakeMaker modules you
1289 should store your module's version number in a non-my package
1290 variable called $VERSION.  This should be a floating point
1291 number with at least two digits after the decimal (i.e., hundredths,
1292 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
1293 See L<Exporter> for details.
1294
1295 It may be handy to add a function or method to retrieve the number.
1296 Use the number in announcements and archive file names when
1297 releasing the module (ModuleName-1.02.tar.Z).
1298 See perldoc ExtUtils::MakeMaker.pm for details.
1299
1300 =item How to release and distribute a module.
1301
1302 It's good idea to post an announcement of the availability of your
1303 module (or the module itself if small) to the comp.lang.perl.announce
1304 Usenet newsgroup.  This will at least ensure very wide once-off
1305 distribution.
1306
1307 If possible, register the module with CPAN.  You should
1308 include details of its location in your announcement.
1309
1310 Some notes about ftp archives: Please use a long descriptive file
1311 name that includes the version number. Most incoming directories
1312 will not be readable/listable, i.e., you won't be able to see your
1313 file after uploading it. Remember to send your email notification
1314 message as soon as possible after uploading else your file may get
1315 deleted automatically. Allow time for the file to be processed
1316 and/or check the file has been processed before announcing its
1317 location.
1318
1319 FTP Archives for Perl Modules:
1320
1321 Follow the instructions and links on:
1322
1323    http://www.perl.com/CPAN/modules/00modlist.long.html
1324    http://www.perl.com/CPAN/modules/04pause.html
1325
1326 or upload to one of these sites:
1327
1328    https://pause.kbx.de/pause/
1329    http://pause.perl.org/pause/
1330
1331 and notify <modules@perl.org>.
1332
1333 By using the WWW interface you can ask the Upload Server to mirror
1334 your modules from your ftp or WWW site into your own directory on
1335 CPAN!
1336
1337 Please remember to send me an updated entry for the Module list!
1338
1339 =item Take care when changing a released module.
1340
1341 Always strive to remain compatible with previous released versions.
1342 Otherwise try to add a mechanism to revert to the
1343 old behavior if people rely on it.  Document incompatible changes.
1344
1345 =back
1346
1347 =back
1348
1349 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1350
1351 =over 4
1352
1353 =item There is no requirement to convert anything.
1354
1355 If it ain't broke, don't fix it! Perl 4 library scripts should
1356 continue to work with no problems. You may need to make some minor
1357 changes (like escaping non-array @'s in double quoted strings) but
1358 there is no need to convert a .pl file into a Module for just that.
1359
1360 =item Consider the implications.
1361
1362 All Perl applications that make use of the script will need to
1363 be changed (slightly) if the script is converted into a module.  Is
1364 it worth it unless you plan to make other changes at the same time?
1365
1366 =item Make the most of the opportunity.
1367
1368 If you are going to convert the script to a module you can use the
1369 opportunity to redesign the interface.  The guidelines for module
1370 creation above include many of the issues you should consider.
1371
1372 =item The pl2pm utility will get you started.
1373
1374 This utility will read *.pl files (given as parameters) and write
1375 corresponding *.pm files. The pl2pm utilities does the following:
1376
1377 =over 10
1378
1379 =item *
1380 Adds the standard Module prologue lines
1381
1382 =item *
1383 Converts package specifiers from ' to ::
1384
1385 =item *
1386 Converts die(...) to croak(...)
1387
1388 =item *
1389 Several other minor changes
1390
1391 =back
1392
1393 Being a mechanical process pl2pm is not bullet proof. The converted
1394 code will need careful checking, especially any package statements.
1395 Don't delete the original .pl file till the new .pm one works!
1396
1397 =back
1398
1399 =head2 Guidelines for Reusing Application Code
1400
1401 =over 4
1402
1403 =item Complete applications rarely belong in the Perl Module Library.
1404
1405 =item Many applications contain some Perl code that could be reused.
1406
1407 Help save the world! Share your code in a form that makes it easy
1408 to reuse.
1409
1410 =item Break-out the reusable code into one or more separate module files.
1411
1412 =item Take the opportunity to reconsider and redesign the interfaces.
1413
1414 =item In some cases the 'application' can then be reduced to a small
1415
1416 fragment of code built on top of the reusable modules. In these cases
1417 the application could invoked as:
1418
1419      % perl -e 'use Module::Name; method(@ARGV)' ...
1420 or
1421      % perl -mModule::Name ...    (in perl5.002 or higher)
1422
1423 =back
1424
1425 =head1 NOTE
1426
1427 Perl does not enforce private and public parts of its modules as you may
1428 have been used to in other languages like C++, Ada, or Modula-17.  Perl
1429 doesn't have an infatuation with enforced privacy.  It would prefer
1430 that you stayed out of its living room because you weren't invited, not
1431 because it has a shotgun.
1432
1433 The module and its user have a contract, part of which is common law,
1434 and part of which is "written".  Part of the common law contract is
1435 that a module doesn't pollute any namespace it wasn't asked to.  The
1436 written contract for the module (A.K.A. documentation) may make other
1437 provisions.  But then you know when you C<use RedefineTheWorld> that
1438 you're redefining the world and willing to take the consequences.