Debian Codegraph @

vendor/opam/src/format/opamPp.mli

raw
1 (**************************************************************************)
2 (* *)
3 (* Copyright 2012-2018 OCamlPro *)
4 (* Copyright 2012 INRIA *)
5 (* *)
6 (* All rights reserved. This file is distributed under the terms of the *)
7 (* GNU Lesser General Public License version 2.1, with the special *)
8 (* exception on linking described in the file LICENSE. *)
9 (* *)
10 (**************************************************************************)
11
12 (** Generic bidirectional transformation toolbox for parsing/printing *)
13
14 open OpamParserTypes.FullPos
15
16 (** {2 Parsing positions and error reporting helpers} *)
17
18 (** Format error reporting: position and message *)
19 type bad_format = pos option * string
20
21 (** All the following parsing function raise [Bad_format] in case the
22 input does not have the right format. *)
23 exception Bad_format of bad_format
24 exception Bad_format_list of bad_format list
25 exception Bad_version of bad_format
26
27 (** Raise [Bad_format]. *)
28 val bad_format: ?pos:pos -> ('a, unit, string, 'b) format4 -> 'a
29
30 (** Raise [Bad_version]. *)
31 val bad_version: ?pos:pos -> ('a, unit, string, 'b) format4 -> 'a
32
33 val string_of_bad_format: ?file:string -> exn -> string
34
35 (** Adds a position to a Bad_format exception if it doesn't have one yet *)
36 val add_pos: pos -> exn -> exn
37
38 (** {2 Parser/printers} *)
39
40 (** The type of bidirectional parsers from ['a] to ['b]. We abuse the terms
41 and describe going from ['a] to ['b] as "parsing", and going from ['b] to
42 ['a] as "printing". Parsing is generally error-prone, while printing is
43 not expected to fail, so the handling isn't really symmetrical.
44
45 [parse (print x)] should always be the identity, while no guarantee is
46 given regarding [print (parse x)] *)
47 type ('a, 'b) t = private {
48 parse: pos:pos -> 'a -> 'b;
49 print: 'b -> 'a;
50 ppname: string;
51 name_constr: string -> string;
52 }
53
54 (** Base constructor for Pp.t, from a parser function and a printer function.
55 [name_constr] is used to construct the resulting name when on the left of
56 a pipe. Names are for tracing errors. *)
57 val pp :
58 ?name:string -> ?name_constr:(string -> string) ->
59 (pos:pos -> 'a -> 'b) ->
60 ('b -> 'a) ->
61 ('a, 'b) t
62
63 (** Constructor of Pp.t from a name and a pair *)
64 val of_pair :
65 string ->
66 ('a -> 'b) * ('b -> 'a) ->
67 ('a, 'b) t
68
69 (** Base call for parsing with a pp *)
70 val parse : ('a, 'b) t -> pos:pos -> 'a -> 'b
71
72 (** Base call for printing with a pp *)
73 val print : ('a, 'b) t -> 'b -> 'a
74
75 (** Error handling *)
76
77 (** Raises an exception handled by parser calls *)
78 val unexpected : ?pos:pos -> unit -> 'a
79
80 (** {3 Various pp constructors} *)
81
82 module Op : sig
83
84 (** Piping pps together: the left-hand pp is called first when parsing, last
85 when printing *)
86 val ( -| ) : ('a, 'b) t -> ('b, 'c) t -> ('a, 'c) t
87
88 (** Combinator to parse lists to different types using nested pairs *)
89 val ( ^+ ) : ('a, 'b) t -> ('a list, 'c) t -> ('a list, 'b * 'c) t
90
91 end
92
93 val identity : ('a, 'a) t
94
95 (** Always parses to [None] *)
96 val ignore : ('a, 'b option) t
97
98 (** Identity pp, unless the check fails. The check is turned into an assertion
99 when printing. If no [errmsg] is given, raises [Unexpected], otherwise
100 call [raise] with the given [errmsg]. By default [raise] raises
101 [Bad_format]. *)
102 val check :
103 ?name:string ->
104 ?raise:(?pos:pos -> (string -> 'a, unit, string, 'a) format4
105 -> string -> 'a) ->
106 ?errmsg:string -> ('a -> bool) -> ('a, 'a) t
107
108 val map_pair :
109 ?name:string ->
110 ?posf1:('a -> pos) ->
111 ?posf2:('b -> pos) ->
112 ('a, 'c) t -> ('b, 'd) t -> ('a * 'b, 'c * 'd) t
113
114 (** Builds a pp of pairs by passing the second term along *)
115 val map_fst :
116 ('a, 'b) t -> ('a * 'c, 'b * 'c) t
117
118 (** Builds a pp of pairs by passing the first term along *)
119 val map_snd :
120 ('a, 'b) t -> ('c * 'a, 'c * 'b) t
121
122 val map_list :
123 ?name:string ->
124 ?posf:('a -> pos) -> ('a, 'b) t -> ('a list, 'b list) t
125
126 val map_option : ?name:string -> ('a, 'b) t -> ('a option, 'b option) t
127
128 (** Parsing fails on non-singleton lists *)
129 val singleton : ('a list, 'a) t
130
131 (** Use for the rightmost element to close a [^+] sequence, e.g.
132 [pp1 ^+ pp2 ^+ last -| pp3] *)
133 val last : ('a list, 'a) t
134
135 module type STR = sig
136 type t
137 val of_string : string -> t
138 val to_string : t -> string
139 end
140
141 (** Generates a string pp from a module with of/to string functions *)
142 val of_module :
143 string -> (module STR with type t = 'a) -> (string, 'a) t
144
145 (** Parses to None on the empty list. Often combined with singleton
146 ([opt (singleton _)]) *)
147 val opt : ('a list, 'b) t -> ('a list, 'b option) t
148
149 val default : 'a -> ('a option, 'a) t
150
151 (** [fallback p1 p2] is [p1], except that parsing is allowed to fail and will in
152 that case try to parse through [p2]. Can be useful for backwards
153 compatibility, but use with care *)
154 val fallback : ('a, 'b) t -> ('a, 'b) t -> ('a, 'b) t
155
156 (** {3 Combinators to parse to a record from a list of (field name, field
157 setter, field getter)} *)
158
159 (** Used to parse a single field of a record: ['a] on the left is the
160 accumulator, or value of the record parsed so far. (in lens terms, [get]
161 would be the print operation that extracts the field for the record, while
162 [set] would be the parse operation that takes the input and record, and
163 updates a given field in the record) *)
164 type ('a, 'value) field_parser = ('a * 'value option, 'a) t
165
166 (** Make a field parser from setter, getter and base pp. [cleanup] is an
167 optional sanitisation function that is called on parsed elements
168 before calling the setter. *)
169 val ppacc :
170 ?cleanup:(pos:pos -> 'acc -> 'a -> 'a) ->
171 ('a -> 'acc -> 'acc) ->
172 ('acc -> 'a) ->
173 ('value, 'a) t ->
174 ('acc, 'value) field_parser
175
176 (** Same as [ppacc], but when the field may be unset in the record, i.e. the
177 getter returns an option *)
178 val ppacc_opt :
179 ?cleanup:(pos:pos -> 'acc -> 'a -> 'a) ->
180 ('a -> 'acc -> 'acc) ->
181 ('acc -> 'a option) ->
182 ('value, 'a) t ->
183 ('acc, 'value) field_parser
184
185 (** A field parser that ignores its argument *)
186 val ppacc_ignore : ('a, value) field_parser
187
188 val embed :
189 ('a -> 'acc -> 'acc) -> ('acc -> 'a) -> ('a, 'value) field_parser ->
190 ('acc, 'value) field_parser