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 A number of modules are included the Perl distribution.  These are
  10 described below, and all end in F<.pm>.  You may also discover files in
  11 the library directory that end in either F<.pl> or F<.ph>.  These are old
  12 libraries supplied so that old programs that use them still run.  The
  13 F<.pl> files will all eventually be converted into standard modules, and
  14 the F<.ph> files made by B<h2ph> will probably end up as extension modules
  15 made by B<h2xs>.  (Some F<.ph> values may already be available through the
  16 POSIX module.)  The B<pl2pm> file in the distribution may help in your
  17 conversion, but it's just a mechanical process and therefore far from
  18 bulletproof.
  19
  20 =head2 Pragmatic Modules
  21
  22 They work somewhat like pragmas in that they tend to affect the compilation of
  23 your program, and thus will usually work well only when used within a
  24 C<use>, or C<no>.  Most of these are lexically scoped, so an inner BLOCK
  25 may countermand any of these by saying:
  26
  27     no integer;
  28     no strict 'refs';
  29
  30 which lasts until the end of that BLOCK.
  31
  32 Unlike the pragmas that effect the C<$^H> hints variable, the C<use
  33 vars> and C<use subs> declarations are not BLOCK-scoped.  They allow
  34 you to predeclare a variables or subroutines within a particular
  35 I<file> rather than just a block.  Such declarations are effective
  36 for the entire file for which they were declared.  You cannot rescind
  37 them with C<no vars> or C<no subs>.
  38
  39 The following pragmas are defined (and have their own documentation).
  40
  41 =over 12
  42
  43 =item use autouse MODULE => qw(sub1 sub2 sub3)
  44
  45 Defers C<require MODULE> until someone calls one of the specified
  46 subroutines (which must be exported by MODULE).  This pragma should be
  47 used with caution, and only when necessary.
  48
  49 =item blib
  50
  51 manipulate @INC at compile time to use MakeMaker's uninstalled version
  52 of a package
  53
  54 =item diagnostics
  55
  56 force verbose warning diagnostics
  57
  58 =item integer
  59
  60 compute arithmetic in integer instead of double
  61
  62 =item less
  63
  64 request less of something from the compiler
  65
  66 =item lib
  67
  68 manipulate @INC at compile time
  69
  70 =item locale
  71
  72 use or ignore current locale for builtin operations (see L<perllocale>)
  73
  74 =item ops
  75
  76 restrict named opcodes when compiling or running Perl code
  77
  78 =item overload
  79
  80 overload basic Perl operations
  81
  82 =item re
  83
  84 alter behaviour of regular expressions
  85
  86 =item sigtrap
  87
  88 enable simple signal handling
  89
  90 =item strict
  91
  92 restrict unsafe constructs
  93
  94 =item subs
  95
  96 predeclare sub names
  97
  98 =item vmsish
  99
 100 adopt certain VMS-specific behaviors
 101
 102 =item vars
 103
 104 predeclare global variable names
 105
 106 =back
 107
 108 =head2 Standard Modules
 109
 110 Standard, bundled modules are all expected to behave in a well-defined
 111 manner with respect to namespace pollution because they use the
 112 Exporter module.  See their own documentation for details.
 113
 114 =over 12
 115
 116 =item AnyDBM_File
 117
 118 provide framework for multiple DBMs
 119
 120 =item AutoLoader
 121
 122 load functions only on demand
 123
 124 =item AutoSplit
 125
 126 split a package for autoloading
 127
 128 =item Benchmark
 129
 130 benchmark running times of code
 131
 132 =item CPAN
 133
 134 interface to Comprehensive Perl Archive Network
 135
 136 =item CPAN::FirstTime
 137
 138 create a CPAN configuration file
 139
 140 =item CPAN::Nox
 141
 142 run CPAN while avoiding compiled extensions
 143
 144 =item Carp
 145
 146 warn of errors (from perspective of caller)
 147
 148 =item Class::Struct
 149
 150 declare struct-like datatypes
 151
 152 =item Config
 153
 154 access Perl configuration information
 155
 156 =item Cwd
 157
 158 get pathname of current working directory
 159
 160 =item DB_File
 161
 162 access to Berkeley DB
 163
 164 =item Devel::Peek
 165
 166 data debugging tool for the XS programmer
 167
 168 =item Devel::SelfStubber
 169
 170 generate stubs for a SelfLoading module
 171
 172 =item DirHandle
 173
 174 supply object methods for directory handles
 175
 176 =item DynaLoader
 177
 178 dynamically load C libraries into Perl code
 179
 180 =item English
 181
 182 use nice English (or awk) names for ugly punctuation variables
 183
 184 =item Env
 185
 186 import environment variables
 187
 188 =item Exporter
 189
 190 implements default import method for modules
 191
 192 =item ExtUtils::Embed
 193
 194 utilities for embedding Perl in C/C++ applications
 195
 196 =item ExtUtils::Install
 197
 198 install files from here to there
 199
 200 =item ExtUtils::Liblist
 201
 202 determine libraries to use and how to use them
 203
 204 =item ExtUtils::MM_OS2
 205
 206 methods to override Unix behaviour in ExtUtils::MakeMaker
 207
 208 =item ExtUtils::MM_Unix
 209
 210 methods used by ExtUtils::MakeMaker
 211
 212 =item ExtUtils::MM_VMS
 213
 214 methods to override Unix behaviour in ExtUtils::MakeMaker
 215
 216 =item ExtUtils::MakeMaker
 217
 218 create an extension Makefile
 219
 220 =item ExtUtils::Manifest
 221
 222 utilities to write and check a MANIFEST file
 223
 224 =item ExtUtils::Mkbootstrap
 225
 226 make a bootstrap file for use by DynaLoader
 227
 228 =item ExtUtils::Mksymlists
 229
 230 write linker options files for dynamic extension
 231
 232 =item ExtUtils::testlib
 233
 234 add blib/* directories to @INC
 235
 236 =item Fatal
 237
 238 make errors in builtins or Perl functions fatal
 239
 240 =item Fcntl
 241
 242 load the C Fcntl.h defines
 243
 244 =item File::Basename
 245
 246 split a pathname into pieces
 247
 248 =item File::CheckTree
 249
 250 run many filetest checks on a tree
 251
 252 =item File::Compare
 253
 254 compare files or filehandles
 255
 256 =item File::Copy
 257
 258 copy files or filehandles
 259
 260 =item File::Find
 261
 262 traverse a file tree
 263
 264 =item File::Path
 265
 266 create or remove a series of directories
 267
 268 =item File::Spec
 269
 270 portably perform operations on file names
 271
 272 =item File::Spec::Functions
 273
 274 function call interface to File::Spec module
 275
 276 =item File::stat
 277
 278 by-name interface to Perl's builtin stat() functions
 279
 280 =item FileCache
 281
 282 keep more files open than the system permits
 283
 284 =item FileHandle
 285
 286 supply object methods for filehandles
 287
 288 =item FindBin
 289
 290 locate directory of original Perl script
 291
 292 =item GDBM_File
 293
 294 access to the gdbm library
 295
 296 =item Getopt::Long
 297
 298 extended processing of command line options
 299
 300 =item Getopt::Std
 301
 302 process single-character switches with switch clustering
 303
 304 =item I18N::Collate
 305
 306 compare 8-bit scalar data according to the current locale
 307
 308 =item IO
 309
 310 load various IO modules
 311
 312 =item IO::File
 313
 314 supply object methods for filehandles
 315
 316 =item IO::Handle
 317
 318 supply object methods for I/O handles
 319
 320 =item IO::Pipe
 321
 322 supply object methods for pipes
 323
 324 =item IO::Seekable
 325
 326 supply seek based methods for I/O objects
 327
 328 =item IO::Select
 329
 330 OO interface to the select system call
 331
 332 =item IO::Socket
 333
 334 object interface to socket communications
 335
 336 =item IPC::Open2
 337
 338 open a process for both reading and writing
 339
 340 =item IPC::Open3
 341
 342 open a process for reading, writing, and error handling
 343
 344 =item Math::BigFloat
 345
 346 arbitrary length float math package
 347
 348 =item Math::BigInt
 349
 350 arbitrary size integer math package
 351
 352 =item Math::Complex
 353
 354 complex numbers and associated mathematical functions
 355
 356 =item Math::Trig
 357
 358 simple interface to parts of Math::Complex for those who
 359 need trigonometric functions only for real numbers
 360
 361 =item NDBM_File
 362
 363 tied access to ndbm files
 364
 365 =item Net::Ping
 366
 367 Hello, anybody home?
 368
 369 =item Net::hostent
 370
 371 by-name interface to Perl's builtin gethost*() functions
 372
 373 =item Net::netent
 374
 375 by-name interface to Perl's builtin getnet*() functions
 376
 377 =item Net::protoent
 378
 379 by-name interface to Perl's builtin getproto*() functions
 380
 381 =item Net::servent
 382
 383 by-name interface to Perl's builtin getserv*() functions
 384
 385 =item Opcode
 386
 387 disable named opcodes when compiling or running Perl code
 388
 389 =item Pod::Text
 390
 391 convert POD data to formatted ASCII text
 392
 393 =item POSIX
 394
 395 interface to IEEE Standard 1003.1
 396
 397 =item SDBM_File
 398
 399 tied access to sdbm files
 400
 401 =item Safe
 402
 403 compile and execute code in restricted compartments
 404
 405 =item Search::Dict
 406
 407 search for key in dictionary file
 408
 409 =item SelectSaver
 410
 411 save and restore selected file handle
 412
 413 =item SelfLoader
 414
 415 load functions only on demand
 416
 417 =item Shell
 418
 419 run shell commands transparently within Perl
 420
 421 =item Socket
 422
 423 load the C socket.h defines and structure manipulators
 424
 425 =item Symbol
 426
 427 manipulate Perl symbols and their names
 428
 429 =item Sys::Hostname
 430
 431 try every conceivable way to get hostname
 432
 433 =item Sys::Syslog
 434
 435 interface to the Unix syslog(3) calls
 436
 437 =item Term::Cap
 438
 439 termcap interface
 440
 441 =item Term::Complete
 442
 443 word completion module
 444
 445 =item Term::ReadLine
 446
 447 interface to various C<readline> packages
 448
 449 =item Test::Harness
 450
 451 run Perl standard test scripts with statistics
 452
 453 =item Text::Abbrev
 454
 455 create an abbreviation table from a list
 456
 457 =item Text::ParseWords
 458
 459 parse text into an array of tokens
 460
 461 =item Text::Soundex
 462
 463 implementation of the Soundex Algorithm as described by Knuth
 464
 465 =item Text::Tabs
 466
 467 expand and unexpand tabs per the Unix expand(1) and unexpand(1)
 468
 469 =item Text::Wrap
 470
 471 line wrapping to form simple paragraphs
 472
 473 =item Tie::Hash
 474
 475 base class definitions for tied hashes
 476
 477 =item Tie::RefHash
 478
 479 base class definitions for tied hashes with references as keys
 480
 481 =item Tie::Scalar
 482
 483 base class definitions for tied scalars
 484
 485 =item Tie::SubstrHash
 486
 487 fixed-table-size, fixed-key-length hashing
 488
 489 =item Time::Local
 490
 491 efficiently compute time from local and GMT time
 492
 493 =item Time::gmtime
 494
 495 by-name interface to Perl's builtin gmtime() function
 496
 497 =item Time::localtime
 498
 499 by-name interface to Perl's builtin localtime() function
 500
 501 =item Time::tm
 502
 503 internal object used by Time::gmtime and Time::localtime
 504
 505 =item UNIVERSAL
 506
 507 base class for ALL classes (blessed references)
 508
 509 =item User::grent
 510
 511 by-name interface to Perl's builtin getgr*() functions
 512
 513 =item User::pwent
 514
 515 by-name interface to Perl's builtin getpw*() functions
 516
 517 =back
 518
 519 To find out I<all> the modules installed on your system, including
 520 those without documentation or outside the standard release, do this:
 521
 522     % find `perl -e 'print "@INC"'` -name '*.pm' -print
 523
 524 They should all have their own documentation installed and accessible via
 525 your system man(1) command.  If that fails, try the I<perldoc> program.
 526
 527 =head2 Extension Modules
 528
 529 Extension modules are written in C (or a mix of Perl and C) and may be
 530 statically linked or in general are
 531 dynamically loaded into Perl if and when you need them.  Supported
 532 extension modules include the Socket, Fcntl, and POSIX modules.
 533
 534 Many popular C extension modules do not come bundled (at least, not
 535 completely) due to their sizes, volatility, or simply lack of time for
 536 adequate testing and configuration across the multitude of platforms on
 537 which Perl was beta-tested.  You are encouraged to look for them in
 538 archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
 539 authors before randomly posting asking for their present condition and
 540 disposition.
 541
 542 =head1 CPAN
 543
 544 CPAN stands for the Comprehensive Perl Archive Network.  This is a globally
 545 replicated collection of all known Perl materials, including hundreds
 546 of unbundled modules.  Here are the major categories of modules:
 547
 548 =over
 549
 550 =item *
 551 Language Extensions and Documentation Tools
 552
 553 =item *
 554 Development Support
 555
 556 =item *
 557 Operating System Interfaces
 558
 559 =item *
 560 Networking, Device Control (modems) and InterProcess Communication
 561
 562 =item *
 563 Data Types and Data Type Utilities
 564
 565 =item *
 566 Database Interfaces
 567
 568 =item *
 569 User Interfaces
 570
 571 =item *
 572 Interfaces to / Emulations of Other Programming Languages
 573
 574 =item *
 575 File Names, File Systems and File Locking (see also File Handles)
 576
 577 =item *
 578 String Processing, Language Text Processing, Parsing, and Searching
 579
 580 =item *
 581 Option, Argument, Parameter, and Configuration File Processing
 582
 583 =item *
 584 Internationalization and Locale
 585
 586 =item *
 587 Authentication, Security, and Encryption
 588
 589 =item *
 590 World Wide Web, HTML, HTTP, CGI, MIME
 591
 592 =item *
 593 Server and Daemon Utilities
 594
 595 =item *
 596 Archiving and Compression
 597
 598 =item *
 599 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
 600
 601 =item *
 602 Mail and Usenet News
 603
 604 =item *
 605 Control Flow Utilities (callbacks and exceptions etc)
 606
 607 =item *
 608 File Handle and Input/Output Stream Utilities
 609
 610 =item *
 611 Miscellaneous Modules
 612
 613 =back
 614
 615 The registered CPAN sites as of this writing include the following.
 616 You should try to choose one close to you:
 617
 618 =over
 619
 620 =item *
 621 Africa
 622
 623    South Africa    ftp://ftp.is.co.za/programming/perl/CPAN/
 624                    ftp://ftpza.co.za/pub/mirrors/cpan/
 625
 626 =item *
 627 Asia
 628
 629    Armenia         ftp://sunsite.aua.am/pub/CPAN/
 630    China           ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
 631    Hong Kong       ftp://ftp.hkstar.com/pub/CPAN/
 632    Israel          ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
 633    Japan           ftp://ftp.dti.ad.jp/pub/lang/CPAN/
 634                    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
 635                    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
 636                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
 637                    ftp://mirror.nucba.ac.jp/mirror/Perl/
 638    Singapore       ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
 639    South Korea     ftp://ftp.bora.net/pub/CPAN/
 640                    ftp://ftp.nuri.net/pub/CPAN/
 641    Taiwan          ftp://ftp.wownet.net/pub2/PERL/
 642                    ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
 643    Thailand        ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
 644                    ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
 645
 646 =item *
 647 Australasia
 648
 649    Australia       ftp://cpan.topend.com.au/pub/CPAN/
 650                    ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
 651                    ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
 652                    ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
 653    New Zealand     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
 654                    ftp://sunsite.net.nz/pub/languages/perl/CPAN/
 655
 656 =item *
 657 Central America
 658
 659    Costa Rica      ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
 660
 661 =item *
 662 Europe
 663
 664    Austria         ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
 665    Belgium         ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
 666    Bulgaria        ftp://ftp.ntrl.net/pub/mirrors/CPAN/
 667    Croatia         ftp://ftp.linux.hr/pub/CPAN/
 668    Czech Republic  ftp://ftp.fi.muni.cz/pub/perl/
 669                    ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
 670    Denmark         ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
 671    Estonia         ftp://ftp.ut.ee/pub/languages/perl/CPAN/
 672    Finland         ftp://ftp.funet.fi/pub/languages/perl/CPAN/
 673    France          ftp://ftp.lip6.fr/pub/perl/CPAN/
 674                    ftp://ftp.oleane.net/pub/mirrors/CPAN/
 675                    ftp://ftp.pasteur.fr/pub/computing/CPAN/
 676    Germany         ftp://ftp.archive.de.uu.net/pub/CPAN/
 677                    ftp://ftp.gmd.de/packages/CPAN/
 678                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
 679                    ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/
 680                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
 681                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
 682                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
 683                    ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
 684    Greece          ftp://ftp.ntua.gr/pub/lang/perl/
 685    Hungary         ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
 686    Ireland         ftp://sunsite.compapp.dcu.ie/pub/perl/
 687    Italy           ftp://cis.uniRoma2.it/CPAN/
 688                    ftp://ftp.flashnet.it/pub/CPAN/
 689                    ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
 690    Netherlands     ftp://ftp.cs.uu.nl/mirror/CPAN/
 691                    ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
 692    Norway          ftp://ftp.uit.no/pub/languages/perl/cpan/
 693                    ftp://sunsite.uio.no/pub/languages/perl/CPAN/
 694    Poland          ftp://ftp.man.szczecin.pl/pub/perl/CPAN/
 695                    ftp://ftp.man.torun.pl/pub/doc/CPAN/
 696                    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
 697                    ftp://sunsite.icm.edu.pl/pub/CPAN/
 698    Portugal        ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
 699                    ftp://ftp.ua.pt/pub/CPAN/
 700    Romania         ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
 701                    ftp://ftp.dnttm.ro/pub/CPAN/
 702    Russia          ftp://cpan.npi.msu.su/CPAN/
 703                    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
 704    Slovakia        ftp://ftp.entry.sk/pub/languages/perl/CPAN/
 705    Slovenia        ftp://ftp.arnes.si/software/perl/CPAN/
 706    Spain           ftp://ftp.etse.urv.es/pub/perl/
 707                    ftp://ftp.rediris.es/mirror/CPAN/
 708    Sweden          ftp://ftp.sunet.se/pub/lang/perl/CPAN/
 709    Switzerland     ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
 710    Turkey          ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
 711    United Kingdom  ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
 712                    ftp://ftp.flirble.org/pub/languages/perl/CPAN/
 713                    ftp://ftp.plig.org/pub/CPAN/
 714                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
 715                    ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
 716
 717 =item *
 718 North America
 719
 720    Alberta         ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
 721    California      ftp://ftp.cdrom.com/pub/perl/CPAN/
 722                    ftp://ftp.digital.com/pub/plan/perl/CPAN/
 723    Colorado        ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
 724    Florida         ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
 725    Illinois        ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
 726    Indiana         ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
 727                    ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
 728    Manitoba        ftp://theory.uwinnipeg.ca/pub/CPAN/
 729    Massachusetts   ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
 730                    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
 731    Mexico D.F.     ftp://ftp.msg.com.mx/pub/CPAN/
 732    New York        ftp://ftp.rge.com/pub/languages/perl/
 733    North Carolina  ftp://ftp.duke.edu/pub/perl/
 734    Oklahoma        ftp://ftp.ou.edu/mirrors/CPAN/
 735    Ontario         ftp://ftp.crc.ca/pub/packages/perl/CPAN/
 736    Oregon          ftp://ftp.orst.edu/pub/packages/CPAN/
 737    Pennsylvania    ftp://ftp.epix.net/pub/languages/perl/
 738    Texas           ftp://ftp.sedl.org/pub/mirrors/CPAN/
 739    Utah            ftp://mirror.xmission.com/CPAN/
 740    Virginia        ftp://ftp.perl.org/pub/perl/CPAN/
 741                    ftp://ruff.cs.jmu.edu/pub/CPAN/
 742    Washington      ftp://ftp.spu.edu/pub/CPAN/
 743
 744 =item *
 745 South America
 746
 747    Brazil          ftp://cpan.if.usp.br/pub/mirror/CPAN/
 748    Chile           ftp://ftp.ing.puc.cl/pub/unix/perl/CPAN/
 749                    ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
 750
 751 =back
 752
 753 For an up-to-date listing of CPAN sites,
 754 see F<http://www.perl.com/perl/CPAN> or F<ftp://ftp.perl.com/perl/>.
 755
 756 =head1 Modules: Creation, Use, and Abuse
 757
 758 (The following section is borrowed directly from Tim Bunce's modules
 759 file, available at your nearest CPAN site.)
 760
 761 Perl implements a class using a package, but the presence of a
 762 package doesn't imply the presence of a class.  A package is just a
 763 namespace.  A class is a package that provides subroutines that can be
 764 used as methods.  A method is just a subroutine that expects, as its
 765 first argument, either the name of a package (for "static" methods),
 766 or a reference to something (for "virtual" methods).
 767
 768 A module is a file that (by convention) provides a class of the same
 769 name (sans the .pm), plus an import method in that class that can be
 770 called to fetch exported symbols.  This module may implement some of
 771 its methods by loading dynamic C or C++ objects, but that should be
 772 totally transparent to the user of the module.  Likewise, the module
 773 might set up an AUTOLOAD function to slurp in subroutine definitions on
 774 demand, but this is also transparent.  Only the F<.pm> file is required to
 775 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
 776 the AUTOLOAD mechanism.
 777
 778 =head2 Guidelines for Module Creation
 779
 780 =over 4
 781
 782 =item Do similar modules already exist in some form?
 783
 784 If so, please try to reuse the existing modules either in whole or
 785 by inheriting useful features into a new class.  If this is not
 786 practical try to get together with the module authors to work on
 787 extending or enhancing the functionality of the existing modules.
 788 A perfect example is the plethora of packages in perl4 for dealing
 789 with command line options.
 790
 791 If you are writing a module to expand an already existing set of
 792 modules, please coordinate with the author of the package.  It
 793 helps if you follow the same naming scheme and module interaction
 794 scheme as the original author.
 795
 796 =item Try to design the new module to be easy to extend and reuse.
 797
 798 Use blessed references.  Use the two argument form of bless to bless
 799 into the class name given as the first parameter of the constructor,
 800 e.g.,:
 801
 802  sub new {
 803         my $class = shift;
 804         return bless {}, $class;
 805  }
 806
 807 or even this if you'd like it to be used as either a static
 808 or a virtual method.
 809
 810  sub new {
 811         my $self  = shift;
 812         my $class = ref($self) || $self;
 813         return bless {}, $class;
 814  }
 815
 816 Pass arrays as references so more parameters can be added later
 817 (it's also faster).  Convert functions into methods where
 818 appropriate.  Split large methods into smaller more flexible ones.
 819 Inherit methods from other modules if appropriate.
 820
 821 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
 822 Generally you can delete the "C<eq 'FOO'>" part with no harm at all.
 823 Let the objects look after themselves! Generally, avoid hard-wired
 824 class names as far as possible.
 825
 826 Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
 827 C<$r-E<gt>func()> would work (see L<perlbot> for more details).
 828
 829 Use autosplit so little used or newly added functions won't be a
 830 burden to programs that don't use them. Add test functions to
 831 the module after __END__ either using AutoSplit or by saying:
 832
 833  eval join('',<main::DATA>) || die $@ unless caller();
 834
 835 Does your module pass the 'empty subclass' test? If you say
 836 "C<@SUBCLASS::ISA = qw(YOURCLASS);>" your applications should be able
 837 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
 838 does your application still work if you change:  C<$obj = new YOURCLASS;>
 839 into: C<$obj = new SUBCLASS;> ?
 840
 841 Avoid keeping any state information in your packages. It makes it
 842 difficult for multiple other packages to use yours. Keep state
 843 information in objects.
 844
 845 Always use B<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
 846 Remember that you can add C<no strict qw(...);> to individual blocks
 847 of code that need less strictness. Always use B<-w>. Always use B<-w>!
 848 Follow the guidelines in the perlstyle(1) manual.
 849
 850 =item Some simple style guidelines
 851
 852 The perlstyle manual supplied with Perl has many helpful points.
 853
 854 Coding style is a matter of personal taste. Many people evolve their
 855 style over several years as they learn what helps them write and
 856 maintain good code.  Here's one set of assorted suggestions that
 857 seem to be widely used by experienced developers:
 858
 859 Use underscores to separate words.  It is generally easier to read
 860 $var_names_like_this than $VarNamesLikeThis, especially for
 861 non-native speakers of English. It's also a simple rule that works
 862 consistently with VAR_NAMES_LIKE_THIS.
 863
 864 Package/Module names are an exception to this rule. Perl informally
 865 reserves lowercase module names for 'pragma' modules like integer
 866 and strict. Other modules normally begin with a capital letter and
 867 use mixed case with no underscores (need to be short and portable).
 868
 869 You may find it helpful to use letter case to indicate the scope
 870 or nature of a variable. For example:
 871
 872  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
 873  $Some_Caps_Here  package-wide global/static
 874  $no_caps_here    function scope my() or local() variables
 875
 876 Function and method names seem to work best as all lowercase.
 877 e.g., C<$obj-E<gt>as_string()>.
 878
 879 You can use a leading underscore to indicate that a variable or
 880 function should not be used outside the package that defined it.
 881
 882 =item Select what to export.
 883
 884 Do NOT export method names!
 885
 886 Do NOT export anything else by default without a good reason!
 887
 888 Exports pollute the namespace of the module user.  If you must
 889 export try to use @EXPORT_OK in preference to @EXPORT and avoid
 890 short or common names to reduce the risk of name clashes.
 891
 892 Generally anything not exported is still accessible from outside the
 893 module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
 894 syntax.  By convention you can use a leading underscore on names to
 895 indicate informally that they are 'internal' and not for public use.
 896
 897 (It is actually possible to get private functions by saying:
 898 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
 899 directly as a method, because a method must have a name in the symbol
 900 table.)
 901
 902 As a general rule, if the module is trying to be object oriented
 903 then export nothing. If it's just a collection of functions then
 904 @EXPORT_OK anything but use @EXPORT with caution.
 905
 906 =item Select a name for the module.
 907
 908 This name should be as descriptive, accurate, and complete as
 909 possible.  Avoid any risk of ambiguity. Always try to use two or
 910 more whole words.  Generally the name should reflect what is special
 911 about what the module does rather than how it does it.  Please use
 912 nested module names to group informally or categorize a module.
 913 There should be a very good reason for a module not to have a nested name.
 914 Module names should begin with a capital letter.
 915
 916 Having 57 modules all called Sort will not make life easy for anyone
 917 (though having 23 called Sort::Quick is only marginally better :-).
 918 Imagine someone trying to install your module alongside many others.
 919 If in any doubt ask for suggestions in comp.lang.perl.misc.
 920
 921 If you are developing a suite of related modules/classes it's good
 922 practice to use nested classes with a common prefix as this will
 923 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
 924 Xyz::Model etc. Use the modules in this list as a naming guide.
 925
 926 If adding a new module to a set, follow the original author's
 927 standards for naming modules and the interface to methods in
 928 those modules.
 929
 930 To be portable each component of a module name should be limited to
 931 11 characters. If it might be used on MS-DOS then try to ensure each is
 932 unique in the first 8 characters. Nested modules make this easier.
 933
 934 =item Have you got it right?
 935
 936 How do you know that you've made the right decisions? Have you
 937 picked an interface design that will cause problems later? Have
 938 you picked the most appropriate name? Do you have any questions?
 939
 940 The best way to know for sure, and pick up many helpful suggestions,
 941 is to ask someone who knows. Comp.lang.perl.misc is read by just about
 942 all the people who develop modules and it's the best place to ask.
 943
 944 All you need to do is post a short summary of the module, its
 945 purpose and interfaces. A few lines on each of the main methods is
 946 probably enough. (If you post the whole module it might be ignored
 947 by busy people - generally the very people you want to read it!)
 948
 949 Don't worry about posting if you can't say when the module will be
 950 ready - just say so in the message. It might be worth inviting
 951 others to help you, they may be able to complete it for you!
 952
 953 =item README and other Additional Files.
 954
 955 It's well known that software developers usually fully document the
 956 software they write. If, however, the world is in urgent need of
 957 your software and there is not enough time to write the full
 958 documentation please at least provide a README file containing:
 959
 960 =over 10
 961
 962 =item *
 963 A description of the module/package/extension etc.
 964
 965 =item *
 966 A copyright notice - see below.
 967
 968 =item *
 969 Prerequisites - what else you may need to have.
 970
 971 =item *
 972 How to build it - possible changes to Makefile.PL etc.
 973
 974 =item *
 975 How to install it.
 976
 977 =item *
 978 Recent changes in this release, especially incompatibilities
 979
 980 =item *
 981 Changes / enhancements you plan to make in the future.
 982
 983 =back
 984
 985 If the README file seems to be getting too large you may wish to
 986 split out some of the sections into separate files: INSTALL,
 987 Copying, ToDo etc.
 988
 989 =over 4
 990
 991 =item Adding a Copyright Notice.
 992
 993 How you choose to license your work is a personal decision.
 994 The general mechanism is to assert your Copyright and then make
 995 a declaration of how others may copy/use/modify your work.
 996
 997 Perl, for example, is supplied with two types of licence: The GNU
 998 GPL and The Artistic Licence (see the files README, Copying, and
 999 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
1000
1001 My personal recommendation, out of respect for Larry, Perl, and the
1002 Perl community at large is to state something simply like:
1003
1004  Copyright (c) 1995 Your Name. All rights reserved.
1005  This program is free software; you can redistribute it and/or
1006  modify it under the same terms as Perl itself.
1007
1008 This statement should at least appear in the README file. You may
1009 also wish to include it in a Copying file and your source files.
1010 Remember to include the other words in addition to the Copyright.
1011
1012 =item Give the module a version/issue/release number.
1013
1014 To be fully compatible with the Exporter and MakeMaker modules you
1015 should store your module's version number in a non-my package
1016 variable called $VERSION.  This should be a floating point
1017 number with at least two digits after the decimal (i.e., hundredths,
1018 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
1019 See Exporter.pm in Perl5.001m or later for details.
1020
1021 It may be handy to add a function or method to retrieve the number.
1022 Use the number in announcements and archive file names when
1023 releasing the module (ModuleName-1.02.tar.Z).
1024 See perldoc ExtUtils::MakeMaker.pm for details.
1025
1026 =item How to release and distribute a module.
1027
1028 It's good idea to post an announcement of the availability of your
1029 module (or the module itself if small) to the comp.lang.perl.announce
1030 Usenet newsgroup.  This will at least ensure very wide once-off
1031 distribution.
1032
1033 If possible you should place the module into a major ftp archive and
1034 include details of its location in your announcement.
1035
1036 Some notes about ftp archives: Please use a long descriptive file
1037 name that includes the version number. Most incoming directories
1038 will not be readable/listable, i.e., you won't be able to see your
1039 file after uploading it. Remember to send your email notification
1040 message as soon as possible after uploading else your file may get
1041 deleted automatically. Allow time for the file to be processed
1042 and/or check the file has been processed before announcing its
1043 location.
1044
1045 FTP Archives for Perl Modules:
1046
1047 Follow the instructions and links on
1048
1049    http://franz.ww.tu-berlin.de/modulelist
1050
1051 or upload to one of these sites:
1052
1053    ftp://franz.ww.tu-berlin.de/incoming
1054    ftp://ftp.cis.ufl.edu/incoming
1055
1056 and notify <F<upload@franz.ww.tu-berlin.de>>.
1057
1058 By using the WWW interface you can ask the Upload Server to mirror
1059 your modules from your ftp or WWW site into your own directory on
1060 CPAN!
1061
1062 Please remember to send me an updated entry for the Module list!
1063
1064 =item Take care when changing a released module.
1065
1066 Always strive to remain compatible with previous released versions.
1067 Otherwise try to add a mechanism to revert to the
1068 old behaviour if people rely on it. Document incompatible changes.
1069
1070 =back
1071
1072 =back
1073
1074 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1075
1076 =over 4
1077
1078 =item There is no requirement to convert anything.
1079
1080 If it ain't broke, don't fix it! Perl 4 library scripts should
1081 continue to work with no problems. You may need to make some minor
1082 changes (like escaping non-array @'s in double quoted strings) but
1083 there is no need to convert a .pl file into a Module for just that.
1084
1085 =item Consider the implications.
1086
1087 All Perl applications that make use of the script will need to
1088 be changed (slightly) if the script is converted into a module.  Is
1089 it worth it unless you plan to make other changes at the same time?
1090
1091 =item Make the most of the opportunity.
1092
1093 If you are going to convert the script to a module you can use the
1094 opportunity to redesign the interface. The 'Guidelines for Module
1095 Creation' above include many of the issues you should consider.
1096
1097 =item The pl2pm utility will get you started.
1098
1099 This utility will read *.pl files (given as parameters) and write
1100 corresponding *.pm files. The pl2pm utilities does the following:
1101
1102 =over 10
1103
1104 =item *
1105 Adds the standard Module prologue lines
1106
1107 =item *
1108 Converts package specifiers from ' to ::
1109
1110 =item *
1111 Converts die(...) to croak(...)
1112
1113 =item *
1114 Several other minor changes
1115
1116 =back
1117
1118 Being a mechanical process pl2pm is not bullet proof. The converted
1119 code will need careful checking, especially any package statements.
1120 Don't delete the original .pl file till the new .pm one works!
1121
1122 =back
1123
1124 =head2 Guidelines for Reusing Application Code
1125
1126 =over 4
1127
1128 =item Complete applications rarely belong in the Perl Module Library.
1129
1130 =item Many applications contain some Perl code that could be reused.
1131
1132 Help save the world! Share your code in a form that makes it easy
1133 to reuse.
1134
1135 =item Break-out the reusable code into one or more separate module files.
1136
1137 =item Take the opportunity to reconsider and redesign the interfaces.
1138
1139 =item In some cases the 'application' can then be reduced to a small
1140
1141 fragment of code built on top of the reusable modules. In these cases
1142 the application could invoked as:
1143
1144      % perl -e 'use Module::Name; method(@ARGV)' ...
1145 or
1146      % perl -mModule::Name ...    (in perl5.002 or higher)
1147
1148 =back
1149
1150 =head1 NOTE
1151
1152 Perl does not enforce private and public parts of its modules as you may
1153 have been used to in other languages like C++, Ada, or Modula-17.  Perl
1154 doesn't have an infatuation with enforced privacy.  It would prefer
1155 that you stayed out of its living room because you weren't invited, not
1156 because it has a shotgun.
1157
1158 The module and its user have a contract, part of which is common law,
1159 and part of which is "written".  Part of the common law contract is
1160 that a module doesn't pollute any namespace it wasn't asked to.  The
1161 written contract for the module (A.K.A. documentation) may make other
1162 provisions.  But then you know when you C<use RedefineTheWorld> that
1163 you're redefining the world and willing to take the consequences.