X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlmod.pod;h=48ebf2371125dfb4e2b743d6110c1aaea8e46636;hb=a7ae9550f26a080556f67048e2697d3c5a20f9f4;hp=194cd1125d5adeb08a824607f9155c83d59ad740;hpb=55a864fe4cea1a0586891b83d359ba71e0972da5;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlmod.pod b/pod/perlmod.pod index 194cd11..48ebf23 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -1,33 +1,41 @@ =head1 NAME -perlmod - Perl modules (packages) +perlmod - Perl modules (packages and symbol tables) =head1 DESCRIPTION =head2 Packages Perl provides a mechanism for alternative namespaces to protect packages -from stomping on each other's variables. In fact, apart from certain -magical variables, there's really no such thing as a global variable in -Perl. The package statement declares the compilation unit as being in the -given namespace. The scope of the package declaration is from the -declaration itself through the end of the enclosing block (the same scope -as the local() operator). All further unqualified dynamic identifiers -will be in this namespace. A package statement affects only dynamic -variables--including those you've used local() on--but I lexical -variables created with my(). Typically it would be the first declaration -in a file to be included by the C or C operator. You can -switch into a package in more than one place; it influences merely which -symbol table is used by the compiler for the rest of that block. You can -refer to variables and filehandles in other packages by prefixing the -identifier with the package name and a double colon: -C<$Package::Variable>. If the package name is null, the C
package -is assumed. That is, C<$::sail> is equivalent to C<$main::sail>. - -(The old package delimiter was a single quote, but double colon -is now the preferred delimiter, in part because it's more readable -to humans, and in part because it's more readable to B macros. -It also makes C++ programmers feel like they know what's going on.) +from stomping on each other's variables. In fact, there's really no such +thing as a global variable in Perl (although some identifiers default +to the main package instead of the current one). The package statement +declares the compilation unit as +being in the given namespace. The scope of the package declaration +is from the declaration itself through the end of the enclosing block, +C, C, or end of file, whichever comes first (the same scope +as the my() and local() operators). All further unqualified dynamic +identifiers will be in this namespace. A package statement only affects +dynamic variables--including those you've used local() on--but +I lexical variables created with my(). Typically it would be +the first declaration in a file to be included by the C or +C operator. You can switch into a package in more than one place; +it merely influences which symbol table is used by the compiler for the +rest of that block. You can refer to variables and filehandles in other +packages by prefixing the identifier with the package name and a double +colon: C<$Package::Variable>. If the package name is null, the C
+package is assumed. That is, C<$::sail> is equivalent to C<$main::sail>. + +The old package delimiter was a single quote, but double colon is now the +preferred delimiter, in part because it's more readable to humans, and +in part because it's more readable to B macros. It also makes C++ +programmers feel like they know what's going on--as opposed to using the +single quote as separator, which was there to make Ada programmers feel +like they knew what's going on. Because the old-fashioned syntax is still +supported for backwards compatibility, if you try to use a string like +C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is, +the $s variable in package C, which is probably not what you meant. +Use braces to disambiguate, as in C<"This is ${owner}'s house">. Packages may be nested inside other packages: C<$OUTER::INNER::var>. This implies nothing about the order of name lookups, however. All symbols @@ -38,13 +46,13 @@ It would treat package C as a totally separate global package. Only identifiers starting with letters (or underscore) are stored in a package's symbol table. All other symbols are kept in package C
, -including all of the punctuation variables like $_. In addition, the -identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC, and SIG are -forced to be in package C
, even when used for other purposes than -their built-in one. Note also that, if you have a package called C, -C, or C, then you can't use the qualified form of an identifier -because it will be interpreted instead as a pattern match, a substitution, -or a translation. +including all of the punctuation variables like $_. In addition, when +unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, +INC, and SIG are forced to be in package C
, even when used for other +purposes than their builtin one. Note also that, if you have a package +called C, C, or C, then you can't use the qualified form of an +identifier because it will be interpreted instead as a pattern match, +a substitution, or a transliteration. (Variables beginning with underscore used to be forced into package main, but we decided it was more useful for package writers to be able @@ -62,8 +70,11 @@ temporarily switches back to the C
package to evaluate various expressions in the context of the C
package (or wherever you came from). See L. +The special symbol C<__PACKAGE__> contains the current package, but cannot +(easily) be used to construct variables. + See L for other scoping issues related to my() and local(), -or L regarding closures. +and L regarding closures. =head2 Symbol Tables @@ -77,63 +88,33 @@ use the C<*name> typeglob notation. In fact, the following have the same effect, though the first is more efficient because it does the symbol table lookups at compile time: - local(*main::foo) = *main::bar; local($main::{'foo'}) = - $main::{'bar'}; + local *main::foo = *main::bar; + local $main::{foo} = $main::{bar}; You can use this to print out all the variables in a package, for -instance. Here is F from the Perl library: - - package dumpvar; - sub main::dumpvar { - ($package) = @_; - local(*stab) = eval("*${package}::"); - while (($key,$val) = each(%stab)) { - local(*entry) = $val; - if (defined $entry) { - print "\$$key = '$entry'\n"; - } - - if (defined @entry) { - print "\@$key = (\n"; - foreach $num ($[ .. $#entry) { - print " $num\t'",$entry[$num],"'\n"; - } - print ")\n"; - } - - if ($key ne "${package}::" && defined %entry) { - print "\%$key = (\n"; - foreach $key (sort keys(%entry)) { - print " $key\t'",$entry{$key},"'\n"; - } - print ")\n"; - } - } - } - -Note that even though the subroutine is compiled in package C, -the name of the subroutine is qualified so that its name is inserted -into package C
. +instance. The standard F library and the CPAN module +Devel::Symdump make use of this. Assignment to a typeglob performs an aliasing operation, i.e., *dick = *richard; -causes variables, subroutines, and file handles accessible via the -identifier C to also be accessible via the identifier C. If -you want to alias only a particular variable or subroutine, you can -assign a reference instead: +causes variables, subroutines, formats, and file and directory handles +accessible via the identifier C also to be accessible via the +identifier C. If you want to alias only a particular variable or +subroutine, you can assign a reference instead: *dick = \$richard; -makes $richard and $dick the same variable, but leaves +Which makes $richard and $dick the same variable, but leaves @richard and @dick as separate arrays. Tricky, eh? This mechanism may be used to pass and return cheap references into or from subroutines if you won't want to copy the whole -thing. +thing. It only works when assigning to dynamic variables, not +lexicals. - %some_hash = (); + %some_hash = (); # can't be my() *some_hash = fn( \%another_hash ); sub fn { local *hashsym = shift; @@ -154,10 +135,15 @@ Another use of symbol tables is for making "constant" scalars. *PI = \3.14159265358979; Now you cannot alter $PI, which is probably a good thing all in all. +This isn't the same as a constant subroutine, which is subject to +optimization at compile-time. This isn't. A constant subroutine is one +prototyped to take no arguments and to return a constant expression. +See L for details on these. The C pragma is a +convenient shorthand for these. You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and package the *foo symbol table entry comes from. This may be useful -in a subroutine which is passed typeglobs as arguments +in a subroutine that gets passed typeglobs as arguments: sub identify_typeglob { my $glob = shift; @@ -180,37 +166,43 @@ There are two special subroutine definitions that function as package constructors and destructors. These are the C and C routines. The C is optional for these routines. -A C subroutine is executed as soon as possible, that is, the -moment it is completely defined, even before the rest of the containing -file is parsed. You may have multiple C blocks within a -file--they will execute in order of definition. Because a C -block executes immediately, it can pull in definitions of subroutines -and such from other files in time to be visible to the rest of the -file. - -An C subroutine is executed as late as possible, that is, when the -interpreter is being exited, even if it is exiting as a result of a -die() function. (But not if it's is being blown out of the water by a -signal--you have to trap that yourself (if you can).) You may have -multiple C blocks within a file--they will execute in reverse -order of definition; that is: last in, first out (LIFO). - -Inside an C subroutine C<$?> contains the value that the script is +A C subroutine is executed as soon as possible, that is, the moment +it is completely defined, even before the rest of the containing file +is parsed. You may have multiple C blocks within a file--they +will execute in order of definition. Because a C block executes +immediately, it can pull in definitions of subroutines and such from other +files in time to be visible to the rest of the file. Once a C +has run, it is immediately undefined and any code it used is returned to +Perl's memory pool. This means you can't ever explicitly call a C. + +An C subroutine is executed as late as possible, that is, when +the interpreter is being exited, even if it is exiting as a result of +a die() function. (But not if it's polymorphing into another program +via C, or being blown out of the water by a signal--you have to +trap that yourself (if you can).) You may have multiple C blocks +within a file--they will execute in reverse order of definition; that is: +last in, first out (LIFO). + +Inside an C subroutine, C<$?> contains the value that the script is going to pass to C. You can modify C<$?> to change the exit -value of the script. Beware of changing C<$?> by accident (e.g.,, by +value of the script. Beware of changing C<$?> by accident (e.g. by running something via C). -Note that when you use the B<-n> and B<-p> switches to Perl, C -and C work just as they do in B, as a degenerate case. +Note that when you use the B<-n> and B<-p> switches to Perl, C and +C work just as they do in B, as a degenerate case. As currently +implemented (and subject to change, since its inconvenient at best), +both C I C blocks are run when you use the B<-c> switch +for a compile-only syntax check, although your main code is not. =head2 Perl Classes There is no special class syntax in Perl, but a package may function -as a class if it provides subroutines that function as methods. Such a -package may also derive some of its methods from another class package -by listing the other package name in its @ISA array. +as a class if it provides subroutines to act as methods. Such a +package may also derive some of its methods from another class (package) +by listing the other package name in its global @ISA array (which +must be a package global, not a lexical). -For more on this, see L. +For more on this, see L and L. =head2 Perl Modules @@ -251,7 +243,7 @@ a file called Some/Module.pm and start with this template: # non-exported package globals go here use vars qw(@more $stuff); - # initalize package globals, first exported ones + # initialize package globals, first exported ones $Var1 = ''; %Hashit = (); @@ -285,7 +277,7 @@ a file called Some/Module.pm and start with this template: Then go on to declare and use your variables in functions without any qualifications. -See L and the I for details on +See L and the L for details on mechanics and style issues in module creation. Perl modules are included into your program by saying @@ -298,11 +290,11 @@ or This is exactly equivalent to - BEGIN { require "Module.pm"; import Module; } + BEGIN { require Module; import Module; } or - BEGIN { require "Module.pm"; import Module LIST; } + BEGIN { require Module; import Module LIST; } As a special case @@ -310,7 +302,7 @@ As a special case is exactly equivalent to - BEGIN { require "Module.pm"; } + BEGIN { require Module; } All Perl module files have the extension F<.pm>. C assumes this so that you don't have to spell out "F" in quotes. This also @@ -319,6 +311,19 @@ Module names are also capitalized unless they're functioning as pragmas, "Pragmas" are in effect compiler directives, and are sometimes called "pragmatic modules" (or even "pragmata" if you're a classicist). +The two statements: + + require SomeModule; + require "SomeModule.pm"; + +differ from each other in two ways. In the first case, any double +colons in the module name, such as C, are translated +into your system's directory separator, usually "/". The second +case does not, and would have to be specified literally. The other difference +is that seeing the first C clues in the compiler that uses of +indirect object notation involving "SomeModule", as in C<$ob = purge SomeModule>, +are method calls, not function calls. (Yes, this really can make a difference.) + Because the C statement implies a C block, the importation of semantics happens at the moment the C statement is compiled, before the rest of the file is compiled. This is how it is able @@ -328,7 +333,7 @@ the rest of the current file. This will not work if you use C instead of C. With require you can get into this problem: require Cwd; # make Cwd:: accessible - $here = Cwd::getcwd(); + $here = Cwd::getcwd(); use Cwd; # import names from Cwd:: $here = getcwd(); @@ -336,7 +341,11 @@ instead of C. With require you can get into this problem: require Cwd; # make Cwd:: accessible $here = getcwd(); # oops! no main::getcwd() -In general C is recommended over C. +In general, C is recommended over C, +because it determines module availability at compile time, not in the +middle of your program's execution. An exception would be if two modules +each tried to C each other, and each also called a function from +that other module. In that case, it's easy to use Cs instead. Perl packages may be nested inside other package names, so we can have package names containing C<::>. But if we used that package name @@ -353,1081 +362,14 @@ arrange to autoload) any additional functionality. The POSIX module happens to do both dynamic loading and autoloading, but the user can say just C to get it all. -For more information on writing extension modules, see L +For more information on writing extension modules, see L and L. -=head1 NOTE - -Perl does not enforce private and public parts of its modules as you may -have been used to in other languages like C++, Ada, or Modula-17. Perl -doesn't have an infatuation with enforced privacy. It would prefer -that you stayed out of its living room because you weren't invited, not -because it has a shotgun. - -The module and its user have a contract, part of which is common law, -and part of which is "written". Part of the common law contract is -that a module doesn't pollute any namespace it wasn't asked to. The -written contract for the module (A.K.A. documentation) may make other -provisions. But then you know when you C that -you're redefining the world and willing to take the consequences. - -=head1 THE PERL MODULE LIBRARY - -A number of modules are included the Perl distribution. These are -described below, and all end in F<.pm>. You may also discover files in -the library directory that end in either F<.pl> or F<.ph>. These are old -libraries supplied so that old programs that use them still run. The -F<.pl> files will all eventually be converted into standard modules, and -the F<.ph> files made by B will probably end up as extension modules -made by B. (Some F<.ph> values may already be available through the -POSIX module.) The B file in the distribution may help in your -conversion, but it's just a mechanical process and therefore far from -bulletproof. - -=head2 Pragmatic Modules - -They work somewhat like pragmas in that they tend to affect the compilation of -your program, and thus will usually work well only when used within a -C, or C. Most of these are locally scoped, so an inner BLOCK -may countermand any of these by saying: - - no integer; - no strict 'refs'; - -which lasts until the end of that BLOCK. - -Unlike the pragmas that effect the C<$^H> hints variable, the C and C declarations are not BLOCK-scoped. They allow -you to pre-declare a variables or subroutines within a particular -I rather than just a block. Such declarations are effective -for the entire file for which they were declared. You cannot rescind -them with C or C. - -The following pragmas are defined (and have their own documentation). - -=over 12 - -=item blib - -manipulate @INC at compile time to use MakeMaker's uninstalled version -of a package - -=item diagnostics - -force verbose warning diagnostics - -=item integer - -compute arithmetic in integer instead of double - -=item less - -request less of something from the compiler - -=item lib - -manipulate @INC at compile time - -=item locale - -use or ignore current locale for built-in operations (see L) - -=item ops - -restrict named opcodes when compiling or running Perl code - -=item overload - -overload basic Perl operations - -=item sigtrap - -enable simple signal handling - -=item strict - -restrict unsafe constructs - -=item subs - -pre-declare sub names - -=item vmsish - -adopt certain VMS-specific behaviors - -=item vars - -pre-declare global variable names - -=back - -=head2 Standard Modules - -Standard, bundled modules are all expected to behave in a well-defined -manner with respect to namespace pollution because they use the -Exporter module. See their own documentation for details. - -=over 12 - -=item AnyDBM_File - -provide framework for multiple DBMs - -=item AutoLoader - -load functions only on demand - -=item AutoSplit - -split a package for autoloading - -=item Benchmark - -benchmark running times of code - -=item CPAN - -interface to Comprehensive Perl Archive Network - -=item CPAN::FirstTime - -create a CPAN configuration file - -=item CPAN::Nox - -run CPAN while avoiding compiled extensions - -=item Carp - -warn of errors (from perspective of caller) - -=item Class::Template - -struct/member template builder - -=item Config - -access Perl configuration information - -=item Cwd - -get pathname of current working directory - -=item DB_File - -access to Berkeley DB - -=item Devel::SelfStubber - -generate stubs for a SelfLoading module - -=item DirHandle - -supply object methods for directory handles - -=item DynaLoader - -dynamically load C libraries into Perl code - -=item English - -use nice English (or awk) names for ugly punctuation variables - -=item Env - -import environment variables - -=item Exporter - -implements default import method for modules - -=item ExtUtils::Embed - -utilities for embedding Perl in C/C++ applications - -=item ExtUtils::Install - -install files from here to there - -=item ExtUtils::Liblist - -determine libraries to use and how to use them - -=item ExtUtils::MM_OS2 - -methods to override UN*X behaviour in ExtUtils::MakeMaker - -=item ExtUtils::MM_Unix - -methods used by ExtUtils::MakeMaker - -=item ExtUtils::MM_VMS - -methods to override UN*X behaviour in ExtUtils::MakeMaker - -=item ExtUtils::MakeMaker - -create an extension Makefile - -=item ExtUtils::Manifest - -utilities to write and check a MANIFEST file - -=item ExtUtils::Mkbootstrap - -make a bootstrap file for use by DynaLoader - -=item ExtUtils::Mksymlists - -write linker options files for dynamic extension - -=item ExtUtils::testlib - -add blib/* directories to @INC - -=item Fcntl - -load the C Fcntl.h defines - -=item File::Basename - -split a pathname into pieces - -=item File::CheckTree - -run many filetest checks on a tree - -=item File::Compare - -compare files or filehandles - -=item File::Copy - -copy files or filehandles - -=item File::Find - -traverse a file tree - -=item File::Path - -create or remove a series of directories - -=item File::stat - -by-name interface to Perl's built-in stat() functions - -=item FileCache - -keep more files open than the system permits - -=item FileHandle - -supply object methods for filehandles - -=item FindBin - -locate directory of original perl script - -=item GDBM_File - -access to the gdbm library - -=item Getopt::Long - -extended processing of command line options - -=item Getopt::Std - -process single-character switches with switch clustering - -=item I18N::Collate - -compare 8-bit scalar data according to the current locale - -=item IO - -load various IO modules - -=item IO::File - -supply object methods for filehandles - -=item IO::Handle - -supply object methods for I/O handles - -=item IO::Pipe - -supply object methods for pipes - -=item IO::Seekable - -supply seek based methods for I/O objects - -=item IO::Select - -OO interface to the select system call - -=item IO::Socket - -object interface to socket communications - -=item IPC::Open2 - -open a process for both reading and writing - -=item IPC::Open3 - -open a process for reading, writing, and error handling - -=item Math::BigFloat - -arbitrary length float math package - -=item Math::BigInt - -arbitrary size integer math package - -=item Math::Complex - -complex numbers and associated mathematical functions - -=item NDBM_File - -tied access to ndbm files - -=item Net::Ping - -Hello, anybody home? - -=item Net::hostent - -by-name interface to Perl's built-in gethost*() functions - -=item Net::netent - -by-name interface to Perl's built-in getnet*() functions - -=item Net::protoent - -by-name interface to Perl's built-in getproto*() functions - -=item Net::servent - -by-name interface to Perl's built-in getserv*() functions - -=item Opcode - -disable named opcodes when compiling or running perl code - -=item Pod::Text - -convert POD data to formatted ASCII text - -=item POSIX - -interface to IEEE Standard 1003.1 - -=item SDBM_File - -tied access to sdbm files - -=item Safe - -compile and execute code in restricted compartments - -=item Search::Dict - -search for key in dictionary file - -=item SelectSaver - -save and restore selected file handle - -=item SelfLoader - -load functions only on demand - -=item Shell - -run shell commands transparently within perl - -=item Socket - -load the C socket.h defines and structure manipulators - -=item Symbol - -manipulate Perl symbols and their names - -=item Sys::Hostname - -try every conceivable way to get hostname - -=item Sys::Syslog - -interface to the UNIX syslog(3) calls - -=item Term::Cap - -termcap interface - -=item Term::Complete - -word completion module - -=item Term::ReadLine - -interface to various C packages - -=item Test::Harness - -run perl standard test scripts with statistics - -=item Text::Abbrev - -create an abbreviation table from a list - -=item Text::ParseWords - -parse text into an array of tokens - -=item Text::Soundex - -implementation of the Soundex Algorithm as described by Knuth - -=item Text::Tabs - -expand and unexpand tabs per the unix expand(1) and unexpand(1) - -=item Text::Wrap - -line wrapping to form simple paragraphs - -=item Tie::Hash - -base class definitions for tied hashes - -=item Tie::RefHash - -base class definitions for tied hashes with references as keys - -=item Tie::Scalar - -base class definitions for tied scalars - -=item Tie::SubstrHash - -fixed-table-size, fixed-key-length hashing - -=item Time::Local - -efficiently compute time from local and GMT time - -=item Time::gmtime - -by-name interface to Perl's built-in gmtime() function - -=item Time::localtime - -by-name interface to Perl's built-in localtime() function - -=item Time::tm - -internal object used by Time::gmtime and Time::localtime - -=item UNIVERSAL - -base class for ALL classes (blessed references) - -=item User::grent - -by-name interface to Perl's built-in getgr*() functions - -=item User::pwent - -by-name interface to Perl's built-in getpw*() functions - -=back - -To find out I the modules installed on your system, including -those without documentation or outside the standard release, do this: - - find `perl -e 'print "@INC"'` -name '*.pm' -print - -They should all have their own documentation installed and accessible via -your system man(1) command. If that fails, try the I program. - -=head2 Extension Modules - -Extension modules are written in C (or a mix of Perl and C) and get -dynamically loaded into Perl if and when you need them. Supported -extension modules include the Socket, Fcntl, and POSIX modules. - -Many popular C extension modules do not come bundled (at least, not -completely) due to their sizes, volatility, or simply lack of time for -adequate testing and configuration across the multitude of platforms on -which Perl was beta-tested. You are encouraged to look for them in -archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their -authors before randomly posting asking for their present condition and -disposition. - -=head1 CPAN - -CPAN stands for the Comprehensive Perl Archive Network. This is a globally -replicated collection of all known Perl materials, including hundreds -of unbundled modules. Here are the major categories of modules: - -=over - -=item * -Language Extensions and Documentation Tools - -=item * -Development Support - -=item * -Operating System Interfaces - -=item * -Networking, Device Control (modems) and InterProcess Communication - -=item * -Data Types and Data Type Utilities - -=item * -Database Interfaces - -=item * -User Interfaces - -=item * -Interfaces to / Emulations of Other Programming Languages - -=item * -File Names, File Systems and File Locking (see also File Handles) - -=item * -String Processing, Language Text Processing, Parsing, and Searching - -=item * -Option, Argument, Parameter, and Configuration File Processing - -=item * -Internationalization and Locale - -=item * -Authentication, Security, and Encryption - -=item * -World Wide Web, HTML, HTTP, CGI, MIME - -=item * -Server and Daemon Utilities - -=item * -Archiving and Compression - -=item * -Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing - -=item * -Mail and Usenet News - -=item * -Control Flow Utilities (callbacks and exceptions etc) - -=item * -File Handle and Input/Output Stream Utilities - -=item * -Miscellaneous Modules - -=back - -The registered CPAN sites as of this writing include the following. -You should try to choose one close to you: - -=over - -=item * -Africa - - South Africa ftp://ftp.is.co.za/programming/perl/CPAN/ - -=item * -Asia - - Hong Kong ftp://ftp.hkstar.com/pub/CPAN/ - Japan ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ - ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/ - South Korea ftp://ftp.nuri.net/pub/CPAN/ - Taiwan ftp://dongpo.math.ncu.edu.tw/perl/CPAN/ - ftp://ftp.wownet.net/pub2/PERL/ - -=item * -Australasia - - Australia ftp://ftp.netinfo.com.au/pub/perl/CPAN/ - New Zealand ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/ - -=item * -Europe - - Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ - Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ - Czech Republic ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/ - Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ - Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/ - France ftp://ftp.ibp.fr/pub/perl/CPAN/ - ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/ - Germany ftp://ftp.gmd.de/packages/CPAN/ - ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/ - ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ - ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ - ftp://ftp.uni-erlangen.de/pub/source/Perl/CPAN/ - ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ - Greece ftp://ftp.ntua.gr/pub/lang/perl/ - Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ - Italy ftp://cis.utovrm.it/CPAN/ - the Netherlands ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/ - ftp://ftp.EU.net/packages/cpan/ - Norway ftp://ftp.uit.no/pub/languages/perl/cpan/ - Poland ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ - ftp://sunsite.icm.edu.pl/pub/CPAN/ - Portugal ftp://ftp.ci.uminho.pt/pub/lang/perl/ - ftp://ftp.telepac.pt/pub/CPAN/ - Russia ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ - Slovenia ftp://ftp.arnes.si/software/perl/CPAN/ - Spain ftp://ftp.etse.urv.es/pub/mirror/perl/ - ftp://ftp.rediris.es/mirror/CPAN/ - Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/ - UK ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ - ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ - ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/ - -=item * -North America - - Ontario ftp://ftp.utilis.com/public/CPAN/ - ftp://enterprise.ic.gc.ca/pub/perl/CPAN/ - Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/ - California ftp://ftp.digital.com/pub/plan/perl/CPAN/ - ftp://ftp.cdrom.com/pub/perl/CPAN/ - Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ - Florida ftp://ftp.cis.ufl.edu/pub/perl/CPAN/ - Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/ - Massachusetts ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ - New York ftp://ftp.rge.com/pub/languages/perl/ - North Carolina ftp://ftp.duke.edu/pub/perl/ - Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/ - Oregon http://www.perl.org/CPAN/ - ftp://ftp.orst.edu/pub/packages/CPAN/ - Pennsylvania ftp://ftp.epix.net/pub/languages/perl/ - Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/ - ftp://ftp.metronet.com/pub/perl/ - -=item * -South America - - Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/ - -=back - -For an up-to-date listing of CPAN sites, -see F or F. - -=head1 Modules: Creation, Use, and Abuse - -(The following section is borrowed directly from Tim Bunce's modules -file, available at your nearest CPAN site.) - -Perl implements a class using a package, but the presence of a -package doesn't imply the presence of a class. A package is just a -namespace. A class is a package that provides subroutines that can be -used as methods. A method is just a subroutine that expects, as its -first argument, either the name of a package (for "static" methods), -or a reference to something (for "virtual" methods). - -A module is a file that (by convention) provides a class of the same -name (sans the .pm), plus an import method in that class that can be -called to fetch exported symbols. This module may implement some of -its methods by loading dynamic C or C++ objects, but that should be -totally transparent to the user of the module. Likewise, the module -might set up an AUTOLOAD function to slurp in subroutine definitions on -demand, but this is also transparent. Only the .pm file is required to -exist. - -=head2 Guidelines for Module Creation - -=over 4 - -=item Do similar modules already exist in some form? - -If so, please try to reuse the existing modules either in whole or -by inheriting useful features into a new class. If this is not -practical try to get together with the module authors to work on -extending or enhancing the functionality of the existing modules. -A perfect example is the plethora of packages in perl4 for dealing -with command line options. - -If you are writing a module to expand an already existing set of -modules, please coordinate with the author of the package. It -helps if you follow the same naming scheme and module interaction -scheme as the original author. - -=item Try to design the new module to be easy to extend and reuse. - -Use blessed references. Use the two argument form of bless to bless -into the class name given as the first parameter of the constructor, -e.g.,: - - sub new { - my $class = shift; - return bless {}, $class; - } - -or even this if you'd like it to be used as either a static -or a virtual method. - - sub new { - my $self = shift; - my $class = ref($self) || $self; - return bless {}, $class; - } - -Pass arrays as references so more parameters can be added later -(it's also faster). Convert functions into methods where -appropriate. Split large methods into smaller more flexible ones. -Inherit methods from other modules if appropriate. - -Avoid class name tests like: C. -Generally you can delete the "C" part with no harm at all. -Let the objects look after themselves! Generally, avoid hardwired -class names as far as possible. - -Avoid C<$r-EClass::func()> where using C<@ISA=qw(... Class ...)> and -C<$r-Efunc()> would work (see L for more details). - -Use autosplit so little used or newly added functions won't be a -burden to programs which don't use them. Add test functions to -the module after __END__ either using AutoSplit or by saying: - - eval join('',) || die $@ unless caller(); - -Does your module pass the 'empty subclass' test? If you say -"C<@SUBCLASS::ISA = qw(YOURCLASS);>" your applications should be able -to use SUBCLASS in exactly the same way as YOURCLASS. For example, -does your application still work if you change: C<$obj = new YOURCLASS;> -into: C<$obj = new SUBCLASS;> ? - -Avoid keeping any state information in your packages. It makes it -difficult for multiple other packages to use yours. Keep state -information in objects. - -Always use B<-w>. Try to C (or C). -Remember that you can add C to individual blocks -of code which need less strictness. Always use B<-w>. Always use B<-w>! -Follow the guidelines in the perlstyle(1) manual. - -=item Some simple style guidelines - -The perlstyle manual supplied with perl has many helpful points. - -Coding style is a matter of personal taste. Many people evolve their -style over several years as they learn what helps them write and -maintain good code. Here's one set of assorted suggestions that -seem to be widely used by experienced developers: - -Use underscores to separate words. It is generally easier to read -$var_names_like_this than $VarNamesLikeThis, especially for -non-native speakers of English. It's also a simple rule that works -consistently with VAR_NAMES_LIKE_THIS. - -Package/Module names are an exception to this rule. Perl informally -reserves lowercase module names for 'pragma' modules like integer -and strict. Other modules normally begin with a capital letter and -use mixed case with no underscores (need to be short and portable). - -You may find it helpful to use letter case to indicate the scope -or nature of a variable. For example: - - $ALL_CAPS_HERE constants only (beware clashes with perl vars) - $Some_Caps_Here package-wide global/static - $no_caps_here function scope my() or local() variables - -Function and method names seem to work best as all lowercase. -e.g.,, C<$obj-Eas_string()>. - -You can use a leading underscore to indicate that a variable or -function should not be used outside the package that defined it. - -=item Select what to export. - -Do NOT export method names! - -Do NOT export anything else by default without a good reason! - -Exports pollute the namespace of the module user. If you must -export try to use @EXPORT_OK in preference to @EXPORT and avoid -short or common names to reduce the risk of name clashes. - -Generally anything not exported is still accessible from outside the -module using the ModuleName::item_name (or C<$blessed_ref-Emethod>) -syntax. By convention you can use a leading underscore on names to -indicate informally that they are 'internal' and not for public use. - -(It is actually possible to get private functions by saying: -C. But there's no way to call that -directly as a method, because a method must have a name in the symbol -table.) - -As a general rule, if the module is trying to be object oriented -then export nothing. If it's just a collection of functions then -@EXPORT_OK anything but use @EXPORT with caution. - -=item Select a name for the module. - -This name should be as descriptive, accurate, and complete as -possible. Avoid any risk of ambiguity. Always try to use two or -more whole words. Generally the name should reflect what is special -about what the module does rather than how it does it. Please use -nested module names to group informally or categorize a module. -There should be a very good reason for a module not to have a nested name. -Module names should begin with a capital letter. - -Having 57 modules all called Sort will not make life easy for anyone -(though having 23 called Sort::Quick is only marginally better :-). -Imagine someone trying to install your module alongside many others. -If in any doubt ask for suggestions in comp.lang.perl.misc. - -If you are developing a suite of related modules/classes it's good -practice to use nested classes with a common prefix as this will -avoid namespace clashes. For example: Xyz::Control, Xyz::View, -Xyz::Model etc. Use the modules in this list as a naming guide. - -If adding a new module to a set, follow the original author's -standards for naming modules and the interface to methods in -those modules. - -To be portable each component of a module name should be limited to -11 characters. If it might be used on DOS then try to ensure each is -unique in the first 8 characters. Nested modules make this easier. - -=item Have you got it right? - -How do you know that you've made the right decisions? Have you -picked an interface design that will cause problems later? Have -you picked the most appropriate name? Do you have any questions? - -The best way to know for sure, and pick up many helpful suggestions, -is to ask someone who knows. Comp.lang.perl.misc is read by just about -all the people who develop modules and it's the best place to ask. - -All you need to do is post a short summary of the module, its -purpose and interfaces. A few lines on each of the main methods is -probably enough. (If you post the whole module it might be ignored -by busy people - generally the very people you want to read it!) - -Don't worry about posting if you can't say when the module will be -ready - just say so in the message. It might be worth inviting -others to help you, they may be able to complete it for you! - -=item README and other Additional Files. - -It's well known that software developers usually fully document the -software they write. If, however, the world is in urgent need of -your software and there is not enough time to write the full -documentation please at least provide a README file containing: - -=over 10 - -=item * -A description of the module/package/extension etc. - -=item * -A copyright notice - see below. - -=item * -Prerequisites - what else you may need to have. - -=item * -How to build it - possible changes to Makefile.PL etc. - -=item * -How to install it. - -=item * -Recent changes in this release, especially incompatibilities - -=item * -Changes / enhancements you plan to make in the future. - -=back - -If the README file seems to be getting too large you may wish to -split out some of the sections into separate files: INSTALL, -Copying, ToDo etc. - -=over 4 - -=item Adding a Copyright Notice. - -How you choose to license your work is a personal decision. -The general mechanism is to assert your Copyright and then make -a declaration of how others may copy/use/modify your work. - -Perl, for example, is supplied with two types of license: The GNU -GPL and The Artistic License (see the files README, Copying, and -Artistic). Larry has good reasons for NOT just using the GNU GPL. - -My personal recommendation, out of respect for Larry, Perl, and the -perl community at large is to state something simply like: - - Copyright (c) 1995 Your Name. All rights reserved. - This program is free software; you can redistribute it and/or - modify it under the same terms as Perl itself. - -This statement should at least appear in the README file. You may -also wish to include it in a Copying file and your source files. -Remember to include the other words in addition to the Copyright. - -=item Give the module a version/issue/release number. - -To be fully compatible with the Exporter and MakeMaker modules you -should store your module's version number in a non-my package -variable called $VERSION. This should be a floating point -number with at least two digits after the decimal (i.e., hundredths, -e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version. -See Exporter.pm in Perl5.001m or later for details. - -It may be handy to add a function or method to retrieve the number. -Use the number in announcements and archive file names when -releasing the module (ModuleName-1.02.tar.Z). -See perldoc ExtUtils::MakeMaker.pm for details. - -=item How to release and distribute a module. - -It's good idea to post an announcement of the availability of your -module (or the module itself if small) to the comp.lang.perl.announce -Usenet newsgroup. This will at least ensure very wide once-off -distribution. - -If possible you should place the module into a major ftp archive and -include details of its location in your announcement. - -Some notes about ftp archives: Please use a long descriptive file -name which includes the version number. Most incoming directories -will not be readable/listable, i.e., you won't be able to see your -file after uploading it. Remember to send your email notification -message as soon as possible after uploading else your file may get -deleted automatically. Allow time for the file to be processed -and/or check the file has been processed before announcing its -location. - -FTP Archives for Perl Modules: - -Follow the instructions and links on - - http://franz.ww.tu-berlin.de/modulelist - -or upload to one of these sites: - - ftp://franz.ww.tu-berlin.de/incoming - ftp://ftp.cis.ufl.edu/incoming - -and notify >. - -By using the WWW interface you can ask the Upload Server to mirror -your modules from your ftp or WWW site into your own directory on -CPAN! - -Please remember to send me an updated entry for the Module list! - -=item Take care when changing a released module. - -Always strive to remain compatible with previous released versions -(see 2.2 above) Otherwise try to add a mechanism to revert to the -old behaviour if people rely on it. Document incompatible changes. - -=back - -=back - -=head2 Guidelines for Converting Perl 4 Library Scripts into Modules - -=over 4 - -=item There is no requirement to convert anything. - -If it ain't broke, don't fix it! Perl 4 library scripts should -continue to work with no problems. You may need to make some minor -changes (like escaping non-array @'s in double quoted strings) but -there is no need to convert a .pl file into a Module for just that. - -=item Consider the implications. - -All the perl applications which make use of the script will need to -be changed (slightly) if the script is converted into a module. Is -it worth it unless you plan to make other changes at the same time? - -=item Make the most of the opportunity. - -If you are going to convert the script to a module you can use the -opportunity to redesign the interface. The 'Guidelines for Module -Creation' above include many of the issues you should consider. - -=item The pl2pm utility will get you started. - -This utility will read *.pl files (given as parameters) and write -corresponding *.pm files. The pl2pm utilities does the following: - -=over 10 - -=item * -Adds the standard Module prologue lines - -=item * -Converts package specifiers from ' to :: - -=item * -Converts die(...) to croak(...) - -=item * -Several other minor changes - -=back - -Being a mechanical process pl2pm is not bullet proof. The converted -code will need careful checking, especially any package statements. -Don't delete the original .pl file till the new .pm one works! - -=back - -=head2 Guidelines for Reusing Application Code - -=over 4 - -=item Complete applications rarely belong in the Perl Module Library. - -=item Many applications contain some perl code which could be reused. - -Help save the world! Share your code in a form that makes it easy -to reuse. - -=item Break-out the reusable code into one or more separate module files. - -=item Take the opportunity to reconsider and redesign the interfaces. - -=item In some cases the 'application' can then be reduced to a small - -fragment of code built on top of the reusable modules. In these cases -the application could invoked as: - - perl -e 'use Module::Name; method(@ARGV)' ... -or - perl -mModule::Name ... (in perl5.002 or higher) +=head1 SEE ALSO -=back +See L for general style issues related to building Perl +modules and classes as well as descriptions of the standard library and +CPAN, L for how Perl's standard import/export mechanism works, +L for an in-depth tutorial on creating classes, L +for a hard-core reference document on objects, and L for an +explanation of functions and scoping.