This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
ignore dotfiles (.cvsignore etc) in test (from Warren Jones
[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
9263d47b
GS
168Subroutine definitions (and declarations, for that matter) need
169not necessarily be situated in the package whose symbol table they
170occupy. You can define a subroutine outside its package by
171explicitly qualifying the name of the subroutine:
172
173 package main;
174 sub Some_package::foo { ... } # &foo defined in Some_package
175
176This is just a shorthand for a typeglob assignment at compile time:
177
178 BEGIN { *Some_package::foo = sub { ... } }
179
180and is I<not> the same as writing:
181
182 {
183 package Some_package;
184 sub foo { ... }
185 }
186
187In the first two versions, the body of the subroutine is
188lexically in the main package, I<not> in Some_package. So
189something like this:
190
191 package main;
192
193 $Some_package::name = "fred";
194 $main::name = "barney";
195
196 sub Some_package::foo {
197 print "in ", __PACKAGE__, ": \$name is '$name'\n";
198 }
199
200 Some_package::foo();
201
202prints:
203
204 in main: $name is 'barney'
205
206rather than:
207
208 in Some_package: $name is 'fred'
209
210This also has implications for the use of the SUPER:: qualifier
211(see L<perlobj>).
212
a0d0e21e
LW
213=head2 Package Constructors and Destructors
214
7d981616 215Four special subroutines act as package constructors and destructors.
7d30b5c4 216These are the C<BEGIN>, C<CHECK>, C<INIT>, and C<END> routines. The
7d981616 217C<sub> is optional for these routines.
a0d0e21e 218
f102b883
TC
219A C<BEGIN> subroutine is executed as soon as possible, that is, the moment
220it is completely defined, even before the rest of the containing file
221is parsed. You may have multiple C<BEGIN> blocks within a file--they
222will execute in order of definition. Because a C<BEGIN> block executes
223immediately, it can pull in definitions of subroutines and such from other
224files in time to be visible to the rest of the file. Once a C<BEGIN>
225has run, it is immediately undefined and any code it used is returned to
226Perl's memory pool. This means you can't ever explicitly call a C<BEGIN>.
a0d0e21e 227
4f25aa18
GS
228An C<END> subroutine is executed as late as possible, that is, after
229perl has finished running the program and just before the interpreter
230is being exited, even if it is exiting as a result of a die() function.
231(But not if it's polymorphing into another program via C<exec>, or
232being blown out of the water by a signal--you have to trap that yourself
233(if you can).) You may have multiple C<END> blocks within a file--they
234will execute in reverse order of definition; that is: last in, first
235out (LIFO). C<END> blocks are not executed when you run perl with the
236C<-c> switch.
a0d0e21e 237
19799a22 238Inside an C<END> subroutine, C<$?> contains the value that the program is
c36e9b62 239going to pass to C<exit()>. You can modify C<$?> to change the exit
19799a22 240value of the program. Beware of changing C<$?> by accident (e.g. by
c36e9b62
PP
241running something via C<system>).
242
4f25aa18
GS
243Similar to C<BEGIN> blocks, C<INIT> blocks are run just before the
244Perl runtime begins execution, in "first in, first out" (FIFO) order.
245For example, the code generators documented in L<perlcc> make use of
246C<INIT> blocks to initialize and resolve pointers to XSUBs.
247
7d30b5c4 248Similar to C<END> blocks, C<CHECK> blocks are run just after the
4f25aa18 249Perl compile phase ends and before the run time begins, in
7d30b5c4 250LIFO order. C<CHECK> blocks are again useful in the Perl compiler
4f25aa18
GS
251suite to save the compiled state of the program.
252
19799a22 253When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
5a964f20
TC
254C<END> work just as they do in B<awk>, as a degenerate case. As currently
255implemented (and subject to change, since its inconvenient at best),
19799a22 256both C<BEGIN> and<END> blocks are run when you use the B<-c> switch
5a964f20 257for a compile-only syntax check, although your main code is not.
a0d0e21e
LW
258
259=head2 Perl Classes
260
19799a22 261There is no special class syntax in Perl, but a package may act
5a964f20
TC
262as a class if it provides subroutines to act as methods. Such a
263package may also derive some of its methods from another class (package)
19799a22 264by listing the other package name(s) in its global @ISA array (which
5a964f20 265must be a package global, not a lexical).
4633a7c4 266
f102b883 267For more on this, see L<perltoot> and L<perlobj>.
a0d0e21e
LW
268
269=head2 Perl Modules
270
19799a22
GS
271A module is just a set of related function in a library file a Perl
272package with the same name as the file. It is specifically designed
273to be reusable by other modules or programs. It may do this by
274providing a mechanism for exporting some of its symbols into the
275symbol table of any package using it. Or it may function as a class
276definition and make its semantics available implicitly through
277method calls on the class and its objects, without explicitly
278exportating anything. Or it can do a little of both.
a0d0e21e 279
19799a22
GS
280For example, to start a traditional, non-OO module called Some::Module,
281create a file called F<Some/Module.pm> and start with this template:
9607fc9c
PP
282
283 package Some::Module; # assumes Some/Module.pm
284
285 use strict;
9f1b1f2d 286 use warnings;
9607fc9c
PP
287
288 BEGIN {
289 use Exporter ();
77ca0c92 290 our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
9607fc9c
PP
291
292 # set the version for version checking
293 $VERSION = 1.00;
294 # if using RCS/CVS, this may be preferred
295 $VERSION = do { my @r = (q$Revision: 2.21 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; # must be all one line, for MakeMaker
296
297 @ISA = qw(Exporter);
298 @EXPORT = qw(&func1 &func2 &func4);
299 %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
300
301 # your exported package globals go here,
302 # as well as any optionally exported functions
303 @EXPORT_OK = qw($Var1 %Hashit &func3);
304 }
77ca0c92 305 our @EXPORT_OK;
9607fc9c
PP
306
307 # non-exported package globals go here
77ca0c92
LW
308 our @more;
309 our $stuff;
9607fc9c 310
c2611fb3 311 # initialize package globals, first exported ones
9607fc9c
PP
312 $Var1 = '';
313 %Hashit = ();
314
315 # then the others (which are still accessible as $Some::Module::stuff)
316 $stuff = '';
317 @more = ();
318
319 # all file-scoped lexicals must be created before
320 # the functions below that use them.
321
322 # file-private lexicals go here
323 my $priv_var = '';
324 my %secret_hash = ();
325
326 # here's a file-private function as a closure,
327 # callable as &$priv_func; it cannot be prototyped.
328 my $priv_func = sub {
329 # stuff goes here.
330 };
331
332 # make all your functions, whether exported or not;
333 # remember to put something interesting in the {} stubs
334 sub func1 {} # no prototype
335 sub func2() {} # proto'd void
336 sub func3($$) {} # proto'd to 2 scalars
337
338 # this one isn't exported, but could be called!
339 sub func4(\%) {} # proto'd to 1 hash ref
340
341 END { } # module clean-up code here (global destructor)
4633a7c4 342
19799a22
GS
343 ## YOUR CODE GOES HERE
344
345 1; # don't forget to return a true value from the file
346
347Then go on to declare and use your variables in functions without
348any qualifications. See L<Exporter> and the L<perlmodlib> for
349details on mechanics and style issues in module creation.
4633a7c4
LW
350
351Perl modules are included into your program by saying
a0d0e21e
LW
352
353 use Module;
354
355or
356
357 use Module LIST;
358
359This is exactly equivalent to
360
5a964f20 361 BEGIN { require Module; import Module; }
a0d0e21e
LW
362
363or
364
5a964f20 365 BEGIN { require Module; import Module LIST; }
a0d0e21e 366
cb1a09d0
AD
367As a special case
368
369 use Module ();
370
371is exactly equivalent to
372
5a964f20 373 BEGIN { require Module; }
cb1a09d0 374
19799a22
GS
375All Perl module files have the extension F<.pm>. The C<use> operator
376assumes this so you don't have to spell out "F<Module.pm>" in quotes.
377This also helps to differentiate new modules from old F<.pl> and
378F<.ph> files. Module names are also capitalized unless they're
379functioning as pragmas; pragmas are in effect compiler directives,
380and are sometimes called "pragmatic modules" (or even "pragmata"
381if you're a classicist).
a0d0e21e 382
5a964f20
TC
383The two statements:
384
385 require SomeModule;
386 require "SomeModule.pm";
387
388differ from each other in two ways. In the first case, any double
389colons in the module name, such as C<Some::Module>, are translated
390into your system's directory separator, usually "/". The second
19799a22
GS
391case does not, and would have to be specified literally. The other
392difference is that seeing the first C<require> clues in the compiler
393that uses of indirect object notation involving "SomeModule", as
394in C<$ob = purge SomeModule>, are method calls, not function calls.
395(Yes, this really can make a difference.)
396
397Because the C<use> statement implies a C<BEGIN> block, the importing
398of semantics happens as soon as the C<use> statement is compiled,
a0d0e21e
LW
399before the rest of the file is compiled. This is how it is able
400to function as a pragma mechanism, and also how modules are able to
19799a22 401declare subroutines that are then visible as list or unary operators for
a0d0e21e 402the rest of the current file. This will not work if you use C<require>
19799a22 403instead of C<use>. With C<require> you can get into this problem:
a0d0e21e
LW
404
405 require Cwd; # make Cwd:: accessible
54310121 406 $here = Cwd::getcwd();
a0d0e21e 407
5f05dabc 408 use Cwd; # import names from Cwd::
a0d0e21e
LW
409 $here = getcwd();
410
411 require Cwd; # make Cwd:: accessible
412 $here = getcwd(); # oops! no main::getcwd()
413
5a964f20
TC
414In general, C<use Module ()> is recommended over C<require Module>,
415because it determines module availability at compile time, not in the
416middle of your program's execution. An exception would be if two modules
417each tried to C<use> each other, and each also called a function from
418that other module. In that case, it's easy to use C<require>s instead.
cb1a09d0 419
a0d0e21e
LW
420Perl packages may be nested inside other package names, so we can have
421package names containing C<::>. But if we used that package name
422directly as a filename it would makes for unwieldy or impossible
423filenames on some systems. Therefore, if a module's name is, say,
424C<Text::Soundex>, then its definition is actually found in the library
425file F<Text/Soundex.pm>.
426
19799a22
GS
427Perl modules always have a F<.pm> file, but there may also be
428dynamically linked executables (often ending in F<.so>) or autoloaded
429subroutine definitions (often ending in F<.al> associated with the
430module. If so, these will be entirely transparent to the user of
431the module. It is the responsibility of the F<.pm> file to load
432(or arrange to autoload) any additional functionality. For example,
433although the POSIX module happens to do both dynamic loading and
434autoloading, but the user can say just C<use POSIX> to get it all.
a0d0e21e 435
f102b883 436=head1 SEE ALSO
cb1a09d0 437
f102b883 438See L<perlmodlib> for general style issues related to building Perl
19799a22
GS
439modules and classes, as well as descriptions of the standard library
440and CPAN, L<Exporter> for how Perl's standard import/export mechanism
441works, L<perltoot> and L<perltootc> for an in-depth tutorial on
442creating classes, L<perlobj> for a hard-core reference document on
443objects, L<perlsub> for an explanation of functions and scoping,
444and L<perlxstut> and L<perlguts> for more information on writing
445extension modules.