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