| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLPRAGMA 1" |
| 58 |
.TH PERLPRAGMA 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlpragma \- how to write a user pragma |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
A pragma is a module which influences some aspect of the compile time or run |
| 68 |
time behaviour of Perl, such as \f(CW\*(C`strict\*(C'\fR or \f(CW\*(C`warnings\*(C'\fR. With Perl 5.10 you |
| 69 |
are no longer limited to the built in pragmata; you can now create user |
| 70 |
pragmata that modify the behaviour of user functions within a lexical scope. |
| 71 |
.SH "A basic example" |
| 72 |
.IX Header "A basic example" |
| 73 |
For example, say you need to create a class implementing overloaded |
| 74 |
mathematical operators, and would like to provide your own pragma that |
| 75 |
functions much like \f(CW\*(C`use integer;\*(C'\fR You'd like this code |
| 76 |
.PP |
| 77 |
.Vb 1 |
| 78 |
\& use MyMaths; |
| 79 |
\& |
| 80 |
\& my $l = MyMaths\->new(1.2); |
| 81 |
\& my $r = MyMaths\->new(3.4); |
| 82 |
\& |
| 83 |
\& print "A: ", $l + $r, "\en"; |
| 84 |
\& |
| 85 |
\& use myint; |
| 86 |
\& print "B: ", $l + $r, "\en"; |
| 87 |
\& |
| 88 |
\& { |
| 89 |
\& no myint; |
| 90 |
\& print "C: ", $l + $r, "\en"; |
| 91 |
\& } |
| 92 |
\& |
| 93 |
\& print "D: ", $l + $r, "\en"; |
| 94 |
\& |
| 95 |
\& no myint; |
| 96 |
\& print "E: ", $l + $r, "\en"; |
| 97 |
.Ve |
| 98 |
.PP |
| 99 |
to give the output |
| 100 |
.PP |
| 101 |
.Vb 5 |
| 102 |
\& A: 4.6 |
| 103 |
\& B: 4 |
| 104 |
\& C: 4.6 |
| 105 |
\& D: 4 |
| 106 |
\& E: 4.6 |
| 107 |
.Ve |
| 108 |
.PP |
| 109 |
\&\fIi.e.\fR, where \f(CW\*(C`use myint;\*(C'\fR is in effect, addition operations are forced |
| 110 |
to integer, whereas by default they are not, with the default behaviour being |
| 111 |
restored via \f(CW\*(C`no myint;\*(C'\fR |
| 112 |
.PP |
| 113 |
The minimal implementation of the package \f(CW\*(C`MyMaths\*(C'\fR would be something like |
| 114 |
this: |
| 115 |
.PP |
| 116 |
.Vb 12 |
| 117 |
\& package MyMaths; |
| 118 |
\& use v5.36; |
| 119 |
\& use myint(); |
| 120 |
\& use overload \*(Aq+\*(Aq => sub { |
| 121 |
\& my ($l, $r) = @_; |
| 122 |
\& # Pass 1 to check up one call level from here |
| 123 |
\& if (myint::in_effect(1)) { |
| 124 |
\& int($$l) + int($$r); |
| 125 |
\& } else { |
| 126 |
\& $$l + $$r; |
| 127 |
\& } |
| 128 |
\& }; |
| 129 |
\& |
| 130 |
\& sub new { |
| 131 |
\& my ($class, $value) = @_; |
| 132 |
\& bless \e$value, $class; |
| 133 |
\& } |
| 134 |
\& |
| 135 |
\& 1; |
| 136 |
.Ve |
| 137 |
.PP |
| 138 |
Note how we load the user pragma \f(CW\*(C`myint\*(C'\fR with an empty list \f(CW\*(C`()\*(C'\fR to |
| 139 |
prevent its \f(CW\*(C`import\*(C'\fR being called. |
| 140 |
.PP |
| 141 |
The interaction with the Perl compilation happens inside package \f(CW\*(C`myint\*(C'\fR: |
| 142 |
.PP |
| 143 |
.Vb 1 |
| 144 |
\& package myint; |
| 145 |
\& |
| 146 |
\& use v5.36; |
| 147 |
\& |
| 148 |
\& sub import { |
| 149 |
\& $^H{"myint/in_effect"} = 1; |
| 150 |
\& } |
| 151 |
\& |
| 152 |
\& sub unimport { |
| 153 |
\& $^H{"myint/in_effect"} = 0; |
| 154 |
\& } |
| 155 |
\& |
| 156 |
\& sub in_effect { |
| 157 |
\& my $level = shift // 0; |
| 158 |
\& my $hinthash = (caller($level))[10]; |
| 159 |
\& return $hinthash\->{"myint/in_effect"}; |
| 160 |
\& } |
| 161 |
\& |
| 162 |
\& 1; |
| 163 |
.Ve |
| 164 |
.PP |
| 165 |
As pragmata are implemented as modules, like any other module, \f(CW\*(C`use myint;\*(C'\fR |
| 166 |
becomes |
| 167 |
.PP |
| 168 |
.Vb 4 |
| 169 |
\& BEGIN { |
| 170 |
\& require myint; |
| 171 |
\& myint\->import(); |
| 172 |
\& } |
| 173 |
.Ve |
| 174 |
.PP |
| 175 |
and \f(CW\*(C`no myint;\*(C'\fR is |
| 176 |
.PP |
| 177 |
.Vb 4 |
| 178 |
\& BEGIN { |
| 179 |
\& require myint; |
| 180 |
\& myint\->unimport(); |
| 181 |
\& } |
| 182 |
.Ve |
| 183 |
.PP |
| 184 |
Hence the \f(CW\*(C`import\*(C'\fR and \f(CW\*(C`unimport\*(C'\fR routines are called at \fBcompile time\fR |
| 185 |
for the user's code. |
| 186 |
.PP |
| 187 |
User pragmata store their state by writing to the magical hash \f(CW\*(C`%^H\*(C'\fR, |
| 188 |
hence these two routines manipulate it. The state information in \f(CW\*(C`%^H\*(C'\fR is |
| 189 |
stored in the optree, and can be retrieved read-only at runtime with \f(CWcaller()\fR, |
| 190 |
at index 10 of the list of returned results. In the example pragma, retrieval |
| 191 |
is encapsulated into the routine \f(CWin_effect()\fR, which takes as parameter |
| 192 |
the number of call frames to go up to find the value of the pragma in the |
| 193 |
user's script. This uses \f(CWcaller()\fR to determine the value of |
| 194 |
\&\f(CW$^H{"myint/in_effect"}\fR when each line of the user's script was called, and |
| 195 |
therefore provide the correct semantics in the subroutine implementing the |
| 196 |
overloaded addition. |
| 197 |
.SH "Key naming" |
| 198 |
.IX Header "Key naming" |
| 199 |
There is only a single \f(CW\*(C`%^H\*(C'\fR, but arbitrarily many modules that want |
| 200 |
to use its scoping semantics. To avoid stepping on each other's toes, |
| 201 |
they need to be sure to use different keys in the hash. It is therefore |
| 202 |
conventional for a module to use only keys that begin with the module's |
| 203 |
name (the name of its main package) and a "/" character. After this |
| 204 |
module-identifying prefix, the rest of the key is entirely up to the |
| 205 |
module: it may include any characters whatsoever. For example, a module |
| 206 |
\&\f(CW\*(C`Foo::Bar\*(C'\fR should use keys such as \f(CW\*(C`Foo::Bar/baz\*(C'\fR and \f(CW\*(C`Foo::Bar/$%/_!\*(C'\fR. |
| 207 |
Modules following this convention all play nicely with each other. |
| 208 |
.PP |
| 209 |
The Perl core uses a handful of keys in \f(CW\*(C`%^H\*(C'\fR which do not follow this |
| 210 |
convention, because they predate it. Keys that follow the convention |
| 211 |
won't conflict with the core's historical keys. |
| 212 |
.SH "Implementation details" |
| 213 |
.IX Header "Implementation details" |
| 214 |
The optree is shared between threads. This means there is a possibility that |
| 215 |
the optree will outlive the particular thread (and therefore the interpreter |
| 216 |
instance) that created it, so true Perl scalars cannot be stored in the |
| 217 |
optree. Instead a compact form is used, which can only store values that are |
| 218 |
integers (signed and unsigned), strings or \f(CW\*(C`undef\*(C'\fR \- references and |
| 219 |
floating point values are stringified. If you need to store multiple values |
| 220 |
or complex structures, you should serialise them, for example with \f(CW\*(C`pack\*(C'\fR. |
| 221 |
The deletion of a hash key from \f(CW\*(C`%^H\*(C'\fR is recorded, and as ever can be |
| 222 |
distinguished from the existence of a key with value \f(CW\*(C`undef\*(C'\fR with |
| 223 |
\&\f(CW\*(C`exists\*(C'\fR. |
| 224 |
.PP |
| 225 |
\&\fBDon't\fR attempt to store references to data structures as integers which |
| 226 |
are retrieved via \f(CW\*(C`caller\*(C'\fR and converted back, as this will not be threadsafe. |
| 227 |
Accesses would be to the structure without locking (which is not safe for |
| 228 |
Perl's scalars), and either the structure has to leak, or it has to be |
| 229 |
freed when its creating thread terminates, which may be before the optree |
| 230 |
referencing it is deleted, if other threads outlive it. |