X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlmod.pod;h=6bec46b0287ed487a4938cb86248dab10af76846;hb=40b568c93a31cb8feae8a14551365dff7e76b624;hp=c5ab08a07c1a5ea58a8dd98f5c7cc7636555c440;hpb=4633a7c4bad06b471d9310620b7fe8ddd158cccd;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlmod.pod b/pod/perlmod.pod index c5ab08a..6bec46b 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -1,486 +1,445 @@ =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 others variables. In fact, apart from certain magical -variables, there's really no such thing as a global variable in Perl. -By default, a Perl script starts -compiling into the package known as C
. You can switch namespaces -using the C declaration. The scope of the package declaration is -from the declaration itself to the end of the enclosing block (the same -scope as the local() operator). Typically it would be the first -declaration in a file to be included by the 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 -as 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.) - -Packages may be nested inside other packages: C<$OUTER::INNER::var>. This -implies nothing about the order of name lookups, however. All symbols +Perl provides a mechanism for alternative namespaces to protect +packages from stomping on each other's variables. In fact, 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, C, +or file, whichever comes first (the same scope as the my() and +local() operators). Unqualified dynamic identifiers will be in +this namespace, except for those few identifiers that if unqualified, +default to the main package instead of the current one as described +below. 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 +included by the C, C, or C operators. 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 themselves contain package separators, as in +C<$OUTER::INNER::var>. This implies nothing about the order of +name lookups, however. There are no relative packages: all symbols are either local to the current package, or must be fully qualified from the outer package name down. For instance, there is nowhere -within package C that C<$INNER::var> refers to C<$OUTER::INNER::var>. -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
. -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. - -(Variables beginning with underscore used to be forced into package +within package C that C<$INNER::var> refers to +C<$OUTER::INNER::var>. 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 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 built-in one. If you +have a package called C, C, or C, then you can't use the +qualified form of an identifier because it would be instead interpreted +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 -to use leading underscore to indicate private variables and method names.) +to use leading underscore to indicate private variables and method names. +$_ is still global though. See also L. -Eval()ed strings are compiled in the package in which the eval() was +Ced strings are compiled in the package in which the eval() was compiled. (Assignments to C<$SIG{}>, however, assume the signal handler specified is in the C
package. Qualify the signal handler name if you wish to have a signal handler in a package.) For an example, examine F in the Perl library. It initially switches to the C package so that the debugger doesn't interfere with variables -in the script you are trying to debug. At various points, however, it +in the program you are trying to debug. At various points, however, it 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(), +and L 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 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 the 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 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
. - -Assignment to a typeglob performs an aliasing operation, -i.e., +instance. The standard but antiquated 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 symbol C. If -you only want to alias 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, 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? -=head2 Package Constructors and Destructors - -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. +This mechanism may be used to pass and return cheap references +into or from subroutines if you don't want to copy the whole +thing. It only works when assigning to dynamic variables, not +lexicals. -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). + %some_hash = (); # can't be my() + *some_hash = fn( \%another_hash ); + sub fn { + local *hashsym = shift; + # now use %hashsym normally, and you + # will affect the caller's %another_hash + my %nhash = (); # do what you want + return \%nhash; + } -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. +On return, the reference will overwrite the hash slot in the +symbol table specified by the *some_hash typeglob. This +is a somewhat tricky way of passing around references cheaply +when you don't want to have to remember to dereference variables +explicitly. -=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. - -For more on this, see L. - -=head2 Perl Modules +Another use of symbol tables is for making "constant" scalars. -A module is a just package that is defined in a library file of -the same name, and is designed to be reusable. It may do this by -providing a mechanism for exporting some of its symbols into the symbol -table of any package using it. Or it may function as a class -definition and make its semantics available implicitly through method -calls on the class and its objects, without explicit exportation of any -symbols. Or it can do a little of both. + *PI = \3.14159265358979; -For example, to start a normal module called Fred, create -a file called Fred.pm and put this at the start of it: +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. 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. - package Fred; - require Exporter; - @ISA = qw(Exporter); - @EXPORT = qw(func1 func2); - @EXPORT_OK = qw($sally @listabob %harry func3); +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 that gets passed typeglobs as arguments: -Then go on to declare and use your variables in functions -without any qualifications. -See L and the I for details on -mechanics and style issues in module creation. - -Perl modules are included into your program by saying - - use Module; - -or - - use Module LIST; - -This is exactly equivalent to + sub identify_typeglob { + my $glob = shift; + print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n"; + } + identify_typeglob *foo; + identify_typeglob *bar::baz; - BEGIN { require "Module.pm"; import Module; } +This prints -or - - BEGIN { require "Module.pm"; import Module LIST; } - -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 -helps to differentiate new modules from old F<.pl> and F<.ph> files. -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). - -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 -to function as a pragma mechanism, and also how modules are able to -declare subroutines that are then visible as list operators for -the rest of the current file. This will not work if you use C -instead of C. Therefore, if you're planning on the module altering -your namespace, use C; otherwise, use C. Otherwise you -can get into this problem: - - require Cwd; # make Cwd:: accessible - $here = Cwd::getcwd(); - - use Cwd; # import names from Cwd:: - $here = getcwd(); - - require Cwd; # make Cwd:: accessible - $here = getcwd(); # oops! no main::getcwd() - -Perl packages may be nested inside other package names, so we can have -package names containing C<::>. But if we used that package name -directly as a filename it would makes for unwieldy or impossible -filenames on some systems. Therefore, if a module's name is, say, -C, then its definition is actually found in the library -file F. + You gave me main::foo + You gave me bar::baz -Perl modules always have a F<.pm> file, but there may also be dynamically -linked executables or autoloaded subroutine definitions associated with -the module. If so, these will be entirely transparent to the user of -the module. It is the responsibility of the F<.pm> file to load (or -arrange to autoload) any additional functionality. The POSIX module -happens to do both dynamic loading and autoloading, but the user can -just say C to get it all. +The C<*foo{THING}> notation can also be used to obtain references to the +individual elements of *foo. See L. -For more information on writing extension modules, see L -and L. +Subroutine definitions (and declarations, for that matter) need +not necessarily be situated in the package whose symbol table they +occupy. You can define a subroutine outside its package by +explicitly qualifying the name of the subroutine: -=head1 NOTE + package main; + sub Some_package::foo { ... } # &foo defined in Some_package -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. +This is just a shorthand for a typeglob assignment at compile time: -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 (AKA documentation) may make other -provisions. But then you know when you C that -you're redefining the world and willing to take the consequences. + BEGIN { *Some_package::foo = sub { ... } } -=head1 THE PERL MODULE LIBRARY +and is I the same as writing: -A number of modules are included the 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, so is far from bullet proof. + { + package Some_package; + sub foo { ... } + } -=head2 Pragmatic Modules +In the first two versions, the body of the subroutine is +lexically in the main package, I in Some_package. So +something like this: -They work somewhat like pragmas in that they tend to affect the compilation of -your program, and thus will usually only work well when used within a -C, or C. These are locally scoped, so an inner BLOCK -may countermand any of these by saying + package main; - no integer; - no strict 'refs'; + $Some_package::name = "fred"; + $main::name = "barney"; -which lasts until the end of that BLOCK. + sub Some_package::foo { + print "in ", __PACKAGE__, ": \$name is '$name'\n"; + } -The following programs are defined (and have their own documentation). + Some_package::foo(); -=over 12 +prints: -=item C + in main: $name is 'barney' -Pragma to produce enhanced diagnostics +rather than: -=item C + in Some_package: $name is 'fred' -Pragma to compute arithmetic in integer instead of double +This also has implications for the use of the SUPER:: qualifier +(see L). -=item C - -Pragma to request less of something from the compiler - -=item C - -Pragma to enable stack backtrace on unexpected signals - -=item C - -Pragma to restrict unsafe constructs - -=item C - -Pragma to predeclare sub 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. - -To find out all the modules installed on your system, 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 size, 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. - -=head2 CPAN - -CPAN stands for the Comprehensive Perl Archive Network. This is a globally -replicated collection of all known Perl materials, including hundreds -of unbunded modules. Here are the major categories of modules: - -=over +=head2 Package Constructors and Destructors -=item * -Language Extensions and Documentation Tools +Four special subroutines act as package constructors and destructors. +These are the C, C, 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. 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, after +perl has finished running the program and just before 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). C blocks are not executed when you run perl with the +C<-c> switch, or if compilation fails. + +Inside an C subroutine, C<$?> contains the value that the program is +going to pass to C. You can modify C<$?> to change the exit +value of the program. Beware of changing C<$?> by accident (e.g. by +running something via C). + +Similar to C blocks, C blocks are run just before the +Perl runtime begins execution, in "first in, first out" (FIFO) order. +For example, the code generators documented in L make use of +C blocks to initialize and resolve pointers to XSUBs. + +Similar to C blocks, C blocks are run just after the +Perl compile phase ends and before the run time begins, in +LIFO order. C blocks are again useful in the Perl compiler +suite to save the compiled state of the program. + +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. +Both C and C blocks are run when you use the B<-c> +switch for a compile-only syntax check, although your main code +is not. -=item * -Development Support +=head2 Perl Classes -=item * -Operating System Interfaces +There is no special class syntax in Perl, but a package may act +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(s) in its global @ISA array (which +must be a package global, not a lexical). -=item * -Networking, Device Control (modems) and InterProcess Communication +For more on this, see L and L. -=item * -Data Types and Data Type Utilities +=head2 Perl Modules -=item * -Database Interfaces +A module is just a set of related functions in a library file, i.e., +a Perl package with the same name as the file. It is specifically +designed to be reusable by other modules or programs. It may do this +by providing a mechanism for exporting some of its symbols into the +symbol table of any package using it. Or it may function as a class +definition and make its semantics available implicitly through +method calls on the class and its objects, without explicitly +exporting anything. Or it can do a little of both. -=item * -User Interfaces +For example, to start a traditional, non-OO module called Some::Module, +create a file called F and start with this template: -=item * -Interfaces to / Emulations of Other Programming Languages + package Some::Module; # assumes Some/Module.pm -=item * -File Names, File Systems and File Locking (see also File Handles) + use strict; + use warnings; -=item * -String Processing, Language Text Processing, Parsing and Searching + BEGIN { + use Exporter (); + our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS); -=item * -Option, Argument, Parameter and Configuration File Processing + # 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 -=item * -Internationalization and Locale + @ISA = qw(Exporter); + @EXPORT = qw(&func1 &func2 &func4); + %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ], -=item * -Authentication, Security and Encryption + # your exported package globals go here, + # as well as any optionally exported functions + @EXPORT_OK = qw($Var1 %Hashit &func3); + } + our @EXPORT_OK; -=item * -World Wide Web, HTML, HTTP, CGI, MIME + # non-exported package globals go here + our @more; + our $stuff; -=item * -Server and Daemon Utilities + # initialize package globals, first exported ones + $Var1 = ''; + %Hashit = (); -=item * -Archiving and Compression + # then the others (which are still accessible as $Some::Module::stuff) + $stuff = ''; + @more = (); -=item * -Images, Pixmap and Bitmap Manipulation, Drawing and Graphing + # all file-scoped lexicals must be created before + # the functions below that use them. -=item * -Mail and Usenet News + # file-private lexicals go here + my $priv_var = ''; + my %secret_hash = (); -=item * -Control Flow Utilities (callbacks and exceptions etc) + # here's a file-private function as a closure, + # callable as &$priv_func; it cannot be prototyped. + my $priv_func = sub { + # stuff goes here. + }; -=item * -File Handle and Input/Output Stream Utilities + # 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 -=item * -Miscellaneous Modules + # this one isn't exported, but could be called! + sub func4(\%) {} # proto'd to 1 hash ref -=back + END { } # module clean-up code here (global destructor) -Some of the reguster CPAN sites as of this writing include the following. -You should try to choose one close to you: + ## YOUR CODE GOES HERE -=over + 1; # don't forget to return a true value from the file -=item * -ftp://ftp.sterling.com/programming/languages/perl/ +Then go on to declare and use your variables in functions without +any qualifications. See L and the L for +details on mechanics and style issues in module creation. -=item * -ftp://ftp.sedl.org/pub/mirrors/CPAN/ +Perl modules are included into your program by saying -=item * -ftp://ftp.uoknor.edu/mirrors/CPAN/ + use Module; -=item * -ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/ +or -=item * -ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/ + use Module LIST; -=item * -ftp://ftp.cis.ufl.edu/pub/perl/CPAN/ +This is exactly equivalent to -=item * -ftp://ftp.switch.ch/mirror/CPAN/ + BEGIN { require Module; import Module; } -=item * -ftp://ftp.sunet.se/pub/lang/perl/CPAN/ +or -=item * -ftp://ftp.ci.uminho.pt/pub/lang/perl/ + BEGIN { require Module; import Module LIST; } -=item * -ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/ +As a special case -=item * -ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ + use Module (); -=item * -ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/ +is exactly equivalent to -=item * -ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/ + BEGIN { require Module; } -=item * -ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/ +All Perl module files have the extension F<.pm>. The C operator +assumes this so you don't have to spell out "F" in quotes. +This also helps to differentiate new modules from old F<.pl> and +F<.ph> files. 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). -=item * -ftp://ftp.ibp.fr/pub/perl/CPAN/ +The two statements: -=item * -ftp://ftp.funet.fi/pub/languages/perl/CPAN/ + require SomeModule; + require "SomeModule.pm"; -=item * -ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/ +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.) -=item * -ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/ +Because the C statement implies a C block, the importing +of semantics happens as soon as the C statement is compiled, +before the rest of the file is compiled. This is how it is able +to function as a pragma mechanism, and also how modules are able to +declare subroutines that are then visible as list or unary operators for +the rest of the current file. This will not work if you use C +instead of C. With C you can get into this problem: -=item * -ftp://coombs.anu.edu.au/pub/perl/ + require Cwd; # make Cwd:: accessible + $here = Cwd::getcwd(); -=item * -ftp://dongpo.math.ncu.edu.tw/perl/CPAN/ + use Cwd; # import names from Cwd:: + $here = getcwd(); -=item * -ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/ + require Cwd; # make Cwd:: accessible + $here = getcwd(); # oops! no main::getcwd() -=item * -ftp://ftp.is.co.za/programming/perl/CPAN/ +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. -=back +Perl packages may be nested inside other package names, so we can have +package names containing C<::>. But if we used that package name +directly as a filename it would make for unwieldy or impossible +filenames on some systems. Therefore, if a module's name is, say, +C, then its definition is actually found in the library +file F. -For an up-to-date listing of CPAN sites, -see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/. +Perl modules always have a F<.pm> file, but there may also be +dynamically linked executables (often ending in F<.so>) or autoloaded +subroutine definitions (often ending in F<.al>) associated with the +module. If so, these will be entirely transparent to the user of +the module. It is the responsibility of the F<.pm> file to load +(or arrange to autoload) any additional functionality. For example, +although the POSIX module happens to do both dynamic loading and +autoloading, the user can say just C to get it all. + +=head1 SEE ALSO + +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 and L for an in-depth tutorial on +creating classes, L for a hard-core reference document on +objects, L for an explanation of functions and scoping, +and L and L for more information on writing +extension modules.