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