umarshal.mli (4504B)
1 (* Unison file synchronizer: src/ubase/umarshal.mli *) 2 (* Copyright 2020, Stéphane Glondu (see COPYING for details) *) 3 4 (* The purpose and characteristics of the Umarshal module are not unlike 5 those of Stdlib's Marshal module, with two main differences 6 7 - it is not intended to encode and decode arbitrary data structures. 8 - it is intended to be compatible and stable across all machines and 9 OCaml versions. 10 11 This module provides basic infrastructure for marshaling along with some 12 combinators to build marshaling functions for various data structures. 13 14 The encoding format used by Umarshal is not following any standard, it 15 is a minimal binary format with no overhead designed to encode a limited 16 set of data types in a platform-neutral way. The format does not carry 17 any schema or other type information. *) 18 19 exception Error of string 20 21 (* Type ['a t] defines un-/marshaling functions for a data structure with 22 type ['a]. 23 24 The combinators in this module are used to build [Umarshal.t] values. 25 Combinators are provided for basic types, such as ints, floats and 26 strings, for basic structures such as products (tuples) and sums 27 (variants), and for recursive structures. Other types (such as records) 28 will need to be converted to tuples. All sum and product combinators 29 receive conversion functions for this purpose. 30 31 By convention, a [Umarshal.t] value for a type in another module will be 32 named by the name of the type prefixed with "m", or just "m" in case the 33 type is named "t". 34 35 For example (in other modules): 36 [mtyp : typ Umarshal.t] 37 [m : t Umarshal.t] 38 *) 39 type 'a t 40 41 external id : 'a -> 'a = "%identity" 42 43 val header_size : int 44 val data_size : bytes -> int -> int 45 46 val to_string : 'a t -> 'a -> string 47 val from_bytes : 'a t -> bytes -> int -> 'a 48 val from_string : 'a t -> string -> int -> 'a 49 50 val from_channel : 'a t -> in_channel -> 'a 51 val to_channel : 'a t -> out_channel -> 'a -> unit 52 53 val rec1 : ('a t -> 'a t) -> 'a t 54 val rec2 : ('a t -> 'b t) -> ('b t -> 'a t) -> 'a t * 'b t 55 56 val unit : unit t 57 val bool : bool t 58 val int : int t 59 val int64 : int64 t 60 val float : float t 61 62 val string : string t 63 64 type bytearray = 65 (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t 66 67 val bytearray : bytearray t 68 69 val marshal_to_bytearray : 'a t -> 'a -> bytearray 70 val unmarshal_from_bytearray : 'a t -> bytearray -> int -> 'a 71 72 type int32bigarray = 73 (int32, Bigarray.int32_elt, Bigarray.c_layout) Bigarray.Array1.t 74 75 val int32bigarray : int32bigarray t 76 77 val option : 'a t -> 'a option t 78 val list : 'a t -> 'a list t 79 80 val prod2 : 'a t -> 'b t -> ('r -> 'a * 'b) -> ('a * 'b -> 'r) -> 'r t 81 val prod3 : 'a t -> 'b t -> 'c t -> ('r -> 'a * 'b * 'c) -> ('a * 'b * 'c-> 'r) -> 'r t 82 val prod4 : 'a t -> 'b t -> 'c t -> 'd t -> ('r -> 'a * 'b * 'c * 'd) -> ('a * 'b * 'c * 'd -> 'r) -> 'r t 83 val prod5 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> ('r -> 'a * 'b * 'c * 'd * 'e) -> ('a * 'b * 'c * 'd * 'e -> 'r) -> 'r t 84 val prod6 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> ('r -> 'a * 'b * 'c * 'd * 'e * 'f) -> ('a * 'b * 'c * 'd * 'e * 'f -> 'r) -> 'r t 85 86 val sum1 : 'a t -> ('r -> 'a) -> ('a -> 'r) -> 'r t 87 88 type ('a, 'b) sum2 = I21 of 'a | I22 of 'b 89 val sum2 : 'a t -> 'b t -> ('r -> ('a, 'b) sum2) -> (('a, 'b) sum2 -> 'r) -> 'r t 90 91 type ('a, 'b, 'c) sum3 = I31 of 'a | I32 of 'b | I33 of 'c 92 val sum3 : 'a t -> 'b t -> 'c t -> ('r -> ('a, 'b, 'c) sum3) -> (('a, 'b, 'c) sum3 -> 'r) -> 'r t 93 94 type ('a, 'b, 'c, 'd) sum4 = I41 of 'a | I42 of 'b | I43 of 'c | I44 of 'd 95 val sum4 : 'a t -> 'b t -> 'c t -> 'd t -> ('r -> ('a, 'b, 'c, 'd) sum4) -> (('a, 'b, 'c, 'd) sum4 -> 'r) -> 'r t 96 97 type ('a, 'b, 'c, 'd, 'e) sum5 = I51 of 'a | I52 of 'b | I53 of 'c | I54 of 'd | I55 of 'e 98 val sum5 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> ('r -> ('a, 'b, 'c, 'd, 'e) sum5) -> (('a, 'b, 'c, 'd, 'e) sum5 -> 'r) -> 'r t 99 100 type ('a, 'b, 'c, 'd, 'e, 'f) sum6 = I61 of 'a | I62 of 'b | I63 of 'c | I64 of 'd | I65 of 'e | I66 of 'f 101 val sum6 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> ('r -> ('a, 'b, 'c, 'd, 'e, 'f) sum6) -> (('a, 'b, 'c, 'd, 'e, 'f) sum6 -> 'r) -> 'r t 102 103 val cond : (unit -> bool) -> 'a -> 'a t -> 'a t 104 105 module type PROPLIST_S = sig 106 type key = string 107 type value = Obj.t 108 type map 109 val cardinal : map -> int 110 val empty : map 111 val add : key -> value -> map -> map 112 val iter : (key -> value -> unit) -> map -> unit 113 val find_m : key -> value t 114 end 115 116 module Proplist (S : PROPLIST_S) : sig 117 val m : S.map t 118 end