ocamlsexp/conv.mli

   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]. *)