pod/perlmodlib.PL

   1 #!../miniperl
   2
   3 open (OUT, ">perlmodlib.tmp") or die $!;
   4 my (@pragma, @mod);
   5 open (MANIFEST, "../MANIFEST") or die $!;
   6
   7 while (<MANIFEST>) {
   8      my $filename;
   9      next unless s|^lib/|| or m|^ext/|;
  10      ($filename) = /(\S+)/;
  11      $filename =~ s|^[^/]+/|| if $filename =~ s|^ext/||;
  12      next unless $filename =~ /\.pm$/;
  13      next unless open (MOD, "../lib/$filename");
  14      my ($name, $thing);
  15      my $foundit=0;
  16      {local $/="";
  17      while (<MOD>) {
  18           next unless /^=head1 NAME/;
  19           $foundit++;
  20           last;
  21      }
  22      }
  23      next unless $foundit;
  24      my $title = <MOD>;
  25      chomp($title);
  26      close MOD;
  27
  28      my $perlname = $filename;
  29      $perlname =~ s|\.pm$||;
  30      $perlname =~ s|/|::|g;
  31
  32      ($name, $thing) = split / - /, $title,2;
  33      next unless $name and $thing;
  34      $thing=~s/^perl pragma to //i;
  35      $thing=ucfirst($thing);
  36      $title = "=item $perlname\n\n$thing\n\n";
  37
  38      if ($filename=~/[A-Z]/) {
  39           push @mod, $title;
  40      } else {
  41           push @pragma, $title;
  42      }
  43 }
  44
  45 print OUT <<'EOF';
  46 # Generated by perlmodlib.PL  DO NOT EDIT!
  47
  48 =head1 NAME
  49
  50 perlmodlib - constructing new Perl modules and finding existing ones
  51
  52 =head1 DESCRIPTION
  53
  54 =head1 THE PERL MODULE LIBRARY
  55
  56 Many modules are included the Perl distribution.  These are described
  57 below, and all end in F<.pm>.  You may discover compiled library
  58 file (usually ending in F<.so>) or small pieces of modules to be
  59 autoloaded (ending in F<.al>); these were automatically generated
  60 by the installation process.  You may also discover files in the
  61 library directory that end in either F<.pl> or F<.ph>.  These are
  62 old libraries supplied so that old programs that use them still
  63 run.  The F<.pl> files will all eventually be converted into standard
  64 modules, and the F<.ph> files made by B<h2ph> will probably end up
  65 as extension modules made by B<h2xs>.  (Some F<.ph> values may
  66 already be available through the POSIX, Errno, or Fcntl modules.)
  67 The B<pl2pm> file in the distribution may help in your conversion,
  68 but it's just a mechanical process and therefore far from bulletproof.
  69
  70 =head2 Pragmatic Modules
  71
  72 They work somewhat like compiler directives (pragmata) in that they
  73 tend to affect the compilation of your program, and thus will usually
  74 work well only when used within a C<use>, or C<no>.  Most of these
  75 are lexically scoped, so an inner BLOCK may countermand them
  76 by saying:
  77
  78     no integer;
  79     no strict 'refs';
  80     no warnings;
  81
  82 which lasts until the end of that BLOCK.
  83
  84 Some pragmas are lexically scoped--typically those that affect the
  85 C<$^H> hints variable.  Others affect the current package instead,
  86 like C<use vars> and C<use subs>, which allow you to predeclare a
  87 variables or subroutines within a particular I<file> rather than
  88 just a block.  Such declarations are effective for the entire file
  89 for which they were declared.  You cannot rescind them with C<no
  90 vars> or C<no subs>.
  91
  92 The following pragmas are defined (and have their own documentation).
  93
  94 =over 12
  95
  96 EOF
  97
  98 print OUT $_ for (sort @pragma);
  99
 100 print OUT <<EOF;
 101 =back
 102
 103 =head2 Standard Modules
 104
 105 Standard, bundled modules are all expected to behave in a well-defined
 106 manner with respect to namespace pollution because they use the
 107 Exporter module.  See their own documentation for details.
 108
 109 =over 12
 110
 111 EOF
 112
 113 print OUT $_ for (sort @mod);
 114
 115 print OUT <<'EOF';
 116 =back
 117
 118 To find out I<all> modules installed on your system, including
 119 those without documentation or outside the standard release,
 120 just do this:
 121
 122     % find `perl -e 'print "@INC"'` -name '*.pm' -print
 123
 124 They should all have their own documentation installed and accessible
 125 via your system man(1) command.  If you do not have a B<find>
 126 program, you can use the Perl B<find2perl> program instead, which
 127 generates Perl code as output you can run through perl.  If you
 128 have a B<man> program but it doesn't find your modules, you'll have
 129 to fix your manpath.  See L<perl> for details.  If you have no
 130 system B<man> command, you might try the B<perldoc> program.
 131
 132 =head2 Extension Modules
 133
 134 Extension modules are written in C (or a mix of Perl and C).  They
 135 are usually dynamically loaded into Perl if and when you need them,
 136 but may also be be linked in statically.  Supported extension modules
 137 include Socket, Fcntl, and POSIX.
 138
 139 Many popular C extension modules do not come bundled (at least, not
 140 completely) due to their sizes, volatility, or simply lack of time
 141 for adequate testing and configuration across the multitude of
 142 platforms on which Perl was beta-tested.  You are encouraged to
 143 look for them on CPAN (described below), or using web search engines
 144 like Alta Vista or Deja News.
 145
 146 =head1 CPAN
 147
 148 CPAN stands for Comprehensive Perl Archive Network; it's a globally
 149 replicated trove of Perl materials, including documentation, style
 150 guides, tricks and traps, alternate ports to non-Unix systems and
 151 occasional binary distributions for these.   Search engines for
 152 CPAN can be found at http://cpan.perl.com/ and at
 153 http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
 154
 155 Most importantly, CPAN includes around a thousand unbundled modules,
 156 some of which require a C compiler to build.  Major categories of
 157 modules are:
 158
 159 =over
 160
 161 =item *
 162
 163 Language Extensions and Documentation Tools
 164
 165 =item *
 166
 167 Development Support
 168
 169 =item *
 170
 171 Operating System Interfaces
 172
 173 =item *
 174
 175 Networking, Device Control (modems) and InterProcess Communication
 176
 177 =item *
 178
 179 Data Types and Data Type Utilities
 180
 181 =item *
 182
 183 Database Interfaces
 184
 185 =item *
 186
 187 User Interfaces
 188
 189 =item *
 190
 191 Interfaces to / Emulations of Other Programming Languages
 192
 193 =item *
 194
 195 File Names, File Systems and File Locking (see also File Handles)
 196
 197 =item *
 198
 199 String Processing, Language Text Processing, Parsing, and Searching
 200
 201 =item *
 202
 203 Option, Argument, Parameter, and Configuration File Processing
 204
 205 =item *
 206
 207 Internationalization and Locale
 208
 209 =item *
 210
 211 Authentication, Security, and Encryption
 212
 213 =item *
 214
 215 World Wide Web, HTML, HTTP, CGI, MIME
 216
 217 =item *
 218
 219 Server and Daemon Utilities
 220
 221 =item *
 222
 223 Archiving and Compression
 224
 225 =item *
 226
 227 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
 228
 229 =item *
 230
 231 Mail and Usenet News
 232
 233 =item *
 234
 235 Control Flow Utilities (callbacks and exceptions etc)
 236
 237 =item *
 238
 239 File Handle and Input/Output Stream Utilities
 240
 241 =item *
 242
 243 Miscellaneous Modules
 244
 245 =back
 246
 247 Registered CPAN sites as of this writing include the following.
 248 You should try to choose one close to you:
 249
 250 =over
 251
 252 =item Africa
 253
 254  South Africa   ftp://ftp.is.co.za/programming/perl/CPAN/
 255                 ftp://ftp.saix.net/pub/CPAN/
 256                 ftp://ftpza.co.za/pub/mirrors/cpan/
 257                 ftp://ftp.sun.ac.za/CPAN/
 258
 259 =item Asia
 260
 261  China          ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
 262                 http://www2.linuxforum.net/mirror/CPAN/
 263  Hong Kong      http://CPAN.pacific.net.hk/
 264                 ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
 265  Indonesia      http://piksi.itb.ac.id/CPAN/
 266                 ftp://mirrors.piksi.itb.ac.id/CPAN/
 267                 http://CPAN.mweb.co.id/
 268                 ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
 269  Israel         http://www.iglu.org.il:/pub/CPAN/
 270                 ftp://ftp.iglu.org.il/pub/CPAN/
 271                 http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
 272                 ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
 273  Japan          ftp://ftp.u-aizu.ac.jp/pub/lang/perl/CPAN/
 274                 ftp://ftp.kddlabs.co.jp/CPAN/
 275                 http://mirror.nucba.ac.jp/mirror/Perl/
 276                 ftp://mirror.nucba.ac.jp/mirror/Perl/
 277                 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
 278                 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
 279                 ftp://ftp.dti.ad.jp/pub/lang/CPAN/
 280                 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
 281  Saudi Arabia   ftp://ftp.isu.net.sa/pub/CPAN/
 282  Singapore      http://ftp.nus.edu.sg/unix/perl/CPAN/
 283                 ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
 284  South Korea    http://CPAN.bora.net/
 285                 ftp://ftp.bora.net/pub/CPAN/
 286                 http://ftp.kornet.net/CPAN/
 287                 ftp://ftp.kornet.net/pub/CPAN/
 288                 ftp://ftp.nuri.net/pub/CPAN/
 289  Taiwan         ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
 290                 ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
 291                 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
 292  Thailand       http://download.nectec.or.th/CPAN/
 293                 ftp://ftp.nectec.or.th/pub/languages/CPAN/
 294                 ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
 295
 296 =item Central America
 297
 298  Costa Rica     ftp://ftp.linux.co.cr/mirrors/CPAN/
 299                 http://ftp.ucr.ac.cr/Unix/CPAN/
 300                 ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
 301
 302 =item Europe
 303
 304  Austria        ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
 305  Belgium        http://ftp.easynet.be/CPAN/
 306                 ftp://ftp.easynet.be/CPAN/
 307                 ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
 308  Bulgaria       ftp://ftp.ntrl.net/pub/mirrors/CPAN/
 309  Croatia        ftp://ftp.linux.hr/pub/CPAN/
 310  Czech Republic http://www.fi.muni.cz/pub/perl/
 311                 ftp://ftp.fi.muni.cz/pub/perl/
 312                 ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
 313  Denmark        ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
 314                 http://www.cpan.dk/CPAN/
 315  England        http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
 316                 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
 317                 ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
 318                 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
 319                 ftp://ftp.plig.org/pub/CPAN/
 320                 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
 321                 http://mirror.uklinux.net/CPAN/
 322                 ftp://mirror.uklinux.net/pub/CPAN/
 323                 ftp://usit.shef.ac.uk/pub/packages/CPAN/
 324  Estonia        ftp://ftp.ut.ee/pub/languages/perl/CPAN/
 325  Finland        ftp://ftp.funet.fi/pub/languages/perl/CPAN/
 326  France         ftp://cpan.ftp.worldonline.fr/pub/CPAN/
 327                 ftp://ftp.club-internet.fr/pub/perl/CPAN/
 328                 ftp://ftp.lip6.fr/pub/perl/CPAN/
 329                 ftp://ftp.oleane.net/pub/mirrors/CPAN/
 330                 ftp://ftp.pasteur.fr/pub/computing/CPAN/
 331                 ftp://cpan.cict.fr/pub/CPAN/
 332                 ftp://ftp.uvsq.fr/pub/perl/CPAN/
 333  Germany        ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
 334                 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
 335                 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
 336                 ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
 337                 ftp://ftp.gigabell.net/pub/CPAN/
 338                 http://ftp.gwdg.de/pub/languages/perl/CPAN/
 339                 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
 340                 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
 341                 ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
 342                 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
 343                 ftp://ftp.gmd.de/packages/CPAN/
 344  Greece         ftp://ftp.ntua.gr/pub/lang/perl/
 345  Hungary        http://cpan.artifact.hu/
 346                 ftp://cpan.artifact.hu/CPAN/
 347                 ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
 348  Iceland        http://cpan.gm.is/
 349                 ftp://ftp.gm.is/pub/CPAN/
 350  Ireland        http://cpan.indigo.ie/
 351                 ftp://cpan.indigo.ie/pub/CPAN/
 352                 http://sunsite.compapp.dcu.ie/pub/perl/
 353                 ftp://sunsite.compapp.dcu.ie/pub/perl/
 354  Italy          http://cpan.nettuno.it/
 355                 http://softcity.iol.it/cpan
 356                 ftp://softcity.iol.it/pub/cpan
 357                 ftp://ftp.unina.it/pub/Other/CPAN/
 358                 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
 359                 ftp://cis.uniRoma2.it/CPAN/
 360                 ftp://ftp.edisontel.it/pub/CPAN_Mirror/
 361                 ftp://ftp.flashnet.it/pub/CPAN/
 362  Latvia         http://kvin.lv/pub/CPAN/
 363  Netherlands    ftp://download.xs4all.nl/pub/mirror/CPAN/
 364                 ftp://ftp.nl.uu.net/pub/CPAN/
 365                 ftp://ftp.cpan.nl/pub/CPAN/
 366                 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
 367                 http://www.cs.uu.nl/mirror/CPAN/
 368                 ftp://ftp.cs.uu.nl/mirror/CPAN/
 369  Norway         ftp://sunsite.uio.no/pub/languages/perl/CPAN/
 370                 ftp://ftp.uit.no/pub/languages/perl/cpan/
 371  Poland         ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
 372                 ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
 373                 ftp://ftp.man.torun.pl/pub/doc/CPAN/
 374                 ftp://sunsite.icm.edu.pl/pub/CPAN/
 375  Portugal       ftp://ftp.ua.pt/pub/CPAN/
 376                 ftp://perl.di.uminho.pt/pub/CPAN/
 377                 ftp://ftp.ist.utl.pt/pub/CPAN/
 378                 ftp://ftp.netc.pt/pub/CPAN/
 379  Romania        ftp://archive.logicnet.ro/mirrors/ftp.cpan.org/CPAN/
 380                 ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
 381                 ftp://ftp.dntis.ro/pub/cpan/
 382                 ftp://ftp.opsynet.com/cpan/
 383                 ftp://ftp.dnttm.ro/pub/CPAN/
 384  Russia         ftp://ftp.chg.ru/pub/lang/perl/CPAN/
 385                 http://cpan.rinet.ru/
 386                 ftp://cpan.rinet.ru/pub/mirror/CPAN/
 387                 ftp://ftp.aha.ru/pub/CPAN/
 388                 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
 389  Slovakia       ftp://ftp.entry.sk/pub/languages/perl/CPAN/
 390  Slovenia       ftp://ftp.arnes.si/software/perl/CPAN/
 391  Spain          ftp://ftp.rediris.es/mirror/CPAN/
 392                 ftp://ftp.etse.urv.es/pub/perl/
 393  Sweden         http://ftp.du.se/CPAN/
 394                 ftp://ftp.du.se/pub/CPAN/
 395                 ftp://ftp.sunet.se/pub/lang/perl/CPAN/
 396  Switzerland    ftp://ftp.danyk.ch/CPAN/
 397                 ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
 398  Turkey         ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
 399
 400 =item North America
 401
 402    Alberta        http://sunsite.ualberta.ca/pub/Mirror/CPAN/
 403                   ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
 404    Alabama        http://mirror.hiwaay.net/CPAN/
 405                   ftp://mirror.hiwaay.net/CPAN/
 406    California     http://www.cpan.org/
 407                   ftp://ftp.cpan.org/CPAN/
 408                   ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
 409                   ftp://ftp.digital.com/pub/plan/perl/CPAN/
 410                   http://www.kernel.org/pub/mirrors/cpan/
 411                   ftp://ftp.kernel.org/pub/mirrors/cpan/
 412                   http://www.perl.com/CPAN/
 413                   http://download.sourceforge.net/mirrors/CPAN/
 414    Colorado       ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
 415    Florida        ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
 416    Georgia        ftp://ftp.twoguys.org/CPAN/
 417    Illinois       http://www.neurogames.com/mirrors/CPAN
 418    Indiana        ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
 419                   http://cpan.nitco.com/
 420                   ftp://cpan.nitco.com/pub/CPAN/
 421                   ftp://cpan.in-span.net/
 422                   http://csociety-ftp.ecn.purdue.edu/pub/CPAN
 423                   ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
 424    Manitoba       http://theoryx5.uwinnipeg.ca/pub/CPAN/
 425                   ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
 426    Massachusetts  ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
 427                   ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
 428    Mexico         http://www.msg.com.mx/CPAN/
 429                   ftp://ftp.msg.com.mx/pub/CPAN/
 430    New Jersey     ftp://ftp.cpanel.net/pub/CPAN/
 431    New York       ftp://ftp.freesoftware.com/pub/perl/CPAN/
 432                   http://www.deao.net/mirrors/CPAN/
 433                   ftp://ftp.deao.net/pub/CPAN/
 434                   ftp://ftp.stealth.net/pub/mirrors/ftp.cpan.org/pub/CPAN/
 435                   http://mirror.nyc.anidea.com/CPAN/
 436                   ftp://mirror.nyc.anidea.com/pub/CPAN/
 437                   http://www.rge.com/pub/languages/perl/
 438                   ftp://ftp.rge.com/pub/languages/perl/
 439                   ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
 440    North Carolina ftp://ftp.duke.edu/pub/perl/
 441    Nova Scotia    ftp://cpan.chebucto.ns.ca/pub/CPAN/
 442    Ohio           ftp://ftp.loaded.net/pub/CPAN/
 443    Oklahoma       ftp://ftp.ou.edu/mirrors/CPAN/
 444    Ontario        ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
 445    Oregon         ftp://ftp.orst.edu/pub/packages/CPAN/
 446    Pennsylvania   http://ftp.epix.net/CPAN/
 447                   ftp://ftp.epix.net/pub/languages/perl/
 448                   ftp://carroll.cac.psu.edu/pub/CPAN/
 449    Tennessee      ftp://ftp.sunsite.utk.edu/pub/CPAN/
 450    Texas          http://ftp.sedl.org/pub/mirrors/CPAN/
 451                   http://jhcloos.com/pub/mirror/CPAN/
 452                   ftp://jhcloos.com/pub/mirror/CPAN/
 453    Utah           ftp://mirror.xmission.com/CPAN/
 454    Virginia       http://mirrors.rcn.net/pub/lang/CPAN/
 455                   ftp://mirrors.rcn.net/pub/lang/CPAN/
 456                   ftp://ruff.cs.jmu.edu/pub/CPAN/
 457    Washington     http://cpan.llarian.net/
 458                   ftp://cpan.llarian.net/pub/CPAN/
 459                   ftp://ftp-mirror.internap.com/pub/CPAN/
 460                   ftp://ftp.spu.edu/pub/CPAN/
 461
 462 =item Oceania
 463
 464  Australia      http://ftp.planetmirror.com/pub/CPAN/
 465                 ftp://ftp.planetmirror.com/pub/CPAN/
 466                 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
 467                 ftp://cpan.topend.com.au/pub/CPAN/
 468  New Zealand    ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
 469
 470 =item South America
 471
 472  Argentina      ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
 473  Brazil         ftp://cpan.pop-mg.com.br/pub/CPAN/
 474                 ftp://ftp.matrix.com.br/pub/perl/
 475                 ftp://cpan.if.usp.br/pub/mirror/CPAN/
 476  Chile          ftp://ftp.psinet.cl/pub/programming/perl/CPAN/
 477                 ftp://sunsite.dcc.uchile.cl/pub/lang/perl/
 478
 479 =back
 480
 481 For an up-to-date listing of CPAN sites,
 482 see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
 483
 484 =head1 Modules: Creation, Use, and Abuse
 485
 486 (The following section is borrowed directly from Tim Bunce's modules
 487 file, available at your nearest CPAN site.)
 488
 489 Perl implements a class using a package, but the presence of a
 490 package doesn't imply the presence of a class.  A package is just a
 491 namespace.  A class is a package that provides subroutines that can be
 492 used as methods.  A method is just a subroutine that expects, as its
 493 first argument, either the name of a package (for "static" methods),
 494 or a reference to something (for "virtual" methods).
 495
 496 A module is a file that (by convention) provides a class of the same
 497 name (sans the .pm), plus an import method in that class that can be
 498 called to fetch exported symbols.  This module may implement some of
 499 its methods by loading dynamic C or C++ objects, but that should be
 500 totally transparent to the user of the module.  Likewise, the module
 501 might set up an AUTOLOAD function to slurp in subroutine definitions on
 502 demand, but this is also transparent.  Only the F<.pm> file is required to
 503 exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
 504 the AUTOLOAD mechanism.
 505
 506 =head2 Guidelines for Module Creation
 507
 508 =over 4
 509
 510 =item  *
 511
 512 Do similar modules already exist in some form?
 513
 514 If so, please try to reuse the existing modules either in whole or
 515 by inheriting useful features into a new class.  If this is not
 516 practical try to get together with the module authors to work on
 517 extending or enhancing the functionality of the existing modules.
 518 A perfect example is the plethora of packages in perl4 for dealing
 519 with command line options.
 520
 521 If you are writing a module to expand an already existing set of
 522 modules, please coordinate with the author of the package.  It
 523 helps if you follow the same naming scheme and module interaction
 524 scheme as the original author.
 525
 526 =item  *
 527
 528 Try to design the new module to be easy to extend and reuse.
 529
 530 Try to C<use warnings;> (or C<use warnings qw(...);>).
 531 Remember that you can add C<no warnings qw(...);> to individual blocks
 532 of code that need less warnings.
 533
 534 Use blessed references.  Use the two argument form of bless to bless
 535 into the class name given as the first parameter of the constructor,
 536 e.g.,:
 537
 538  sub new {
 539      my $class = shift;
 540      return bless {}, $class;
 541  }
 542
 543 or even this if you'd like it to be used as either a static
 544 or a virtual method.
 545
 546  sub new {
 547      my $self  = shift;
 548      my $class = ref($self) || $self;
 549      return bless {}, $class;
 550  }
 551
 552 Pass arrays as references so more parameters can be added later
 553 (it's also faster).  Convert functions into methods where
 554 appropriate.  Split large methods into smaller more flexible ones.
 555 Inherit methods from other modules if appropriate.
 556
 557 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
 558 Generally you can delete the C<eq 'FOO'> part with no harm at all.
 559 Let the objects look after themselves! Generally, avoid hard-wired
 560 class names as far as possible.
 561
 562 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
 563 C<< $r->func() >> would work (see L<perlbot> for more details).
 564
 565 Use autosplit so little used or newly added functions won't be a
 566 burden to programs that don't use them. Add test functions to
 567 the module after __END__ either using AutoSplit or by saying:
 568
 569  eval join('',<main::DATA>) || die $@ unless caller();
 570
 571 Does your module pass the 'empty subclass' test? If you say
 572 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
 573 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
 574 does your application still work if you change:  C<$obj = new YOURCLASS;>
 575 into: C<$obj = new SUBCLASS;> ?
 576
 577 Avoid keeping any state information in your packages. It makes it
 578 difficult for multiple other packages to use yours. Keep state
 579 information in objects.
 580
 581 Always use B<-w>.
 582
 583 Try to C<use strict;> (or C<use strict qw(...);>).
 584 Remember that you can add C<no strict qw(...);> to individual blocks
 585 of code that need less strictness.
 586
 587 Always use B<-w>.
 588
 589 Follow the guidelines in the perlstyle(1) manual.
 590
 591 Always use B<-w>.
 592
 593 =item  *
 594
 595 Some simple style guidelines
 596
 597 The perlstyle manual supplied with Perl has many helpful points.
 598
 599 Coding style is a matter of personal taste. Many people evolve their
 600 style over several years as they learn what helps them write and
 601 maintain good code.  Here's one set of assorted suggestions that
 602 seem to be widely used by experienced developers:
 603
 604 Use underscores to separate words.  It is generally easier to read
 605 $var_names_like_this than $VarNamesLikeThis, especially for
 606 non-native speakers of English. It's also a simple rule that works
 607 consistently with VAR_NAMES_LIKE_THIS.
 608
 609 Package/Module names are an exception to this rule. Perl informally
 610 reserves lowercase module names for 'pragma' modules like integer
 611 and strict. Other modules normally begin with a capital letter and
 612 use mixed case with no underscores (need to be short and portable).
 613
 614 You may find it helpful to use letter case to indicate the scope
 615 or nature of a variable. For example:
 616
 617  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
 618  $Some_Caps_Here  package-wide global/static
 619  $no_caps_here    function scope my() or local() variables
 620
 621 Function and method names seem to work best as all lowercase.
 622 e.g., C<< $obj->as_string() >>.
 623
 624 You can use a leading underscore to indicate that a variable or
 625 function should not be used outside the package that defined it.
 626
 627 =item  *
 628
 629 Select what to export.
 630
 631 Do NOT export method names!
 632
 633 Do NOT export anything else by default without a good reason!
 634
 635 Exports pollute the namespace of the module user.  If you must
 636 export try to use @EXPORT_OK in preference to @EXPORT and avoid
 637 short or common names to reduce the risk of name clashes.
 638
 639 Generally anything not exported is still accessible from outside the
 640 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
 641 syntax.  By convention you can use a leading underscore on names to
 642 indicate informally that they are 'internal' and not for public use.
 643
 644 (It is actually possible to get private functions by saying:
 645 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
 646 directly as a method, because a method must have a name in the symbol
 647 table.)
 648
 649 As a general rule, if the module is trying to be object oriented
 650 then export nothing. If it's just a collection of functions then
 651 @EXPORT_OK anything but use @EXPORT with caution.
 652
 653 =item  *
 654
 655 Select a name for the module.
 656
 657 This name should be as descriptive, accurate, and complete as
 658 possible.  Avoid any risk of ambiguity. Always try to use two or
 659 more whole words.  Generally the name should reflect what is special
 660 about what the module does rather than how it does it.  Please use
 661 nested module names to group informally or categorize a module.
 662 There should be a very good reason for a module not to have a nested name.
 663 Module names should begin with a capital letter.
 664
 665 Having 57 modules all called Sort will not make life easy for anyone
 666 (though having 23 called Sort::Quick is only marginally better :-).
 667 Imagine someone trying to install your module alongside many others.
 668 If in any doubt ask for suggestions in comp.lang.perl.misc.
 669
 670 If you are developing a suite of related modules/classes it's good
 671 practice to use nested classes with a common prefix as this will
 672 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
 673 Xyz::Model etc. Use the modules in this list as a naming guide.
 674
 675 If adding a new module to a set, follow the original author's
 676 standards for naming modules and the interface to methods in
 677 those modules.
 678
 679 If developing modules for private internal or project specific use,
 680 that will never be released to the public, then you should ensure
 681 that their names will not clash with any future public module. You
 682 can do this either by using the reserved Local::* category or by
 683 using a category name that includes an underscore like Foo_Corp::*.
 684
 685 To be portable each component of a module name should be limited to
 686 11 characters. If it might be used on MS-DOS then try to ensure each is
 687 unique in the first 8 characters. Nested modules make this easier.
 688
 689 =item  *
 690
 691 Have you got it right?
 692
 693 How do you know that you've made the right decisions? Have you
 694 picked an interface design that will cause problems later? Have
 695 you picked the most appropriate name? Do you have any questions?
 696
 697 The best way to know for sure, and pick up many helpful suggestions,
 698 is to ask someone who knows. Comp.lang.perl.misc is read by just about
 699 all the people who develop modules and it's the best place to ask.
 700
 701 All you need to do is post a short summary of the module, its
 702 purpose and interfaces. A few lines on each of the main methods is
 703 probably enough. (If you post the whole module it might be ignored
 704 by busy people - generally the very people you want to read it!)
 705
 706 Don't worry about posting if you can't say when the module will be
 707 ready - just say so in the message. It might be worth inviting
 708 others to help you, they may be able to complete it for you!
 709
 710 =item  *
 711
 712 README and other Additional Files.
 713
 714 It's well known that software developers usually fully document the
 715 software they write. If, however, the world is in urgent need of
 716 your software and there is not enough time to write the full
 717 documentation please at least provide a README file containing:
 718
 719 =over 10
 720
 721 =item *
 722
 723 A description of the module/package/extension etc.
 724
 725 =item *
 726
 727 A copyright notice - see below.
 728
 729 =item *
 730
 731 Prerequisites - what else you may need to have.
 732
 733 =item *
 734
 735 How to build it - possible changes to Makefile.PL etc.
 736
 737 =item *
 738
 739 How to install it.
 740
 741 =item *
 742
 743 Recent changes in this release, especially incompatibilities
 744
 745 =item *
 746
 747 Changes / enhancements you plan to make in the future.
 748
 749 =back
 750
 751 If the README file seems to be getting too large you may wish to
 752 split out some of the sections into separate files: INSTALL,
 753 Copying, ToDo etc.
 754
 755 =over 4
 756
 757 =item Adding a Copyright Notice.
 758
 759
 760 How you choose to license your work is a personal decision.
 761 The general mechanism is to assert your Copyright and then make
 762 a declaration of how others may copy/use/modify your work.
 763
 764 Perl, for example, is supplied with two types of licence: The GNU
 765 GPL and The Artistic Licence (see the files README, Copying, and
 766 Artistic).  Larry has good reasons for NOT just using the GNU GPL.
 767
 768 My personal recommendation, out of respect for Larry, Perl, and the
 769 Perl community at large is to state something simply like:
 770
 771  Copyright (c) 1995 Your Name. All rights reserved.
 772  This program is free software; you can redistribute it and/or
 773  modify it under the same terms as Perl itself.
 774
 775 This statement should at least appear in the README file. You may
 776 also wish to include it in a Copying file and your source files.
 777 Remember to include the other words in addition to the Copyright.
 778
 779 =item  *
 780
 781 Give the module a version/issue/release number.
 782
 783 To be fully compatible with the Exporter and MakeMaker modules you
 784 should store your module's version number in a non-my package
 785 variable called $VERSION.  This should be a floating point
 786 number with at least two digits after the decimal (i.e., hundredths,
 787 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
 788 See L<Exporter> for details.
 789
 790 It may be handy to add a function or method to retrieve the number.
 791 Use the number in announcements and archive file names when
 792 releasing the module (ModuleName-1.02.tar.Z).
 793 See perldoc ExtUtils::MakeMaker.pm for details.
 794
 795 =item  *
 796
 797 How to release and distribute a module.
 798
 799 It's good idea to post an announcement of the availability of your
 800 module (or the module itself if small) to the comp.lang.perl.announce
 801 Usenet newsgroup.  This will at least ensure very wide once-off
 802 distribution.
 803
 804 If possible, register the module with CPAN.  You should
 805 include details of its location in your announcement.
 806
 807 Some notes about ftp archives: Please use a long descriptive file
 808 name that includes the version number. Most incoming directories
 809 will not be readable/listable, i.e., you won't be able to see your
 810 file after uploading it. Remember to send your email notification
 811 message as soon as possible after uploading else your file may get
 812 deleted automatically. Allow time for the file to be processed
 813 and/or check the file has been processed before announcing its
 814 location.
 815
 816 FTP Archives for Perl Modules:
 817
 818 Follow the instructions and links on:
 819
 820    http://www.perl.com/CPAN/modules/00modlist.long.html
 821    http://www.perl.com/CPAN/modules/04pause.html
 822
 823 or upload to one of these sites:
 824
 825    https://pause.kbx.de/pause/
 826    http://pause.perl.org/pause/
 827
 828 and notify <modules@perl.org>.
 829
 830 By using the WWW interface you can ask the Upload Server to mirror
 831 your modules from your ftp or WWW site into your own directory on
 832 CPAN!
 833
 834 Please remember to send me an updated entry for the Module list!
 835
 836 =item  *
 837
 838 Take care when changing a released module.
 839
 840 Always strive to remain compatible with previous released versions.
 841 Otherwise try to add a mechanism to revert to the
 842 old behavior if people rely on it.  Document incompatible changes.
 843
 844 =back
 845
 846 =back
 847
 848 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
 849
 850 =over 4
 851
 852 =item  *
 853
 854 There is no requirement to convert anything.
 855
 856 If it ain't broke, don't fix it! Perl 4 library scripts should
 857 continue to work with no problems. You may need to make some minor
 858 changes (like escaping non-array @'s in double quoted strings) but
 859 there is no need to convert a .pl file into a Module for just that.
 860
 861 =item  *
 862
 863 Consider the implications.
 864
 865 All Perl applications that make use of the script will need to
 866 be changed (slightly) if the script is converted into a module.  Is
 867 it worth it unless you plan to make other changes at the same time?
 868
 869 =item  *
 870
 871 Make the most of the opportunity.
 872
 873 If you are going to convert the script to a module you can use the
 874 opportunity to redesign the interface.  The guidelines for module
 875 creation above include many of the issues you should consider.
 876
 877 =item  *
 878
 879 The pl2pm utility will get you started.
 880
 881 This utility will read *.pl files (given as parameters) and write
 882 corresponding *.pm files. The pl2pm utilities does the following:
 883
 884 =over 10
 885
 886 =item *
 887
 888 Adds the standard Module prologue lines
 889
 890 =item *
 891
 892 Converts package specifiers from ' to ::
 893
 894 =item *
 895
 896 Converts die(...) to croak(...)
 897
 898 =item *
 899
 900 Several other minor changes
 901
 902 =back
 903
 904 Being a mechanical process pl2pm is not bullet proof. The converted
 905 code will need careful checking, especially any package statements.
 906 Don't delete the original .pl file till the new .pm one works!
 907
 908 =back
 909
 910 =head2 Guidelines for Reusing Application Code
 911
 912 =over 4
 913
 914 =item  *
 915
 916 Complete applications rarely belong in the Perl Module Library.
 917
 918 =item  *
 919
 920 Many applications contain some Perl code that could be reused.
 921
 922 Help save the world! Share your code in a form that makes it easy
 923 to reuse.
 924
 925 =item  *
 926
 927 Break-out the reusable code into one or more separate module files.
 928
 929 =item  *
 930
 931 Take the opportunity to reconsider and redesign the interfaces.
 932
 933 =item  *
 934
 935 In some cases the 'application' can then be reduced to a small
 936
 937 fragment of code built on top of the reusable modules. In these cases
 938 the application could invoked as:
 939
 940      % perl -e 'use Module::Name; method(@ARGV)' ...
 941 or
 942      % perl -mModule::Name ...    (in perl5.002 or higher)
 943
 944 =back
 945
 946 =head1 NOTE
 947
 948 Perl does not enforce private and public parts of its modules as you may
 949 have been used to in other languages like C++, Ada, or Modula-17.  Perl
 950 doesn't have an infatuation with enforced privacy.  It would prefer
 951 that you stayed out of its living room because you weren't invited, not
 952 because it has a shotgun.
 953
 954 The module and its user have a contract, part of which is common law,
 955 and part of which is "written".  Part of the common law contract is
 956 that a module doesn't pollute any namespace it wasn't asked to.  The
 957 written contract for the module (A.K.A. documentation) may make other
 958 provisions.  But then you know when you C<use RedefineTheWorld> that
 959 you're redefining the world and willing to take the consequences.
 960 EOF
 961
 962 close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
 963 close OUT      or warn "$0: failed to close OUT (perlmodlib.tmp): $!";
 964