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; | |
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 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 | }; | |
66 | ||
67 | sub new { | |
68 | my ($class, $value) = @_; | |
69 | bless \$value, $class; | |
70 | } | |
71 | ||
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 RGS |
79 | package myint; |
80 | ||
a550ee30 NC |
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 | ||
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 | |
02e1e451 | 120 | stored in the optree, and can be retrieved at runtime with C<caller()>, at |
46e5f5f4 RGS |
121 | index 10 of the list of returned results. In the example pragma, retrieval |
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 | |
125 | C<$^H{myint}> 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 | ||
129 | =head1 Implementation details | |
130 | ||
260ebcb6 SP |
131 | The optree is shared between threads. This means there is a possibility that |
132 | the optree will outlive the particular thread (and therefore the interpreter | |
a550ee30 | 133 | instance) that created it, so true Perl scalars cannot be stored in the |
260ebcb6 | 134 | optree. Instead a compact form is used, which can only store values that are |
a550ee30 NC |
135 | integers (signed and unsigned), strings or C<undef> - references and |
136 | floating point values are stringified. If you need to store multiple values | |
137 | or complex structures, you should serialise them, for example with C<pack>. | |
138 | The deletion of a hash key from C<%^H> is recorded, and as ever can be | |
139 | distinguished from the existence of a key with value C<undef> with | |
140 | C<exists>. | |
83a47afd NC |
141 | |
142 | B<Don't> attempt to store references to data structures as integers which | |
143 | are retrieved via C<caller> and converted back, as this will not be threadsafe. | |
144 | Accesses would be to the structure without locking (which is not safe for | |
145 | Perl's scalars), and either the structure has to leak, or it has to be | |
146 | freed when its creating thread terminates, which may be before the optree | |
147 | referencing it is deleted, if other threads outlive it. |