1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
|
<!DOCTYPE html>
<html >
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="generator" content="hevea 2.34">
<style type="text/css">
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.footnotetext{margin:0ex; padding:0ex;}
div.footnotetext P{margin:0px; text-indent:1em;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{margin:1em auto 1em 0px;width:50%;}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.titlemain{margin:1ex 2ex 2ex 1ex;}
.titlerest{margin:0ex 2ex;}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
div table{margin-left:inherit;margin-right:inherit;margin-bottom:2px;margin-top:2px}
td table{margin:auto;}
table{border-collapse:collapse;}
td{padding:0;}
.cellpadding0 tr td{padding:0;}
.cellpadding1 tr td{padding:1px;}
pre{text-align:left;margin-left:0ex;margin-right:auto;}
blockquote{margin-left:4ex;margin-right:4ex;text-align:left;}
td p{margin:0px;}
.boxed{border:1px solid black}
.textboxed{border:1px solid black}
.vbar{border:none;width:2px;background-color:black;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.hfill{border:none;height:1px;width:200%;background-color:black;}
.vdisplay{border-collapse:separate;border-spacing:2px;width:auto; empty-cells:show; border:2px solid red;}
.vdcell{white-space:nowrap;padding:0px; border:2px solid green;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px; border:none;}
.dcenter{margin:0ex auto;}
.vdcenter{border:solid #FF8000 2px; margin:0ex auto;}
.minipage{text-align:left; margin-left:0em; margin-right:auto;}
.marginpar{border:solid thin black; width:20%; text-align:left;}
.marginparleft{float:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; margin-left:1ex; margin-right:0ex;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
</style>
<title>gp2c types and the description system
</title>
</head>
<body >
<!--HEVEA command line is: hevea -fix ./type.tex -->
<!--CUT STYLE article--><!--CUT DEF section 1 --><table class="title"><tr><td style="padding:1ex"><h1 class="titlemain"><span style="font-family:monospace">gp2c</span> types and the description system</h1><h3 class="titlerest">By Bill Allombert</h3></td></tr>
</table><!--TOC section id="sec1" Contents-->
<h2 id="sec1" class="section">Contents</h2><!--SEC END --><ul class="toc"><li class="li-toc">
<a href="#sec2">1<span style="font-family:monospace">gp2c</span> types</a>
<ul class="toc"><li class="li-toc">
<a href="#sec3">1.1Introduction</a>
</li><li class="li-toc"><a href="#sec4">1.2List of types</a>
<ul class="toc"><li class="li-toc">
<a href="#sec5">1.2.1Basic types</a>
</li><li class="li-toc"><a href="#sec6">1.2.2Special types</a>
</li><li class="li-toc"><a href="#sec7">1.2.3Internal types</a>
</li><li class="li-toc"><a href="#sec8">1.2.4Types for data structure.</a>
</li></ul>
</li><li class="li-toc"><a href="#sec9">1.3C-Type</a>
</li></ul>
</li><li class="li-toc"><a href="#sec10">2The description system</a>
<ul class="toc"><li class="li-toc">
<a href="#sec11">2.1Introduction</a>
</li><li class="li-toc"><a href="#sec12">2.2Definitions</a>
<ul class="toc"><li class="li-toc">
<a href="#sec13">2.2.1Description</a>
</li><li class="li-toc"><a href="#sec14">2.2.2Rule</a>
</li><li class="li-toc"><a href="#sec15">2.2.3Pattern</a>
</li><li class="li-toc"><a href="#sec16">2.2.4Type</a>
</li><li class="li-toc"><a href="#sec17">2.2.5Modelist</a>
</li><li class="li-toc"><a href="#sec18">2.2.6Action</a>
</li></ul>
</li><li class="li-toc"><a href="#sec19">2.3Pattern atom</a>
</li><li class="li-toc"><a href="#sec20">2.4Matching</a>
</li><li class="li-toc"><a href="#sec21">2.5Mode</a>
</li><li class="li-toc"><a href="#sec22">2.6Lists of replacement strings</a>
</li><li class="li-toc"><a href="#sec23">2.7Lists of RPN commands</a>
</li></ul>
</li></ul>
<!--TOC section id="sec2" <span style="font-family:monospace">gp2c</span> types-->
<h2 id="sec2" class="section">1<span style="font-family:monospace">gp2c</span> types</h2><!--SEC END -->
<!--TOC subsection id="sec3" Introduction-->
<h3 id="sec3" class="subsection">1.1Introduction</h3><!--SEC END --><p>The main feature GP2C adds above GP is the use of types. Types give a
semantic to PARI objects, so that GP2C can generate code that use
specialized (hence faster) PARI functions instead of generic ones. Please
read the section ’Advanced use of GP2C’ in the GP2C manual for how to use
the GP2C types and examples.</p><p>Such types are used in conjunctions with so-called <em>descriptions</em> which
are stored in the field ’Description:’ of the file <span style="font-family:monospace">pari.desc</span> and provide
the actual C code to use depending of the types of the arguments. They are
described in Section<a href="#description">2</a>.</p><p>Abstractly, a GP2C type is a set of pairs (<span style="font-style:italic">A</span>,<span style="font-style:italic">B</span>) where <span style="font-style:italic">A</span> is a mathematical
object and <span style="font-style:italic">B</span> its computer representation. Two different types can contain
the same mathematical object, with a different computer representation.
For example the type <span style="font-style:italic">bool</span> is the set {(true,1L), (false,0L)},
<em>i.e.</em>true and false with true coded by the C-long integer 1 and
false coded by the C-long integer 0; the type <span style="font-style:italic">negbool</span> is
the set {(true,0L), (false,1L)} which is the same set of mathematical objects,
but now true is coded by the C-long integer 0 and false by the C-long
integer 1.</p><p>For each GP2C type, there exists a C type <span style="font-style:italic">Ct</span> such that for all pairs (<span style="font-style:italic">A</span>,<span style="font-style:italic">B</span>)
belonging to the type, the C type of <span style="font-style:italic">B</span> is <span style="font-style:italic">Ct</span>. This C type is specified by
the description <span style="font-family:sans-serif">_typedef</span>.</p><p>The GP2C types are preordered. Abstractly, we say that <span style="font-style:italic">t</span><sub>1</sub>≺
<span style="font-style:italic">t</span><sub>2</sub> if and only if there is a map <span style="font-style:italic">f</span> such that (<span style="font-style:italic">A</span>,<span style="font-style:italic">B</span>)↦ (<span style="font-style:italic">A</span>,<span style="font-style:italic">f</span>(<span style="font-style:italic">B</span>))
defines a one-to-one mapping from <span style="font-style:italic">t</span><sub>1</sub> to <span style="font-style:italic">t</span><sub>2</sub>.
Practically we restrict the relation ≺ to make it a partial order
such that any two types have an upper bound.
This partial order is defined by the chains in the description
<span style="font-family:sans-serif">_type_preorder</span>. It can be printed by running <code>gp2c -t</code>.</p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<div class="center">
<table class="display dcenter"><tr style="vertical-align:middle"><td class="dcell">
<img src="type001.png">
</td></tr>
</table>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 1: Example of type preorder</td></tr>
</table></div>
<a id="fig:type"></a>
</div>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>The process of converting a mathematical object from one type to
another is called casting. The casting methods known to GP2C are
given by the <span style="font-family:sans-serif">_cast</span> description.</p>
<!--TOC subsection id="sec4" List of types-->
<h3 id="sec4" class="subsection">1.2List of types</h3><!--SEC END --><p>In this section, we list the types known to PARI/GP.
The current list is available in the description <span style="font-family:sans-serif">_typedef</span>.</p>
<!--TOC subsubsection id="sec5" Basic types-->
<h4 id="sec5" class="subsubsection">1.2.1Basic types</h4><!--SEC END --><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">small</span></dt><dd class="dd-description"> Small integers represented by C <span style="font-family:sans-serif">long</span> integers.
</dd><dt class="dt-description"><span style="font-weight:bold">int</span></dt><dd class="dd-description"> Multi-precision integers represented by <span style="font-family:monospace">t_INT</span> GENs.
</dd><dt class="dt-description"><span style="font-weight:bold">real</span></dt><dd class="dd-description"> Multi-precision floating point real numbers represented by <span style="font-family:monospace">t_REAL</span> GENs.
</dd><dt class="dt-description"><span style="font-weight:bold">mp</span></dt><dd class="dd-description"> Multi-precision numbers. Union of the types <span style="font-style:italic">int</span> and <span style="font-style:italic">real</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">vecsmall</span></dt><dd class="dd-description"> Vectors of small integers represented by <span style="font-family:monospace">t_VECSMALL</span> GENs.
</dd><dt class="dt-description"><span style="font-weight:bold">vec</span></dt><dd class="dd-description"> Vectors and matrices of PARI objects, represented by <span style="font-family:monospace">t_VEC</span>,
<span style="font-family:monospace">t_COL</span> or <span style="font-family:monospace">t_MAT</span> GENs.
</dd><dt class="dt-description"><span style="font-weight:bold">var</span></dt><dd class="dd-description"> Polynomial variables represented by their variable number which is
a C <span style="font-family:sans-serif">long</span> integer. This is associated to the prototype code ’n’.
</dd><dt class="dt-description"><span style="font-weight:bold">pol</span></dt><dd class="dd-description"> Polynomials represented by <span style="font-family:monospace">t_POL</span> GENs.
</dd><dt class="dt-description"><span style="font-weight:bold">genstr</span></dt><dd class="dd-description"> Strings represented by <span style="font-family:monospace">t_STR</span> GENs.
</dd><dt class="dt-description"><span style="font-weight:bold">list</span></dt><dd class="dd-description"> GP lists represented by <span style="font-family:monospace">t_LIST</span> GENs.
</dd><dt class="dt-description"><span style="font-weight:bold">gen</span></dt><dd class="dd-description"> Generic PARI objects represented by GENs.
</dd></dl>
<!--TOC subsubsection id="sec6" Special types-->
<h4 id="sec6" class="subsubsection">1.2.2Special types</h4><!--SEC END --><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">void</span></dt><dd class="dd-description"> This type is a set with only one element called <span style="font-style:italic">void</span>. This is
the return type of functions not returning anything. GP allows to cast it to
0.
</dd><dt class="dt-description"><span style="font-weight:bold">bool</span></dt><dd class="dd-description"> Boolean values represented as C <span style="font-family:sans-serif">long</span> integers, where 1 is
true and 0 is false.
</dd><dt class="dt-description"><span style="font-weight:bold">negbool</span></dt><dd class="dd-description"> Negated boolean values represented as C <span style="font-family:sans-serif">long</span> integers,
where 0 is true and 1 is false.</dd><dt class="dt-description"><span style="font-weight:bold">lg</span></dt><dd class="dd-description"> Vector lengths represented by the <span style="font-family:sans-serif">lg</span> macro output, i.e.
a C <span style="font-family:sans-serif">long</span> integer equal to the actual length plus one.</dd><dt class="dt-description"><span style="font-weight:bold">str</span></dt><dd class="dd-description"> C strings represented by C <span style="font-family:sans-serif">const char *</span> strings.
</dd><dt class="dt-description"><span style="font-weight:bold">typ</span></dt><dd class="dd-description"> GEN types represented by C <span style="font-family:sans-serif">long</span> integers, as returned by the
<span style="font-family:sans-serif">typ()</span> macro.
</dd></dl>
<!--TOC subsubsection id="sec7" Internal types-->
<h4 id="sec7" class="subsubsection">1.2.3Internal types</h4><!--SEC END --><p>
The following types are mainly for internal use inside GP2C.
</p><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">empty</span></dt><dd class="dd-description"> This type is the empty set. No individual object can be of this
type but a set of objects can. In fact this is a default type for an
unspecified set of objects.
</dd><dt class="dt-description"><span style="font-weight:bold">small_int</span></dt><dd class="dd-description"> Small integers represented by C <span style="font-family:sans-serif">int</span> integers.
This is only available for compatibility with PARI function returning
<span style="font-family:sans-serif">int</span> (instead of <span style="font-family:sans-serif">long</span>).
</dd><dt class="dt-description"><span style="font-weight:bold">bptr</span></dt><dd class="dd-description"> Byte pointer. This is used for the <span style="font-family:sans-serif">primepointer</span> global
variable.
</dd><dt class="dt-description"><span style="font-weight:bold">func_GG</span></dt><dd class="dd-description"> function with protype <span style="font-family:sans-serif">GEN f(GEN,GEN)</span>. Used by
<span style="font-style:italic">forvec</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">pari_sp</span></dt><dd class="dd-description"> This is the stack pointer type <span style="font-family:sans-serif">pari_sp</span>.
</dd></dl>
<!--TOC subsubsection id="sec8" Types for data structure.-->
<h4 id="sec8" class="subsubsection">1.2.4Types for data structure.</h4><!--SEC END --><p>
These types are mainly defined to allow the use of inline member functions.</p><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">nf</span></dt><dd class="dd-description"> Number field as returned by <span style="font-style:italic">nfinit</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">bnf</span></dt><dd class="dd-description"> Big number field as returned by <span style="font-style:italic">bnfinit</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">bnr</span></dt><dd class="dd-description"> Ray class field as returned by <span style="font-style:italic">bnrinit</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">ell</span></dt><dd class="dd-description"> Elliptic curve as returned by <span style="font-style:italic">ellinit</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">bell</span></dt><dd class="dd-description"> Big elliptic curve as returned by <span style="font-style:italic">ellinit</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">clgp</span></dt><dd class="dd-description"> Class group as returned by the ’clgp’ member function.
</dd><dt class="dt-description"><span style="font-weight:bold">prid</span></dt><dd class="dd-description"> Prime ideal as returned by <span style="font-style:italic">idealprimedec</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">gal</span></dt><dd class="dd-description"> Galois group as returned by <span style="font-style:italic">galoisinit</span>.
</dd></dl>
<!--TOC subsection id="sec9" C-Type-->
<h3 id="sec9" class="subsection">1.3C-Type</h3><!--SEC END --><p>
A <span style="font-style:italic">C-Type</span> is just a level of indirection toward real C types.
C-types are defined by the descriptions <span style="font-family:sans-serif">_decl_base</span> and
<span style="font-family:sans-serif">_decl_ext</span>. Each type belongs to a C-type as specified by the
description <span style="font-family:sans-serif">_typedef</span>.</p>
<!--TOC section id="sec10" The description system-->
<h2 id="sec10" class="section">2The description system</h2><!--SEC END --><p><a id="description"></a></p>
<!--TOC subsection id="sec11" Introduction-->
<h3 id="sec11" class="subsection">2.1Introduction</h3><!--SEC END --><p>The description system is a way to describe the PARI application programming
interface in a way understandable by both the GP2C compiler and human
beings. The present document is mostly addressed to this second category.
We start by a simple example:</p><p>The description of the GP function <span style="font-style:italic">sqr</span> is
</p><pre class="verbatim"> (int):int sqri($1)
(mp):mp gsqr($1)
(gen):gen gsqr($1)
</pre><p>Each line is called a <span style="font-style:italic">rule</span>, which in this case consists of three
parts. Let us consider the first one: the parts <code>(int)</code>, <code>:int</code> and
<code>sqri($1)</code> are respectively called the <span style="font-style:italic">pattern</span>, <span style="font-style:italic">type</span>,
and <span style="font-style:italic">action</span> part.</p><p>When GP2C compiles <span style="font-style:italic">sqr(1)</span>, it computes the types of the arguments
(here<span style="font-style:italic">1</span> is of type <span style="font-style:italic">small</span>) and matches them against the patterns
from top to bottom. The “best” rule is used; in case of a tie, the topmost
rule wins. Here, all three rules apply, and the first rule wins. Since the type
of this rule is <span style="font-style:italic">int</span>, GP2C sets the type of the expression
<span style="font-style:italic">sqr(1)</span> to <span style="font-style:italic">int</span>. The action part is <code>sqri($1)</code>, so GP2C
generates the C code <span style="font-family:sans-serif">sqri($1)</span> where <span style="font-family:sans-serif">$1</span> is replaced by the
code of the argument <span style="font-style:italic">1</span> cast to the pattern type (<span style="font-style:italic">int</span>). The result
is the C code <span style="font-family:sans-serif">sqri(gen_1)</span>.</p><p>Now a more complex example: the description of the GP function <span style="font-style:italic">exp</span> is
</p><pre class="verbatim"> (real):real mpexp($1)
(mp):mp:prec gexp($1, prec)
(gen):gen:prec gexp($1, prec)
</pre><p>
When GP2C compiles <span style="font-style:italic">exp(1)</span>, it looks for the "best" rules.
The first rule cannot be used, because there is no way to cast a
<span style="font-style:italic">small</span> to a <span style="font-style:italic">real</span>, so it uses the second rule.
This time the result will be
of type <span style="font-style:italic">mp</span>. The extra part <code>:prec</code> is called a mode. The
mode ‘prec’ states that the action part will use the special ‘prec’
variable that holds the current real precision. This is obvious from
the action part code, but GP2C do not parse the action part so it
needs this mode. Note that the last rule is also valid and has the
same action part so would generate the exact same code. However, the
type of the expression would be less precise.</p><p>The description of the GP function <span style="font-style:italic">matdet</span> is
</p><pre class="verbatim"> (gen, ?0):gen det($1)
(gen, 1):gen det2($1)
(gen, #small):gen $"incorrect flag in matdet"
(gen, small):gen det0($1, $2)
</pre><p>
We see several new pattern atoms:
</p><ul class="itemize"><li class="li-itemize">
<span style="font-style:italic">1</span> matches a literal 1, e.g. <span style="font-style:italic">matdet(M,1)</span> would match the
second rule.
</li><li class="li-itemize"><span style="font-style:italic">?0</span> matches an optional literal 0: <span style="font-style:italic">matdet(M)</span>,
<span style="font-style:italic">matdet(M,0)</span> and <span style="font-style:italic">matdet(M,)</span> all match the first rule.
</li><li class="li-itemize"><span style="font-style:italic">#small</span> matches an unspecified literal <span style="font-style:italic">small</span>.
</li></ul><p>
Finally, we also see a new action <span style="font-style:italic">$"…"</span>, which causes GP2C
to display the error message and abort.</p>
<!--TOC subsection id="sec12" Definitions-->
<h3 id="sec12" class="subsection">2.2Definitions</h3><!--SEC END --><p>
We now give a formal definition of descriptions.
</p>
<!--TOC subsubsection id="sec13" Description-->
<h4 id="sec13" class="subsubsection">2.2.1Description</h4><!--SEC END --><p>
A description is a line-separated list of <span style="font-style:italic">rules</span>.
</p>
<!--TOC subsubsection id="sec14" Rule-->
<h4 id="sec14" class="subsubsection">2.2.2Rule</h4><!--SEC END --><p>
A rule is a line of the form
</p><blockquote class="quote">
(<span style="font-style:italic">pattern</span>)<span style="font-style:italic">:type</span><span style="font-style:italic">:modelist</span> <span style="font-style:italic">action</span>
</blockquote><p>
Only the pattern part is mandatory, though most rules also include
an action and a type.</p>
<!--TOC subsubsection id="sec15" Pattern-->
<h4 id="sec15" class="subsubsection">2.2.3Pattern</h4><!--SEC END --><p>
A pattern is a comma-separated list of <span style="font-style:italic">pattern atoms</span>.</p>
<!--TOC subsubsection id="sec16" Type-->
<h4 id="sec16" class="subsubsection">2.2.4Type</h4><!--SEC END --><p>
The type of a rule is a standard GP2C type.</p>
<!--TOC subsubsection id="sec17" Modelist-->
<h4 id="sec17" class="subsubsection">2.2.5Modelist</h4><!--SEC END --><p>
A modelist is a colon-separated list of <span style="font-style:italic">modes</span>.</p>
<!--TOC subsubsection id="sec18" Action-->
<h4 id="sec18" class="subsubsection">2.2.6Action</h4><!--SEC END --><p>An action is a string (normally a piece of C code) that can
include <span style="font-style:italic">replacement strings</span>. Replacement strings start by
a $ and are substituted according to the replacement rules.</p>
<!--TOC subsection id="sec19" Pattern atom-->
<h3 id="sec19" class="subsection">2.3Pattern atom</h3><!--SEC END --><p>A pattern atom is one of the following, where <span style="font-style:italic">type</span> is any GP2C type,
<span style="font-style:italic">n</span> any small integer, <span style="font-style:italic">"str"</span> any character string and <span style="font-style:italic">ctype</span>
any C-type. A pattern atom can match an object.</p><ul class="itemize"><li class="li-itemize">
<span style="font-style:italic">type</span>. This matches any object of type comparable to <span style="font-style:italic">type</span>.
</li><li class="li-itemize"><span style="font-style:italic">n</span>. This matches a constant small integer value equal to <span style="font-style:italic">n</span>.
</li><li class="li-itemize"><span style="font-style:italic">?n</span>. This matches an optional <span style="font-style:italic">small</span> value which defaults to
<span style="font-style:italic">n</span>.
</li><li class="li-itemize"><span style="font-style:italic">?type</span>. This matches an optional <span style="font-style:italic">type</span> value with standard default value.
</li><li class="li-itemize"><span style="font-style:italic">"str"</span>. This matches a constant character string equal to <span style="font-style:italic">str</span>.
</li><li class="li-itemize"><span style="font-style:italic">&type</span>. This matches a reference (the GP <span style="font-style:italic">&x</span> construction) to
an object of type equal or less than <span style="font-style:italic">type</span> referencing the same data type.
</li><li class="li-itemize"><span style="font-style:italic">nothing</span>. This matches a missing argument.
</li><li class="li-itemize"><span style="font-style:italic">#type</span>. This matches a constant value of type <span style="font-style:italic">type</span>.
</li><li class="li-itemize"><span style="font-style:italic">...</span> This matches any number of arguments matching the previous atom.
This must be the last atom of the pattern. This allows to implement functions
taking an unlimited number of arguments.
</li><li class="li-itemize"><span style="font-style:italic">C!ctype</span>. This matches any object of C-type <span style="font-style:italic">ctype</span>.
</li><li class="li-itemize"><span style="font-style:italic">@type</span>. This matches a variable of type <span style="font-style:italic">type</span>. This is mainly used
for expressions that evaluate their arguments several times.
</li><li class="li-itemize"><span style="font-style:italic">*type</span>. This matches an lvalue of type <span style="font-style:italic">type</span>. This is used in
constructions that modify their arguments.
</li></ul>
<!--TOC subsection id="sec20" Matching-->
<h3 id="sec20" class="subsection">2.4Matching</h3><!--SEC END --><p>The best rule is determined as follows:
</p><ol class="enumerate" type=1><li class="li-enumerate">
The result of matching a pattern atom against some GP code is
either ’reject’ or ’match’.
</li><li class="li-enumerate">There are three matching levels: ’partial’, ’normal’ and ’perfect’.
</li><li class="li-enumerate">A pattern matches if all the atoms match.
</li><li class="li-enumerate">A rule matches if its pattern matches.
</li><li class="li-enumerate">The best rule is the matching rule with the higher number of normal
and perfect matches. In case of a tie, the highest number of perfect matches
wins. If there is still a tie, the topmost rule wins.
</li></ol><p>When matching the pattern atoms <span style="font-style:italic">type</span> and <span style="font-style:italic">?type</span>, the matching
level is determined as follows:
</p><ul class="itemize"><li class="li-itemize">
a perfect match occurs when the type of the object is exactly <span style="font-style:italic">type</span>,
</li><li class="li-itemize">a normal match when the type is less than <span style="font-style:italic">type</span>,
</li><li class="li-itemize">a partial match when the type is bigger than <span style="font-style:italic">type</span>.
</li><li class="li-itemize">Rejection happens when the types are uncomparable.
</li></ul><p>
Other pattern atoms always result in a reject or a perfect match.</p>
<!--TOC subsection id="sec21" Mode-->
<h3 id="sec21" class="subsection">2.5Mode</h3><!--SEC END --><p>
Modes are used in descriptions to give more information to GP2C about the
action part. They are usually useless to human beings that are smart
enough to understand the action part. The current list of modes is:
</p><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">prec</span></dt><dd class="dd-description"> The action uses the <span style="font-family:sans-serif">prec</span> variable.
</dd><dt class="dt-description"><span style="font-weight:bold">parens</span></dt><dd class="dd-description"> The action does not have top precedence. GP2C will put it between
parentheses when needed (see $())
</dd><dt class="dt-description"><span style="font-weight:bold">copy</span></dt><dd class="dd-description"> The action returns data that access memory belonging to other
objects. GP2C will generate calls to <span style="font-family:sans-serif">gcopy()</span> when needed.
</dd></dl>
<!--TOC subsection id="sec22" Lists of replacement strings-->
<h3 id="sec22" class="subsection">2.6Lists of replacement strings</h3><!--SEC END --><p>The following special sequences can occur in the action part:
</p><ul class="itemize"><li class="li-itemize"><span style="font-family:sans-serif">$n</span>. This is replaced by the <span style="font-style:italic">n</span>-th argument of the function.</li><li class="li-itemize"><span style="font-family:sans-serif">$(n)</span>. This is replaced by the <span style="font-style:italic">n</span>-th argument of the function
between parenthesis if it has the parens mode.</li><li class="li-itemize"><span style="font-family:sans-serif">$type:n</span>. This is replaced by the <span style="font-style:italic">n</span>-th argument of the
function cast to type <span style="font-style:italic">type</span>.</li><li class="li-itemize"><span style="font-family:sans-serif">$(type:n)</span>. Combination of $(n) and $type:n.</li><li class="li-itemize"><span style="font-family:sans-serif">$%n</span>. This is replaced by the <span style="font-style:italic">n</span>-th argument of the function,
which must be a constant string, with all % characters doubled and no quotes.
This is for use inside format specification.</li><li class="li-itemize"><span style="font-family:sans-serif">$prec</span>: short cut for <span style="font-family:sans-serif">$</span><span style="font-family:sans-serif">prec</span>.
</li><li class="li-itemize"><span style="font-family:sans-serif">$bitprec</span>: short cut for <span style="font-family:sans-serif">$</span><span style="font-family:sans-serif">bitprec</span>.
</li><li class="li-itemize"><span style="font-family:sans-serif">$"message"</span>. Signals an invalid condition. GP2C will abort by
printing the error message <span style="font-family:sans-serif">message</span>.</li><li class="li-itemize"><span style="font-family:sans-serif">${RPN sequence}</span>
The RPN sequence is a space separated list of RPN commands that will be
evaluated by the GP2C internal RPN evaluator.
If the stack is empty at the end of the evaluation, this is replaced by
the empty string, else this is replaced by the integer at the top of the
stack. Some RPN commands generate text, in that case it is pasted just before
the $ sign.
</li></ul>
<!--TOC subsection id="sec23" Lists of RPN commands-->
<h3 id="sec23" class="subsection">2.7Lists of RPN commands</h3><!--SEC END --><p>
The commands are evaluated with respect to a stack of integer values,
initially empty.
The exact list of command supported by a particular GP2C version is the
<span style="font-family:sans-serif">%accepted_command</span> hash in the script <span style="font-family:monospace">scripts/822_desc.pl.in</span>.</p><dl class="description"><dt class="dt-description">
<span style="font-weight:bold"><span style="font-style:italic">literal integer</span></span></dt><dd class="dd-description"> push the integer at the top of the stack.
</dd><dt class="dt-description"><span style="font-weight:bold">:</span><span style="font-weight:bold"><span style="font-style:italic">type</span></span></dt><dd class="dd-description"> push the type <span style="font-style:italic">type</span> at the top of the stack.
</dd><dt class="dt-description"><span style="font-weight:bold">add, sub, mul, div, mod</span></dt><dd class="dd-description"> 2-ary arithmetic operators
</dd><dt class="dt-description"><span style="font-weight:bold">neg</span></dt><dd class="dd-description"> 1-ary arithmetic operator
</dd><dt class="dt-description"><span style="font-weight:bold">and, or, xor</span></dt><dd class="dd-description"> 2-ary logical operators
</dd><dt class="dt-description"><span style="font-weight:bold">not</span></dt><dd class="dd-description"> 1-ary logical operator
</dd><dt class="dt-description"><span style="font-weight:bold">type</span></dt><dd class="dd-description"> pop an integer <span style="font-style:italic">n</span> and push the type of the <span style="font-style:italic">n</span>-th argument.
</dd><dt class="dt-description"><span style="font-weight:bold">value</span></dt><dd class="dd-description"> pop an integer <span style="font-style:italic">n</span> and push the value of the <span style="font-style:italic">n</span>-th argument,
provided it is a constant integer.
</dd><dt class="dt-description"><span style="font-weight:bold">code</span></dt><dd class="dd-description"> pop an integer <span style="font-style:italic">n</span> and generate the C code for the <span style="font-style:italic">n</span>-th argument.
</dd><dt class="dt-description"><span style="font-weight:bold">cast</span></dt><dd class="dd-description"> pop an integer <span style="font-style:italic">n</span> and a type <span style="font-style:italic">t</span> and generate the C code for the
<span style="font-style:italic">n</span>-th argument cast to type <span style="font-style:italic">t</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">parens</span></dt><dd class="dd-description"> this is a flag requesting <span style="font-weight:bold">code</span> and <span style="font-weight:bold">cast</span> to enclose
the C code between parenthesis if the argument has the <span style="font-style:italic">parens</span> mode.
</dd><dt class="dt-description"><span style="font-weight:bold">str_format, str_raw</span></dt><dd class="dd-description"> pop an integer <span style="font-style:italic">n</span> such that the <span style="font-style:italic">n</span>-th argument
is a constant string and display the string without leading and ending ".
Furthermore <span style="font-weight:bold">str_format</span> will display the string in a way suitable for
inclusion in a format string by quoting meta-characters.
</dd><dt class="dt-description"><span style="font-weight:bold">prec</span></dt><dd class="dd-description"> display the local precision (in prec format).
</dd><dt class="dt-description"><span style="font-weight:bold">bitprec</span></dt><dd class="dd-description"> display the local precision in bit.
</dd></dl><p>The following RPN commands are useful with the <span style="font-style:italic">...</span> pattern atom to
implement functions that take an unlimited number of arguments.
</p><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">nbarg</span></dt><dd class="dd-description"> push the actual number of arguments of the function.
</dd><dt class="dt-description"><span style="font-weight:bold">format_string, format_args</span></dt><dd class="dd-description"> pop an integer <span style="font-style:italic">n</span> such that the <span style="font-style:italic">n</span>-th
argument corresponds to a <span style="font-style:italic">...</span> pattern atom and generate a format string
and a list of arguments, see the description of the GP function <span style="font-style:italic">print</span>.
</dd><dt class="dt-description"><span style="font-weight:bold">code, cast</span></dt><dd class="dd-description"> If the integer <span style="font-style:italic">n</span> corresponds to a <span style="font-style:italic">...</span> pattern atom,
generate a comma-separated list of C code for the arguments <span style="font-style:italic">n</span>−1, <span style="font-style:italic">n</span>, <span style="font-style:italic">n</span>+1,
…, <span style="font-weight:bold">nbarg</span>, by matching each argument against the <span style="font-style:italic">n</span>−1 pattern atom.
</dd><dt class="dt-description"><span style="font-weight:bold">stdref</span></dt><dd class="dd-description"> this is a flag requesting <span style="font-weight:bold">code</span> and <span style="font-weight:bold">type</span> to
prepend a ’&’ before each arguments.
</dd></dl><p>
The following RPN commands are useful to implement functions that take closures
as arguments.
</p><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">wrapper, cookie</span></dt><dd class="dd-description"> pop an integer <span style="font-style:italic">n</span> and generate a call to the wrapper
(resp. the cookie associated to the wrapper) for the <span style="font-style:italic">n</span>-th argument. The
wrapper generated depends on the wrapper prototype in the Wrapper field.
The cookie is the list of local variables seen by the closure.
</dd></dl><!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<hr style="height:2"><blockquote class="quote"><em>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</em><a href="http://hevea.inria.fr/index.html"><em>H</em><em><span style="font-size:small"><sup>E</sup></span></em><em>V</em><em><span style="font-size:small"><sup>E</sup></span></em><em>A</em></a><em>.</em></blockquote></body>
</html>
|
