=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<not> lexical
-variables created with my(). Typically it would be the first declaration
-in a file to be included by the C<require> or C<use> 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<main> 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<emacs> 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<eval>, C<sub>, 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<not> lexical variables created with my(). Typically it would be
+the first declaration in a file to be included by the C<require> or
+C<use> 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<main>
+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<emacs> 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<owner>, 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
Only identifiers starting with letters (or underscore) are stored in a
package's symbol table. All other symbols are kept in package C<main>,
-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<main>, even when used for other purposes than
-their built-in one. Note also that, if you have a package called C<m>,
-C<s>, or C<y>, 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<main>, even when used for other
+purposes than their builtin one. Note also that, if you have a package
+called C<m>, C<s>, or C<y>, 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
expressions in the context of the C<main> package (or wherever you came
from). See L<perldebug>.
+The special symbol C<__PACKAGE__> contains the current package, but cannot
+(easily) be used to construct variables.
+
See L<perlsub> for other scoping issues related to my() and local(),
-
or L<perlref> regarding closures.
+
and L<perlref> regarding closures.
=head2 Symbol Tables
-The symbol table for a package happens to be stored in the associative
-array of that name appended with two colons. The main symbol table's
-name is thus C<%main::>, or C<%::> for short. Likewise symbol table for
-the nested package mentioned earlier is named C<%OUTER::INNER::>.
+The symbol table for a package happens to be stored in the hash of that
+name with two colons appended. The main symbol table's name is thus
+C<%main::>, or C<%::> for short. Likewise symbol table for the nested
+package mentioned earlier is named C<%OUTER::INNER::>.
-The value in each entry of the associative array is what you are referring
-to when you 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:
+The value in each entry of the hash is what you are referring to when you
+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<dumpvar.pl> 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<dumpvar>,
-the name of the subroutine is qualified so that its name is inserted
-into package C<main>.
+instance. The standard F<dumpvar.pl> 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<richard> to also be accessible via the identifier C<dick>. 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<richard> also to be accessible via the
+identifier C<dick>. 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;
*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<perlsub> for details on these. The C<use constant> 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;
constructors and destructors. These are the C<BEGIN> and C<END>
routines. The C<sub> is optional for these routines.
-A C<BEGIN> 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<BEGIN> blocks within a
-file--they will execute in order of definition. Because a C<BEGIN>
-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<END> 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<END> blocks within a file--they will execute in reverse
-order of definition; that is: last in, first out (LIFO).
-
-Inside an C<END> subroutine C<$?> contains the value that the script is
+A C<BEGIN> 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<BEGIN> blocks within a file--they
+will execute in order of definition. Because a C<BEGIN> 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<BEGIN>
+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<BEGIN>.
+
+An C<END> 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<exec>, or being blown out of the water by a signal--you have to
+trap that yourself (if you can).) You may have multiple C<END> blocks
+within a file--they will execute in reverse order of definition; that is:
+last in, first out (LIFO).
+
+Inside an C<END> subroutine, C<$?> contains the value that the script is
going to pass to C<exit()>. 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<system>).
-Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN>
-and C<END> work just as they do in B<awk>, as a degenerate case.
+Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
+C<END> work just as they do in B<awk>, as a degenerate case. As currently
+implemented (and subject to change, since its inconvenient at best),
+both C<BEGIN> I<and> C<END> 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<perlobj>.
+For more on this, see L<perltoot> and L<perlobj>.
=head2 Perl Modules
calls on the class and its objects, without explicit exportation of any
symbols. Or it can do a little of both.
-For example, to start a normal module called Fred, create
-a file called Fred.pm and put this at the start of it:
+For example, to start a normal module called Some::Module, create
+a file called Some/Module.pm and start with this template:
+
+ package Some::Module; # assumes Some/Module.pm
+
+ use strict;
+
+ BEGIN {
+ use Exporter ();
+ use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
+
+ # set the version for version checking
+ $VERSION = 1.00;
+ # if using RCS/CVS, this may be preferred
+ $VERSION = do { my @r = (q$Revision: 2.21 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; # must be all one line, for MakeMaker
+
+ @ISA = qw(Exporter);
+ @EXPORT = qw(&func1 &func2 &func4);
+ %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
+
+ # your exported package globals go here,
+ # as well as any optionally exported functions
+ @EXPORT_OK = qw($Var1 %Hashit &func3);
+ }
+ use vars @EXPORT_OK;
+
+ # non-exported package globals go here
+ use vars qw(@more $stuff);
+
+ # initalize package globals, first exported ones
+ $Var1 = '';
+ %Hashit = ();
+
+ # then the others (which are still accessible as $Some::Module::stuff)
+ $stuff = '';
+ @more = ();
+
+ # all file-scoped lexicals must be created before
+ # the functions below that use them.
+
+ # file-private lexicals go here
+ my $priv_var = '';
+ my %secret_hash = ();
+
+ # here's a file-private function as a closure,
+ # callable as &$priv_func; it cannot be prototyped.
+ my $priv_func = sub {
+ # stuff goes here.
+ };
- package Fred;
- use strict;
- use Exporter ();
- use vars qw(@ISA @EXPORT @EXPORT_OK);
- @ISA = qw(Exporter);
- @EXPORT = qw(&func1 &func2);
- @EXPORT_OK = qw($sally @listabob %harry &func3);
- use vars qw($sally @listabob %harry);
+ # make all your functions, whether exported or not;
+ # remember to put something interesting in the {} stubs
+ sub func1 {} # no prototype
+ sub func2() {} # proto'd void
+ sub func3($$) {} # proto'd to 2 scalars
+
+ # this one isn't exported, but could be called!
+ sub func4(\%) {} # proto'd to 1 hash ref
+
+ END { } # module clean-up code here (global destructor)
Then go on to declare and use your variables in functions
without any qualifications.
-See L<Exporter> and the I<Perl Modules File> for details on
+See L<Exporter> and the L<perlmodlib> for details on
mechanics and style issues in module creation.
Perl modules are included into your program by saying
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
is exactly equivalent to
- BEGIN { require "Module.pm"; }
+ BEGIN { require Module; }
All Perl module files have the extension F<.pm>. C<use> assumes this so
that you don't have to spell out "F<Module.pm>" in quotes. This also
"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<Some::Module>, 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<require> 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<use> statement implies a C<BEGIN> block, the importation
of semantics happens at the moment the C<use> statement is compiled,
before the rest of the file is compiled. This is how it is able
instead of C<use>. 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();
require Cwd; # make Cwd:: accessible
$here = getcwd(); # oops! no main::getcwd()
-In general C<use Module ();> is recommended over C<require Module;>.
+In general, C<use Module ()> is recommended over C<require Module>,
+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<use> each other, and each also called a function from
+that other module. In that case, it's easy to use C<require>s 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
happens to do both dynamic loading and autoloading, but the user can
say just C<use POSIX> to get it all.
-For more information on writing extension modules, see L<perlxs>
+For more information on writing extension modules, see L<perlxstut>
and L<perlguts>.
-=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<use RedefineTheWorld> 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<h2ph> will probably end up as extension modules
-made by B<h2xs>. (Some F<.ph> values may already be available through the
-POSIX module.) The B<pl2pm> file in the distribution may help in your
-conversion, but it's just a mechanical process, so is 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<use>, or C<no>. 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<use
-vars> and C<use subs> declarations are not BLOCK-scoped. They allow
-you to pre-declare a variables or subroutines within a particular
-<I>file</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<no vars> or C<no subs>.
-
-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<perllocale>)
-
-=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 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 Fatal
-
-replace functions with equivalents which succeed or die
-
-=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<readline> 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<all> 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<perldoc> 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 *
-ftp://ftp.sterling.com/programming/languages/perl/
-
-=item *
-ftp://ftp.sedl.org/pub/mirrors/CPAN/
-
-=item *
-ftp://ftp.uoknor.edu/mirrors/CPAN/
-
-=item *
-ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/
-
-=item *
-ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/
-
-=item *
-ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
-
-=item *
-ftp://ftp.switch.ch/mirror/CPAN/
-
-=item *
-ftp://ftp.sunet.se/pub/lang/perl/CPAN/
-
-=item *
-ftp://ftp.ci.uminho.pt/pub/lang/perl/
-
-=item *
-ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
-
-=item *
-ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
-
-=item *
-ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/
-
-=item *
-ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/
-
-=item *
-ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
-
-=item *
-ftp://ftp.ibp.fr/pub/perl/CPAN/
-
-=item *
-ftp://ftp.funet.fi/pub/languages/perl/CPAN/
-
-=item *
-ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/
-
-=item *
-ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/
-
-=item *
-ftp://coombs.anu.edu.au/pub/perl/
-
-=item *
-ftp://dongpo.math.ncu.edu.tw/perl/CPAN/
-
-=item *
-ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
-
-=item *
-ftp://ftp.is.co.za/programming/perl/CPAN/
-
-=back
-
-For an up-to-date listing of CPAN sites,
-see F<http://www.perl.com/perl/CPAN> or F<ftp://ftp.perl.com/perl/>.
-
-=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<die "Invalid" unless ref $ref eq 'FOO'>.
-Generally you can delete the "C<eq 'FOO'>" part with no harm at all.
-Let the objects look after themselves! Generally, avoid hardwired
-class names as far as possible.
-
-Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
-C<$r-E<gt>func()> would work (see L<perlbot> 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('',<main::DATA>) || die $@ unless caller();
-
-Does your module pass the 'empty sub-class' 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<use strict;> (or C<use strict qw(...);>).
-Remember that you can add C<no strict qw(...);> 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-E<gt>as_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-E<gt>method>)
-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<my $subref = sub { ... }; &$subref;>. 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 upload@franz.ww.tu-berlin.de.
-
-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)
+=head1 SEE ALSO
-=back
+See L<perlmodlib> for general style issues related to building Perl
+modules and classes as well as descriptions of the standard library and
+CPAN, L<Exporter> for how Perl's standard import/export mechanism works,
+L<perltoot> for an in-depth tutorial on creating classes, L<perlobj>
+for a hard-core reference document on objects, and L<perlsub> for an
+explanation of functions and scoping.
https://perl5.git.perl.org / perl5.git / blobdiff