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