Debian Codegraph @

vendor/opam/src/format/opamFormat.mli

raw
1 (**************************************************************************)
2 (* *)
3 (* Copyright 2012-2020 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 (** OPAM files syntax and conversion tools *)
13
14 open OpamParserTypes.FullPos
15 open OpamTypes
16 open OpamPp
17
18 (** Get the position out of a value *)
19 val value_pos: value -> pos
20
21 (** {3 low-level Pps for the Lines parser ([string list list])} *)
22
23 type lines = string list list
24
25 (** Provided an empty element, addition and fold operations with signatures as
26 per Set.S, and a pp from lines to elements, returns a pp parsing from
27 lines *)
28 val lines_set:
29 empty:'set ->
30 add:('elt -> 'set -> 'set) ->
31 fold:(('elt -> lines -> lines) -> 'set -> lines -> lines) ->
32 (string list, 'elt) t ->
33 (lines, 'set) t
34
35 (** Provided an empty element, addition and fold operations with signatures as
36 per Map.S, and a pp from lines to key, value pairs, returns a pp parsing
37 from lines *)
38 val lines_map :
39 empty:'map ->
40 add:('k -> 'v -> 'map -> 'map) ->
41 fold:(('k -> 'v -> lines -> lines) -> 'map -> lines -> lines) ->
42 (string list, 'k * 'v) t ->
43 (lines, 'map) t
44
45 (** {3 Pps for the type [value], used by opam-syntax files ([opamfile])} *)
46
47 module V : sig
48 (** These base converters raise [Unexpected] when not run on the right input
49 (which is then converted to [Bad_format] by the parser. *)
50
51 val bool : (value, bool) t
52 val int : (value, int) t
53
54 (** positive or null integer *)
55 val pos_int : (value, int) t
56
57 val ident : (value, string) t
58 val string : (value, string) t
59
60 (** Trimmed string *)
61 val string_tr : (value, string) t
62
63 (** Command arguments, i.e. strings or idents *)
64 val simple_arg : (value, simple_arg) t
65
66 (** Strings or bools *)
67 val variable_contents : (value, variable_contents) t
68
69 (** "[a b c]"; also allows just "a" to be parsed as a singleton list *)
70 val list : (value, value list) t
71
72 (** "(a b c)" *)
73 val group : (value, value list) t
74
75 (** Options in the [value] type sense, i.e. a value with an optional list
76 of parameters in braces: ["value {op1 op2}"] *)
77 val option :
78 (value, value * value list) t
79
80 val map_group : (value, 'a) t -> (value, 'a list) t
81
82 (** An expected list depth may be specified to enable removal of extra
83 brackets (never use [~depth] for an inner list) *)
84 val map_list : ?depth:int -> (value, 'a) t -> (value, 'a list) t
85
86 (** Normalises to the given list depth when parsing, and removes brackets
87 that can be made implicit when printing *)
88 val list_depth : int -> (value, value) t
89
90 (** Maps on the two terms of an option constructor. *)
91 val map_option : (value, 'a) t -> (value list, 'b) t -> (value, 'a * 'b) t
92
93 (** Maps over two options (e.g. [v {op1} {op2}]) *)
94 val map_options_2 :
95 (value, 'a) t -> (value list, 'b) t -> (value list, 'c) t ->
96 (value, 'a * 'b * 'c) t
97
98 (** Maps over three options (e.g. [v {op1} {op2} {op3}]) *)
99 val map_options_3 :
100 (value, 'a) t ->
101 (value list, 'b) t -> (value list, 'c) t -> (value list, 'd) t ->
102 (value, 'a * 'b * 'c * 'd) t
103
104 (** A pair is simply a list with two elements in the [value] type *)
105 val map_pair :
106 (value, 'a) t ->
107 (value, 'b) t -> (value, 'a * 'b) t
108
109 (** A triple is simply a list with three elements in the [value] type *)
110 val map_triple :
111 (value, 'a) t ->
112 (value, 'b) t ->
113 (value, 'c) t -> (value, 'a * 'b * 'c) t
114
115 val url : (value, url) t
116
117 (** Specialised url parser when the backend is already known *)
118 val url_with_backend : OpamUrl.backend -> (value, url) t
119
120 val compiler_version : (value, string) t
121
122 val filter_ident :
123 (value,
124 name option list * variable *
125 (string * string) option)
126 t
127
128 val filter : (value list, filter) t
129
130 (** Arguments in commands (term + optional filter) *)
131 val arg : (value, simple_arg * filter option) t
132
133 val command : (value, (simple_arg * filter option) list * filter option) t
134
135 (** Simple dependency constraints *)
136 val constraints :
137 (value, 'a) t ->
138 (value list, (OpamFormula.relop * 'a) OpamFormula.formula) t
139
140 (** Dependency constraints mixed with filters *)
141 val filtered_constraints :
142 (value, 'version) t ->
143 (value list, 'version filter_or_constraint OpamFormula.formula) t
144
145 (** Package versions *)
146 val version: (value, version) t
147
148 (** Package versions as filters, as they may appear in dependency (may be an
149 expanded string or an ident) *)
150 val ext_version: (value, filter) t
151
152 (** A package name, encoded as a string, but with restrictions *)
153 val pkgname: (value, name) t
154
155 (** Returns an atom parser [("package" {>= "version"})] from a constraint
156 and a version parser*)
157 val package_atom:
158 (value list, 'a) t -> (value, name * 'a) t
159
160 (** Takes a parser for constraints. Lists without operator will be
161 understood as conjunctions or disjunctions depending on the first
162 argument. *)
163 val package_formula :
164 [< `Conj | `Disj ] ->
165 (value list, 'a) t ->
166 (value, (name * 'a) OpamFormula.formula) t
167
168 (** Like [package_formula], but takes the list items directly *)
169 val package_formula_items :
170 [< `Conj | `Disj ] ->
171 (value list, 'a) t ->
172 (value list, (name * 'a) OpamFormula.formula) t
173
174 (** Environment variable updates syntax *)
175 val env_binding : (value, env_update) t
176
177 val os_constraint : (value, (bool * string) OpamFormula.formula) t
178 end
179
180 (** {3 Specific Pps for items lists and fields (opamfile)} *)
181
182 module I :
183 sig
184 val file : (opamfile, filename * opamfile_item list) t
185
186 val map_file : (opamfile_item list, 'a) t -> (opamfile, filename * 'a) t
187
188 val item : (opamfile_item, string * value) t
189
190 val items : (opamfile_item list, (string * value) list) t
191
192 (** Suitable for the [fields] [sections] argument, when the sections are
193 anonymous ([section_name = None]) *)
194 val anonymous_section : ('a, 'b) t -> ((string option * 'a) list, 'b) t
195
196 type ('a, 'value) fields_def = (string * ('a, 'value) field_parser) list
197
198 (** Parses an item list into a record using a fields_def; errors in a field
199 cause the field to be ignored, and are aggregated into the returned
200 [field, bad_format] list. Errors are ignored when printing back. *)
201 val fields :
202 ?name:string ->
203 empty:'a ->
204 ?sections:
205 ('a, (string option * (opamfile_item list)) list) fields_def ->
206 ?mandatory_fields:string list ->
207 ('a, value) fields_def ->
208 (opamfile_item list, 'a * (string * bad_format) list) t
209
210 (** Intended to be piped after [fields]. If the errors list is non-empty, this
211 raises [Bad_format_list] if [strict], and otherwise prints warnings for
212 all the errors. The errors are then dropped when parsing, and initialised
213 to empty when printing. [strict] is taken from the global settings if
214 unspecified. [condition] may be added to only show the errors when it
215 returns [true], and only log them otherwise. *)
216 val show_errors :
217 ?name:string ->
218 ?strict:bool ->
219 ?condition:('a -> bool) ->
220 unit ->
221 ('a * (string * bad_format) list, 'a) t
222
223 (** Intended to be piped after [fields], this processes the given function on
224 the errors, then drops them when parsing. When printing, just sets empty
225 errors. *)
226 val on_errors :
227 ?name:string -> ('a -> string * bad_format -> 'a) ->
228 ('a * (string * bad_format) list, 'a) t
229
230 (** Partitions items in an opamfile base on a condition on the variable
231 names. If a section is encountered, it is kept in the second list (as
232 filter returning false), unless [section] is true. *)
233 val partition_fields :
234 ?section:bool -> (string -> bool) ->
235 (opamfile_item list, opamfile_item list * opamfile_item list) t
236
237 (** Partitions items in an opamfile base on a generic condition on the
238 items *)
239 val partition :
240 (opamfile_item -> bool) ->
241 (opamfile_item list, opamfile_item list * opamfile_item list) t
242
243 (** Parse a single field from a file, return the result and the unchanged
244 item list. The single field is ignored when printing back. *)
245 val field :
246 string ->
247 (pos:pos -> value -> 'a) ->
248 (opamfile_item list, 'a option * opamfile_item list) t
249
250 (** Parse a single section with the given "kind", towards its name and
251 contents *)
252 val section :
253 string ->
254 (opamfile_item, (string option * opamfile_item list)) t
255
256 (** Extracts a single item with the given variable name from an item list.
257 The item is removed from the returned item list, and the two are
258 re-combined when printing *)
259 val extract_field :
260 string ->
261 (opamfile_item list, value option * opamfile_item list) t
262
263 (** Checks the [opam_version] field; otherwise the identity *)
264 val check_opam_version :
265 ?optional:bool -> format_version:opam_version -> ?f:(opam_version -> bool)
266 -> unit ->
267 (opamfile_item list, opamfile_item list) t
268
269 (** Add [opam-version] field printing at printing, and removes it from parsed
270 fields if [undefined] (default is false) *)
271 val opam_version :
272 ?undefined:bool -> format_version:opam_version -> unit ->
273 (opamfile_item list, opamfile_item list) t
274
275 (** Signature handling (wip) *)
276
277 (** A signature is a keyid, an algorithm and the signature proper *)
278 type signature = string * string * string
279
280 val signature : (value, signature) t
281
282 exception Invalid_signature of
283 pos * (string * string * string) list option
284
285 (** Pp for signed files. Will assert fail if attempting to write a file with
286 an invalid signature. *)
287 val signed:
288 check:(signature list -> string -> bool) ->
289 (opamfile_item list, signature list * opamfile_item list) t
290 end