| 1 | (* File: conv.mli |
| 2 | |
| 3 | Copyright (C) 2005- |
| 4 | |
| 5 | Jane Street Holding, LLC |
| 6 | Author: Markus Mottl |
| 7 | email: mmottl\@janestcapital.com |
| 8 | WWW: http://www.janestcapital.com/ocaml |
| 9 | |
| 10 | This library is free software; you can redistribute it and/or |
| 11 | modify it under the terms of the GNU Lesser General Public |
| 12 | License as published by the Free Software Foundation; either |
| 13 | version 2 of the License, or (at your option) any later version. |
| 14 | |
| 15 | This library is distributed in the hope that it will be useful, |
| 16 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 17 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 18 | Lesser General Public License for more details. |
| 19 | |
| 20 | You should have received a copy of the GNU Lesser General Public |
| 21 | License along with this library; if not, write to the Free Software |
| 22 | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 23 | *) |
| 24 | |
| 25 | (** Conv: Utility Module for S-expression Conversions *) |
| 26 | |
| 27 | open Bigarray |
| 28 | |
| 29 | (** Dummy definition for "optional" options *) |
| 30 | type 'a sexp_option = 'a option |
| 31 | |
| 32 | |
| 33 | (** {6 Conversion of OCaml-values to S-expressions} *) |
| 34 | |
| 35 | val default_string_of_float : (float -> string) ref |
| 36 | (** [default_string_of_float] reference to the default function used |
| 37 | to convert floats to strings. |
| 38 | |
| 39 | Initially set to [fun n -> sprintf "%.20G" n]. |
| 40 | *) |
| 41 | |
| 42 | val write_old_option_format : bool ref |
| 43 | (** [write_old_option_format] reference for the default option format |
| 44 | used to write option values. If set to [true], the old-style option |
| 45 | format will be used, the new-style one otherwise. |
| 46 | |
| 47 | Initially set to [true]. |
| 48 | *) |
| 49 | |
| 50 | val read_old_option_format : bool ref |
| 51 | (** [read_old_option_format] reference for the default option format |
| 52 | used to read option values. [Of_sexp_error] will be raised with |
| 53 | old-style option values if this reference is set to [false]. |
| 54 | Reading new-style option values is always supported. |
| 55 | |
| 56 | Initially set to [true]. |
| 57 | *) |
| 58 | |
| 59 | val sexp_of_unit : unit -> Sexp.t |
| 60 | (** [sexp_of_unit ()] converts a value of type [unit] to an S-expression. *) |
| 61 | |
| 62 | val sexp_of_bool : bool -> Sexp.t |
| 63 | (** [sexp_of_bool b] converts the value [x] of type [bool] to an |
| 64 | S-expression. *) |
| 65 | |
| 66 | val sexp_of_string : string -> Sexp.t |
| 67 | (** [sexp_of_bool str] converts the value [str] of type [string] to an |
| 68 | S-expression. *) |
| 69 | |
| 70 | val sexp_of_char : char -> Sexp.t |
| 71 | (** [sexp_of_char c] converts the value [c] of type [char] to an |
| 72 | S-expression. *) |
| 73 | |
| 74 | val sexp_of_int : int -> Sexp.t |
| 75 | (** [sexp_of_int n] converts the value [n] of type [int] to an |
| 76 | S-expression. *) |
| 77 | |
| 78 | val sexp_of_float : float -> Sexp.t |
| 79 | (** [sexp_of_float n] converts the value [n] of type [float] to an |
| 80 | S-expression. *) |
| 81 | |
| 82 | val sexp_of_int32 : int32 -> Sexp.t |
| 83 | (** [sexp_of_int32 n] converts the value [n] of type [int32] to an |
| 84 | S-expression. *) |
| 85 | |
| 86 | val sexp_of_int64 : int64 -> Sexp.t |
| 87 | (** [sexp_of_int64 n] converts the value [n] of type [int64] to an |
| 88 | S-expression. *) |
| 89 | |
| 90 | val sexp_of_nativeint : nativeint -> Sexp.t |
| 91 | (** [sexp_of_nativeint n] converts the value [n] of type [nativeint] to an |
| 92 | S-expression. *) |
| 93 | |
| 94 | val sexp_of_big_int : Big_int.big_int -> Sexp.t |
| 95 | (** [sexp_of_big_int n] converts the value [n] of type [Big_int.big_int] |
| 96 | to an S-expression. *) |
| 97 | |
| 98 | val sexp_of_nat : Nat.nat -> Sexp.t |
| 99 | (** [sexp_of_nat n] converts the value [n] of type [Nat.nat] to an |
| 100 | S-expression. *) |
| 101 | |
| 102 | val sexp_of_num : Num.num -> Sexp.t |
| 103 | (** [sexp_of_num n] converts the value [n] of type [Num.num] to an |
| 104 | S-expression. *) |
| 105 | |
| 106 | val sexp_of_ratio : Ratio.ratio -> Sexp.t |
| 107 | (** [sexp_of_ratio n] converts the value [n] of type [Ratio.ratio] to an |
| 108 | S-expression. *) |
| 109 | |
| 110 | val sexp_of_ref : ('a -> 'b) -> 'a ref -> 'b |
| 111 | (** [sexp_of_ref conv r] converts the value [r] of type ['a ref] to |
| 112 | an S-expression. Uses [conv] to convert values of type ['a] to an |
| 113 | S-expression. *) |
| 114 | |
| 115 | val sexp_of_lazy : ('a -> 'b) -> 'a lazy_t -> 'b |
| 116 | (** [sexp_of_ref conv l] converts the value [l] of type ['a lazy_t] to |
| 117 | an S-expression. Uses [conv] to convert values of type ['a] to an |
| 118 | S-expression. *) |
| 119 | |
| 120 | val sexp_of_option : ('a -> Sexp.t) -> 'a option -> Sexp.t |
| 121 | (** [sexp_of_option conv opt] converts the value [opt] of type ['a |
| 122 | option] to an S-expression. Uses [conv] to convert values of type |
| 123 | ['a] to an S-expression. *) |
| 124 | |
| 125 | val sexp_of_pair : ('a -> Sexp.t) -> ('b -> Sexp.t) -> 'a * 'b -> Sexp.t |
| 126 | (** [sexp_of_pair conv1 conv2 pair] converts a pair to an S-expression. |
| 127 | It uses its first argument to convert the first element of the pair, |
| 128 | and its second argument to convert the second element of the pair. *) |
| 129 | |
| 130 | val sexp_of_triple : |
| 131 | ('a -> Sexp.t) -> ('b -> Sexp.t) -> ('c -> Sexp.t) -> 'a * 'b * 'c -> Sexp.t |
| 132 | (** [sexp_of_triple conv1 conv2 conv3 triple] converts a triple to |
| 133 | an S-expression using [conv1], [conv2], and [conv3] to convert its |
| 134 | elements. *) |
| 135 | |
| 136 | val sexp_of_list : ('a -> Sexp.t) -> 'a list -> Sexp.t |
| 137 | (** [sexp_of_list conv lst] converts the value [lst] of type ['a |
| 138 | list] to an S-expression. Uses [conv] to convert values of type |
| 139 | ['a] to an S-expression. *) |
| 140 | |
| 141 | val sexp_of_array : ('a -> Sexp.t) -> 'a array -> Sexp.t |
| 142 | (** [sexp_of_array conv ar] converts the value [ar] of type ['a |
| 143 | array] to an S-expression. Uses [conv] to convert values of type |
| 144 | ['a] to an S-expression. *) |
| 145 | |
| 146 | val sexp_of_hashtbl : |
| 147 | ('a -> Sexp.t) -> ('b -> Sexp.t) -> ('a, 'b) Hashtbl.t -> Sexp.t |
| 148 | (** [sexp_of_hashtbl conv_key conv_value htbl] converts the value [htbl] |
| 149 | of type [('a, 'b) Hashtbl.t] to an S-expression. Uses [conv_key] |
| 150 | to convert the hashtable keys of type ['a], and [conv_value] to |
| 151 | convert hashtable values of type ['b] to S-expressions. *) |
| 152 | |
| 153 | val sexp_of_float32_vec : |
| 154 | (float, float32_elt, fortran_layout) Array1.t -> Sexp.t |
| 155 | (** [sexp_of_float32_vec vec] converts the one-dimensional bigarray |
| 156 | [vec] of 32-bit floats in Fortran-layout to an S-expression. *) |
| 157 | |
| 158 | val sexp_of_float64_vec : |
| 159 | (float, float64_elt, fortran_layout) Array1.t -> Sexp.t |
| 160 | (** [sexp_of_float64_vec vec] converts the one-dimensional bigarray |
| 161 | [vec] of 64-bit floats in Fortran-layout to an S-expression. *) |
| 162 | |
| 163 | val sexp_of_vec : (float, float64_elt, fortran_layout) Array1.t -> Sexp.t |
| 164 | (** [sexp_of_vec vec] same as {!Conv.sexp_of_float64_vec}. *) |
| 165 | |
| 166 | val sexp_of_float32_mat : |
| 167 | (float, float32_elt, fortran_layout) Array2.t -> Sexp.t |
| 168 | (** [sexp_of_float32_mat mat] converts the two-dimensional bigarray |
| 169 | [mat] of 32-bit floats in Fortran-layout to an S-expression. *) |
| 170 | |
| 171 | val sexp_of_float64_mat : |
| 172 | (float, float64_elt, fortran_layout) Array2.t -> Sexp.t |
| 173 | (** [sexp_of_float64_mat mat] converts the two-dimensional bigarray |
| 174 | [mat] of 64-bit floats in Fortran-layout to an S-expression. *) |
| 175 | |
| 176 | val sexp_of_mat : (float, float64_elt, fortran_layout) Array2.t -> Sexp.t |
| 177 | (** [sexp_of_mat mat] same as {!Conv.sexp_of_float64_mat}. *) |
| 178 | |
| 179 | val sexp_of_abstr : 'a -> Sexp.t |
| 180 | (** [sexp_of_abstr x] converts the value [x] of abstract type to an |
| 181 | S-expression. *) |
| 182 | |
| 183 | val sexp_of_fun : ('a -> 'b) -> Sexp.t |
| 184 | (** [sexp_of_fun f] converts the value [f] of function type to an |
| 185 | S-expression. *) |
| 186 | |
| 187 | (** Type used for declaring existing types as opaque to sexp converters, |
| 188 | i.e. even if there is a defined converter for ['a], it will not |
| 189 | be called. This is useful to e.g. suppress printing of extremely |
| 190 | large sub-structures for purely informational, human-readable output. |
| 191 | *) |
| 192 | type 'a opaque = 'a |
| 193 | |
| 194 | val sexp_of_opaque : ('a -> Sexp.t) -> 'a opaque -> Sexp.t |
| 195 | (** [sexp_of_opaque _ _] converts opaque OCaml-values to S-expressions. *) |
| 196 | |
| 197 | val string_of__of__sexp_of : ('a -> Sexp.t) -> 'a -> string |
| 198 | (** [string_of__of__sexp_of conv x] converts the OCaml-value [x] to |
| 199 | an S-expression represented as a string by using conversion function |
| 200 | [conv]. *) |
| 201 | |
| 202 | |
| 203 | (** {6 Conversion of S-expressions to OCaml-values} *) |
| 204 | |
| 205 | exception Of_sexp_error of string * Sexp.t |
| 206 | (** [Of_sexp_error (reason, sexp)] the exception raised when an |
| 207 | S-expression could not be successfully converted to an OCaml-value. *) |
| 208 | |
| 209 | val record_check_extra_fields : bool ref |
| 210 | (** [record_check_extra_fields] checks for extra (= unknown) fields |
| 211 | in record S-expressions. *) |
| 212 | |
| 213 | val of_sexp_error : string -> Sexp.t -> 'a |
| 214 | (** [of_sexp_error reason sexp] @raise the exception [Of_sexp_error |
| 215 | (reason, sexp)]. *) |
| 216 | |
| 217 | val unit_of_sexp : Sexp.t -> unit |
| 218 | (** [unit_of_sexp sexp] converts S-expression [sexp] to a value of type |
| 219 | [unit]. *) |
| 220 | |
| 221 | val bool_of_sexp : Sexp.t -> bool |
| 222 | (** [bool_of_sexp sexp] converts S-expression [sexp] to a value of type |
| 223 | [bool]. *) |
| 224 | |
| 225 | val string_of_sexp : Sexp.t -> string |
| 226 | (** [string_of_sexp sexp] converts S-expression [sexp] to a value of type |
| 227 | [string]. *) |
| 228 | |
| 229 | val char_of_sexp : Sexp.t -> char |
| 230 | (** [char_of_sexp sexp] converts S-expression [sexp] to a value of type |
| 231 | [char]. *) |
| 232 | |
| 233 | val int_of_sexp : Sexp.t -> int |
| 234 | (** [int_of_sexp sexp] converts S-expression [sexp] to a value of type |
| 235 | [int]. *) |
| 236 | |
| 237 | val float_of_sexp : Sexp.t -> float |
| 238 | (** [float_of_sexp sexp] converts S-expression [sexp] to a value of type |
| 239 | [float]. *) |
| 240 | |
| 241 | val int32_of_sexp : Sexp.t -> int32 |
| 242 | (** [int32_of_sexp sexp] converts S-expression [sexp] to a value of type |
| 243 | [int32]. *) |
| 244 | |
| 245 | val int64_of_sexp : Sexp.t -> int64 |
| 246 | (** [int64_of_sexp sexp] converts S-expression [sexp] to a value of type |
| 247 | [int64]. *) |
| 248 | |
| 249 | val nativeint_of_sexp : Sexp.t -> nativeint |
| 250 | (** [nativeint_of_sexp sexp] converts S-expression [sexp] to a value |
| 251 | of type [nativeint]. *) |
| 252 | |
| 253 | val big_int_of_sexp : Sexp.t -> Big_int.big_int |
| 254 | (** [big_int_of_sexp sexp] converts S-expression [sexp] to a value |
| 255 | of type [Big_int.big_int]. *) |
| 256 | |
| 257 | val nat_of_sexp : Sexp.t -> Nat.nat |
| 258 | (** [nat_of_sexp sexp] converts S-expression [sexp] to a value |
| 259 | of type [Nat.nat]. *) |
| 260 | |
| 261 | val num_of_sexp : Sexp.t -> Num.num |
| 262 | (** [num_of_sexp sexp] converts S-expression [sexp] to a value |
| 263 | of type [Nat.num]. *) |
| 264 | |
| 265 | val ratio_of_sexp : Sexp.t -> Ratio.ratio |
| 266 | (** [ratio_of_sexp sexp] converts S-expression [sexp] to a value |
| 267 | of type [Nat.ratio]. *) |
| 268 | |
| 269 | val ref_of_sexp : (Sexp.t -> 'a) -> Sexp.t -> 'a ref |
| 270 | (** [ref_of_sexp conv sexp] converts S-expression [sexp] to a value |
| 271 | of type ['a ref] using conversion function [conv], which converts |
| 272 | an S-expression to a value of type ['a]. *) |
| 273 | |
| 274 | val lazy_of_sexp : (Sexp.t -> 'a) -> Sexp.t -> 'a lazy_t |
| 275 | (** [lazy_of_sexp conv sexp] converts S-expression [sexp] to a value |
| 276 | of type ['a lazy_t] using conversion function [conv], which converts |
| 277 | an S-expression to a value of type ['a]. *) |
| 278 | |
| 279 | val option_of_sexp : (Sexp.t -> 'a) -> Sexp.t -> 'a option |
| 280 | (** [option_of_sexp conv sexp] converts S-expression [sexp] to a value |
| 281 | of type ['a option] using conversion function [conv], which converts |
| 282 | an S-expression to a value of type ['a]. *) |
| 283 | |
| 284 | val pair_of_sexp : (Sexp.t -> 'a) -> (Sexp.t -> 'b) -> Sexp.t -> 'a * 'b |
| 285 | (** [pair_of_sexp conv1 conv2 sexp] converts S-expression [sexp] to a pair |
| 286 | of type ['a * 'b] using conversion functions [conv1] and [conv2], |
| 287 | which convert S-expressions to values of type ['a] and ['b] |
| 288 | respectively. *) |
| 289 | |
| 290 | val triple_of_sexp : |
| 291 | (Sexp.t -> 'a) -> (Sexp.t -> 'b) -> (Sexp.t -> 'c) -> Sexp.t -> 'a * 'b * 'c |
| 292 | (** [triple_of_sexp conv1 conv2 conv3 sexp] converts S-expression [sexp] |
| 293 | to a triple of type ['a * 'b * 'c] using conversion functions [conv1], |
| 294 | [conv2], and [conv3], which convert S-expressions to values of type |
| 295 | ['a], ['b], and ['c] respectively. *) |
| 296 | |
| 297 | val list_of_sexp : (Sexp.t -> 'a) -> Sexp.t -> 'a list |
| 298 | (** [list_of_sexp conv sexp] converts S-expression [sexp] to a value |
| 299 | of type ['a list] using conversion function [conv], which converts |
| 300 | an S-expression to a value of type ['a]. *) |
| 301 | |
| 302 | val array_of_sexp : (Sexp.t -> 'a) -> Sexp.t -> 'a array |
| 303 | (** [array_of_sexp conv sexp] converts S-expression [sexp] to a value |
| 304 | of type ['a array] using conversion function [conv], which converts |
| 305 | an S-expression to a value of type ['a]. *) |
| 306 | |
| 307 | val hashtbl_of_sexp : |
| 308 | (Sexp.t -> 'a) -> (Sexp.t -> 'b) -> Sexp.t -> ('a, 'b) Hashtbl.t |
| 309 | (** [hashtbl_of_sexp conv_key conv_value sexp] converts S-expression |
| 310 | [sexp] to a value of type [('a, 'b) Hashtbl.t] using conversion |
| 311 | function [conv_key], which converts an S-expression to hashtable |
| 312 | key of type ['a], and function [conv_value], which converts an |
| 313 | S-expression to hashtable value of type ['b]. *) |
| 314 | |
| 315 | val float32_vec_of_sexp : |
| 316 | Sexp.t -> (float, float32_elt, fortran_layout) Array1.t |
| 317 | (** [float32_vec_of_sexp sexp] converts S-expression [sexp] to a |
| 318 | one-dimensional bigarray of 32-bit floats in Fortran-layout. *) |
| 319 | |
| 320 | val float64_vec_of_sexp : |
| 321 | Sexp.t -> (float, float64_elt, fortran_layout) Array1.t |
| 322 | (** [float64_vec_of_sexp sexp] converts S-expression [sexp] to a |
| 323 | one-dimensional bigarray of 64-bit floats in Fortran-layout. *) |
| 324 | |
| 325 | val vec_of_sexp : Sexp.t -> (float, float64_elt, fortran_layout) Array1.t |
| 326 | (** [vec_of_sexp sexp] same as {!float64_vec_of_sexp}. *) |
| 327 | |
| 328 | val float32_mat_of_sexp : |
| 329 | Sexp.t -> (float, float32_elt, fortran_layout) Array2.t |
| 330 | (** [float32_mat_of_sexp sexp] converts S-expression [sexp] to a |
| 331 | two-dimensional bigarray of 32-bit floats in Fortran-layout. *) |
| 332 | |
| 333 | val float64_mat_of_sexp : |
| 334 | Sexp.t -> (float, float64_elt, fortran_layout) Array2.t |
| 335 | (** [float64_mat_of_sexp sexp] converts S-expression [sexp] to a |
| 336 | two-dimensional bigarray of 64-bit floats in Fortran-layout. *) |
| 337 | |
| 338 | val mat_of_sexp : Sexp.t -> (float, float64_elt, fortran_layout) Array2.t |
| 339 | (** [mat_of_sexp sexp] same as {!Conv.float64_mat_of_sexp}. *) |
| 340 | |
| 341 | val fun_of_sexp : Sexp.t -> ('a -> 'b) |
| 342 | (** [fun_of_sexp sexp] @raise a conversion error when attempting to |
| 343 | convert an S-expression to a function. *) |
| 344 | |
| 345 | val of_string__of__of_sexp : (Sexp.t -> 'a) -> string -> 'a |
| 346 | (** [of_string__of__of_sexp conv str] converts the S-expression [str] |
| 347 | represented as a string to an OCaml-value by using conversion function |
| 348 | [conv]. *) |