3 perlmod - Perl modules (packages and symbol tables)
7 =head2 Is this the document you were after?
9 There are other documents which might contain the information that you're
16 Perl's packages, namespaces, and some info on classes.
20 Tutorial on making a new module.
24 Best practices for making a new module.
29 X<package> X<namespace> X<variable, global> X<global variable> X<global>
31 Unlike Perl 4, in which all the variables were dynamic and shared one
32 global name space, causing maintainability problems, Perl 5 provides two
33 mechanisms for protecting code from having its variables stomped on by
34 other code: lexical variables created with C<my>, C<our> or C<state> and
35 the C<package> declaration which instructs the compiler as to which
36 namespace to prefix to unqualified dynamic names, which both protects
37 against accidental stomping and provides an interface for deliberately
38 clobbering global dynamic variables declared and used in other scopes or
39 packages, when that is what you want to do.
40 The scope of the package declaration is from the
41 declaration itself through the end of the enclosing block, C<eval>,
42 or file, whichever comes first (the same scope as the my(), our(), state(), and
43 local() operators, and also the effect
44 of the experimental "reference aliasing," which may change), or until
45 the next C<package> declaration. Unqualified dynamic identifiers will be in
46 this namespace, except for those few identifiers that, if unqualified,
47 default to the main package instead of the current one as described
48 below. A package statement affects only dynamic global
49 symbols, including subroutine names, and variables you've used local()
50 on, but I<not> lexical variables created with my(), our() or state().
51 Typically it is the first declaration in a file
52 included by the C<do>, C<require>, or C<use> operators. You can
53 switch into a package in more than one place: C<package> has no
54 effect beyond specifying which symbol table the compiler will use for
55 dynamic symbols for the rest of that block or until the next C<package> statement.
56 You can refer to variables and filehandles in other packages
57 by prefixing the identifier with the package name and a double
58 colon: C<$Package::Variable>. If the package name is null, the
59 C<main> package is assumed. That is, C<$::sail> is equivalent to
62 The old package delimiter was a single quote, but double colon is now the
63 preferred delimiter, in part because it's more readable to humans, and
64 in part because it's more readable to B<emacs> macros. It also makes C++
65 programmers feel like they know what's going on--as opposed to using the
66 single quote as separator, which was there to make Ada programmers feel
67 like they knew what was going on. Because the old-fashioned syntax is still
68 supported for backwards compatibility, if you try to use a string like
69 C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
70 the $s variable in package C<owner>, which is probably not what you meant.
71 Use braces to disambiguate, as in C<"This is ${owner}'s house">.
74 Packages may themselves contain package separators, as in
75 C<$OUTER::INNER::var>. This implies nothing about the order of
76 name lookups, however. There are no relative packages: all symbols
77 are either local to the current package, or must be fully qualified
78 from the outer package name down. For instance, there is nowhere
79 within package C<OUTER> that C<$INNER::var> refers to
80 C<$OUTER::INNER::var>. C<INNER> refers to a totally
81 separate global package. The custom of treating package names as a
82 hierarchy is very strong, but the language in no way enforces it.
84 Only identifiers starting with letters (or underscore) are stored
85 in a package's symbol table. All other symbols are kept in package
86 C<main>, including all punctuation variables, like $_. In addition,
87 when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
88 ARGVOUT, ENV, INC, and SIG are forced to be in package C<main>,
89 even when used for other purposes than their built-in ones. If you
90 have a package called C<m>, C<s>, or C<y>, then you can't use the
91 qualified form of an identifier because it would be instead interpreted
92 as a pattern match, a substitution, or a transliteration.
93 X<variable, punctuation>
95 Variables beginning with underscore used to be forced into package
96 main, but we decided it was more useful for package writers to be able
97 to use leading underscore to indicate private variables and method names.
98 However, variables and functions named with a single C<_>, such as
99 $_ and C<sub _>, are still forced into the package C<main>. See also
100 L<perlvar/"The Syntax of Variable Names">.
102 C<eval>ed strings are compiled in the package in which the eval() was
103 compiled. (Assignments to C<$SIG{}>, however, assume the signal
104 handler specified is in the C<main> package. Qualify the signal handler
105 name if you wish to have a signal handler in a package.) For an
106 example, examine F<perldb.pl> in the Perl library. It initially switches
107 to the C<DB> package so that the debugger doesn't interfere with variables
108 in the program you are trying to debug. At various points, however, it
109 temporarily switches back to the C<main> package to evaluate various
110 expressions in the context of the C<main> package (or wherever you came
111 from). See L<perldebug>.
113 The special symbol C<__PACKAGE__> contains the current package, but cannot
114 (easily) be used to construct variable names. After C<my($foo)> has hidden
115 package variable C<$foo>, it can still be accessed, without knowing what
116 package you are in, as C<${__PACKAGE__.'::foo'}>.
118 See L<perlsub> for other scoping issues related to my() and local(),
119 and L<perlref> regarding closures.
122 X<symbol table> X<stash> X<%::> X<%main::> X<typeglob> X<glob> X<alias>
124 The symbol table for a package happens to be stored in the hash of that
125 name with two colons appended. The main symbol table's name is thus
126 C<%main::>, or C<%::> for short. Likewise the symbol table for the nested
127 package mentioned earlier is named C<%OUTER::INNER::>.
129 The value in each entry of the hash is what you are referring to when you
130 use the C<*name> typeglob notation.
132 local *main::foo = *main::bar;
134 You can use this to print out all the variables in a package, for
135 instance. The standard but antiquated F<dumpvar.pl> library and
136 the CPAN module Devel::Symdump make use of this.
138 The results of creating new symbol table entries directly or modifying any
139 entries that are not already typeglobs are undefined and subject to change
140 between releases of perl.
142 Assignment to a typeglob performs an aliasing operation, i.e.,
146 causes variables, subroutines, formats, and file and directory handles
147 accessible via the identifier C<richard> also to be accessible via the
148 identifier C<dick>. If you want to alias only a particular variable or
149 subroutine, assign a reference instead:
153 Which makes $richard and $dick the same variable, but leaves
154 @richard and @dick as separate arrays. Tricky, eh?
156 There is one subtle difference between the following statements:
161 C<*foo = *bar> makes the typeglobs themselves synonymous while
162 C<*foo = \$bar> makes the SCALAR portions of two distinct typeglobs
163 refer to the same scalar value. This means that the following code:
166 *foo = \$bar; # Make $foo an alias for $bar
169 local $bar = 2; # Restrict changes to block
170 print $foo; # Prints '1'!
173 Would print '1', because C<$foo> holds a reference to the I<original>
174 C<$bar>. The one that was stuffed away by C<local()> and which will be
175 restored when the block ends. Because variables are accessed through the
176 typeglob, you can use C<*foo = *bar> to create an alias which can be
177 localized. (But be aware that this means you can't have a separate
178 C<@foo> and C<@bar>, etc.)
180 What makes all of this important is that the Exporter module uses glob
181 aliasing as the import/export mechanism. Whether or not you can properly
182 localize a variable that has been exported from a module depends on how
185 @EXPORT = qw($FOO); # Usual form, can't be localized
186 @EXPORT = qw(*FOO); # Can be localized
188 You can work around the first case by using the fully qualified name
189 (C<$Package::FOO>) where you need a local value, or by overriding it
190 by saying C<*FOO = *Package::FOO> in your script.
192 The C<*x = \$y> mechanism may be used to pass and return cheap references
193 into or from subroutines if you don't want to copy the whole
194 thing. It only works when assigning to dynamic variables, not
197 %some_hash = (); # can't be my()
198 *some_hash = fn( \%another_hash );
200 local *hashsym = shift;
201 # now use %hashsym normally, and you
202 # will affect the caller's %another_hash
203 my %nhash = (); # do what you want
207 On return, the reference will overwrite the hash slot in the
208 symbol table specified by the *some_hash typeglob. This
209 is a somewhat tricky way of passing around references cheaply
210 when you don't want to have to remember to dereference variables
213 Another use of symbol tables is for making "constant" scalars.
214 X<constant> X<scalar, constant>
216 *PI = \3.14159265358979;
218 Now you cannot alter C<$PI>, which is probably a good thing all in all.
219 This isn't the same as a constant subroutine, which is subject to
220 optimization at compile-time. A constant subroutine is one prototyped
221 to take no arguments and to return a constant expression. See
222 L<perlsub> for details on these. The C<use constant> pragma is a
223 convenient shorthand for these.
225 You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and
226 package the *foo symbol table entry comes from. This may be useful
227 in a subroutine that gets passed typeglobs as arguments:
229 sub identify_typeglob {
231 print 'You gave me ', *{$glob}{PACKAGE},
232 '::', *{$glob}{NAME}, "\n";
234 identify_typeglob *foo;
235 identify_typeglob *bar::baz;
239 You gave me main::foo
242 The C<*foo{THING}> notation can also be used to obtain references to the
243 individual elements of *foo. See L<perlref>.
245 Subroutine definitions (and declarations, for that matter) need
246 not necessarily be situated in the package whose symbol table they
247 occupy. You can define a subroutine outside its package by
248 explicitly qualifying the name of the subroutine:
251 sub Some_package::foo { ... } # &foo defined in Some_package
253 This is just a shorthand for a typeglob assignment at compile time:
255 BEGIN { *Some_package::foo = sub { ... } }
257 and is I<not> the same as writing:
260 package Some_package;
264 In the first two versions, the body of the subroutine is
265 lexically in the main package, I<not> in Some_package. So
270 $Some_package::name = "fred";
271 $main::name = "barney";
273 sub Some_package::foo {
274 print "in ", __PACKAGE__, ": \$name is '$name'\n";
281 in main: $name is 'barney'
285 in Some_package: $name is 'fred'
287 This also has implications for the use of the SUPER:: qualifier
290 =head2 BEGIN, UNITCHECK, CHECK, INIT and END
291 X<BEGIN> X<UNITCHECK> X<CHECK> X<INIT> X<END>
293 Five specially named code blocks are executed at the beginning and at
294 the end of a running Perl program. These are the C<BEGIN>,
295 C<UNITCHECK>, C<CHECK>, C<INIT>, and C<END> blocks.
297 These code blocks can be prefixed with C<sub> to give the appearance of a
298 subroutine (although this is not considered good style). One should note
299 that these code blocks don't really exist as named subroutines (despite
300 their appearance). The thing that gives this away is the fact that you can
301 have B<more than one> of these code blocks in a program, and they will get
302 B<all> executed at the appropriate moment. So you can't execute any of
303 these code blocks by name.
305 A C<BEGIN> code block is executed as soon as possible, that is, the moment
306 it is completely defined, even before the rest of the containing file (or
307 string) is parsed. You may have multiple C<BEGIN> blocks within a file (or
308 eval'ed string); they will execute in order of definition. Because a C<BEGIN>
309 code block executes immediately, it can pull in definitions of subroutines
310 and such from other files in time to be visible to the rest of the compile
311 and run time. Once a C<BEGIN> has run, it is immediately undefined and any
312 code it used is returned to Perl's memory pool.
314 An C<END> code block is executed as late as possible, that is, after
315 perl has finished running the program and just before the interpreter
316 is being exited, even if it is exiting as a result of a die() function.
317 (But not if it's morphing into another program via C<exec>, or
318 being blown out of the water by a signal--you have to trap that yourself
319 (if you can).) You may have multiple C<END> blocks within a file--they
320 will execute in reverse order of definition; that is: last in, first
321 out (LIFO). C<END> blocks are not executed when you run perl with the
322 C<-c> switch, or if compilation fails.
324 Note that C<END> code blocks are B<not> executed at the end of a string
325 C<eval()>: if any C<END> code blocks are created in a string C<eval()>,
326 they will be executed just as any other C<END> code block of that package
327 in LIFO order just before the interpreter is being exited.
329 Inside an C<END> code block, C<$?> contains the value that the program is
330 going to pass to C<exit()>. You can modify C<$?> to change the exit
331 value of the program. Beware of changing C<$?> by accident (e.g. by
332 running something via C<system>).
335 Inside of a C<END> block, the value of C<${^GLOBAL_PHASE}> will be
338 C<UNITCHECK>, C<CHECK> and C<INIT> code blocks are useful to catch the
339 transition between the compilation phase and the execution phase of
342 C<UNITCHECK> blocks are run just after the unit which defined them has
343 been compiled. The main program file and each module it loads are
344 compilation units, as are string C<eval>s, run-time code compiled using the
345 C<(?{ })> construct in a regex, calls to C<do FILE>, C<require FILE>,
346 and code after the C<-e> switch on the command line.
348 C<BEGIN> and C<UNITCHECK> blocks are not directly related to the phase of
349 the interpreter. They can be created and executed during any phase.
351 C<CHECK> code blocks are run just after the B<initial> Perl compile phase ends
352 and before the run time begins, in LIFO order. C<CHECK> code blocks are used
353 in the Perl compiler suite to save the compiled state of the program.
355 Inside of a C<CHECK> block, the value of C<${^GLOBAL_PHASE}> will be
358 C<INIT> blocks are run just before the Perl runtime begins execution, in
359 "first in, first out" (FIFO) order.
361 Inside of an C<INIT> block, the value of C<${^GLOBAL_PHASE}> will be C<"INIT">.
363 The C<CHECK> and C<INIT> blocks in code compiled by C<require>, string C<do>,
364 or string C<eval> will not be executed if they occur after the end of the
365 main compilation phase; that can be a problem in mod_perl and other persistent
366 environments which use those functions to load code at runtime.
368 When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
369 C<END> work just as they do in B<awk>, as a degenerate case.
370 Both C<BEGIN> and C<CHECK> blocks are run when you use the B<-c>
371 switch for a compile-only syntax check, although your main code
374 The B<begincheck> program makes it all clear, eventually:
380 print "10. Ordinary code runs at runtime.\n";
382 END { print "16. So this is the end of the tale.\n" }
383 INIT { print " 7. INIT blocks run FIFO just before runtime.\n" }
385 print " 4. And therefore before any CHECK blocks.\n"
387 CHECK { print " 6. So this is the sixth line.\n" }
389 print "11. It runs in order, of course.\n";
391 BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
392 END { print "15. Read perlmod for the rest of the story.\n" }
393 CHECK { print " 5. CHECK blocks run LIFO after all compilation.\n" }
394 INIT { print " 8. Run this again, using Perl's -c switch.\n" }
396 print "12. This is anti-obfuscated code.\n";
398 END { print "14. END blocks run LIFO at quitting time.\n" }
399 BEGIN { print " 2. So this line comes out second.\n" }
401 print " 3. UNITCHECK blocks run LIFO after each file is compiled.\n"
403 INIT { print " 9. You'll see the difference right away.\n" }
405 print "13. It only _looks_ like it should be confusing.\n";
412 There is no special class syntax in Perl, but a package may act
413 as a class if it provides subroutines to act as methods. Such a
414 package may also derive some of its methods from another class (package)
415 by listing the other package name(s) in its global @ISA array (which
416 must be a package global, not a lexical).
418 For more on this, see L<perlootut> and L<perlobj>.
423 A module is just a set of related functions in a library file, i.e.,
424 a Perl package with the same name as the file. It is specifically
425 designed to be reusable by other modules or programs. It may do this
426 by providing a mechanism for exporting some of its symbols into the
427 symbol table of any package using it, or it may function as a class
428 definition and make its semantics available implicitly through
429 method calls on the class and its objects, without explicitly
430 exporting anything. Or it can do a little of both.
432 For example, to start a traditional, non-OO module called Some::Module,
433 create a file called F<Some/Module.pm> and start with this template:
435 package Some::Module; # assumes Some/Module.pm
443 # set the version for version checking
446 # Inherit from Exporter to export functions and variables
447 our @ISA = qw(Exporter);
449 # Functions and variables which are exported by default
450 our @EXPORT = qw(func1 func2);
452 # Functions and variables which can be optionally exported
453 our @EXPORT_OK = qw($Var1 %Hashit func3);
456 # exported package globals go here
460 # non-exported package globals go here
461 # (they are still accessible as $Some::Module::stuff)
465 # file-private lexicals go here, before any functions which use them
467 my %secret_hash = ();
469 # here's a file-private function as a closure,
470 # callable as $priv_func->();
471 my $priv_func = sub {
475 # make all your functions, whether exported or not;
476 # remember to put something interesting in the {} stubs
480 # this one isn't exported, but could be called directly
481 # as Some::Module::func3()
484 END { ... } # module clean-up code here (global destructor)
486 1; # don't forget to return a true value from the file
488 Then go on to declare and use your variables in functions without
489 any qualifications. See L<Exporter> and the L<perlmodlib> for
490 details on mechanics and style issues in module creation.
492 Perl modules are included into your program by saying
500 This is exactly equivalent to
502 BEGIN { require 'Module.pm'; 'Module'->import; }
506 BEGIN { require 'Module.pm'; 'Module'->import( LIST ); }
512 is exactly equivalent to
514 BEGIN { require 'Module.pm'; }
516 All Perl module files have the extension F<.pm>. The C<use> operator
517 assumes this so you don't have to spell out "F<Module.pm>" in quotes.
518 This also helps to differentiate new modules from old F<.pl> and
519 F<.ph> files. Module names are also capitalized unless they're
520 functioning as pragmas; pragmas are in effect compiler directives,
521 and are sometimes called "pragmatic modules" (or even "pragmata"
522 if you're a classicist).
527 require "SomeModule.pm";
529 differ from each other in two ways. In the first case, any double
530 colons in the module name, such as C<Some::Module>, are translated
531 into your system's directory separator, usually "/". The second
532 case does not, and would have to be specified literally. The other
533 difference is that seeing the first C<require> clues in the compiler
534 that uses of indirect object notation involving "SomeModule", as
535 in C<$ob = purge SomeModule>, are method calls, not function calls.
536 (Yes, this really can make a difference.)
538 Because the C<use> statement implies a C<BEGIN> block, the importing
539 of semantics happens as soon as the C<use> statement is compiled,
540 before the rest of the file is compiled. This is how it is able
541 to function as a pragma mechanism, and also how modules are able to
542 declare subroutines that are then visible as list or unary operators for
543 the rest of the current file. This will not work if you use C<require>
544 instead of C<use>. With C<require> you can get into this problem:
546 require Cwd; # make Cwd:: accessible
547 $here = Cwd::getcwd();
549 use Cwd; # import names from Cwd::
552 require Cwd; # make Cwd:: accessible
553 $here = getcwd(); # oops! no main::getcwd()
555 In general, C<use Module ()> is recommended over C<require Module>,
556 because it determines module availability at compile time, not in the
557 middle of your program's execution. An exception would be if two modules
558 each tried to C<use> each other, and each also called a function from
559 that other module. In that case, it's easy to use C<require> instead.
561 Perl packages may be nested inside other package names, so we can have
562 package names containing C<::>. But if we used that package name
563 directly as a filename it would make for unwieldy or impossible
564 filenames on some systems. Therefore, if a module's name is, say,
565 C<Text::Soundex>, then its definition is actually found in the library
566 file F<Text/Soundex.pm>.
568 Perl modules always have a F<.pm> file, but there may also be
569 dynamically linked executables (often ending in F<.so>) or autoloaded
570 subroutine definitions (often ending in F<.al>) associated with the
571 module. If so, these will be entirely transparent to the user of
572 the module. It is the responsibility of the F<.pm> file to load
573 (or arrange to autoload) any additional functionality. For example,
574 although the POSIX module happens to do both dynamic loading and
575 autoloading, the user can say just C<use POSIX> to get it all.
577 =head2 Making your module threadsafe
578 X<threadsafe> X<thread safe>
579 X<module, threadsafe> X<module, thread safe>
580 X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread>
582 Perl supports a type of threads called interpreter threads (ithreads).
583 These threads can be used explicitly and implicitly.
585 Ithreads work by cloning the data tree so that no data is shared
586 between different threads. These threads can be used by using the C<threads>
587 module or by doing fork() on win32 (fake fork() support). When a
588 thread is cloned all Perl data is cloned, however non-Perl data cannot
589 be cloned automatically. Perl after 5.8.0 has support for the C<CLONE>
590 special subroutine. In C<CLONE> you can do whatever
592 like for example handle the cloning of non-Perl data, if necessary.
593 C<CLONE> will be called once as a class method for every package that has it
594 defined (or inherits it). It will be called in the context of the new thread,
595 so all modifications are made in the new area. Currently CLONE is called with
596 no parameters other than the invocant package name, but code should not assume
597 that this will remain unchanged, as it is likely that in future extra parameters
598 will be passed in to give more information about the state of cloning.
600 If you want to CLONE all objects you will need to keep track of them per
601 package. This is simply done using a hash and Scalar::Util::weaken().
603 Perl after 5.8.7 has support for the C<CLONE_SKIP> special subroutine.
604 Like C<CLONE>, C<CLONE_SKIP> is called once per package; however, it is
605 called just before cloning starts, and in the context of the parent
606 thread. If it returns a true value, then no objects of that class will
607 be cloned; or rather, they will be copied as unblessed, undef values.
608 For example: if in the parent there are two references to a single blessed
609 hash, then in the child there will be two references to a single undefined
610 scalar value instead.
611 This provides a simple mechanism for making a module threadsafe; just add
612 C<sub CLONE_SKIP { 1 }> at the top of the class, and C<DESTROY()> will
613 now only be called once per object. Of course, if the child thread needs
614 to make use of the objects, then a more sophisticated approach is
617 Like C<CLONE>, C<CLONE_SKIP> is currently called with no parameters other
618 than the invocant package name, although that may change. Similarly, to
619 allow for future expansion, the return value should be a single C<0> or
624 See L<perlmodlib> for general style issues related to building Perl
625 modules and classes, as well as descriptions of the standard library
626 and CPAN, L<Exporter> for how Perl's standard import/export mechanism
627 works, L<perlootut> and L<perlobj> for in-depth information on
628 creating classes, L<perlobj> for a hard-core reference document on
629 objects, L<perlsub> for an explanation of functions and scoping,
630 and L<perlxstut> and L<perlguts> for more information on writing