~ubuntu-branches/ubuntu/intrepid/perl-doc-html/intrepid

<div id="contentBody"><div class="title_container"><div class="page_title">perlpragma</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#DESCRIPTION">DESCRIPTION</a><li><a href="#A-basic-example">A basic example</a><li><a href="#Implementation-details">Implementation details</a></ul><a name="NAME"></a><h1>NAME</h1>

perlpragma - how to write a user pragma

<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>

A pragma is a module which influences some aspect of the compile time or run

time behaviour of Perl, such as <code class="inline">strict</code>

or <code class="inline">warnings</code>

. With Perl 5.10 you

are no longer limited to the built in pragmata; you can now create user

pragmata that modify the behaviour of user functions within a lexical scope.

<a name="A-basic-example"></a><h1>A basic example</h1>

For example, say you need to create a class implementing overloaded

mathematical operators, and would like to provide your own pragma that

functions much like <code class="inline"><a class="l_k" href="functions/use.html">use</a> integer;</code>

100

You'd like this code

101

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> MyMaths;</pre>

102

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $l = MyMaths->new(1.2);

103

<a class="l_k" href="functions/my.html">my</a> $r = MyMaths->new(3.4);</pre>

104

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> "A: ", $l + $r, "\n";</pre>

105

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> myint;

106

<a class="l_k" href="functions/print.html">print</a> "B: ", $l + $r, "\n";</pre>

107

<pre class="verbatim"> {

108

<a class="l_k" href="functions/no.html">no</a> myint;

109

<a class="l_k" href="functions/print.html">print</a> "C: ", $l + $r, "\n";

110

}</pre>

111

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> "D: ", $l + $r, "\n";</pre>

112

<pre class="verbatim"> <a class="l_k" href="functions/no.html">no</a> myint;

113

<a class="l_k" href="functions/print.html">print</a> "E: ", $l + $r, "\n";</pre>

114

to give the output

115

<pre class="verbatim"> A: 4.6

116

B: 4

117

C: 4.6

118

D: 4

119

E: 4.6</pre>i.e., where <code class="inline"><a class="l_k" href="functions/use.html">use</a> myint;</code>

120

is in effect, addition operations are forced

121

to integer, whereas by default they are not, with the default behaviour being

122

restored via <code class="inline"><a class="l_k" href="functions/no.html">no</a> myint;</code>

123

124

The minimal implementation of the package <code class="inline">MyMaths</code>

125

would be something like

126

this:

127

<pre class="verbatim"><a name="package-MyMaths"></a> package MyMaths;

128

<a class="l_k" href="functions/use.html">use</a> warnings;

129

<a class="l_k" href="functions/use.html">use</a> strict;

130

<a class="l_k" href="functions/use.html">use</a> myint();

131

<a class="l_k" href="functions/use.html">use</a> overload '+' => <a class="l_k" href="functions/sub.html">sub</a> {

132

<a class="l_k" href="functions/my.html">my</a> ($l, $r) = @_;

133

# Pass 1 to check up one call level from here

134

if (myint::in_effect(1)) {

135

<a class="l_k" href="functions/int.html">int</a>($$l) + <a class="l_k" href="functions/int.html">int</a>($$r);

136

} else {

137

$$l + $$r;

138

}

139

};</pre>

140

<pre class="verbatim"><a name="new"></a> sub new {

141

<a class="l_k" href="functions/my.html">my</a> ($class, $value) = @_;

142

<a class="l_k" href="functions/bless.html">bless</a> \$value, $class;

143

}</pre>

144

145

Note how we load the user pragma <code class="inline">myint</code>

146

with an empty list <code class="inline">()</code>

147

148

prevent its <code class="inline"><a class="l_k" href="functions/import.html">import</a></code> being called.

149

The interaction with the Perl compilation happens inside package <code class="inline">myint</code>

150

:

151

<pre class="verbatim"><a name="package-myint"></a> package myint;</pre>

152

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> strict;

153

<a class="l_k" href="functions/use.html">use</a> warnings;</pre>

154

<pre class="verbatim"><a name="import"></a> sub import {

155

$^H{myint} = 1;

156

}</pre>

157

<pre class="verbatim"><a name="unimport"></a> sub unimport {

158

$^H{myint} = 0;

159

}</pre>

160

<pre class="verbatim"><a name="in_effect"></a> sub in_effect {

161

<a class="l_k" href="functions/my.html">my</a> $level = <a class="l_k" href="functions/shift.html">shift</a> // 0;

162

<a class="l_k" href="functions/my.html">my</a> $hinthash = (<a class="l_k" href="functions/caller.html">caller</a>($level))[10];

163

<a class="l_k" href="functions/return.html">return</a> $hinthash->{myint};

164

}</pre>

165

166

As pragmata are implemented as modules, like any other module, <code class="inline"><a class="l_k" href="functions/use.html">use</a> myint;</code>

167

168

becomes

169

<pre class="verbatim"> BEGIN {

170

<a class="l_k" href="functions/require.html">require</a> myint;

171

myint->import();

172

}</pre>

173

and <code class="inline"><a class="l_k" href="functions/no.html">no</a> myint;</code>

174

is

175

<pre class="verbatim"> BEGIN {

176

<a class="l_k" href="functions/require.html">require</a> myint;

177

myint->unimport();

178

}</pre>

179

Hence the <code class="inline"><a class="l_k" href="functions/import.html">import</a></code> and <code class="inline">unimport</code>

180

routines are called at compile time

181

for the user's code.

182

User pragmata store their state by writing to the magical hash <code class="inline">%^H</code>

183

184

hence these two routines manipulate it. The state information in <code class="inline">%^H</code>

185

186

stored in the optree, and can be retrieved at runtime with <code class="inline"><a class="l_k" href="functions/caller.html">caller()</a></code>, at

187

index 10 of the list of returned results. In the example pragma, retrieval

188

is encapsulated into the routine <code class="inline">in_effect()</code>

189

, which takes as parameter

190

the number of call frames to go up to find the value of the pragma in the

191

user's script. This uses <code class="inline"><a class="l_k" href="functions/caller.html">caller()</a></code> to determine the value of

192

<code class="inline">$^H{myint}</code>

193

when each line of the user's script was called, and

194

therefore provide the correct semantics in the subroutine implementing the

195

overloaded addition.

196

<a name="Implementation-details"></a><h1>Implementation details</h1>

197

The optree is shared between threads. This means there is a possibility that

198

the optree will outlive the particular thread (and therefore the interpreter

199

instance) that created it, so true Perl scalars cannot be stored in the

200

optree. Instead a compact form is used, which can only store values that are

201

integers (signed and unsigned), strings or <code class="inline"><a class="l_k" href="functions/undef.html">undef</a></code> - references and

202

floating point values are stringified. If you need to store multiple values

203

or complex structures, you should serialise them, for example with <code class="inline"><a class="l_k" href="functions/pack.html">pack</a></code>.

204

The deletion of a hash key from <code class="inline">%^H</code>

205

is recorded, and as ever can be

206

distinguished from the existence of a key with value <code class="inline"><a class="l_k" href="functions/undef.html">undef</a></code> with

207

<code class="inline"><a class="l_k" href="functions/exists.html">exists</a></code>.

208

Don't attempt to store references to data structures as integers which

209

are retrieved via <code class="inline"><a class="l_k" href="functions/caller.html">caller</a></code> and converted back, as this will not be threadsafe.

210

Accesses would be to the structure without locking (which is not safe for

211

Perl's scalars), and either the structure has to leak, or it has to be

212

freed when its creating thread terminates, which may be before the optree

213

referencing it is deleted, if other threads outlive it.

214

</div>

215

216

</div>

217

</div>

218

219

220

221

222

223

</div>

224

<h1>Search:</h1>

225

226

227

228

229

</form>

230

231

232

<h2>Labels:</h2>

233

234

235

236

237

</div>

238

</div>

239

</div>

240

241

</div>

242

243

</body>

244

</html>

Older »