1N/Aperlmod - Perl modules (packages and symbol tables)
1N/APerl provides a mechanism for alternative namespaces to protect
1N/Apackages from stomping on each other's variables. In fact, there's
1N/Areally no such thing as a global variable in Perl. The package
1N/Astatement declares the compilation unit as being in the given
1N/Anamespace. The scope of the package declaration is from the
1N/Adeclaration itself through the end of the enclosing block, C<eval>,
1N/Aor file, whichever comes first (the same scope as the my() and
1N/Alocal() operators). Unqualified dynamic identifiers will be in
1N/Athis namespace, except for those few identifiers that if unqualified,
1N/Adefault to the main package instead of the current one as described
1N/Abelow. A package statement affects only dynamic variables--including
1N/Athose you've used local() on--but I<not> lexical variables created
1N/Awith my(). Typically it would be the first declaration in a file
1N/Aincluded by the C<do>, C<require>, or C<use> operators. You can
1N/Aswitch into a package in more than one place; it merely influences
1N/Awhich symbol table is used by the compiler for the rest of that
1N/Ablock. You can refer to variables and filehandles in other packages
1N/Aby prefixing the identifier with the package name and a double
1N/Acolon: C<$Package::Variable>. If the package name is null, the
1N/AC<main> package is assumed. That is, C<$::sail> is equivalent to
1N/AThe old package delimiter was a single quote, but double colon is now the
1N/Apreferred delimiter, in part because it's more readable to humans, and
1N/Ain part because it's more readable to B<emacs> macros. It also makes C++
1N/Aprogrammers feel like they know what's going on--as opposed to using the
1N/Asingle quote as separator, which was there to make Ada programmers feel
1N/Alike they knew what was going on. Because the old-fashioned syntax is still
1N/Asupported for backwards compatibility, if you try to use a string like
1N/AC<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
1N/Athe $s variable in package C<owner>, which is probably not what you meant.
1N/AUse braces to disambiguate, as in C<"This is ${owner}'s house">.
1N/APackages may themselves contain package separators, as in
1N/AC<$OUTER::INNER::var>. This implies nothing about the order of
1N/Aname lookups, however. There are no relative packages: all symbols
1N/Aare either local to the current package, or must be fully qualified
1N/Afrom the outer package name down. For instance, there is nowhere
1N/Awithin package C<OUTER> that C<$INNER::var> refers to
1N/AC<$OUTER::INNER::var>. C<INNER> refers to a totally
1N/Aseparate global package.
1N/AOnly identifiers starting with letters (or underscore) are stored
1N/Ain a package's symbol table. All other symbols are kept in package
1N/AC<main>, including all punctuation variables, like $_. In addition,
1N/Awhen unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
1N/AARGVOUT, ENV, INC, and SIG are forced to be in package C<main>,
1N/Aeven when used for other purposes than their built-in ones. If you
1N/Ahave a package called C<m>, C<s>, or C<y>, then you can't use the
1N/Aqualified form of an identifier because it would be instead interpreted
1N/Aas a pattern match, a substitution, or a transliteration.
1N/AVariables beginning with underscore used to be forced into package
1N/Amain, but we decided it was more useful for package writers to be able
1N/Ato use leading underscore to indicate private variables and method names.
1N/AHowever, variables and functions named with a single C<_>, such as
1N/A$_ and C<sub _>, are still forced into the package C<main>. See also
1N/AL<perlvar/"Technical Note on the Syntax of Variable Names">.
1N/AC<eval>ed strings are compiled in the package in which the eval() was
1N/Acompiled. (Assignments to C<$SIG{}>, however, assume the signal
1N/Ahandler specified is in the C<main> package. Qualify the signal handler
1N/Aname if you wish to have a signal handler in a package.) For an
1N/Aexample, examine F<
perldb.pl> in the Perl library. It initially switches
1N/Ato the C<DB> package so that the debugger doesn't interfere with variables
1N/Ain the program you are trying to debug. At various points, however, it
1N/Atemporarily switches back to the C<main> package to evaluate various
1N/Aexpressions in the context of the C<main> package (or wherever you came
1N/Afrom). See L<perldebug>.
1N/AThe special symbol C<__PACKAGE__> contains the current package, but cannot
1N/A(easily) be used to construct variable names.
1N/ASee L<perlsub> for other scoping issues related to my() and local(),
1N/Aand L<perlref> regarding closures.
1N/AThe symbol table for a package happens to be stored in the hash of that
1N/Aname with two colons appended. The main symbol table's name is thus
1N/AC<%main::>, or C<%::> for short. Likewise the symbol table for the nested
1N/Apackage mentioned earlier is named C<%OUTER::INNER::>.
1N/AThe value in each entry of the hash is what you are referring to when you
1N/Ause the C<*name> typeglob notation. In fact, the following have the same
1N/Aeffect, though the first is more efficient because it does the symbol
1N/Atable lookups at compile time:
1N/A local *main::foo = *main::bar;
1N/A local $main::{foo} = $main::{bar};
1N/A(Be sure to note the B<vast> difference between the second line above
1N/Aand C<local $main::foo = $main::bar>. The former is accessing the hash
1N/AC<%main::>, which is the symbol table of package C<main>. The latter is
1N/Asimply assigning scalar C<$bar> in package C<main> to scalar C<$foo> of
1N/AYou can use this to print out all the variables in a package, for
1N/Athe CPAN module Devel::Symdump make use of this.
1N/AAssignment to a typeglob performs an aliasing operation,
i.e.,
1N/Acauses variables, subroutines, formats, and file and directory handles
1N/Aaccessible via the identifier C<richard> also to be accessible via the
1N/Aidentifier C<dick>. If you want to alias only a particular variable or
1N/Asubroutine, assign a reference instead:
1N/AWhich makes $richard and $dick the same variable, but leaves
1N/A@richard and @dick as separate arrays. Tricky, eh?
1N/AThere is one subtle difference between the following statements:
1N/AC<*foo = *bar> makes the typeglobs themselves synonymous while
1N/AC<*foo = \$bar> makes the SCALAR portions of two distinct typeglobs
1N/Arefer to the same scalar value. This means that the following code:
1N/A *foo = \$bar; # Make $foo an alias for $bar
1N/A local $bar = 2; # Restrict changes to block
1N/A print $foo; # Prints '1'!
1N/AWould print '1', because C<$foo> holds a reference to the I<original>
1N/AC<$bar> -- the one that was stuffed away by C<local()> and which will be
1N/Arestored when the block ends. Because variables are accessed through the
1N/Atypeglob, you can use C<*foo = *bar> to create an alias which can be
1N/Alocalized. (But be aware that this means you can't have a separate
1N/AC<@foo> and C<@bar>, etc.)
1N/AWhat makes all of this important is that the Exporter module uses glob
1N/Alocalize a variable that has been exported from a module depends on how
1N/A @EXPORT = qw($FOO); # Usual form, can't be localized
1N/A @EXPORT = qw(*FOO); # Can be localized
1N/AYou can work around the first case by using the fully qualified name
1N/A(C<$Package::FOO>) where you need a local value, or by overriding it
1N/Aby saying C<*FOO = *Package::FOO> in your script.
1N/AThe C<*x = \$y> mechanism may be used to pass and return cheap references
1N/Ainto or from subroutines if you don't want to copy the whole
1N/Athing. It only works when assigning to dynamic variables, not
1N/A %some_hash = (); # can't be my()
1N/A *some_hash = fn( \%another_hash );
1N/A local *hashsym = shift;
1N/A # now use %hashsym normally, and you
1N/A # will affect the caller's %another_hash
1N/A my %nhash = (); # do what you want
1N/AOn return, the reference will overwrite the hash slot in the
1N/Asymbol table specified by the *some_hash typeglob. This
1N/Ais a somewhat tricky way of passing around references cheaply
1N/Awhen you don't want to have to remember to dereference variables
1N/AAnother use of symbol tables is for making "constant" scalars.
1N/A *PI = \3.14159265358979;
1N/ANow you cannot alter C<$PI>, which is probably a good thing all in all.
1N/AThis isn't the same as a constant subroutine, which is subject to
1N/Aoptimization at compile-time. A constant subroutine is one prototyped
1N/Ato take no arguments and to return a constant expression. See
1N/AL<perlsub> for details on these. The C<use constant> pragma is a
1N/Aconvenient shorthand for these.
1N/AYou can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and
1N/Apackage the *foo symbol table entry comes from. This may be useful
1N/Ain a subroutine that gets passed typeglobs as arguments:
1N/A sub identify_typeglob {
1N/A print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
1N/A identify_typeglob *foo;
1N/A identify_typeglob *bar::baz;
1N/A You gave me main::foo
1N/A You gave me bar::baz
1N/AThe C<*foo{THING}> notation can also be used to obtain references to the
1N/Aindividual elements of *foo. See L<perlref>.
1N/ASubroutine definitions (and declarations, for that matter) need
1N/Anot necessarily be situated in the package whose symbol table they
1N/Aoccupy. You can define a subroutine outside its package by
1N/Aexplicitly qualifying the name of the subroutine:
1N/A sub Some_package::foo { ... } # &foo defined in Some_package
1N/AThis is just a shorthand for a typeglob assignment at compile time:
1N/A BEGIN { *Some_package::foo = sub { ... } }
1N/Aand is I<not> the same as writing:
1N/A package Some_package;
1N/AIn the first two versions, the body of the subroutine is
1N/Alexically in the main package, I<not> in Some_package. So
1N/A $Some_package::name = "fred";
1N/A $main::name = "barney";
1N/A sub Some_package::foo {
1N/A print "in ", __PACKAGE__, ": \$name is '$name'\n";
1N/A Some_package::foo();
1N/A in main: $name is 'barney'
1N/A in Some_package: $name is 'fred'
1N/AThis also has implications for the use of the SUPER:: qualifier
1N/A=head2 BEGIN, CHECK, INIT and END
1N/AFour specially named code blocks are executed at the beginning and at the end
1N/Aof a running Perl program. These are the C<BEGIN>, C<CHECK>, C<INIT>, and
1N/AThese code blocks can be prefixed with C<sub> to give the appearance of a
1N/Asubroutine (although this is not considered good style). One should note
1N/Athat these code blocks don't really exist as named subroutines (despite
1N/Atheir appearance). The thing that gives this away is the fact that you can
1N/Ahave B<more than one> of these code blocks in a program, and they will get
1N/AB<all> executed at the appropriate moment. So you can't execute any of
1N/Athese code blocks by name.
1N/AA C<BEGIN> code block is executed as soon as possible, that is, the moment
1N/Ait is completely defined, even before the rest of the containing file (or
1N/Astring) is parsed. You may have multiple C<BEGIN> blocks within a file (or
1N/Aeval'ed string) -- they will execute in order of definition. Because a C<BEGIN>
1N/Acode block executes immediately, it can pull in definitions of subroutines
1N/Aand such from other files in time to be visible to the rest of the compile
1N/Aand run time. Once a C<BEGIN> has run, it is immediately undefined and any
1N/Acode it used is returned to Perl's memory pool.
1N/AIt should be noted that C<BEGIN> code blocks B<are> executed inside string
1N/AC<eval()>'s. The C<CHECK> and C<INIT> code blocks are B<not> executed inside
1N/Aa string eval, which
e.g. can be a problem in a mod_perl environment.
1N/AAn C<END> code block is executed as late as possible, that is, after
1N/Aperl has finished running the program and just before the interpreter
1N/Ais being exited, even if it is exiting as a result of a die() function.
1N/A(But not if it's polymorphing into another program via C<exec>, or
1N/Abeing blown out of the water by a signal--you have to trap that yourself
1N/A(if you can).) You may have multiple C<END> blocks within a file--they
1N/Awill execute in reverse order of definition; that is: last in, first
1N/Aout (LIFO). C<END> blocks are not executed when you run perl with the
1N/AC<-c> switch, or if compilation fails.
1N/ANote that C<END> code blocks are B<not> executed at the end of a string
1N/AC<eval()>: if any C<END> code blocks are created in a string C<eval()>,
1N/Athey will be executed just as any other C<END> code block of that package
1N/Ain LIFO order just before the interpreter is being exited.
1N/AInside an C<END> code block, C<$?> contains the value that the program is
1N/Agoing to pass to C<exit()>. You can modify C<$?> to change the exit
1N/Avalue of the program. Beware of changing C<$?> by accident (
e.g. by
1N/Arunning something via C<system>).
1N/AC<CHECK> and C<INIT> code blocks are useful to catch the transition between
1N/Athe compilation phase and the execution phase of the main program.
1N/AC<CHECK> code blocks are run just after the B<initial> Perl compile phase ends
1N/Aand before the run time begins, in LIFO order. C<CHECK> code blocks are used
1N/Ain the Perl compiler suite to save the compiled state of the program.
1N/AC<INIT> blocks are run just before the Perl runtime begins execution, in
1N/A"first in, first out" (FIFO) order. For example, the code generators
1N/Adocumented in L<perlcc> make use of C<INIT> blocks to initialize and
1N/Aresolve pointers to XSUBs.
1N/AWhen you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and
1N/AC<END> work just as they do in B<awk>, as a degenerate case.
1N/ABoth C<BEGIN> and C<CHECK> blocks are run when you use the B<-c>
1N/Aswitch for a compile-only syntax check, although your main code
1N/AThe B<begincheck> program makes it all clear, eventually:
1N/A print " 8. Ordinary code runs at runtime.\n";
1N/A END { print "14. So this is the end of the tale.\n" }
1N/A INIT { print " 5. INIT blocks run FIFO just before runtime.\n" }
1N/A CHECK { print " 4. So this is the fourth line.\n" }
1N/A print " 9. It runs in order, of course.\n";
1N/A BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
1N/A END { print "13. Read perlmod for the rest of the story.\n" }
1N/A CHECK { print " 3. CHECK blocks run LIFO at compilation's end.\n" }
1N/A INIT { print " 6. Run this again, using Perl's -c switch.\n" }
1N/A print "10. This is anti-obfuscated code.\n";
1N/A END { print "12. END blocks run LIFO at quitting time.\n" }
1N/A BEGIN { print " 2. So this line comes out second.\n" }
1N/A INIT { print " 7. You'll see the difference right away.\n" }
1N/A print "11. It merely _looks_ like it should be confusing.\n";
1N/AThere is no special class syntax in Perl, but a package may act
1N/Aas a class if it provides subroutines to act as methods. Such a
1N/Apackage may also derive some of its methods from another class (package)
1N/Aby listing the other package name(s) in its global @ISA array (which
1N/Amust be a package global, not a lexical).
1N/AFor more on this, see L<perltoot> and L<perlobj>.
1N/AA module is just a set of related functions in a library file,
i.e.,
1N/Aa Perl package with the same name as the file. It is specifically
1N/Adesigned to be reusable by other modules or programs. It may do this
1N/Aby providing a mechanism for exporting some of its symbols into the
1N/Asymbol table of any package using it, or it may function as a class
1N/Adefinition and make its semantics available implicitly through
1N/Amethod calls on the class and its objects, without explicitly
1N/Aexporting anything. Or it can do a little of both.
1N/AFor example, to start a traditional, non-OO module called Some::Module,
1N/A our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
1N/A # set the version for version checking
1N/A $VERSION = sprintf "%d.%03d", q$Revision: 1.1 $ =~ /(\d+)/g;
1N/A @ISA = qw(Exporter);
1N/A @EXPORT = qw(&func1 &func2 &func4);
1N/A %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
1N/A # your exported package globals go here,
1N/A # as well as any optionally exported functions
1N/A @EXPORT_OK = qw($Var1 %Hashit &func3);
1N/A # exported package globals go here
1N/A # non-exported package globals go here
1N/A # initialize package globals, first exported ones
1N/A # then the others (which are still accessible as $Some::Module::stuff)
1N/A # all file-scoped lexicals must be created before
1N/A # the functions below that use them.
1N/A # file-private lexicals go here
1N/A my %secret_hash = ();
1N/A # here's a file-private function as a closure,
1N/A # callable as &$priv_func; it cannot be prototyped.
1N/A my $priv_func = sub {
1N/A # make all your functions, whether exported or not;
1N/A # remember to put something interesting in the {} stubs
1N/A sub func1 {} # no prototype
1N/A sub func2() {} # proto'd void
1N/A sub func3($$) {} # proto'd to 2 scalars
1N/A # this one isn't exported, but could be called!
1N/A sub func4(\%) {} # proto'd to 1 hash ref
1N/A END { } # module clean-up code here (global destructor)
1N/A ## YOUR CODE GOES HERE
1N/A 1; # don't forget to return a true value from the file
1N/AThen go on to declare and use your variables in functions without
1N/Aany qualifications. See L<Exporter> and the L<perlmodlib> for
1N/Adetails on mechanics and style issues in module creation.
1N/APerl modules are included into your program by saying
1N/AThis is exactly equivalent to
1N/A BEGIN { require Module; import Module; }
1N/A BEGIN { require Module; import Module LIST; }
1N/Ais exactly equivalent to
1N/A BEGIN { require Module; }
1N/AAll Perl module files have the extension F<.pm>. The C<use> operator
1N/Aassumes this so you don't have to spell out "F<
Module.pm>" in quotes.
1N/AThis also helps to differentiate new modules from old F<.pl> and
1N/AF<.ph> files. Module names are also capitalized unless they're
1N/Afunctioning as pragmas; pragmas are in effect compiler directives,
1N/Aand are sometimes called "pragmatic modules" (or even "pragmata"
1N/Aif you're a classicist).
1N/Adiffer from each other in two ways. In the first case, any double
1N/Acolons in the module name, such as C<Some::Module>, are translated
1N/Ainto your system's directory separator, usually "/". The second
1N/Acase does not, and would have to be specified literally. The other
1N/Adifference is that seeing the first C<require> clues in the compiler
1N/Athat uses of indirect object notation involving "SomeModule", as
1N/Ain C<$ob = purge SomeModule>, are method calls, not function calls.
1N/A(Yes, this really can make a difference.)
1N/ABecause the C<use> statement implies a C<BEGIN> block, the importing
1N/Aof semantics happens as soon as the C<use> statement is compiled,
1N/Abefore the rest of the file is compiled. This is how it is able
1N/Ato function as a pragma mechanism, and also how modules are able to
1N/Adeclare subroutines that are then visible as list or unary operators for
1N/Athe rest of the current file. This will not work if you use C<require>
1N/Ainstead of C<use>. With C<require> you can get into this problem:
1N/A require Cwd; # make Cwd:: accessible
1N/A $here = Cwd::getcwd();
1N/A use Cwd; # import names from Cwd::
1N/A require Cwd; # make Cwd:: accessible
1N/A $here = getcwd(); # oops! no main::getcwd()
1N/AIn general, C<use Module ()> is recommended over C<require Module>,
1N/Abecause it determines module availability at compile time, not in the
1N/Amiddle of your program's execution. An exception would be if two modules
1N/Aeach tried to C<use> each other, and each also called a function from
1N/Athat other module. In that case, it's easy to use C<require> instead.
1N/APerl packages may be nested inside other package names, so we can have
1N/Apackage names containing C<::>. But if we used that package name
1N/Adirectly as a filename it would make for unwieldy or impossible
1N/Afilenames on some systems. Therefore, if a module's name is, say,
1N/AC<Text::Soundex>, then its definition is actually found in the library
1N/APerl modules always have a F<.pm> file, but there may also be
1N/Adynamically linked executables (often ending in F<.so>) or autoloaded
1N/Asubroutine definitions (often ending in F<.al>) associated with the
1N/Amodule. If so, these will be entirely transparent to the user of
1N/Athe module. It is the responsibility of the F<.pm> file to load
1N/A(or arrange to autoload) any additional functionality. For example,
1N/Aalthough the POSIX module happens to do both dynamic loading and
1N/Aautoloading, the user can say just C<use POSIX> to get it all.
1N/A=head2 Making your module threadsafe
1N/ASince 5.6.0, Perl has had support for a new type of threads called
1N/Ainterpreter threads (ithreads). These threads can be used explicitly
1N/AIthreads work by cloning the data tree so that no data is shared
1N/Abetween different threads. These threads can be used by using the C<threads>
1N/Amodule or by doing fork() on win32 (fake fork() support). When a
1N/Athread is cloned all Perl data is cloned, however non-Perl data cannot
1N/Abe cloned automatically. Perl after 5.7.2 has support for the C<CLONE>
1N/Aspecial subroutine . In C<CLONE> you can do whatever you need to do,
1N/Alike for example handle the cloning of non-Perl data, if necessary.
1N/AC<CLONE> will be executed once for every package that has it defined
1N/A(or inherits it). It will be called in the context of the new thread,
1N/Aso all modifications are made in the new area.
1N/AIf you want to CLONE all objects you will need to keep track of them per
1N/Apackage. This is simply done using a hash and Scalar::Util::weaken().
1N/ASee L<perlmodlib> for general style issues related to building Perl
1N/Amodules and classes, as well as descriptions of the standard library
1N/Aworks, L<perltoot> and L<perltooc> for an in-depth tutorial on
1N/Acreating classes, L<perlobj> for a hard-core reference document on
1N/Aobjects, L<perlsub> for an explanation of functions and scoping,
1N/Aand L<perlxstut> and L<perlguts> for more information on writing