opam-format 2.0.0~beta5 · OCaml Package

Generic bidirectional transformation toolbox for parsing/printing

Parsing positions and error reporting helpers

type bad_format = OpamTypes.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:OpamTypes.pos ->
  ('a, unit, string, 'b) Stdlib.format4 ->
  'a

Raise Bad_format.

val string_of_bad_format : ?file:string -> exn -> string

val add_pos : OpamTypes.pos -> exn -> exn

Adds a position to a Bad_format exception if it doesn't have one yet

Parser/printers

type ('a, 'b) t = private {

parse : pos:OpamTypes.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:OpamTypes.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 fof Pp.t from a name and a pair

val parse : ('a, 'b) t -> pos:OpamTypes.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:OpamTypes.pos -> unit -> 'a

Raises an exception handled by parser calls

Various pp constructors

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 -> OpamTypes.pos) ->
  ?posf2:('b -> OpamTypes.pos) ->
  ('a, 'c) t ->
  ('b, 'd) t ->
  ('a * 'b, 'c * 'd) t

val map_fst : ('a, 'b) t -> ('a * 'c, 'b * 'c) t

Builds a pp of pairs by passing the second term along

val map_snd : ('a, 'b) t -> ('c * 'a, 'c * 'b) t

Builds a pp of pairs by passing the first term along

val map_list : 
  ?name:string ->
  ?posf:('a -> OpamTypes.pos) ->
  ('a, 'b) t ->
  ('a list, 'b list) t

val map_option : ?name:string -> ('a, 'b) t -> ('a option, 'b option) 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

val of_module : string -> (module STR with type t = 'a) -> (string, 'a) t

Generates a string pp from a module with of/to string functions

val opt : ('a list, 'b) t -> ('a list, 'b option) t

Parses to None on the empty list. Often combined with singleton (opt (singleton _))

val default : 'a -> ('a option, 'a) t

val fallback : ('a, 'b) t -> ('a, 'b) t -> ('a, 'b) 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

Combinators to parse to a record from a list of (field name, field setter, field getter)

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:OpamTypes.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:OpamTypes.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, OpamTypes.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

package opam-format

Parsing positions and error reporting helpers

Parser/printers

Various pp constructors

Combinators to parse to a record from a list of (field name, field setter, field getter)