Module SExpr

module SExpr: Libs.ExtSexp_Conv.Sexp_conv

Saving data to a human-readable format/reading data from a human-readable format.

This module provides a set of combinators which may be used to convert any OCaml data to a text representation as S-Expressions (a format comparable to XML or JSON and widely used in the world or programming). While this format is not terribly efficient in terms of disk usage, it has the advantage of being totally platform-independent: S-Expressions written with one version of OCaml may be transmitted across the network or saved and read with another version of OCaml. The secondary advantage is that this format is human-readable and may be used, for instance, for debuggging purposes, or as an alternative to Haskell's more powerful Typeable.

Note that you don't need to learn how to use these combinators in order to take advantage of the full power of this library. A syntax extension is provided with Batteries Included to automatically generate further combinators from any of your type definitions.

As an example, let us consider type foobar, usually defined as type foobar = Foo of int | Bar. To have the compiler automatically generate combinators for foobar, you need to take two steps

add TYPE_CONV "<name of your module>" at the beginning of your module implementation
replace your previous definition with type foobar = Foo of int | Bar with sexp both in the interface (if you have one) and in the implementation

The compiler will then automatically generate functions foobar_of_sexp : Sexp.t -> foobar and

sexp_of_foobar: foobar ->
    Sexp.t

. This feature also works with more complex types and is already aware of most types of Batteries-Included.
Author(s): Markus Mottl (Sexplib), David Teller

type t = Sexplib.Sexp.t

The type of S-Expressions

type 'a sexp_option = 'a option

Dummy definition for "optional" options

Conversion of OCaml-values to S-expressions

val default_string_of_float : (float -> string) Standard.ref

default_string_of_float reference to the default function used to convert floats to strings.

Initially set to fun n -> sprintf "%.20G" n.

val write_old_option_format : bool Standard.ref

write_old_option_format reference for the default option format used to write option values. If set to true, the old-style option format will be used, the new-style one otherwise.

Initially set to true.

val read_old_option_format : bool Standard.ref

read_old_option_format reference for the default option format used to read option values. Of_sexp_error will be raised with old-style option values if this reference is set to false. Reading new-style option values is always supported.

Initially set to true.

val sexp_of_unit : unit -> Sexplib.Sexp.t

sexp_of_unit () converts a value of type unit to an S-expression.

val sexp_of_bool : bool -> Sexplib.Sexp.t

sexp_of_bool b converts the value x of type bool to an S-expression.

val sexp_of_string : string -> Sexplib.Sexp.t

sexp_of_bool str converts the value str of type string to an S-expression.

val sexp_of_char : char -> Sexplib.Sexp.t

sexp_of_char c converts the value c of type char to an S-expression.

val sexp_of_int : int -> Sexplib.Sexp.t

sexp_of_int n converts the value n of type int to an S-expression.

val sexp_of_float : float -> Sexplib.Sexp.t

sexp_of_float n converts the value n of type float to an S-expression.

val sexp_of_int32 : int32 -> Sexplib.Sexp.t

sexp_of_int32 n converts the value n of type int32 to an S-expression.

val sexp_of_int64 : int64 -> Sexplib.Sexp.t

sexp_of_int64 n converts the value n of type int64 to an S-expression.

val sexp_of_nativeint : nativeint -> Sexplib.Sexp.t

sexp_of_nativeint n converts the value n of type nativeint to an S-expression.

val sexp_of_big_int : Big_int.big_int -> Sexplib.Sexp.t

sexp_of_big_int n converts the value n of type Big_int.big_int to an S-expression.

val sexp_of_nat : Nat.nat -> Sexplib.Sexp.t

sexp_of_nat n converts the value n of type Nat.nat to an S-expression.

val sexp_of_num : Num.num -> Sexplib.Sexp.t

sexp_of_num n converts the value n of type Num.num to an S-expression.

val sexp_of_ratio : Ratio.ratio -> Sexplib.Sexp.t

sexp_of_ratio n converts the value n of type Ratio.ratio to an S-expression.

val sexp_of_ref : ('a -> 'b) -> 'a Standard.ref -> 'b

sexp_of_ref conv r converts the value r of type 'a ref to an S-expression. Uses conv to convert values of type 'a to an S-expression.

val sexp_of_lazy : ('a -> 'b) -> 'a lazy_t -> 'b

sexp_of_ref conv l converts the value l of type 'a lazy_t to an S-expression. Uses conv to convert values of type 'a to an S-expression.

val sexp_of_option : ('a -> Sexplib.Sexp.t) -> 'a option -> Sexplib.Sexp.t

sexp_of_option conv opt converts the value opt of type

'a
    option

to an S-expression. Uses conv to convert values of type 'a to an S-expression.

val sexp_of_pair : ('a -> Sexplib.Sexp.t) -> ('b -> Sexplib.Sexp.t) -> 'a * 'b -> Sexplib.Sexp.t

sexp_of_pair conv1 conv2 pair converts a pair to an S-expression. It uses its first argument to convert the first element of the pair, and its second argument to convert the second element of the pair.

val sexp_of_triple : ('a -> Sexplib.Sexp.t) ->
       ('b -> Sexplib.Sexp.t) ->
       ('c -> Sexplib.Sexp.t) -> 'a * 'b * 'c -> Sexplib.Sexp.t

sexp_of_triple conv1 conv2 conv3 triple converts a triple to an S-expression using conv1, conv2, and conv3 to convert its elements.

val sexp_of_list : ('a -> Sexplib.Sexp.t) -> 'a list -> Sexplib.Sexp.t

sexp_of_list conv lst converts the value lst of type

'a
    list

to an S-expression. Uses conv to convert values of type 'a to an S-expression.

val sexp_of_array : ('a -> Sexplib.Sexp.t) -> 'a array -> Sexplib.Sexp.t

sexp_of_array conv ar converts the value ar of type

'a
    array

to an S-expression. Uses conv to convert values of type 'a to an S-expression.

val sexp_of_hashtbl : ('a -> Sexplib.Sexp.t) ->
       ('b -> Sexplib.Sexp.t) -> ('a, 'b) Hashtbl.t -> Sexplib.Sexp.t

sexp_of_hashtbl conv_key conv_value htbl converts the value htbl of type ('a, 'b) Hashtbl.t to an S-expression. Uses conv_key to convert the hashtable keys of type 'a, and conv_value to convert hashtable values of type 'b to S-expressions.

val sexp_of_float32_vec : (float, Big_array.float32_elt, Big_array.fortran_layout) Big_array.Array1.t ->
       Sexplib.Sexp.t

sexp_of_float32_vec vec converts the one-dimensional bigarray vec of 32-bit floats in Fortran-layout to an S-expression.

val sexp_of_float64_vec : (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array1.t ->
       Sexplib.Sexp.t

sexp_of_float64_vec vec converts the one-dimensional bigarray vec of 64-bit floats in Fortran-layout to an S-expression.

val sexp_of_vec : (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array1.t ->
       Sexplib.Sexp.t

sexp_of_vec vec same as Conv.sexp_of_float64_vec.

val sexp_of_float32_mat : (float, Big_array.float32_elt, Big_array.fortran_layout) Big_array.Array2.t ->
       Sexplib.Sexp.t

sexp_of_float32_mat mat converts the two-dimensional bigarray mat of 32-bit floats in Fortran-layout to an S-expression.

val sexp_of_float64_mat : (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array2.t ->
       Sexplib.Sexp.t

sexp_of_float64_mat mat converts the two-dimensional bigarray mat of 64-bit floats in Fortran-layout to an S-expression.

val sexp_of_mat : (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array2.t ->
       Sexplib.Sexp.t

sexp_of_mat mat same as Conv.sexp_of_float64_mat.

val sexp_of_abstr : 'a -> Sexplib.Sexp.t

sexp_of_abstr x converts the value x of abstract type to an S-expression. This means the user need not provide converters, but the result cannot be interpreted.

val sexp_of_fun : ('a -> 'b) -> Sexplib.Sexp.t

sexp_of_fun f converts the value f of function type to an S-expression.

type 'a sexp_opaque = 'a

Type used for declaring existing types as opaque to sexp converters, i.e. even if there is a defined converter for 'a, it will not be called. This is useful to e.g. suppress printing of extremely large sub-structures for purely informational, human-readable output.

val sexp_of_opaque : 'a -> Sexplib.Sexp.t

sexp_of_opaque _ _ converts opaque OCaml-values to S-expressions.

These values may never be decoded.

val string_of__of__sexp_of : ('a -> Sexplib.Sexp.t) -> 'a -> string

string_of__of__sexp_of conv x converts the OCaml-value x to an S-expression represented as a string by using conversion function conv.

Conversion of S-expressions to OCaml-values

exception Of_sexp_error of string * Sexplib.Sexp.t

Of_sexp_error (reason, sexp) the exception raised when an S-expression could not be successfully converted to an OCaml-value.

val record_check_extra_fields : bool Standard.ref

record_check_extra_fields checks for extra (= unknown) fields in record S-expressions.

val of_sexp_error : string -> Sexplib.Sexp.t -> 'a

of_sexp_error reason sexp raises exception

Of_sexp_error
    (reason, sexp)

val unit_of_sexp : Sexplib.Sexp.t -> unit

unit_of_sexp sexp converts S-expression sexp to a value of type unit.

val bool_of_sexp : Sexplib.Sexp.t -> bool

bool_of_sexp sexp converts S-expression sexp to a value of type bool.

val string_of_sexp : Sexplib.Sexp.t -> string

string_of_sexp sexp converts S-expression sexp to a value of type string.

val char_of_sexp : Sexplib.Sexp.t -> char

char_of_sexp sexp converts S-expression sexp to a value of type char.

val int_of_sexp : Sexplib.Sexp.t -> int

int_of_sexp sexp converts S-expression sexp to a value of type int.

val float_of_sexp : Sexplib.Sexp.t -> float

float_of_sexp sexp converts S-expression sexp to a value of type float.

val int32_of_sexp : Sexplib.Sexp.t -> int32

int32_of_sexp sexp converts S-expression sexp to a value of type int32.

val int64_of_sexp : Sexplib.Sexp.t -> int64

int64_of_sexp sexp converts S-expression sexp to a value of type int64.

val nativeint_of_sexp : Sexplib.Sexp.t -> nativeint

nativeint_of_sexp sexp converts S-expression sexp to a value of type nativeint.

val big_int_of_sexp : Sexplib.Sexp.t -> Big_int.big_int

big_int_of_sexp sexp converts S-expression sexp to a value of type Big_int.big_int.

val nat_of_sexp : Sexplib.Sexp.t -> Nat.nat

nat_of_sexp sexp converts S-expression sexp to a value of type Nat.nat.

val num_of_sexp : Sexplib.Sexp.t -> Num.num

num_of_sexp sexp converts S-expression sexp to a value of type Nat.num.

val ratio_of_sexp : Sexplib.Sexp.t -> Ratio.ratio

ratio_of_sexp sexp converts S-expression sexp to a value of type Nat.ratio.

val ref_of_sexp : (Sexplib.Sexp.t -> 'a) -> Sexplib.Sexp.t -> 'a Standard.ref

ref_of_sexp conv sexp converts S-expression sexp to a value of type 'a ref using conversion function conv, which converts an S-expression to a value of type 'a.

val lazy_of_sexp : (Sexplib.Sexp.t -> 'a) -> Sexplib.Sexp.t -> 'a lazy_t

lazy_of_sexp conv sexp converts S-expression sexp to a value of type 'a lazy_t using conversion function conv, which converts an S-expression to a value of type 'a.

val option_of_sexp : (Sexplib.Sexp.t -> 'a) -> Sexplib.Sexp.t -> 'a option

option_of_sexp conv sexp converts S-expression sexp to a value of type 'a option using conversion function conv, which converts an S-expression to a value of type 'a.

val pair_of_sexp : (Sexplib.Sexp.t -> 'a) -> (Sexplib.Sexp.t -> 'b) -> Sexplib.Sexp.t -> 'a * 'b

pair_of_sexp conv1 conv2 sexp converts S-expression sexp to a pair of type 'a * 'b using conversion functions conv1 and conv2, which convert S-expressions to values of type 'a and 'b respectively.

val triple_of_sexp : (Sexplib.Sexp.t -> 'a) ->
       (Sexplib.Sexp.t -> 'b) ->
       (Sexplib.Sexp.t -> 'c) -> Sexplib.Sexp.t -> 'a * 'b * 'c

triple_of_sexp conv1 conv2 conv3 sexp converts S-expression sexp to a triple of type 'a * 'b * 'c using conversion functions conv1, conv2, and conv3, which convert S-expressions to values of type 'a, 'b, and 'c respectively.

val list_of_sexp : (Sexplib.Sexp.t -> 'a) -> Sexplib.Sexp.t -> 'a list

list_of_sexp conv sexp converts S-expression sexp to a value of type 'a list using conversion function conv, which converts an S-expression to a value of type 'a.

val array_of_sexp : (Sexplib.Sexp.t -> 'a) -> Sexplib.Sexp.t -> 'a array

array_of_sexp conv sexp converts S-expression sexp to a value of type 'a array using conversion function conv, which converts an S-expression to a value of type 'a.

val hashtbl_of_sexp : (Sexplib.Sexp.t -> 'a) ->
       (Sexplib.Sexp.t -> 'b) -> Sexplib.Sexp.t -> ('a, 'b) Hashtbl.t

hashtbl_of_sexp conv_key conv_value sexp converts S-expression sexp to a value of type ('a, 'b) Hashtbl.t using conversion function conv_key, which converts an S-expression to hashtable key of type 'a, and function conv_value, which converts an S-expression to hashtable value of type 'b.

val float32_vec_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float32_elt, Big_array.fortran_layout) Big_array.Array1.t

float32_vec_of_sexp sexp converts S-expression sexp to a one-dimensional bigarray of 32-bit floats in Fortran-layout.

val float64_vec_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array1.t

float64_vec_of_sexp sexp converts S-expression sexp to a one-dimensional bigarray of 64-bit floats in Fortran-layout.

val vec_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array1.t

vec_of_sexp sexp same as SExpr.float64_vec_of_sexp.

val float32_mat_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float32_elt, Big_array.fortran_layout) Big_array.Array2.t

float32_mat_of_sexp sexp converts S-expression sexp to a one-dimensional bigarray of 32-bit floats in Fortran-layout.

val float64_vec_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array1.t

float64_vec_of_sexp sexp converts S-expression sexp to a one-dimensional bigarray of 64-bit floats in Fortran-layout.

val vec_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array1.t

vec_of_sexp sexp same as SExpr.float64_vec_of_sexp.

val float32_mat_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float32_elt, Big_array.fortran_layout) Big_array.Array2.t

float32_mat_of_sexp sexp converts S-expression sexp to a two-dimensional bigarray of 32-bit floats in Fortran-layout.

val float64_mat_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array2.t

float64_mat_of_sexp sexp converts S-expression sexp to a two-dimensional bigarray of 64-bit floats in Fortran-layout.

val mat_of_sexp : Sexplib.Sexp.t ->
       (float, Big_array.float64_elt, Big_array.fortran_layout) Big_array.Array2.t

mat_of_sexp sexp same as Conv.float64_mat_of_sexp.

val fun_of_sexp : Sexplib.Sexp.t -> 'a -> 'b

fun_of_sexp sexp raises a conversion error when attempting to convert an S-expression to a function.

val of_string__of__of_sexp : (Sexplib.Sexp.t -> 'a) -> string -> 'a

of_string__of__of_sexp conv str converts the S-expression str represented as a string to an OCaml-value by using conversion function conv.

Loading S-Expressions

val load_sexp : ?buf:string -> string -> t

load_sexp ?buf file reads one S-expression from file file using buffer buf for storing intermediate data. Ignores any trailing data. Faster than the scan-functions.
Raises

ParseError if the S-expression is unparseable.
End_of_file if no S-expression could be read.

val load_sexps : ?buf:string -> string -> t list

load_sexps file reads a list of whitespace separated S-expressions from file file using buffer buf for storing intermediate data. Faster than the scan-functions.
Raises

ParseError if there is unparseable data in the file.
End_of_file if the last S-expression is incomplete.

val load_rev_sexps : ?buf:string -> string -> t list

load_rev_sexps file same as Sexp.load_sexps, but returns a reversed list of S-expressions, which is slightly more efficient.

val input_sexp : ?text_line:int ->
       ?text_char:int ->
       ?buf_pos:int -> IO.input -> t

input_sexp ?text_line ?text_char ?buf_pos ic parses an S-expression from input channel ic using initial position information text_line, text_char, and buf_pos. NOTE: this function is not as fast on files as Sexp.load_sexp, and is also slightly slower than the scan-functions. But it is guaranteed that input_sexp is only going to read data parseable as an S-expression. Thus, subsequent input functions will see the data immediately following it.

text_line : default = 1

text_char : default = 1

buf_pos : default = 0

val input_sexps : ?text_line:int ->
       ?text_char:int ->
       ?buf_pos:int ->
       ?buf:string -> IO.input -> t list

input_sexps ?text_line ?text_char ?buf_pos ??buf ic parses whitespace separated S-expressions from input channel ic until EOF is reached. Faster than the scan-functions. NOTE: buf_pos is the initial global buffer position used for locating errors and does not refer to buf.

text_line : default = 1

text_char : default = 1

buf_pos : default = 0

val input_rev_sexps : ?text_line:int ->
       ?text_char:int ->
       ?buf_pos:int ->
       ?buf:string -> IO.input -> t list

input_rev_sexps ?buf ic same as Sexp.input_sexps, but returns a reversed list of S-expressions, which is slightly more efficient.

Output of S-expressions to I/O-channels or strings

val output_hum : 'a IO.output -> t -> unit

output_hum oc sexp outputs S-expression sexp to output channel oc in human readable form.

val output_hum_indent : int -> 'a IO.output -> t -> unit

output_hum_indent indent oc sexp outputs S-expression sexp to output channel oc in human readable form using indentation level indent.

val output_mach : 'a IO.output -> t -> unit

output_mach oc sexp outputs S-expression sexp to output channel oc in machine readable (i.e. most compact) form.

val output : 'a IO.output -> t -> unit

as output_mach.

val print : 'a IO.output -> t -> unit

as output_hum

May be used to display the contents of a S-expression using Printf.

val to_string_hum : ?indent:int -> t -> string

to_string_hum ?indent sexp converts S-expression sexp to a string in human readable form with indentation level indent.

indent : default = !default_indent

val to_string_mach : t -> string

to_string_mach sexp converts S-expression sexp to a string in machine readable (i.e. most compact) form.

val to_string : t -> string

to_string sexp same as to_string_mach.

Boilerplate code

val t_of_sexp : Sexplib.Sexp.t -> t

S-Expressions

val sexp_of_t : t -> Sexplib.Sexp.t