-
Notifications
You must be signed in to change notification settings - Fork 0
/
cudf_parser.mli
155 lines (112 loc) · 6.02 KB
/
cudf_parser.mli
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
(*****************************************************************************)
(* libCUDF - CUDF (Common Upgrade Description Format) manipulation library *)
(* Copyright (C) 2009-2012 Stefano Zacchiroli <[email protected]> *)
(* *)
(* This library is free software: you can redistribute it and/or modify *)
(* it under the terms of the GNU Lesser General Public License as *)
(* published by the Free Software Foundation, either version 3 of the *)
(* License, or (at your option) any later version. A special linking *)
(* exception to the GNU Lesser General Public License applies to this *)
(* library, see the COPYING file for more information. *)
(*****************************************************************************)
(** Parser for CUDF related documents *)
open Cudf
open Cudf_types
(** a CUDF parser opened on some input source *)
type cudf_parser
(** Error during parsing (syntax error, type error, ...). Arguments are error
message and error location. *)
exception Parse_error of string * loc
(** create a CUDF parser reading data from an input channel
@param typedecl (initial) per-stanza and per-property type declarations to
be used while parsing. Default: {!Cudf_conf.stanza_typedecl}
*)
val from_in_channel : ?typedecl:Cudf_conf.stanza_typedecl ->
in_channel -> cudf_parser
(** create a CUDF parser reading data from an Extlib input channel
@param typedecl (initial) per-stanza and per-property type declarations to
be used while parsing. Default: {!Cudf_conf.stanza_typedecl}
*)
val from_IO_in_channel : ?typedecl:Cudf_conf.stanza_typedecl ->
IO.input -> cudf_parser
(** create a CUDF parser reading data from a file
@param typedecl as per {!Cudf_parser.from_in_channel}
*)
val from_file : ?typedecl:Cudf_conf.stanza_typedecl ->
string -> cudf_parser
(** Dispose a CUDF parser.
Afterwards, the parser should not be used any longer *)
val close : cudf_parser -> unit
(** {6 Full CUDF document parsing}
"parse_*" functions offer plain syntax parsing, with no semantic
interpretation of what is being parsed. "load_*" functions offer
the latter, hence also checking for semantic constraints (such as
the lack of key duplication).
All full parsing function are granted to raise only
{!Cudf_parser.Parse_error}; finer grained exception are mapped to it.
*)
(** parse a CUDF document (or a universe) as a whole
@return a triple [preamble, packages, request] where preamble and request
are returned only if actually met in the parsed document. Note that a
document with no request part is not a valid CUDF document (but might still
be used to represent solver solutions, for instance).
@raise Parse_error when an error during parsing is encountered (might be a
syntax error, a type error, ..)
*)
val parse : cudf_parser -> preamble option * package list * request option
(** same as {!Cudf_parser.parse}, but additionally loads the package
list as an abstract {!Cudf.universe}.
{b Note}: to load compact universes (i.e. only containing package names,
versions, and installed status) that will be tested as solutions you should
use {!Cudf_parser.load_solution} instead: the present function does not
expand missing metadata with respect to the initial status.
@raise Parse_error as {!Cudf_parser.parse} does
@raise Cudf.Constraint_violation as {!Cudf.load_universe} does
*)
val load : cudf_parser -> preamble option * universe * request option
(** Load a solution wrt to a given CUDF document, whose universe is given.
Solution format is as per Appendix B of CUDF 2.0 spec
@raise Parse_error as {!Cudf_parser.parse} does *)
val load_solution : cudf_parser -> universe -> preamble option * universe
(** Shorthand: parse a file given its name *)
val parse_from_file : ?typedecl:Cudf_conf.stanza_typedecl ->
string -> preamble option * package list * request option
(** Shorthand: load from a file given its name *)
val load_from_file : ?typedecl:Cudf_conf.stanza_typedecl ->
string -> preamble option * universe * request option
(** Shorthand: load a solution from a file given its name *)
val load_solution_from_file : string -> universe -> preamble option * universe
(** {6 Item-by-item CUDF parsing} *)
(** Parse the next information item (either a package description, a user
request, or a preamble) from the given input channel.
Beware that parsing is stateful; in particular when the preamble is parsed,
the list of allowed properties for future package stanzas is internally
updated.
*)
val parse_item : cudf_parser -> cudf_item
(** {6 Low-level parsing functions}
The following parsing function usually raise fine grained exceptions such
as {!Cudf_types.Syntax_error} and {!Cudf_types.Type_error}.
*)
type loc_map = (string * loc) list
(** Parse a file stanza (i.e., a RFC822-like stanza, with the notable
simplification that all field/value pairs are one-liners). Strip
any heading blanks lines leading to the first available
field/value pair.
@return an associative list mapping field name to field values and a
location map mapping field names to locations
@raise End_of_file if no other stanza is available due to reached EOF
@raise Cudf_types.Syntax_error when a syntax error is encountered
*)
val parse_stanza : cudf_parser -> loc_map * string stanza
(** Type check an untyped stanza according to a given set of type declarations.
Also take care of default values, adding missing properties where needed;
fail if a required property is missing.
@param loc location map from prop name to locations, default is None
(i.e. use dummy locations)
@raise Syntax_error if a property does not match its declared type; this
exception is also raised when an undeclared property is encountered
@raise Type_error when a property has a value of the wrong type
*)
val type_check_stanza : ?locs:loc_map ->
string stanza -> typedecl -> typed_value stanza