perlmod(1)

1PERLMOD(1)             Perl Programmers Reference Guide             PERLMOD(1)
2
3
4

NAME

6       perlmod - Perl modules (packages and symbol tables)
7

DESCRIPTION

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

NAME

DESCRIPTION

SEE ALSO