| 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"; |
| 37 | |
| 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 | |
| 74 | Note how we load the user pragma C<myint> with an empty list C<()> to |
| 75 | prevent its C<import> being called. |
| 76 | |
| 77 | The interaction with the Perl compilation happens inside package C<myint>: |
| 78 | |
| 79 | package myint; |
| 80 | |
| 81 | use strict; |
| 82 | use warnings; |
| 83 | |
| 84 | sub import { |
| 85 | $^H{"myint/in_effect"} = 1; |
| 86 | } |
| 87 | |
| 88 | sub unimport { |
| 89 | $^H{"myint/in_effect"} = 0; |
| 90 | } |
| 91 | |
| 92 | sub in_effect { |
| 93 | my $level = shift // 0; |
| 94 | my $hinthash = (caller($level))[10]; |
| 95 | return $hinthash->{"myint/in_effect"}; |
| 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 | |
| 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 |
| 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 |
| 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/in_effect"}> when each line of the user's script was called, and |
| 126 | therefore provide the correct semantics in the subroutine implementing the |
| 127 | overloaded addition. |
| 128 | |
| 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 | |
| 145 | =head1 Implementation details |
| 146 | |
| 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 |
| 149 | instance) that created it, so true Perl scalars cannot be stored in the |
| 150 | optree. Instead a compact form is used, which can only store values that are |
| 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>. |
| 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. |