grammarFunctor.mli 19.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
(******************************************************************************)
(*                                                                            *)
(*                                   Menhir                                   *)
(*                                                                            *)
(*                       François Pottier, Inria Paris                        *)
(*              Yann Régis-Gianas, PPS, Université Paris Diderot              *)
(*                                                                            *)
(*  Copyright Inria. All rights reserved. This file is distributed under the  *)
(*  terms of the GNU General Public License version 2, as described in the    *)
(*  file LICENSE.                                                             *)
(*                                                                            *)
(******************************************************************************)

14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
(* The functor [Make] transforms an abstract syntax tree for the grammar into a
   rich internal representation of the grammar. *)

(* The reason why this is now a functor, and the reason why its verbosity can
   be controlled, is that we may wish to invoke it several times, e.g. on the
   grammar before %inlining, and on the grammar after %inlining. 2015/11/10 *)

module Make (G : sig

  (* An abstract syntax tree for the grammar. *)
  val grammar: UnparameterizedSyntax.grammar

  (* This flag indicates whether it is OK to produce warnings, verbose
     information, etc., when this functor is invoked. If it is set to
     [false], then only serious errors can be signaled. *)
  val verbose: bool

end) : sig
32 33 34 35 36 37 38 39 40 41

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

module Nonterminal : sig

  (* The type of nonterminals. *)

  type t

42 43 44 45
  (* Comparison. *)

  val compare: t -> t -> int

46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
  (* 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
69
     for use as a valid nonterminal name or as a valid OCaml
70 71 72 73
     identifier. *)

  val print: bool -> t -> string

74
  (* This is the OCaml type associated with a nonterminal
75 76 77 78 79 80
     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

81 82 83 84 85
  (* 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

86 87 88 89
  (* Creation of a table indexed by nonterminals. *)

  val init: (t -> 'a) -> 'a array

90 91 92 93 94 95 96 97 98 99 100
  (* 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
101
  val foldx: (t -> 'a -> 'a) -> 'a -> 'a
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117

  (* 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

118 119 120 121 122
  (* [attributes nt] is the list of attributes attached with the nonterminal
     symbol [nt]. *)

  val attributes: t -> Syntax.attribute list

123 124
end

125 126 127 128 129 130 131
(* ------------------------------------------------------------------------ *)
(* Sets of nonterminals. *)

module NonterminalMap : GMap.S with type key = Nonterminal.t

module NonterminalSet = NonterminalMap.Domain

132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
(* ------------------------------------------------------------------------ *)
(* 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
149
  val compare: t -> t -> int
150 151 152 153 154

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

  val lookup : string -> t

155 156 157
  (* 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 :-) *)
158 159

  val t2i: t -> int
160
  val i2t: int -> t (* unsafe! *)
161 162 163 164 165

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

  val print: t -> string

166
  (* This is the OCaml type associated with a terminal
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
     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
182 183
     [ocamllex]'s [eof] pattern. It is used only by the reference
     interpreter, and in a rather non-essential way. *)
184 185 186

  val eof: t option

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

  val pseudo: t -> bool
POTTIER Francois's avatar
POTTIER Francois committed
190
  val real: t -> bool
191

192 193 194 195
  (* Creation of a table indexed by terminals. *)

  val init: (t -> 'a) -> 'a array

196 197
  (* 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
198
     numeric indices produced by [t2i] above. *)
199 200 201 202

  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
203

POTTIER Francois's avatar
POTTIER Francois committed
204
  (* Iteration over all terminals except [#]. *)
POTTIER Francois's avatar
POTTIER Francois committed
205

POTTIER Francois's avatar
POTTIER Francois committed
206
  val foldx: (t -> 'a -> 'a) -> 'a -> 'a
207 208
  val mapx: (t -> 'a) -> 'a list

POTTIER Francois's avatar
POTTIER Francois committed
209
  (* [iter_real] offers iteration over all real terminals. *)
210 211 212

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

213 214 215 216 217
  (* [attributes t] is the list of attributes attached with the terminal
     symbol [t]. *)

  val attributes: t -> Syntax.attribute list

218 219 220 221 222
  (* 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
223

224 225 226 227 228 229
  (* 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
230 231
  module Word (X : sig end) : sig

232
    type word = int
POTTIER Francois's avatar
POTTIER Francois committed
233 234 235 236 237 238 239 240 241 242 243
    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
244 245
    (* Lexicographic ordering. *)
    val compare: word -> word -> int
POTTIER Francois's avatar
POTTIER Francois committed
246
  end
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
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

287 288 289 290
  (* [lookup] maps an identifier to a symbol, or raises [Not_found]. *)

  val lookup : string -> t

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
  (* 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

344 345 346 347
  (* Comparison. *)

  val compare: index -> index -> int

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
  (* 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

387 388 389 390 391 392 393 394 395 396 397 398 399
  (* [lhs_attributes prod] returns the attributes attached with the
     head symbol of the production [prod]. It is equivalent to
     [Nonterminal.attributes (nt prod)]. [rhs_attributes prod] returns
     an array of the attributes attached with each element in the
     right-hand side of the production [prod]. *)

  val lhs_attributes: index -> Syntax.attributes
  val rhs_attributes: index -> Syntax.attributes array

  (* Creation of a table indexed by productions. *)

  val init: (index -> 'a) -> 'a array

400 401 402 403 404 405 406
  (* 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
407
  val amap: (index -> 'a) -> 'a array
408 409 410 411 412

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

  val iterx: (index -> unit) -> unit
  val foldx: (index -> 'a -> 'a) -> 'a -> 'a
413
  val mapx: (index -> 'a) -> 'a list
414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437

  (* 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

438 439 440 441 442
  (* 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

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
  (* 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

476 477 478 479 480
  (* [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
481
  val nullable_symbol: Symbol.t -> bool
482

POTTIER Francois's avatar
POTTIER Francois committed
483 484 485
  (* [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
486
  val first_symbol: Symbol.t -> TerminalSet.t
POTTIER Francois's avatar
POTTIER Francois committed
487

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

493
  val nullable_first_prod: Production.index -> int -> bool * TerminalSet.t
494

495 496 497 498 499 500 501
  (* [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

502 503 504 505 506 507 508 509 510 511 512 513
  (* [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

514 515 516 517
  (* [attributes] are the attributes attached with the grammar. *)

  val attributes: Syntax.attributes

518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565
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

566
(* ------------------------------------------------------------------------ *)
567
(* [%on_error_reduce] declarations. *)
568 569 570

module OnErrorReduce : sig

571 572 573 574 575 576 577 578 579 580 581
  (* [reduce prod] tells whether the left-hand side of [prod] (a nonterminal
     symbol) appears in an [%on_error_reduce] declaration. *)

  val reduce: Production.index -> bool

  (* [iter f] applies the function [f] in turn, in an arbitrary order, to
     every nonterminal symbol that appears in an [%on_error_reduce]
     declaration. *)

  val iter: (Nonterminal.t -> unit) -> unit

582 583 584 585
  (* When two productions could be reduced, in a single state, due to
     [%on_error_reduce] declarations, these productions can be compared, using
     [preferable], to test if one of them takes precedence over the other.
     This is a partial order; two productions may be incomparable. *)
586

587
  val preferable: Production.index -> Production.index -> bool
588 589 590

end

591 592 593
(* ------------------------------------------------------------------------ *)
(* Diagnostics. *)

POTTIER Francois's avatar
POTTIER Francois committed
594 595 596
(* 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. *)
597 598 599

val diagnostics: unit -> unit

600 601 602
(* ------------------------------------------------------------------------ *)

end (* module Make *)