5 Jane Street Holding, LLC
7 email: mmottl\@janestcapital.com
8 WWW: http://www.janestcapital.com/ocaml
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.
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.
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
25 (** Conv: Utility Module for S-expression Conversions *)
29 (** Dummy definition for "optional" options *)
30 type 'a sexp_option
= 'a
option
33 (** {6 Conversion of OCaml-values to S-expressions} *)
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.
39 Initially set to [fun n -> sprintf "%.20G" n].
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.
47 Initially set to [true].
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.
56 Initially set to [true].
59 val sexp_of_unit
: unit -> Sexp.t
60 (** [sexp_of_unit ()] converts a value of type [unit] to an S-expression. *)
62 val sexp_of_bool
: bool -> Sexp.t
63 (** [sexp_of_bool b] converts the value [x] of type [bool] to an
66 val sexp_of_string
: string -> Sexp.t
67 (** [sexp_of_bool str] converts the value [str] of type [string] to an
70 val sexp_of_char
: char
-> Sexp.t
71 (** [sexp_of_char c] converts the value [c] of type [char] to an
74 val sexp_of_int
: int -> Sexp.t
75 (** [sexp_of_int n] converts the value [n] of type [int] to an
78 val sexp_of_float
: float -> Sexp.t
79 (** [sexp_of_float n] converts the value [n] of type [float] to an
82 val sexp_of_int32
: int32
-> Sexp.t
83 (** [sexp_of_int32 n] converts the value [n] of type [int32] to an
86 val sexp_of_int64
: int64
-> Sexp.t
87 (** [sexp_of_int64 n] converts the value [n] of type [int64] to an
90 val sexp_of_nativeint
: nativeint
-> Sexp.t
91 (** [sexp_of_nativeint n] converts the value [n] of type [nativeint] to an
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. *)
98 val sexp_of_nat
: Nat.nat
-> Sexp.t
99 (** [sexp_of_nat n] converts the value [n] of type [Nat.nat] to an
102 val sexp_of_num
: Num.num
-> Sexp.t
103 (** [sexp_of_num n] converts the value [n] of type [Num.num] to an
106 val sexp_of_ratio
: Ratio.ratio
-> Sexp.t
107 (** [sexp_of_ratio n] converts the value [n] of type [Ratio.ratio] to an
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
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
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. *)
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. *)
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
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. *)
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. *)
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. *)
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. *)
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. *)
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}. *)
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. *)
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. *)
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}. *)
179 val sexp_of_abstr
: 'a
-> Sexp.t
180 (** [sexp_of_abstr x] converts the value [x] of abstract type to an
183 val sexp_of_fun
: ('a
-> 'b
) -> Sexp.t
184 (** [sexp_of_fun f] converts the value [f] of function type to an
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.
194 val sexp_of_opaque
: ('a
-> Sexp.t
) -> 'a opaque
-> Sexp.t
195 (** [sexp_of_opaque _ _] converts opaque OCaml-values to S-expressions. *)
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
203 (** {6 Conversion of S-expressions to OCaml-values} *)
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. *)
209 val record_check_extra_fields
: bool ref
210 (** [record_check_extra_fields] checks for extra (= unknown) fields
211 in record S-expressions. *)
213 val of_sexp_error
: string -> Sexp.t
-> 'a
214 (** [of_sexp_error reason sexp] @raise the exception [Of_sexp_error
217 val unit_of_sexp
: Sexp.t
-> unit
218 (** [unit_of_sexp sexp] converts S-expression [sexp] to a value of type
221 val bool_of_sexp
: Sexp.t
-> bool
222 (** [bool_of_sexp sexp] converts S-expression [sexp] to a value of type
225 val string_of_sexp
: Sexp.t
-> string
226 (** [string_of_sexp sexp] converts S-expression [sexp] to a value of type
229 val char_of_sexp
: Sexp.t
-> char
230 (** [char_of_sexp sexp] converts S-expression [sexp] to a value of type
233 val int_of_sexp
: Sexp.t
-> int
234 (** [int_of_sexp sexp] converts S-expression [sexp] to a value of type
237 val float_of_sexp
: Sexp.t
-> float
238 (** [float_of_sexp sexp] converts S-expression [sexp] to a value of type
241 val int32_of_sexp
: Sexp.t
-> int32
242 (** [int32_of_sexp sexp] converts S-expression [sexp] to a value of type
245 val int64_of_sexp
: Sexp.t
-> int64
246 (** [int64_of_sexp sexp] converts S-expression [sexp] to a value of type
249 val nativeint_of_sexp
: Sexp.t
-> nativeint
250 (** [nativeint_of_sexp sexp] converts S-expression [sexp] to a value
251 of type [nativeint]. *)
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]. *)
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]. *)
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]. *)
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]. *)
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]. *)
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]. *)
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]. *)
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]
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. *)
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]. *)
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]. *)
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]. *)
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. *)
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. *)
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}. *)
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. *)
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. *)
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}. *)
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. *)
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