OpamPp
Generic bidirectional transformation toolbox for parsing/printing
type bad_format = OpamParserTypes.FullPos.pos option * string
Format error reporting: position and message
exception Bad_format of bad_format
All the following parsing function raise Bad_format
in case the input does not have the right format.
exception Bad_format_list of bad_format list
val bad_format : ?pos:OpamParserTypes.FullPos.pos -> ('a, unit, string, 'b) format4 -> 'a
Raise Bad_format
.
val add_pos : OpamParserTypes.FullPos.pos -> exn -> exn
Adds a position to a Bad_format exception if it doesn't have one yet
type ('a, 'b) t = private {
parse : pos:OpamParserTypes.FullPos.pos -> 'a -> 'b; |
print : 'b -> 'a; |
ppname : string; |
name_constr : string -> string; |
}
The type of bidirectional parsers from 'a
to 'b
. We abuse the terms and describe going from 'a
to 'b
as "parsing", and going from 'b
to 'a
as "printing". Parsing is generally error-prone, while printing is not expected to fail, so the handling isn't really symmetrical.
parse (print x)
should always be the identity, while no guarantee is given regarding print (parse x)
val pp : ?name:string -> ?name_constr:(string -> string) -> (pos:OpamParserTypes.FullPos.pos ->
'a -> 'b) -> ('b -> 'a) -> ('a, 'b) t
Base constructor for Pp.t, from a parser function and a printer function. name_constr
is used to construct the resulting name when on the left of a pipe. Names are for tracing errors.
val of_pair : string -> (('a -> 'b) * ('b -> 'a)) -> ('a, 'b) t
Constructor of Pp.t from a name and a pair
val parse : ('a, 'b) t -> pos:OpamParserTypes.FullPos.pos -> 'a -> 'b
Base call for parsing with a pp
val print : ('a, 'b) t -> 'b -> 'a
Base call for printing with a pp
Error handling
val unexpected : ?pos:OpamParserTypes.FullPos.pos -> unit -> 'a
Raises an exception handled by parser calls
module Op : sig ... end
val identity : ('a, 'a) t
val ignore : ('a, 'b option) t
Always parses to None
val check : ?name:string -> ?errmsg:string -> ('a -> bool) -> ('a, 'a) t
Identity pp, unless the check fails. The check is turned into an assertion when printing
val map_pair : ?name:string -> ?posf1:('a -> OpamParserTypes.FullPos.pos) -> ?posf2:('b -> OpamParserTypes.FullPos.pos) ->
('a, 'c) t -> ('b, 'd) t -> ('a * 'b, 'c * 'd) t
Builds a pp of pairs by passing the second term along
Builds a pp of pairs by passing the first term along
val map_list : ?name:string -> ?posf:('a -> OpamParserTypes.FullPos.pos) -> ('a, 'b) t -> ('a list, 'b list) t
val singleton : ('a list, 'a) t
Parsing fails on non-singleton lists
val last : ('a list, 'a) t
Use for the rightmost element to close a ^+
sequence, e.g. pp1 ^+ pp2 ^+ last -| pp3
module type STR = sig ... end
Generates a string pp from a module with of/to string functions
Parses to None on the empty list. Often combined with singleton (opt (singleton _)
)
val default : 'a -> ('a option, 'a) t
fallback p1 p2
is p1
, except that parsing is allowed to fail and will in that case try to parse through p2
. Can be useful for backwards compatibility, but use with care
type ('a, 'value) field_parser = ('a * 'value option, 'a) t
Used to parse a single field of a record: 'a
on the left is the accumulator, or value of the record parsed so far. (in lens terms, get
would be the print operation that extracts the field for the record, while set
would be the parse operation that takes the input and record, and updates a given field in the record)
val ppacc : ?cleanup:(pos:OpamParserTypes.FullPos.pos -> 'acc -> 'a -> 'a) ->
('a -> 'acc -> 'acc) -> ('acc -> 'a) -> ('value, 'a) t -> ('acc, 'value) field_parser
Make a field parser from setter, getter and base pp. cleanup
is an optional sanitisation function that is called on parsed elements before calling the setter.
val ppacc_opt : ?cleanup:(pos:OpamParserTypes.FullPos.pos -> 'acc -> 'a -> 'a) ->
('a -> 'acc -> 'acc) -> ('acc -> 'a option) -> ('value, 'a) t -> ('acc, 'value) field_parser
Same as ppacc
, but when the field may be unset in the record, i.e. the getter returns an option
val ppacc_ignore : ('a, OpamParserTypes.FullPos.value) field_parser
A field parser that ignores its argument
val embed : ('a -> 'acc -> 'acc) -> ('acc -> 'a) -> ('a, 'value) field_parser -> ('acc, 'value) field_parser