Debian Codegraph @

upstream/debian-unstable/man1/perlpragma.1

raw
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.