grammar.mli 15.9 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
(* This module transforms [Front.grammar], an abstract syntax tree for
   the grammar, into an internal representation of the grammar that is
   more usable. *)

(* ------------------------------------------------------------------------ *)
(* Nonterminals. *)

module Nonterminal : sig

  (* The type of nonterminals. *)

  type t

14
15
16
17
  (* Comparison. *)

  val compare: t -> t -> int

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
  (* The number of nonterminals. This includes the extra nonterminals
     that are internally generated for the grammar's entry points. *)

  val n: int

  (* [lookup] maps an identifier to a nonterminal, or raises [Not_found]. *)

  val lookup : string -> t

  (* Nonterminals can be converted to integers. This feature is
     exploited in the table-based back-end. *)

  val n2i: t -> int

  (* This produces a string representation of a nonterminal. It should
     in principle never be applied to one of the internally generated
     nonterminals, as we do not wish users to become aware of the
     existence of these extra nonterminals. However, we do sometimes
     violate this rule when it is difficult to do otherwise.

     The Boolean parameter tells whether the string representation
     should be normalized, that is, whether parentheses and commas
     should be eliminated. This is necessary if the string is intended
     for use as a valid nonterminal name or as a valid Objective Caml
     identifier. *)

  val print: bool -> t -> string

  (* This is the Objective Caml type associated with a nonterminal
     symbol. It is known only if a %type declaration was provided.
     This function is not applicable to the internally generated
     nonterminals. *)

  val ocamltype: t -> Stretch.ocamltype option

53
54
55
56
57
  (* A start symbol always has a type. This allows us to define
     a simplified version of [ocamltype] for start symbols. *)

  val ocamltype_of_start_symbol: t -> Stretch.ocamltype

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
  (* Iteration over nonterminals. The order in which elements are
     examined, and the order of [map]'s output list, correspond to the
     numeric indices produced by [n2i] above. *)

  val iter: (t -> unit) -> unit
  val fold: (t -> 'a -> 'a) -> 'a -> 'a
  val map: (t -> 'a) -> 'a list

  (* Iteration over all nonterminals, except the start nonterminals. *)

  val iterx: (t -> unit) -> unit
  val foldx: (t -> 'a -> 'a) -> 'a -> 'a 

  (* Tabulation of a function over nonterminals. *)

  val tabulate: (t -> 'a) -> (t -> 'a)

  (* [positions nt] is a list of the positions associated with the
     definition of [nt]. There can be more than one position because
     definitions can be split over multiple files. *)

  val positions: t -> Positions.t list

  (* This tells whether a non-terminal symbol is one of the start
     symbols. *)

  val is_start: t -> bool

end

(* ------------------------------------------------------------------------ *)
(* Terminals. *)

module Terminal : sig

  (* The type of terminals. *)

  type t

  (* The number of terminals. This includes the two pseudo-tokens
     [#] and [error]. *)

  val n: int

  (* Comparison. *)

  val equal: t -> t -> bool
105
  val compare: t -> t -> int
106
107
108
109
110

  (* [lookup] maps an identifier to a terminal, or raises [Not_found]. *)

  val lookup : string -> t

111
112
113
  (* Terminals can be converted to integers. This feature is exploited in the
     table-based back-end and in [LRijkstra]. The reverse conversion, [i2t],
     is unsafe and should not be used. [LRijkstra] uses it :-) *)
114
115

  val t2i: t -> int
116
  val i2t: int -> t (* unsafe! *)
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

  (* This produces a string representation of a terminal. *)

  val print: t -> string

  (* This is the Objective Caml type associated with a terminal
     symbol. It is known only if the %token declaration was
     accompanied with a type. *)

  val ocamltype: t -> Stretch.ocamltype option

  (* These are the two pseudo-tokens [#] and [error]. The former is
     used to denote the end of the token stream. The latter is
     accessible to the user and is used for handling errors. *)

  val sharp: t
  val error: t

  (* This is the programmer-defined [EOF] token, if there is one. It
     is recognized based solely on its name, which is fragile, but
     this behavior is documented. This token is assumed to represent
138
139
     [ocamllex]'s [eof] pattern. It is used only by the reference
     interpreter, and in a rather non-essential way. *)
140
141
142

  val eof: t option

POTTIER Francois's avatar
POTTIER Francois committed
143
  (* A terminal symbol is pseudo if it is [#] or [error]. It is real otherwise. *)
144
145

  val pseudo: t -> bool
POTTIER Francois's avatar
POTTIER Francois committed
146
  val real: t -> bool
147
148
149

  (* Iteration over terminals. The order in which elements are
     examined, and the order of [map]'s output list, correspond to the
POTTIER Francois's avatar
POTTIER Francois committed
150
     numeric indices produced by [t2i] above. *)
151
152
153
154

  val iter: (t -> unit) -> unit
  val fold: (t -> 'a -> 'a) -> 'a -> 'a
  val map: (t -> 'a) -> 'a list
POTTIER Francois's avatar
POTTIER Francois committed
155
156
157

  (* [mapx] offers iteration over all terminals except [#]. *)

158
159
  val mapx: (t -> 'a) -> 'a list

POTTIER Francois's avatar
POTTIER Francois committed
160
  (* [iter_real] offers iteration over all real terminals. *)
POTTIER Francois's avatar
POTTIER Francois committed
161
162
163

  val iter_real: (t -> unit) -> unit

164
165
166
167
168
  (* The sub-module [Word] offers an implementation of words (that is,
     sequences) of terminal symbols. It is used by [LRijkstra]. We
     make it a functor, because it has internal state (a hash table)
     and a side effect (failure if there are more than 256 terminal
     symbols). *)
POTTIER Francois's avatar
POTTIER Francois committed
169

170
171
172
173
174
175
  (* The type [word] should be treated, as much as possible, as an
     abstract type. In fact, for efficiency reasons, we represent a
     word as a unique integer codes, and we allocate these integer
     codes sequentially, from 0 upwards. The conversion from [int]
     to [word] is of course unsafe and should be used wisely. *)

POTTIER Francois's avatar
POTTIER Francois committed
176
177
  module Word (X : sig end) : sig

178
    type word = int
POTTIER Francois's avatar
POTTIER Francois committed
179
180
181
182
183
184
185
186
187
188
189
    val epsilon: word
    val singleton: t -> word
    val append: word -> word -> word
    val length: word -> int
    (* [first w z] returns the first symbol of the word [w.z]. *)
    val first: word -> t -> t
    val elements: word -> t list
    val print: word -> string
    (* [verbose()] prints statistics about the use of the internal
       hash-consing table so far. *)
    val verbose: unit -> unit
POTTIER Francois's avatar
POTTIER Francois committed
190
191
    (* Lexicographic ordering. *)
    val compare: word -> word -> int
POTTIER Francois's avatar
POTTIER Francois committed
192
  end
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
end

(* ------------------------------------------------------------------------ *)
(* Sets and maps over terminals. *)

module TerminalSet : sig

  (* All of the operations documented in [GSet] are available. *)

  include GSet.S with type element = Terminal.t

  (* This offers a string representation of a set of terminals. The
     symbols are simply listed one after the other and separated with
     spaces. *)

  val print: t -> string

  (* This is the set of all terminal symbols except the pseudo-tokens
     [#] and [error]. *)

  val universe: t

end

(* All of the operations documented in [GMap] are available. *)

module TerminalMap : GMap.S with type key = Terminal.t

(* ------------------------------------------------------------------------ *)
(* Symbols. *)

module Symbol : sig

  (* A symbol is either a nonterminal or a terminal. *)

  type t =
    | N of Nonterminal.t
    | T of Terminal.t

  (* Comparison. *)

  val equal: t -> t -> bool
  val lequal: t list -> t list -> bool

  (* These produce a string representation of a symbol, of a list of
     symbols, or of an array of symbols. The symbols are simply listed
     one after the other and separated with spaces. [printao] prints
     an array of symbols, starting at a particular offset. [printaod]
     is analogous, but can also print a single dot at a particular
     position between two symbols. *)

  val print: t -> string
  val printl: t list -> string
  val printa: t array -> string
  val printao: int -> t array -> string
  val printaod: int -> int -> t array -> string

end

(* ------------------------------------------------------------------------ *)
(* Sets and maps over symbols. *)

(* All of the operations documented in [Set] are available. *)

module SymbolSet : Set.S with type elt = Symbol.t

module SymbolMap : sig

  (* All of the operations documented in [Map] are available. *)

  include Map.S with type key = Symbol.t

  val domain: 'a t -> key list

  (* This returns [true] if and only if all of the symbols in
     the domain of the map at hand are nonterminals. *)

  val purelynonterminal: 'a t -> bool

end

(* ------------------------------------------------------------------------ *)
(* Productions. *)

module Production : sig

  (* This is the type of productions. This includes user-defined
     productions as well as the internally generated productions
     associated with the start symbols. *)

  type index

286
287
288
289
  (* Comparison. *)

  val compare: index -> index -> int

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
  (* Productions can be converted to integers and back. This is unsafe
     and should be avoided as much as possible. This feature is
     exploited, for efficiency, in the encoding of items. *)

  val p2i: index -> int
  val i2p: int -> index

  (* The number of productions. *)

  val n: int

  (* These map a production index to the production's definition, that
     is, a nonterminal (the left-hand side) and an array of symbols
     (the right-hand side). *)

  val def: index -> Nonterminal.t * Symbol.t array
  val nt: index -> Nonterminal.t
  val rhs: index -> Symbol.t array
  val length: index -> int

  (* This maps a production index to an array of the identifiers that
     should be used for naming the semantic values of the symbols in
     the right-hand side. *)

  val identifiers: index -> Syntax.identifier array

  (* This maps a production index to the production's semantic action.
     This function is not applicable to a start production. *)

  val action: index -> Syntax.action

  (* [positions prod] is a list of the positions associated with
     production [prod]. This is usually a singleton list, but there
     can be more than one position for start productions when the
     definition of the corresponding start symbol is split over
     multiple files. *)

  val positions: index -> Positions.t list

  (* Iteration over all productions. The order in which elements
     are examined, and the order of [map]'s output list, correspond
     to the numeric indices produced by [p2i] above. *)

  val iter: (index -> unit) -> unit
  val fold: (index -> 'a -> 'a) -> 'a -> 'a
  val map: (index -> 'a) -> 'a list
POTTIER Francois's avatar
POTTIER Francois committed
336
  val amap: (index -> 'a) -> 'a array
337
338
339
340
341

  (* Iteration over all productions, except the start productions. *)

  val iterx: (index -> unit) -> unit
  val foldx: (index -> 'a -> 'a) -> 'a -> 'a
342
  val mapx: (index -> 'a) -> 'a list
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366

  (* This maps a (user) non-terminal start symbol to the corresponding
     start production. *)

  val startsymbol2startprod: Nonterminal.t -> index

  (* Iteration over the productions associated with a specific
     nonterminal. *)

  val iternt: Nonterminal.t -> (index -> unit) -> unit
  val foldnt: Nonterminal.t -> 'a -> (index -> 'a -> 'a) -> 'a

  (* This allows determining whether a production is a start
     production. If it is a start production, the start symbol that it
     is associated with is returned. If it is a regular production,
     nothing is returned. *)

  val classify: index -> Nonterminal.t option

  (* [is_start] is easier to use than [classify] when the start symbol
     is not needed. *)

  val is_start: index -> bool

367
368
369
370
371
  (* The integer [start] is published so as to allow the table back-end
     to produce code for [is_start]. It should not be used otherwise. *)

  val start: int

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
402
403
404
  (* This produces a string representation of a production. It should
     never be applied to a start production, as we do not wish users
     to become aware of the existence of these extra productions. *)

  val print: index -> string

  (* Tabulation of a Boolean function over productions. [tabulateb f]
     returns a tabulated version of [f] as well as the number of
     productions where [f] is true. *)

  val tabulate: (index -> 'a) -> (index -> 'a)
  val tabulateb: (index -> bool) -> (index -> bool) * int

end

(* ------------------------------------------------------------------------ *)
(* Maps over productions. *)

module ProductionMap : sig

  include GMap.S with type key = Production.index

  (* Iteration over the start productions only. *)

  val start: (Production.index -> 'a) -> 'a t

end

(* ------------------------------------------------------------------------ *)
(* Analysis of the grammar. *)

module Analysis : sig

405
406
407
408
409
410
  (* [nullable nt] is the NULLABLE flag of the non-terminal symbol [nt].
     That is, it is true if and only if this symbol produces the empty
     word [epsilon]. *)

  val nullable: Nonterminal.t -> bool

POTTIER Francois's avatar
POTTIER Francois committed
411
412
413
414
  (* [first nt] is the FIRST set of the non-terminal symbol [nt]. *)

  val first: Nonterminal.t -> TerminalSet.t

POTTIER Francois's avatar
POTTIER Francois committed
415
  (* [nullable_first_prod prod i] considers the suffix of the production
416
     [prod] defined by offset [i]. It returns its NULLABLE flag as well
417
     as its FIRST set. The offset [i] must be contained between [0] and
418
     [n], inclusive, where [n] is the length of production [prod]. *)
419

420
  val nullable_first_prod: Production.index -> int -> bool * TerminalSet.t
421

422
423
424
425
426
427
428
  (* [first_prod_lookahead prod i t] computes [FIRST(alpha.t)], where [alpha]
     is the suffix of the production defined by offset [i], and [t] is a
     terminal symbol. The offset [i] must be contained between [0] and [n],
     inclusive, where [n] is the length of production [prod]. *)

  val first_prod_lookahead: Production.index -> int -> Terminal.t -> TerminalSet.t

429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
  (* [explain_first_rhs tok rhs i] explains why the token [tok] appears
     in the FIRST set for the string of symbols found at offset [i] in
     the array [rhs]. *)

  val explain_first_rhs: Terminal.t -> Symbol.t array -> int -> string

  (* [follow nt] is the FOLLOW set of the non-terminal symbol [nt], that
     is, the set of terminal symbols that could follow an expansion of
     [nt] in a valid sentence. *)

  val follow: Nonterminal.t -> TerminalSet.t

end

(* ------------------------------------------------------------------------ *)
(* Conflict resolution via precedences. *)

module Precedence : sig

  (* Shift/reduce conflicts require making a choice between shifting a
     token and reducing a production. How these choices are made is of
     no concern to the back-end, but here is a rough explanation.

     Shifting is preferred when the token has higher precedence than
     the production, or they have same precedence and the token is
     right-associative.

     Reducing is preferred when the token has lower precedence than
     the production, or they have same precedence and the token is
     left-associative.

     Neither is allowed when the token and the production have same
     precedence and the token is non-associative.

     No preference is explicitly specified when the token or the
     production has undefined precedence. In that case, the default
     choice is to prefer shifting, but a conflict will be reported. *)

  type choice =
    | ChooseShift
    | ChooseReduce
    | ChooseNeither
    | DontKnow

  val shift_reduce: Terminal.t -> Production.index -> choice

  (* Reduce/reduce conflicts require making a choice between reducing
     two distinct productions. This is done by exploiting a partial
     order on productions.

     For compatibility with ocamlyacc, this order should be total and
     should correspond to textual order when the two productions
     originate in the same source file. When they originate in
     different source files, the two productions should be
     incomparable. *)

  val reduce_reduce: Production.index -> Production.index -> Production.index option

end

489
490
491
492
493
494
495
496
497
498
(* ------------------------------------------------------------------------ *)
(* %on_error_reduce declarations. *)

module OnErrorReduce : sig

  (* This is the set of %on_error_reduce declarations. *)
  val declarations: StringSet.t

end

499
500
501
(* ------------------------------------------------------------------------ *)
(* Diagnostics. *)

POTTIER Francois's avatar
POTTIER Francois committed
502
503
504
(* This function prints warnings about useless precedence declarations for
   terminal symbols (%left, %right, %nonassoc) and productions (%prec). It
   should be invoked after only the automaton has been constructed. *)
505
506
507

val diagnostics: unit -> unit