Debian Codegraph @

vendor/opam/src/format/opamFormula.mli

raw
1 (**************************************************************************)
2 (* *)
3 (* Copyright 2012-2019 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 (** Formulas on packages, opt. with sub-formulas on versions, and conversion
13 functions *)
14
15 (** binary operations (compatible with the Dose type for Cudf operators!) *)
16 type relop = OpamParserTypes.FullPos.relop_kind (* = [ `Eq | `Neq | `Geq | `Gt | `Leq | `Lt ] *)
17
18 (** Version constraints for OPAM *)
19 type version_constraint = relop * OpamPackage.Version.t
20
21 (** Formula atoms for OPAM *)
22 type atom = OpamPackage.Name.t * version_constraint option
23
24 (** Pretty-printing of atoms *)
25 val string_of_atom: atom -> string
26
27 (** The compact atom format used in requests, "pkgOPvers", with '.' allowed
28 instead of '=' *)
29 val short_string_of_atom: atom -> string
30
31 (** Parses a package or atom, in a format similar to [short_string_of_atom].
32 @raise [Failure] if the format is incorrect *)
33 val atom_of_string: string -> atom
34
35 (** Prints atoms as a conjunction ("&") using the short format *)
36 val string_of_atoms: atom list -> string
37
38 (** Checks if a package verifies an atom *)
39 val check: atom -> OpamPackage.t -> bool
40
41 (** Return all packages satisfying the given atoms from a set (i.e. name
42 matching at least one of the atoms, version matching all atoms with the
43 appropriate name). If [disj] is true, returns packages that satisfy at
44 least one of the constraint of a given name, otherwise that satisfy all
45 constraints. *)
46 val packages_of_atoms:
47 ?disj:bool -> OpamPackage.Set.t -> atom list -> OpamPackage.Set.t
48
49 (** AND formulas *)
50 type 'a conjunction = 'a list
51
52 (** Pretty print AND formulas *)
53 val string_of_conjunction: ('a -> string) -> 'a conjunction -> string
54
55 (** OR formulas *)
56 type 'a disjunction = 'a list
57
58 (** Pretty print OR formulas *)
59 val string_of_disjunction: ('a -> string) -> 'a disjunction -> string
60
61 (** CNF formulas (Conjunctive Normal Form) *)
62 type 'a cnf = 'a disjunction conjunction
63
64 (** DNF formulas (Disjunctive Normal Form) *)
65 type 'a dnf = 'a conjunction disjunction
66
67 (** Pretty print CNF formulas *)
68 val string_of_cnf: ('a -> string) -> 'a cnf -> string
69
70 (** Pretty print DNF formulas *)
71 val string_of_dnf: ('a -> string) -> 'a dnf -> string
72
73 (** General formulas *)
74 type 'a formula =
75 | Empty
76 | Atom of 'a
77 | Block of 'a formula
78 | And of 'a formula * 'a formula
79 | Or of 'a formula * 'a formula
80
81 val compare_formula: ('a -> 'a -> int) -> 'a formula -> 'a formula -> int
82
83 (** Eval a formula *)
84 val eval: ('a -> bool) -> 'a formula -> bool
85
86 val partial_eval:
87 ('a -> [ `Formula of 'b formula | `True | `False ]) ->
88 'a formula ->
89 [ `Formula of 'b formula | `True | `False ]
90
91 (** Check a relational operator against an integer from compare *)
92 val check_relop: relop -> int -> bool
93
94 (** Evaluate a relational operator between versions *)
95 val eval_relop: relop -> OpamPackage.Version.t -> OpamPackage.Version.t -> bool
96
97 val neg_relop: relop -> relop
98
99 (** Pretty print a formula *)
100 val string_of_formula: ('a -> string) -> 'a formula -> string
101
102 (** Convert a list of formulas to an AND-formula ([Empty] formulas are
103 ignored) *)
104 val ands: 'a formula list -> 'a formula
105
106 (** Converts back an AND-formula to a list (flattens top-level ands) *)
107 val ands_to_list: 'a formula -> 'a formula list
108
109 (** Convert a list of formulas to an OR-formula ([Empty] formulas are
110 ignored) *)
111 val ors: 'a formula list -> 'a formula
112
113 (** Converts back an OR-formula to a list (flattens top-level ors) *)
114 val ors_to_list: 'a formula -> 'a formula list
115
116 (** Map on atoms. Atoms for which the given function returns Empty
117 will be simply removed *)
118 val map: ('a -> 'b formula) -> 'a formula -> 'b formula
119
120 (** Maps top-down on a formula *)
121 val map_formula: ('a formula -> 'a formula) -> 'a formula -> 'a formula
122
123 (** Maps bottom-up on a formula (atoms first) *)
124 val map_up_formula: ('a formula -> 'a formula) -> 'a formula -> 'a formula
125
126 (** Negates a formula (given the function to negate atoms) *)
127 val neg: ('a -> 'a) -> 'a formula -> 'a formula
128
129 (** Iter function *)
130 val iter: ('a -> unit) -> 'a formula -> unit
131
132 (** Fold function (bottom-up, left-to-right) *)
133 val fold_left: ('a -> 'b -> 'a) -> 'a -> 'b formula -> 'a
134
135 (** Fold function (bottom-up, right-to-left) *)
136 val fold_right: ('a -> 'b -> 'a) -> 'a -> 'b formula -> 'a
137
138 (** Sort formula, using [compare] function. `Block` around `Or` and `And` \
139 are removed. *)
140 val sort: ('a -> 'a -> int) -> 'a formula -> 'a formula
141
142 (** Expressions composed entirely of version constraints *)
143 type version_formula = version_constraint formula
144
145 (** Checks if a given version satisfies a formula *)
146 val check_version_formula: version_formula -> OpamPackage.Version.t -> bool
147
148 (** An atom is: [name] * ([relop] * [version]) formula.
149 Examples of valid formulae:
150 - "foo" \{> "1" & (<"3" | ="5")\}
151 - "foo" \{= "1" | > "4"\} | ("bar" "bouh") *)
152 type t = (OpamPackage.Name.t * version_formula) formula
153
154 val compare: t -> t -> int
155
156 (** Returns [true] if [package] verifies [formula] (i.e. it is within at least
157 one package set that is a solution of the formula, and is named in the
158 formula) *)
159 val verifies: t -> OpamPackage.t -> bool
160
161 (** Checks if a given set of (installed) packages satisfies a formula *)
162 val satisfies_depends: OpamPackage.Set.t -> t -> bool
163
164 (** Returns the subset of packages possibly matching the formula (i.e. including
165 all disjunction cases) *)
166 val packages: OpamPackage.Set.t -> t -> OpamPackage.Set.t
167
168 val compare_nc:
169 (OpamPackage.Name.t * version_formula) ->
170 (OpamPackage.Name.t * version_formula) ->
171 int
172
173 (** Convert a formula to CNF *)
174 val cnf_of_formula: 'a formula -> 'a formula
175
176 (** Convert a formula to CNF, but as a nested list *)
177 val formula_to_cnf: 'a formula -> 'a cnf
178
179 (** Convert a formula to DNF *)
180 val dnf_of_formula: 'a formula -> 'a formula
181
182 (** Convert a formula to DNF, but as a nested list *)
183 val formula_to_dnf: 'a formula -> 'a dnf
184
185 (** Transform a formula where versions can be expressed using formulas
186 to a flat atom formula *)
187 val to_atom_formula: t -> atom formula
188
189 (** Convert an atom-formula to a t-formula *)
190 val of_atom_formula: atom formula -> t
191
192 (** [simplify_ineq_formula comp f] returns a canonical version of inequality
193 formula [f], based on comparison function [comp], where each version appears
194 at most once, and in increasing order. Returns [Some Empty] if the formula
195 is always [true], [None] if it is always false *)
196 val simplify_ineq_formula:
197 ('a -> 'a -> int) -> (relop * 'a) formula -> (relop * 'a) formula option
198
199 (** Like [simplify_ineq_formula], but specialised on version formulas *)
200 val simplify_version_formula: version_formula -> version_formula option
201
202 (** A more aggressive version of [simplify_version_formula] that attempts to
203 find a shorter formula describing the same subset of versions within a given
204 set. The empty formula is returned for an empty set, and the original
205 formula is otherwise returned as is if no versions match. *)
206 val simplify_version_set: OpamPackage.Version.Set.t -> version_formula -> version_formula
207
208 (** [formula_of_version_set set subset] generates a formula that is enough to
209 describe all packages of [subset] and exclude packages otherwise in [set] *)
210 val formula_of_version_set:
211 OpamPackage.Version.Set.t -> OpamPackage.Version.Set.t -> version_formula
212
213 (** {2 Atoms} *)
214
215 (** Return all the atoms *)
216 val atoms: t -> atom list
217
218 (** Pretty print the formula *)
219 val to_string: t -> string
220
221 (** Return a conjunction. If the initial formula is not a
222 conjunction, then fail. *)
223 val to_conjunction: t -> atom conjunction
224
225 (** Return a formula from a conjunction of atoms *)
226 val of_conjunction: atom conjunction -> t
227
228 (** Return a disjunction of atoms from a package formula. It the initial formula
229 is not a disjunction, then fail. *)
230 val to_disjunction: t -> atom disjunction
231
232 (** Like [to_disjunction], but accepts conjunctions within constraint formulas,
233 resolving them using the provided package set. Conjunctions between packages
234 still raise [Failure]. *)
235 val set_to_disjunction: OpamPackage.Set.t -> t -> atom disjunction
236
237 (** Return a formula from a disjunction of atoms *)
238 val of_disjunction: atom disjunction -> t
239
240 (** Return an equivalent CNF formula *)
241 val to_cnf: t -> atom cnf
242
243 (** Return an equivalent DNF formula *)
244 val to_dnf: t -> atom dnf