1=head1 NAME 2 3perlmod - Perl modules (packages and symbol tables) 4 5=head1 DESCRIPTION 6 7=head2 Packages 8 9Perl provides a mechanism for alternative namespaces to protect packages 10from stomping on each other's variables. In fact, apart from certain 11magical variables, there's really no such thing as a global variable 12in Perl. The package statement declares the compilation unit as 13being in the given namespace. The scope of the package declaration 14is from the declaration itself through the end of the enclosing block, 15C<eval>, C<sub>, or end of file, whichever comes first (the same scope 16as the my() and local() operators). All further unqualified dynamic 17identifiers will be in this namespace. A package statement affects 18only dynamic variables--including those you've used local() on--but 19I<not> lexical variables created with my(). Typically it would be 20the first declaration in a file to be included by the C<require> or 21C<use> operator. You can switch into a package in more than one place; 22it influences merely which symbol table is used by the compiler for the 23rest of that block. You can refer to variables and filehandles in other 24packages by prefixing the identifier with the package name and a double 25colon: C<$Package::Variable>. If the package name is null, the C<main> 26package is assumed. That is, C<$::sail> is equivalent to C<$main::sail>. 27 28(The old package delimiter was a single quote, but double colon 29is now the preferred delimiter, in part because it's more readable 30to humans, and in part because it's more readable to B<emacs> macros. 31It also makes C++ programmers feel like they know what's going on.) 32 33Packages may be nested inside other packages: C<$OUTER::INNER::var>. This 34implies nothing about the order of name lookups, however. All symbols 35are either local to the current package, or must be fully qualified 36from the outer package name down. For instance, there is nowhere 37within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>. 38It would treat package C<INNER> as a totally separate global package. 39 40Only identifiers starting with letters (or underscore) are stored in a 41package's symbol table. All other symbols are kept in package C<main>, 42including all of the punctuation variables like $_. In addition, the 43identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC, and SIG are 44forced to be in package C<main>, even when used for other purposes than 45their builtin one. Note also that, if you have a package called C<m>, 46C<s>, or C<y>, then you can't use the qualified form of an identifier 47because it will be interpreted instead as a pattern match, a substitution, 48or a translation. 49 50(Variables beginning with underscore used to be forced into package 51main, but we decided it was more useful for package writers to be able 52to use leading underscore to indicate private variables and method names. 53$_ is still global though.) 54 55Eval()ed strings are compiled in the package in which the eval() was 56compiled. (Assignments to C<$SIG{}>, however, assume the signal 57handler specified is in the C<main> package. Qualify the signal handler 58name if you wish to have a signal handler in a package.) For an 59example, examine F<perldb.pl> in the Perl library. It initially switches 60to the C<DB> package so that the debugger doesn't interfere with variables 61in the script you are trying to debug. At various points, however, it 62temporarily switches back to the C<main> package to evaluate various 63expressions in the context of the C<main> package (or wherever you came 64from). See L<perldebug>. 65 66The special symbol C<__PACKAGE__> contains the current package, but cannot 67(easily) be used to construct variables. 68 69See L<perlsub> for other scoping issues related to my() and local(), 70and L<perlref> regarding closures. 71 72=head2 Symbol Tables 73 74The symbol table for a package happens to be stored in the hash of that 75name with two colons appended. The main symbol table's name is thus 76C<%main::>, or C<%::> for short. Likewise symbol table for the nested 77package mentioned earlier is named C<%OUTER::INNER::>. 78 79The value in each entry of the hash is what you are referring to when you 80use the C<*name> typeglob notation. In fact, the following have the same 81effect, though the first is more efficient because it does the symbol 82table lookups at compile time: 83 84 local *main::foo = *main::bar; 85 local $main::{foo} = $main::{bar}; 86 87You can use this to print out all the variables in a package, for 88instance. Here is F<dumpvar.pl> from the Perl library: 89 90 package dumpvar; 91 sub main::dumpvar { 92 ($package) = @_; 93 local(*stab) = eval("*${package}::"); 94 while (($key,$val) = each(%stab)) { 95 local(*entry) = $val; 96 if (defined $entry) { 97 print "\$$key = '$entry'\n"; 98 } 99 100 if (defined @entry) { 101 print "\@$key = (\n"; 102 foreach $num ($[ .. $#entry) { 103 print " $num\t'",$entry[$num],"'\n"; 104 } 105 print ")\n"; 106 } 107 108 if ($key ne "${package}::" && defined %entry) { 109 print "\%$key = (\n"; 110 foreach $key (sort keys(%entry)) { 111 print " $key\t'",$entry{$key},"'\n"; 112 } 113 print ")\n"; 114 } 115 } 116 } 117 118Note that even though the subroutine is compiled in package C<dumpvar>, 119the name of the subroutine is qualified so that its name is inserted into 120package C<main>. While popular many years ago, this is now considered 121very poor style; in general, you should be writing modules and using the 122normal export mechanism instead of hammering someone else's namespace, 123even main's. 124 125Assignment to a typeglob performs an aliasing operation, i.e., 126 127 *dick = *richard; 128 129causes variables, subroutines, and file handles accessible via the 130identifier C<richard> to also be accessible via the identifier C<dick>. If 131you want to alias only a particular variable or subroutine, you can 132assign a reference instead: 133 134 *dick = \$richard; 135 136makes $richard and $dick the same variable, but leaves 137@richard and @dick as separate arrays. Tricky, eh? 138 139This mechanism may be used to pass and return cheap references 140into or from subroutines if you won't want to copy the whole 141thing. 142 143 %some_hash = (); 144 *some_hash = fn( \%another_hash ); 145 sub fn { 146 local *hashsym = shift; 147 # now use %hashsym normally, and you 148 # will affect the caller's %another_hash 149 my %nhash = (); # do what you want 150 return \%nhash; 151 } 152 153On return, the reference will overwrite the hash slot in the 154symbol table specified by the *some_hash typeglob. This 155is a somewhat tricky way of passing around references cheaply 156when you won't want to have to remember to dereference variables 157explicitly. 158 159Another use of symbol tables is for making "constant" scalars. 160 161 *PI = \3.14159265358979; 162 163Now you cannot alter $PI, which is probably a good thing all in all. 164This isn't the same as a constant subroutine (one prototyped to 165take no arguments and to return a constant expression), which is 166subject to optimization at compile-time. This isn't. See L<perlsub> 167for details on these. 168 169You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and 170package the *foo symbol table entry comes from. This may be useful 171in a subroutine which is passed typeglobs as arguments 172 173 sub identify_typeglob { 174 my $glob = shift; 175 print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n"; 176 } 177 identify_typeglob *foo; 178 identify_typeglob *bar::baz; 179 180This prints 181 182 You gave me main::foo 183 You gave me bar::baz 184 185The *foo{THING} notation can also be used to obtain references to the 186individual elements of *foo, see L<perlref>. 187 188=head2 Package Constructors and Destructors 189 190There are two special subroutine definitions that function as package 191constructors and destructors. These are the C<BEGIN> and C<END> 192routines. The C<sub> is optional for these routines. 193 194A C<BEGIN> subroutine is executed as soon as possible, that is, the moment 195it is completely defined, even before the rest of the containing file 196is parsed. You may have multiple C<BEGIN> blocks within a file--they 197will execute in order of definition. Because a C<BEGIN> block executes 198immediately, it can pull in definitions of subroutines and such from other 199files in time to be visible to the rest of the file. Once a C<BEGIN> 200has run, it is immediately undefined and any code it used is returned to 201Perl's memory pool. This means you can't ever explicitly call a C<BEGIN>. 202 203An C<END> subroutine is executed as late as possible, that is, when the 204interpreter is being exited, even if it is exiting as a result of a 205die() function. (But not if it's is being blown out of the water by a 206signal--you have to trap that yourself (if you can).) You may have 207multiple C<END> blocks within a file--they will execute in reverse 208order of definition; that is: last in, first out (LIFO). 209 210Inside an C<END> subroutine C<$?> contains the value that the script is 211going to pass to C<exit()>. You can modify C<$?> to change the exit 212value of the script. Beware of changing C<$?> by accident (e.g. by 213running something via C<system>). 214 215Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN> 216and C<END> work just as they do in B<awk>, as a degenerate case. 217 218=head2 Perl Classes 219 220There is no special class syntax in Perl, but a package may function 221as a class if it provides subroutines that function as methods. Such a 222package may also derive some of its methods from another class package 223by listing the other package name in its @ISA array. 224 225For more on this, see L<perltoot> and L<perlobj>. 226 227=head2 Perl Modules 228 229A module is just a package that is defined in a library file of 230the same name, and is designed to be reusable. It may do this by 231providing a mechanism for exporting some of its symbols into the symbol 232table of any package using it. Or it may function as a class 233definition and make its semantics available implicitly through method 234calls on the class and its objects, without explicit exportation of any 235symbols. Or it can do a little of both. 236 237For example, to start a normal module called Some::Module, create 238a file called Some/Module.pm and start with this template: 239 240 package Some::Module; # assumes Some/Module.pm 241 242 use strict; 243 244 BEGIN { 245 use Exporter (); 246 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); 247 248 # set the version for version checking 249 $VERSION = 1.00; 250 # if using RCS/CVS, this may be preferred 251 $VERSION = do { my @r = (q$Revision: 2.21 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; # must be all one line, for MakeMaker 252 253 @ISA = qw(Exporter); 254 @EXPORT = qw(&func1 &func2 &func4); 255 %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ], 256 257 # your exported package globals go here, 258 # as well as any optionally exported functions 259 @EXPORT_OK = qw($Var1 %Hashit &func3); 260 } 261 use vars @EXPORT_OK; 262 263 # non-exported package globals go here 264 use vars qw(@more $stuff); 265 266 # initalize package globals, first exported ones 267 $Var1 = ''; 268 %Hashit = (); 269 270 # then the others (which are still accessible as $Some::Module::stuff) 271 $stuff = ''; 272 @more = (); 273 274 # all file-scoped lexicals must be created before 275 # the functions below that use them. 276 277 # file-private lexicals go here 278 my $priv_var = ''; 279 my %secret_hash = (); 280 281 # here's a file-private function as a closure, 282 # callable as &$priv_func; it cannot be prototyped. 283 my $priv_func = sub { 284 # stuff goes here. 285 }; 286 287 # make all your functions, whether exported or not; 288 # remember to put something interesting in the {} stubs 289 sub func1 {} # no prototype 290 sub func2() {} # proto'd void 291 sub func3($$) {} # proto'd to 2 scalars 292 293 # this one isn't exported, but could be called! 294 sub func4(\%) {} # proto'd to 1 hash ref 295 296 END { } # module clean-up code here (global destructor) 297 298Then go on to declare and use your variables in functions 299without any qualifications. 300See L<Exporter> and the L<perlmodlib> for details on 301mechanics and style issues in module creation. 302 303Perl modules are included into your program by saying 304 305 use Module; 306 307or 308 309 use Module LIST; 310 311This is exactly equivalent to 312 313 BEGIN { require "Module.pm"; import Module; } 314 315or 316 317 BEGIN { require "Module.pm"; import Module LIST; } 318 319As a special case 320 321 use Module (); 322 323is exactly equivalent to 324 325 BEGIN { require "Module.pm"; } 326 327All Perl module files have the extension F<.pm>. C<use> assumes this so 328that you don't have to spell out "F<Module.pm>" in quotes. This also 329helps to differentiate new modules from old F<.pl> and F<.ph> files. 330Module names are also capitalized unless they're functioning as pragmas, 331"Pragmas" are in effect compiler directives, and are sometimes called 332"pragmatic modules" (or even "pragmata" if you're a classicist). 333 334Because the C<use> statement implies a C<BEGIN> block, the importation 335of semantics happens at the moment the C<use> statement is compiled, 336before the rest of the file is compiled. This is how it is able 337to function as a pragma mechanism, and also how modules are able to 338declare subroutines that are then visible as list operators for 339the rest of the current file. This will not work if you use C<require> 340instead of C<use>. With require you can get into this problem: 341 342 require Cwd; # make Cwd:: accessible 343 $here = Cwd::getcwd(); 344 345 use Cwd; # import names from Cwd:: 346 $here = getcwd(); 347 348 require Cwd; # make Cwd:: accessible 349 $here = getcwd(); # oops! no main::getcwd() 350 351In general C<use Module ();> is recommended over C<require Module;>. 352 353Perl packages may be nested inside other package names, so we can have 354package names containing C<::>. But if we used that package name 355directly as a filename it would makes for unwieldy or impossible 356filenames on some systems. Therefore, if a module's name is, say, 357C<Text::Soundex>, then its definition is actually found in the library 358file F<Text/Soundex.pm>. 359 360Perl modules always have a F<.pm> file, but there may also be dynamically 361linked executables or autoloaded subroutine definitions associated with 362the module. If so, these will be entirely transparent to the user of 363the module. It is the responsibility of the F<.pm> file to load (or 364arrange to autoload) any additional functionality. The POSIX module 365happens to do both dynamic loading and autoloading, but the user can 366say just C<use POSIX> to get it all. 367 368For more information on writing extension modules, see L<perlxstut> 369and L<perlguts>. 370 371=head1 SEE ALSO 372 373See L<perlmodlib> for general style issues related to building Perl 374modules and classes as well as descriptions of the standard library and 375CPAN, L<Exporter> for how Perl's standard import/export mechanism works, 376L<perltoot> for an in-depth tutorial on creating classes, L<perlobj> 377for a hard-core reference document on objects, and L<perlsub> for an 378explanation of functions and scoping. 379