note strict/lax version requirements in documentation
[p5sagit/p5-mst-13.2.git] / pod / perlpragma.pod
CommitLineData
a550ee30 1=head1 NAME
2
3perlpragma - how to write a user pragma
4
5=head1 DESCRIPTION
6
7A pragma is a module which influences some aspect of the compile time or run
8time behaviour of Perl, such as C<strict> or C<warnings>. With Perl 5.10 you
9are no longer limited to the built in pragmata; you can now create user
10pragmata that modify the behaviour of user functions within a lexical scope.
11
12=head1 A basic example
13
14For example, say you need to create a class implementing overloaded
15mathematical operators, and would like to provide your own pragma that
16functions much like C<use integer;> You'd like this code
17
18 use MyMaths;
19
20 my $l = MyMaths->new(1.2);
21 my $r = MyMaths->new(3.4);
22
23 print "A: ", $l + $r, "\n";
24
25 use myint;
26 print "B: ", $l + $r, "\n";
27
28 {
29 no myint;
30 print "C: ", $l + $r, "\n";
31 }
32
33 print "D: ", $l + $r, "\n";
34
35 no myint;
36 print "E: ", $l + $r, "\n";
02e1e451 37
a550ee30 38to give the output
39
40 A: 4.6
41 B: 4
42 C: 4.6
43 D: 4
44 E: 4.6
45
46I<i.e.>, where C<use myint;> is in effect, addition operations are forced
47to integer, whereas by default they are not, with the default behaviour being
48restored via C<no myint;>
49
50The minimal implementation of the package C<MyMaths> would be something like
51this:
52
53 package MyMaths;
54 use warnings;
55 use strict;
56 use myint();
57 use overload '+' => sub {
58 my ($l, $r) = @_;
59 # Pass 1 to check up one call level from here
60 if (myint::in_effect(1)) {
61 int($$l) + int($$r);
62 } else {
63 $$l + $$r;
64 }
65 };
66
67 sub new {
68 my ($class, $value) = @_;
69 bless \$value, $class;
70 }
71
72 1;
73
02e1e451 74Note how we load the user pragma C<myint> with an empty list C<()> to
75prevent its C<import> being called.
a550ee30 76
02e1e451 77The interaction with the Perl compilation happens inside package C<myint>:
a550ee30 78
02e1e451 79 package myint;
80
a550ee30 81 use strict;
82 use warnings;
83
84 sub import {
85 $^H{myint} = 1;
86 }
87
88 sub unimport {
89 $^H{myint} = 0;
90 }
91
92 sub in_effect {
93 my $level = shift // 0;
94 my $hinthash = (caller($level))[10];
95 return $hinthash->{myint};
96 }
97
98 1;
99
100As pragmata are implemented as modules, like any other module, C<use myint;>
101becomes
102
103 BEGIN {
104 require myint;
105 myint->import();
106 }
107
108and C<no myint;> is
109
110 BEGIN {
111 require myint;
112 myint->unimport();
113 }
114
115Hence the C<import> and C<unimport> routines are called at B<compile time>
116for the user's code.
117
46e5f5f4 118User pragmata store their state by writing to the magical hash C<%^H>,
119hence these two routines manipulate it. The state information in C<%^H> is
02e1e451 120stored in the optree, and can be retrieved at runtime with C<caller()>, at
46e5f5f4 121index 10 of the list of returned results. In the example pragma, retrieval
122is encapsulated into the routine C<in_effect()>, which takes as parameter
123the number of call frames to go up to find the value of the pragma in the
124user's script. This uses C<caller()> to determine the value of
125C<$^H{myint}> when each line of the user's script was called, and
a550ee30 126therefore provide the correct semantics in the subroutine implementing the
127overloaded addition.
128
129=head1 Implementation details
130
260ebcb6 131The optree is shared between threads. This means there is a possibility that
132the optree will outlive the particular thread (and therefore the interpreter
a550ee30 133instance) that created it, so true Perl scalars cannot be stored in the
260ebcb6 134optree. Instead a compact form is used, which can only store values that are
a550ee30 135integers (signed and unsigned), strings or C<undef> - references and
136floating point values are stringified. If you need to store multiple values
137or complex structures, you should serialise them, for example with C<pack>.
138The deletion of a hash key from C<%^H> is recorded, and as ever can be
139distinguished from the existence of a key with value C<undef> with
140C<exists>.
83a47afd 141
142B<Don't> attempt to store references to data structures as integers which
143are retrieved via C<caller> and converted back, as this will not be threadsafe.
144Accesses would be to the structure without locking (which is not safe for
145Perl's scalars), and either the structure has to leak, or it has to be
146freed when its creating thread terminates, which may be before the optree
147referencing it is deleted, if other threads outlive it.