164 lines
5.1 KiB
Plaintext
164 lines
5.1 KiB
Plaintext
=head1 NAME
|
|
|
|
perlpragma - how to write a user pragma
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
A pragma is a module which influences some aspect of the compile time or run
|
|
time behaviour of Perl, such as C<strict> or C<warnings>. With Perl 5.10 you
|
|
are no longer limited to the built in pragmata; you can now create user
|
|
pragmata that modify the behaviour of user functions within a lexical scope.
|
|
|
|
=head1 A basic example
|
|
|
|
For example, say you need to create a class implementing overloaded
|
|
mathematical operators, and would like to provide your own pragma that
|
|
functions much like C<use integer;> You'd like this code
|
|
|
|
use MyMaths;
|
|
|
|
my $l = MyMaths->new(1.2);
|
|
my $r = MyMaths->new(3.4);
|
|
|
|
print "A: ", $l + $r, "\n";
|
|
|
|
use myint;
|
|
print "B: ", $l + $r, "\n";
|
|
|
|
{
|
|
no myint;
|
|
print "C: ", $l + $r, "\n";
|
|
}
|
|
|
|
print "D: ", $l + $r, "\n";
|
|
|
|
no myint;
|
|
print "E: ", $l + $r, "\n";
|
|
|
|
to give the output
|
|
|
|
A: 4.6
|
|
B: 4
|
|
C: 4.6
|
|
D: 4
|
|
E: 4.6
|
|
|
|
I<i.e.>, where C<use myint;> is in effect, addition operations are forced
|
|
to integer, whereas by default they are not, with the default behaviour being
|
|
restored via C<no myint;>
|
|
|
|
The minimal implementation of the package C<MyMaths> would be something like
|
|
this:
|
|
|
|
package MyMaths;
|
|
use warnings;
|
|
use strict;
|
|
use myint();
|
|
use overload '+' => sub {
|
|
my ($l, $r) = @_;
|
|
# Pass 1 to check up one call level from here
|
|
if (myint::in_effect(1)) {
|
|
int($$l) + int($$r);
|
|
} else {
|
|
$$l + $$r;
|
|
}
|
|
};
|
|
|
|
sub new {
|
|
my ($class, $value) = @_;
|
|
bless \$value, $class;
|
|
}
|
|
|
|
1;
|
|
|
|
Note how we load the user pragma C<myint> with an empty list C<()> to
|
|
prevent its C<import> being called.
|
|
|
|
The interaction with the Perl compilation happens inside package C<myint>:
|
|
|
|
package myint;
|
|
|
|
use strict;
|
|
use warnings;
|
|
|
|
sub import {
|
|
$^H{"myint/in_effect"} = 1;
|
|
}
|
|
|
|
sub unimport {
|
|
$^H{"myint/in_effect"} = 0;
|
|
}
|
|
|
|
sub in_effect {
|
|
my $level = shift // 0;
|
|
my $hinthash = (caller($level))[10];
|
|
return $hinthash->{"myint/in_effect"};
|
|
}
|
|
|
|
1;
|
|
|
|
As pragmata are implemented as modules, like any other module, C<use myint;>
|
|
becomes
|
|
|
|
BEGIN {
|
|
require myint;
|
|
myint->import();
|
|
}
|
|
|
|
and C<no myint;> is
|
|
|
|
BEGIN {
|
|
require myint;
|
|
myint->unimport();
|
|
}
|
|
|
|
Hence the C<import> and C<unimport> routines are called at B<compile time>
|
|
for the user's code.
|
|
|
|
User pragmata store their state by writing to the magical hash C<%^H>,
|
|
hence these two routines manipulate it. The state information in C<%^H> is
|
|
stored in the optree, and can be retrieved read-only at runtime with C<caller()>,
|
|
at index 10 of the list of returned results. In the example pragma, retrieval
|
|
is encapsulated into the routine C<in_effect()>, which takes as parameter
|
|
the number of call frames to go up to find the value of the pragma in the
|
|
user's script. This uses C<caller()> to determine the value of
|
|
C<$^H{"myint/in_effect"}> when each line of the user's script was called, and
|
|
therefore provide the correct semantics in the subroutine implementing the
|
|
overloaded addition.
|
|
|
|
=head1 Key naming
|
|
|
|
There is only a single C<%^H>, but arbitrarily many modules that want
|
|
to use its scoping semantics. To avoid stepping on each other's toes,
|
|
they need to be sure to use different keys in the hash. It is therefore
|
|
conventional for a module to use only keys that begin with the module's
|
|
name (the name of its main package) and a "/" character. After this
|
|
module-identifying prefix, the rest of the key is entirely up to the
|
|
module: it may include any characters whatsoever. For example, a module
|
|
C<Foo::Bar> should use keys such as C<Foo::Bar/baz> and C<Foo::Bar/$%/_!>.
|
|
Modules following this convention all play nicely with each other.
|
|
|
|
The Perl core uses a handful of keys in C<%^H> which do not follow this
|
|
convention, because they predate it. Keys that follow the convention
|
|
won't conflict with the core's historical keys.
|
|
|
|
=head1 Implementation details
|
|
|
|
The optree is shared between threads. This means there is a possibility that
|
|
the optree will outlive the particular thread (and therefore the interpreter
|
|
instance) that created it, so true Perl scalars cannot be stored in the
|
|
optree. Instead a compact form is used, which can only store values that are
|
|
integers (signed and unsigned), strings or C<undef> - references and
|
|
floating point values are stringified. If you need to store multiple values
|
|
or complex structures, you should serialise them, for example with C<pack>.
|
|
The deletion of a hash key from C<%^H> is recorded, and as ever can be
|
|
distinguished from the existence of a key with value C<undef> with
|
|
C<exists>.
|
|
|
|
B<Don't> attempt to store references to data structures as integers which
|
|
are retrieved via C<caller> and converted back, as this will not be threadsafe.
|
|
Accesses would be to the structure without locking (which is not safe for
|
|
Perl's scalars), and either the structure has to leak, or it has to be
|
|
freed when its creating thread terminates, which may be before the optree
|
|
referencing it is deleted, if other threads outlive it.
|