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; | |
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 | }; | |
f703fc96 | 66 | |
a550ee30 NC |
67 | sub new { |
68 | my ($class, $value) = @_; | |
69 | bless \$value, $class; | |
70 | } | |
f703fc96 | 71 | |
a550ee30 NC |
72 | 1; |
73 | ||
02e1e451 RGS |
74 | Note how we load the user pragma C<myint> with an empty list C<()> to |
75 | prevent its C<import> being called. | |
a550ee30 | 76 | |
02e1e451 | 77 | The interaction with the Perl compilation happens inside package C<myint>: |
a550ee30 | 78 | |
02e1e451 | 79 | package myint; |
f703fc96 | 80 | |
a550ee30 NC |
81 | use strict; |
82 | use warnings; | |
f703fc96 | 83 | |
a550ee30 | 84 | sub import { |
09f1e2c2 | 85 | $^H{"myint/in_effect"} = 1; |
a550ee30 | 86 | } |
f703fc96 | 87 | |
a550ee30 | 88 | sub unimport { |
09f1e2c2 | 89 | $^H{"myint/in_effect"} = 0; |
a550ee30 | 90 | } |
f703fc96 | 91 | |
a550ee30 NC |
92 | sub in_effect { |
93 | my $level = shift // 0; | |
94 | my $hinthash = (caller($level))[10]; | |
09f1e2c2 | 95 | return $hinthash->{"myint/in_effect"}; |
a550ee30 | 96 | } |
f703fc96 | 97 | |
a550ee30 NC |
98 | 1; |
99 | ||
100 | As pragmata are implemented as modules, like any other module, C<use myint;> | |
101 | becomes | |
102 | ||
103 | BEGIN { | |
104 | require myint; | |
105 | myint->import(); | |
106 | } | |
107 | ||
108 | and C<no myint;> is | |
109 | ||
110 | BEGIN { | |
111 | require myint; | |
112 | myint->unimport(); | |
113 | } | |
114 | ||
115 | Hence the C<import> and C<unimport> routines are called at B<compile time> | |
116 | for the user's code. | |
117 | ||
46e5f5f4 RGS |
118 | User pragmata store their state by writing to the magical hash C<%^H>, |
119 | hence these two routines manipulate it. The state information in C<%^H> is | |
5ff2e4c0 KW |
120 | stored in the optree, and can be retrieved read-only at runtime with C<caller()>, |
121 | at index 10 of the list of returned results. In the example pragma, retrieval | |
46e5f5f4 RGS |
122 | is encapsulated into the routine C<in_effect()>, which takes as parameter |
123 | the number of call frames to go up to find the value of the pragma in the | |
124 | user's script. This uses C<caller()> to determine the value of | |
09f1e2c2 | 125 | C<$^H{"myint/in_effect"}> when each line of the user's script was called, and |
a550ee30 NC |
126 | therefore provide the correct semantics in the subroutine implementing the |
127 | overloaded addition. | |
128 | ||
09f1e2c2 Z |
129 | =head1 Key naming |
130 | ||
131 | There is only a single C<%^H>, but arbitrarily many modules that want | |
132 | to use its scoping semantics. To avoid stepping on each other's toes, | |
133 | they need to be sure to use different keys in the hash. It is therefore | |
134 | conventional for a module to use only keys that begin with the module's | |
135 | name (the name of its main package) and a "/" character. After this | |
136 | module-identifying prefix, the rest of the key is entirely up to the | |
137 | module: it may include any characters whatsoever. For example, a module | |
138 | C<Foo::Bar> should use keys such as C<Foo::Bar/baz> and C<Foo::Bar/$%/_!>. | |
139 | Modules following this convention all play nicely with each other. | |
140 | ||
141 | The Perl core uses a handful of keys in C<%^H> which do not follow this | |
142 | convention, because they predate it. Keys that follow the convention | |
143 | won't conflict with the core's historical keys. | |
144 | ||
a550ee30 NC |
145 | =head1 Implementation details |
146 | ||
260ebcb6 SP |
147 | The optree is shared between threads. This means there is a possibility that |
148 | the optree will outlive the particular thread (and therefore the interpreter | |
a550ee30 | 149 | instance) that created it, so true Perl scalars cannot be stored in the |
260ebcb6 | 150 | optree. Instead a compact form is used, which can only store values that are |
a550ee30 NC |
151 | integers (signed and unsigned), strings or C<undef> - references and |
152 | floating point values are stringified. If you need to store multiple values | |
153 | or complex structures, you should serialise them, for example with C<pack>. | |
154 | The deletion of a hash key from C<%^H> is recorded, and as ever can be | |
155 | distinguished from the existence of a key with value C<undef> with | |
156 | C<exists>. | |
83a47afd NC |
157 | |
158 | B<Don't> attempt to store references to data structures as integers which | |
159 | are retrieved via C<caller> and converted back, as this will not be threadsafe. | |
160 | Accesses would be to the structure without locking (which is not safe for | |
161 | Perl's scalars), and either the structure has to leak, or it has to be | |
162 | freed when its creating thread terminates, which may be before the optree | |
163 | referencing it is deleted, if other threads outlive it. |