positions.mli 4.44 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
(* TEMPORARY clean up this over-complicated API? *)
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

(** Extension of standard library's positions. *)

(** {2 Extended lexing positions} *)

(** Abstract type for pairs of positions in the lexing stream. *)
type t

(** Decoration of a value with a position. *)
type 'a located =
    {
      value    : 'a;
      position : t;
    }

(** [value dv] returns the raw value that underlies the
    decorated value [dv]. *)
val value: 'a located -> 'a

(** [position dv] returns the position that decorates the
    decorated value [dv]. *)
val position: 'a located -> t

38 39 40
(** [decompose dv] returns a pair of the value and position. *)
val decompose: 'a located -> 'a * t

41 42 43
(** [with_pos p v] decorates [v] with a position [p]. *)
val with_pos : t -> 'a -> 'a located
val with_cpos: Lexing.lexbuf -> 'a -> 'a located
44
val with_loc : (Lexing.position * Lexing.position) -> 'a -> 'a located
45 46 47 48 49

val unknown_pos : 'a -> 'a located

(** [map f v] extends the decoration from [v] to [f v]. *)
val map: ('a -> 'b) -> 'a located -> 'b located
50
val pmap: (t -> 'a -> 'b) -> 'a located -> 'b located
51 52 53 54 55 56 57

(** [iter f dv] applies [f] to the value inside [dv]. *)
val iter: ('a -> unit) -> 'a located -> unit

(** [mapd f v] extends the decoration from [v] to both members of the pair [f v]. *)
val mapd: ('a -> 'b1 * 'b2) -> 'a located -> 'b1 located * 'b2 located

POTTIER Francois's avatar
POTTIER Francois committed
58
(** This value is used when an object does not come from
59 60 61 62 63
    a particular input location. *)
val dummy: t

(** {2 Accessors} *)

64
(** [column p] returns the number of characters from the
65 66 67 68 69 70
    beginning of the line of the Lexing.position [p]. *)
val column : Lexing.position -> int

(** [column p] returns the line number of to the Lexing.position [p]. *)
val line : Lexing.position -> int

71
(** [characters p1 p2] returns the character interval
72
    between [p1] and [p2] assuming they are located in the same
73
    line.
74 75 76 77 78 79 80
*)
val characters : Lexing.position -> Lexing.position -> int * int

val start_of_position: t -> Lexing.position

val end_of_position: t -> Lexing.position

81
val filename_of_position: t -> string
82 83 84 85 86 87 88

(** {2 Position handling} *)

(** [join p1 p2] returns a position that starts where [p1]
    starts and stops where [p2] stops. *)
val join : t -> t -> t

89
val import : Lexing.position * Lexing.position -> t
90 91 92 93 94 95 96

val ljoinf : ('a -> t) -> 'a list -> t

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

val join_located : 'a located -> 'b located -> ('a -> 'b -> 'c) -> 'c located

97
val join_located_list :
98
  ('a located) list -> ('a list -> 'b list) -> ('b list) located
99

100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117

(** [string_of_lex_pos p] returns a string representation for
    the lexing position [p]. *)
val string_of_lex_pos : Lexing.position -> string

(** [string_of_pos p] returns the standard (Emacs-like) representation
    of the position [p]. *)
val string_of_pos : t -> string

(** [pos_or_undef po] is the identity function except if po = None,
    in that case, it returns [undefined_position]. *)
val pos_or_undef : t option -> t

(** {2 Interaction with the lexer runtime} *)

(** [cpos lexbuf] returns the current position of the lexer. *)
val cpos : Lexing.lexbuf -> t

118
(** [string_of_cpos p] returns a string representation of
119 120 121 122 123 124 125 126 127 128 129 130 131
    the lexer's current position. *)
val string_of_cpos : Lexing.lexbuf -> string

(* The functions that print error messages and warnings require a list of
   positions. The following auxiliary functions help build such lists. *)

type positions =
    t list

val one: Lexing.position -> positions

val lexbuf: Lexing.lexbuf -> positions

132 133
(* Low-level printing function, for debugging. *)
val print: Lexing.position -> unit