1PERLMOD(1) Perl Programmers Reference Guide PERLMOD(1)
2
6 perlmod - Perl modules (packages and symbol tables)
7
9 Packages
10 Perl provides a mechanism for alternative namespaces to protect
11 packages from stomping on each other's variables. In fact, there's
12 really no such thing as a global variable in Perl. The package
13 statement declares the compilation unit as being in the given
14 namespace. The scope of the package declaration is from the
15 declaration itself through the end of the enclosing block, "eval", or
16 file, whichever comes first (the same scope as the my() and local()
17 operators). Unqualified dynamic identifiers will be in this namespace,
18 except for those few identifiers that if unqualified, default to the
19 main package instead of the current one as described below. A package
20 statement affects only dynamic variables--including those you've used
21 local() on--but not lexical variables created with my(). Typically it
22 would be the first declaration in a file included by the "do",
23 "require", or "use" operators. You can switch into a package in more
24 than one place; it merely influences which symbol table is used by the
25 compiler for the rest of that block. You can refer to variables and
26 filehandles in other packages by prefixing the identifier with the
27 package name and a double colon: $Package::Variable. If the package
28 name is null, the "main" package is assumed. That is, $::sail is
29 equivalent to $main::sail.
30 The old package delimiter was a single quote, but double colon is now
32 the preferred delimiter, in part because it's more readable to humans,
33 and in part because it's more readable to emacs macros. It also makes
34 C++ programmers feel like they know what's going on--as opposed to
35 using the single quote as separator, which was there to make Ada
36 programmers feel like they knew what was going on. Because the old-
37 fashioned syntax is still supported for backwards compatibility, if you
38 try to use a string like "This is $owner's house", you'll be accessing
39 $owner::s; that is, the $s variable in package "owner", which is
40 probably not what you meant. Use braces to disambiguate, as in "This
41 is ${owner}'s house".
42 Packages may themselves contain package separators, as in
44 $OUTER::INNER::var. This implies nothing about the order of name
45 lookups, however. There are no relative packages: all symbols are
46 either local to the current package, or must be fully qualified from
47 the outer package name down. For instance, there is nowhere within
48 package "OUTER" that $INNER::var refers to $OUTER::INNER::var. "INNER"
49 refers to a totally separate global package.
50 Only identifiers starting with letters (or underscore) are stored in a
52 package's symbol table. All other symbols are kept in package "main",
53 including all punctuation variables, like $_. In addition, when
54 unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV,
55 INC, and SIG are forced to be in package "main", even when used for
56 other purposes than their built-in ones. If you have a package called
57 "m", "s", or "y", then you can't use the qualified form of an
58 identifier because it would be instead interpreted as a pattern match,
59 a substitution, or a transliteration.
60 Variables beginning with underscore used to be forced into package
62 main, but we decided it was more useful for package writers to be able
63 to use leading underscore to indicate private variables and method
64 names. However, variables and functions named with a single "_", such
65 as $_ and "sub _", are still forced into the package "main". See also
66 "The Syntax of Variable Names" in perlvar.
67 "eval"ed strings are compiled in the package in which the eval() was
69 compiled. (Assignments to $SIG{}, however, assume the signal handler
70 specified is in the "main" package. Qualify the signal handler name if
71 you wish to have a signal handler in a package.) For an example,
72 examine perldb.pl in the Perl library. It initially switches to the
73 "DB" package so that the debugger doesn't interfere with variables in
74 the program you are trying to debug. At various points, however, it
75 temporarily switches back to the "main" package to evaluate various
76 expressions in the context of the "main" package (or wherever you came
77 from). See perldebug.
78 The special symbol "__PACKAGE__" contains the current package, but
80 cannot (easily) be used to construct variable names.
81 See perlsub for other scoping issues related to my() and local(), and
83 perlref regarding closures.
84 Symbol Tables
86 The symbol table for a package happens to be stored in the hash of that
87 name with two colons appended. The main symbol table's name is thus
88 %main::, or %:: for short. Likewise the symbol table for the nested
89 package mentioned earlier is named %OUTER::INNER::.
90 The value in each entry of the hash is what you are referring to when
92 you use the *name typeglob notation.
93 local *main::foo = *main::bar;
95 You can use this to print out all the variables in a package, for
97 instance. The standard but antiquated dumpvar.pl library and the CPAN
98 module Devel::Symdump make use of this.
99 The results of creating new symbol table entries directly or modifying
101 any entries that are not already typeglobs are undefined and subject to
102 change between releases of perl.
103 Assignment to a typeglob performs an aliasing operation, i.e.,
105 *dick = *richard;
107 causes variables, subroutines, formats, and file and directory handles
109 accessible via the identifier "richard" also to be accessible via the
110 identifier "dick". If you want to alias only a particular variable or
111 subroutine, assign a reference instead:
112 *dick = \$richard;
114 Which makes $richard and $dick the same variable, but leaves @richard
116 and @dick as separate arrays. Tricky, eh?
117 There is one subtle difference between the following statements:
119 *foo = *bar;
121 *foo = \$bar;
122 "*foo = *bar" makes the typeglobs themselves synonymous while "*foo =
124 \$bar" makes the SCALAR portions of two distinct typeglobs refer to the
125 same scalar value. This means that the following code:
126 $bar = 1;
128 *foo = \$bar; # Make $foo an alias for $bar
129 {
131 local $bar = 2; # Restrict changes to block
132 print $foo; # Prints '1'!
133 }
134 Would print '1', because $foo holds a reference to the original $bar.
136 The one that was stuffed away by "local()" and which will be restored
137 when the block ends. Because variables are accessed through the
138 typeglob, you can use "*foo = *bar" to create an alias which can be
139 localized. (But be aware that this means you can't have a separate @foo
140 and @bar, etc.)
141 What makes all of this important is that the Exporter module uses glob
143 aliasing as the import/export mechanism. Whether or not you can
144 properly localize a variable that has been exported from a module
145 depends on how it was exported:
146 @EXPORT = qw($FOO); # Usual form, can't be localized
148 @EXPORT = qw(*FOO); # Can be localized
149 You can work around the first case by using the fully qualified name
151 ($Package::FOO) where you need a local value, or by overriding it by
152 saying "*FOO = *Package::FOO" in your script.
153 The "*x = \$y" mechanism may be used to pass and return cheap
155 references into or from subroutines if you don't want to copy the whole
156 thing. It only works when assigning to dynamic variables, not
157 lexicals.
158 %some_hash = (); # can't be my()
160 *some_hash = fn( \%another_hash );
161 sub fn {
162 local *hashsym = shift;
163 # now use %hashsym normally, and you
164 # will affect the caller's %another_hash
165 my %nhash = (); # do what you want
166 return \%nhash;
167 }
168 On return, the reference will overwrite the hash slot in the symbol
170 table specified by the *some_hash typeglob. This is a somewhat tricky
171 way of passing around references cheaply when you don't want to have to
172 remember to dereference variables explicitly.
173 Another use of symbol tables is for making "constant" scalars.
175 *PI = \3.14159265358979;
177 Now you cannot alter $PI, which is probably a good thing all in all.
179 This isn't the same as a constant subroutine, which is subject to
180 optimization at compile-time. A constant subroutine is one prototyped
181 to take no arguments and to return a constant expression. See perlsub
182 for details on these. The "use constant" pragma is a convenient
183 shorthand for these.
184 You can say *foo{PACKAGE} and *foo{NAME} to find out what name and
186 package the *foo symbol table entry comes from. This may be useful in
187 a subroutine that gets passed typeglobs as arguments:
188 sub identify_typeglob {
190 my $glob = shift;
191 print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
192 }
193 identify_typeglob *foo;
194 identify_typeglob *bar::baz;
195 This prints
197 You gave me main::foo
199 You gave me bar::baz
200 The *foo{THING} notation can also be used to obtain references to the
202 individual elements of *foo. See perlref.
203 Subroutine definitions (and declarations, for that matter) need not
205 necessarily be situated in the package whose symbol table they occupy.
206 You can define a subroutine outside its package by explicitly
207 qualifying the name of the subroutine:
208 package main;
210 sub Some_package::foo { ... } # &foo defined in Some_package
211 This is just a shorthand for a typeglob assignment at compile time:
213 BEGIN { *Some_package::foo = sub { ... } }
215 and is not the same as writing:
217 {
219 package Some_package;
220 sub foo { ... }
221 }
222 In the first two versions, the body of the subroutine is lexically in
224 the main package, not in Some_package. So something like this:
225 package main;
227 $Some_package::name = "fred";
229 $main::name = "barney";
230 sub Some_package::foo {
232 print "in ", __PACKAGE__, ": \$name is '$name'\n";
233 }
234 Some_package::foo();
236 prints:
238 in main: $name is 'barney'
240 rather than:
242 in Some_package: $name is 'fred'
244 This also has implications for the use of the SUPER:: qualifier (see
246 perlobj).
247 BEGIN, UNITCHECK, CHECK, INIT and END
249 Five specially named code blocks are executed at the beginning and at
250 the end of a running Perl program. These are the "BEGIN", "UNITCHECK",
251 "CHECK", "INIT", and "END" blocks.
252 These code blocks can be prefixed with "sub" to give the appearance of
254 a subroutine (although this is not considered good style). One should
255 note that these code blocks don't really exist as named subroutines
256 (despite their appearance). The thing that gives this away is the fact
257 that you can have more than one of these code blocks in a program, and
258 they will get all executed at the appropriate moment. So you can't
259 execute any of these code blocks by name.
260 A "BEGIN" code block is executed as soon as possible, that is, the
262 moment it is completely defined, even before the rest of the containing
263 file (or string) is parsed. You may have multiple "BEGIN" blocks
264 within a file (or eval'ed string); they will execute in order of
265 definition. Because a "BEGIN" code block executes immediately, it can
266 pull in definitions of subroutines and such from other files in time to
267 be visible to the rest of the compile and run time. Once a "BEGIN" has
268 run, it is immediately undefined and any code it used is returned to
269 Perl's memory pool.
270 An "END" code block is executed as late as possible, that is, after
272 perl has finished running the program and just before the interpreter
273 is being exited, even if it is exiting as a result of a die() function.
274 (But not if it's morphing into another program via "exec", or being
275 blown out of the water by a signal--you have to trap that yourself (if
276 you can).) You may have multiple "END" blocks within a file--they will
277 execute in reverse order of definition; that is: last in, first out
278 (LIFO). "END" blocks are not executed when you run perl with the "-c"
279 switch, or if compilation fails.
280 Note that "END" code blocks are not executed at the end of a string
282 "eval()": if any "END" code blocks are created in a string "eval()",
283 they will be executed just as any other "END" code block of that
284 package in LIFO order just before the interpreter is being exited.
285 Inside an "END" code block, $? contains the value that the program is
287 going to pass to "exit()". You can modify $? to change the exit value
288 of the program. Beware of changing $? by accident (e.g. by running
289 something via "system").
290 Inside of a "END" block, the value of "${^GLOBAL_PHASE}" will be "END".
292 "UNITCHECK", "CHECK" and "INIT" code blocks are useful to catch the
294 transition between the compilation phase and the execution phase of the
295 main program.
296 "UNITCHECK" blocks are run just after the unit which defined them has
298 been compiled. The main program file and each module it loads are
299 compilation units, as are string "eval"s, code compiled using the "(?{
300 })" construct in a regex, calls to "do FILE", "require FILE", and code
301 after the "-e" switch on the command line.
302 "BEGIN" and "UNITCHECK" blocks are not directly related to the phase of
304 the interpreter. They can be created and executed during any phase.
305 "CHECK" code blocks are run just after the initial Perl compile phase
307 ends and before the run time begins, in LIFO order. "CHECK" code
308 blocks are used in the Perl compiler suite to save the compiled state
309 of the program.
310 Inside of a "CHECK" block, the value of "${^GLOBAL_PHASE}" will be
312 "CHECK".
313 "INIT" blocks are run just before the Perl runtime begins execution, in
315 "first in, first out" (FIFO) order.
316 Inside of an "INIT" block, the value of "${^GLOBAL_PHASE}" will be
318 "INIT".
319 The "CHECK" and "INIT" blocks in code compiled by "require", string
321 "do", or string "eval" will not be executed if they occur after the end
322 of the main compilation phase; that can be a problem in mod_perl and
323 other persistent environments which use those functions to load code at
324 runtime.
325 When you use the -n and -p switches to Perl, "BEGIN" and "END" work
327 just as they do in awk, as a degenerate case. Both "BEGIN" and "CHECK"
328 blocks are run when you use the -c switch for a compile-only syntax
329 check, although your main code is not.
330 The begincheck program makes it all clear, eventually:
332 #!/usr/bin/perl
334 # begincheck
336 print "10. Ordinary code runs at runtime.\n";
338 END { print "16. So this is the end of the tale.\n" }
340 INIT { print " 7. INIT blocks run FIFO just before runtime.\n" }
341 UNITCHECK {
342 print " 4. And therefore before any CHECK blocks.\n"
343 }
344 CHECK { print " 6. So this is the sixth line.\n" }
345 print "11. It runs in order, of course.\n";
347 BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
349 END { print "15. Read perlmod for the rest of the story.\n" }
350 CHECK { print " 5. CHECK blocks run LIFO after all compilation.\n" }
351 INIT { print " 8. Run this again, using Perl's -c switch.\n" }
352 print "12. This is anti-obfuscated code.\n";
354 END { print "14. END blocks run LIFO at quitting time.\n" }
356 BEGIN { print " 2. So this line comes out second.\n" }
357 UNITCHECK {
358 print " 3. UNITCHECK blocks run LIFO after each file is compiled.\n"
359 }
360 INIT { print " 9. You'll see the difference right away.\n" }
361 print "13. It merely _looks_ like it should be confusing.\n";
363 __END__
365 Perl Classes
367 There is no special class syntax in Perl, but a package may act as a
368 class if it provides subroutines to act as methods. Such a package may
369 also derive some of its methods from another class (package) by listing
370 the other package name(s) in its global @ISA array (which must be a
371 package global, not a lexical).
372 For more on this, see perlootut and perlobj.
374 Perl Modules
376 A module is just a set of related functions in a library file, i.e., a
377 Perl package with the same name as the file. It is specifically
378 designed to be reusable by other modules or programs. It may do this
379 by providing a mechanism for exporting some of its symbols into the
380 symbol table of any package using it, or it may function as a class
381 definition and make its semantics available implicitly through method
382 calls on the class and its objects, without explicitly exporting
383 anything. Or it can do a little of both.
384 For example, to start a traditional, non-OO module called Some::Module,
386 create a file called Some/Module.pm and start with this template:
387 package Some::Module; # assumes Some/Module.pm
389 use strict;
391 use warnings;
392 BEGIN {
394 require Exporter;
395 # set the version for version checking
397 our $VERSION = 1.00;
398 # Inherit from Exporter to export functions and variables
400 our @ISA = qw(Exporter);
401 # Functions and variables which are exported by default
403 our @EXPORT = qw(func1 func2);
404 # Functions and variables which can be optionally exported
406 our @EXPORT_OK = qw($Var1 %Hashit func3);
407 }
408 # exported package globals go here
410 our $Var1 = '';
411 our %Hashit = ();
412 # non-exported package globals go here
414 # (they are still accessible as $Some::Module::stuff)
415 our @more = ();
416 our $stuff = '';
417 # file-private lexicals go here, before any functions which use them
419 my $priv_var = '';
420 my %secret_hash = ();
421 # here's a file-private function as a closure,
423 # callable as $priv_func->();
424 my $priv_func = sub {
425 ...
426 };
427 # make all your functions, whether exported or not;
429 # remember to put something interesting in the {} stubs
430 sub func1 { ... }
431 sub func2 { ... }
432 # this one isn't exported, but could be called directly
434 # as Some::Module::func3()
435 sub func3 { ... }
436 END { ... } # module clean-up code here (global destructor)
438 1; # don't forget to return a true value from the file
440 Then go on to declare and use your variables in functions without any
442 qualifications. See Exporter and the perlmodlib for details on
443 mechanics and style issues in module creation.
444 Perl modules are included into your program by saying
446 use Module;
448 or
450 use Module LIST;
452 This is exactly equivalent to
454 BEGIN { require 'Module.pm'; 'Module'->import; }
456 or
458 BEGIN { require 'Module.pm'; 'Module'->import( LIST ); }
460 As a special case
462 use Module ();
464 is exactly equivalent to
466 BEGIN { require 'Module.pm'; }
468 All Perl module files have the extension .pm. The "use" operator
470 assumes this so you don't have to spell out "Module.pm" in quotes.
471 This also helps to differentiate new modules from old .pl and .ph
472 files. Module names are also capitalized unless they're functioning as
473 pragmas; pragmas are in effect compiler directives, and are sometimes
474 called "pragmatic modules" (or even "pragmata" if you're a classicist).
475 The two statements:
477 require SomeModule;
479 require "SomeModule.pm";
480 differ from each other in two ways. In the first case, any double
482 colons in the module name, such as "Some::Module", are translated into
483 your system's directory separator, usually "/". The second case does
484 not, and would have to be specified literally. The other difference is
485 that seeing the first "require" clues in the compiler that uses of
486 indirect object notation involving "SomeModule", as in "$ob = purge
487 SomeModule", are method calls, not function calls. (Yes, this really
488 can make a difference.)
489 Because the "use" statement implies a "BEGIN" block, the importing of
491 semantics happens as soon as the "use" statement is compiled, before
492 the rest of the file is compiled. This is how it is able to function
493 as a pragma mechanism, and also how modules are able to declare
494 subroutines that are then visible as list or unary operators for the
495 rest of the current file. This will not work if you use "require"
496 instead of "use". With "require" you can get into this problem:
497 require Cwd; # make Cwd:: accessible
499 $here = Cwd::getcwd();
500 use Cwd; # import names from Cwd::
502 $here = getcwd();
503 require Cwd; # make Cwd:: accessible
505 $here = getcwd(); # oops! no main::getcwd()
506 In general, "use Module ()" is recommended over "require Module",
508 because it determines module availability at compile time, not in the
509 middle of your program's execution. An exception would be if two
510 modules each tried to "use" each other, and each also called a function
511 from that other module. In that case, it's easy to use "require"
512 instead.
513 Perl packages may be nested inside other package names, so we can have
515 package names containing "::". But if we used that package name
516 directly as a filename it would make for unwieldy or impossible
517 filenames on some systems. Therefore, if a module's name is, say,
518 "Text::Soundex", then its definition is actually found in the library
519 file Text/Soundex.pm.
520 Perl modules always have a .pm file, but there may also be dynamically
522 linked executables (often ending in .so) or autoloaded subroutine
523 definitions (often ending in .al) associated with the module. If so,
524 these will be entirely transparent to the user of the module. It is
525 the responsibility of the .pm file to load (or arrange to autoload) any
526 additional functionality. For example, although the POSIX module
527 happens to do both dynamic loading and autoloading, the user can say
528 just "use POSIX" to get it all.
529 Making your module threadsafe
531 Since 5.6.0, Perl has had support for a new type of threads called
532 interpreter threads (ithreads). These threads can be used explicitly
533 and implicitly.
534 Ithreads work by cloning the data tree so that no data is shared
536 between different threads. These threads can be used by using the
537 "threads" module or by doing fork() on win32 (fake fork() support).
538 When a thread is cloned all Perl data is cloned, however non-Perl data
539 cannot be cloned automatically. Perl after 5.7.2 has support for the
540 "CLONE" special subroutine. In "CLONE" you can do whatever you need to
541 do, like for example handle the cloning of non-Perl data, if necessary.
542 "CLONE" will be called once as a class method for every package that
543 has it defined (or inherits it). It will be called in the context of
544 the new thread, so all modifications are made in the new area.
545 Currently CLONE is called with no parameters other than the invocant
546 package name, but code should not assume that this will remain
547 unchanged, as it is likely that in future extra parameters will be
548 passed in to give more information about the state of cloning.
549 If you want to CLONE all objects you will need to keep track of them
551 per package. This is simply done using a hash and
552 Scalar::Util::weaken().
553 Perl after 5.8.7 has support for the "CLONE_SKIP" special subroutine.
555 Like "CLONE", "CLONE_SKIP" is called once per package; however, it is
556 called just before cloning starts, and in the context of the parent
557 thread. If it returns a true value, then no objects of that class will
558 be cloned; or rather, they will be copied as unblessed, undef values.
559 For example: if in the parent there are two references to a single
560 blessed hash, then in the child there will be two references to a
561 single undefined scalar value instead. This provides a simple
562 mechanism for making a module threadsafe; just add "sub CLONE_SKIP { 1
563 }" at the top of the class, and "DESTROY()" will now only be called
564 once per object. Of course, if the child thread needs to make use of
565 the objects, then a more sophisticated approach is needed.
566 Like "CLONE", "CLONE_SKIP" is currently called with no parameters other
568 than the invocant package name, although that may change. Similarly, to
569 allow for future expansion, the return value should be a single 0 or 1
570 value.
571
573 See perlmodlib for general style issues related to building Perl
574 modules and classes, as well as descriptions of the standard library
575 and CPAN, Exporter for how Perl's standard import/export mechanism
576 works, perlootut and perlobj for in-depth information on creating
577 classes, perlobj for a hard-core reference document on objects, perlsub
578 for an explanation of functions and scoping, and perlxstut and perlguts
579 for more information on writing extension modules.
580perl v5.16.3 2013-03-04 PERLMOD(1)