Module Sexplib__Sexp
Sexp: Module for handling S-expressions (I/O, etc.)
include Sexplib.Sexp_intf.S
type t
= Sexplib.Type.t
=
|
Atom of string
|
List of t list
Type of S-expressions
type bigstring
= (char, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t
Type of bigstrings
Defaults
S-expression size
val size : t -> int * int
size sexp
- returns
(n_atoms, n_chars)
, wheren_atoms
is the number of atoms in S-expressionsexp
, andn_chars
is the number of characters in the atoms of the S-expression.
Scan functions
val scan_sexp : ?buf:Stdlib.Buffer.t -> Stdlib.Lexing.lexbuf -> t
scan_sexp ?buf lexbuf
scans an S-expression from lex bufferlexbuf
using the optional string bufferbuf
for storing intermediate strings.
val scan_sexps : ?buf:Stdlib.Buffer.t -> Stdlib.Lexing.lexbuf -> t list
scan_sexps ?buf lexbuf
reads a list of whitespace separated S-expressions from lex bufferlexbuf
using the optional string bufferbuf
for storing intermediate strings.
val scan_rev_sexps : ?buf:Stdlib.Buffer.t -> Stdlib.Lexing.lexbuf -> t list
scan_rev_sexps ?buf lexbuf
same asscan_sexps
, but returns the reversed list and is slightly more efficient.
val scan_sexp_opt : ?buf:Stdlib.Buffer.t -> Stdlib.Lexing.lexbuf -> t option
scan_sexp_opt ?buf lexbuf
is equivalent toscan_sexp ?buf lexbuf
except that it returnsNone
when the eof is reached.
val scan_iter_sexps : ?buf:Stdlib.Buffer.t -> f:(t -> unit) -> Stdlib.Lexing.lexbuf -> unit
scan_iter_sexps ?buf ~f lexbuf
iterates over all whitespace separated S-expressions scanned from lex bufferlexbuf
using functionf
, and the optional string bufferbuf
for storing intermediate strings.
val scan_fold_sexps : ?buf:Stdlib.Buffer.t -> f:('a -> t -> 'a) -> init:'a -> Stdlib.Lexing.lexbuf -> 'a
scan_fold_sexps ?buf ~f ~init lexbuf
folds over all whitespace separated S-expressions scanned from lex bufferlexbuf
using functionf
, initial stateinit
, and the optional string bufferbuf
for storing intermediate strings.
val scan_sexps_conv : ?buf:Stdlib.Buffer.t -> f:(t -> 'a) -> Stdlib.Lexing.lexbuf -> 'a list
scan_sexps_conv ?buf ~f lexbuf
maps all whitespace separated S-expressions scanned from lex bufferlexbuf
to some list using functionf
, and the optional string bufferbuf
for storing intermediate strings.
Type and exception definitions for (partial) parsing
module Parse_pos : sig ... end
module Cont_state : sig ... end
type ('a, 't) parse_result
= ('a, 't) Sexplib.Pre_sexp.parse_result
=
|
Done of 't * Parse_pos.t
Done (t, parse_pos)
finished parsing an S-expression. Current parse position isparse_pos
.|
Cont of Cont_state.t * ('a, 't) parse_fun
Cont (cont_state, parse_fun)
met the end of input before completely parsing an S-expression. The user has to callparse_fun
to continue parsing the S-expression in another buffer.cont_state
is the current parsing state of the continuation. NOTE: the continuation may only be called once and will raiseFailure
otherwise!Type of result from calling
Sexp
.parse.
and ('a, 't) parse_fun
= pos:int -> len:int -> 'a -> ('a, 't) parse_result
Type of parsing functions with given offsets and lengths.
module Annotated : sig ... end
Module for parsing S-expressions annotated with location information
type 't parse_state
= private 't Sexplib.Pre_sexp.parse_state
=
{
parse_pos : Parse_pos.t;
Current parse position
}
Type of state maintained during parsing
type parse_error
= Sexplib.Pre_sexp.parse_error
=
{
err_msg : string;
Reason why parsing failed
parse_state : [ `Sexp of t list list parse_state | `Annot of Annotated.stack parse_state ];
State of parser
}
Type of parse errors
exception
Parse_error of parse_error
Exception raised during partial parsing
Unannotated (partial) parsing
val parse : ?parse_pos:Parse_pos.t -> ?len:int -> string -> (string, t) parse_result
parse ?parse_pos ?len str
(partially) parses an S-expression in string bufferstr
starting out with position information provided inparse_pos
and reading at mostlen
characters. To parse a single atom that is not delimited by whitespace it is necessary to call this function a second time with the returned continuation, and a dummy buffer that contains whitespace.parse
starts parsingstr
at positionparse_pos.buf_pos
. Each subsequentparse_fun
from aCont
uses thebuf
andpos
that is supplied to it. The finalparse_fun
that returnsDone
mutates thebuf_pos
in the originally suppliedparse_pos
, and then returns it.- parameter parse_pos
default =
Parse_pos.create ()
- parameter len
default =
String.length str - parse_pos.Parse_pos.buf_pos
val parse_bigstring : ?parse_pos:Parse_pos.t -> ?len:int -> bigstring -> (bigstring, t) parse_result
parse_bigstring ?parse_pos ?len str
same asparse
, but operates on bigstrings.
val input_sexp : ?parse_pos:Parse_pos.t -> Stdlib.in_channel -> t
input_sexp ?parse_pos ic
parses an S-expression from input channelic
using initial position information inparse_pos
. NOTE: this function is not as fast on files asSexp
.load_sexp, and is also slightly slower than the scan-functions. But it is guaranteed thatinput_sexp
is only going to read data parseable as an S-expression. Thus, subsequent input functions will see the data immediately following it.- parameter parse_pos
default =
Parse_pos.create ()
val input_sexps : ?parse_pos:Parse_pos.t -> ?buf:bytes -> Stdlib.in_channel -> t list
input_sexps ?parse_pos ?buf ic
parses whitespace separated S-expressions from input channelic
until EOF is reached. Faster than the scan-functions.- parameter parse_pos
default =
Parse_pos.create ()
val input_rev_sexps : ?parse_pos:Parse_pos.t -> ?buf:bytes -> Stdlib.in_channel -> t list
input_rev_sexps ?parse_pos ?buf ic
same asSexp
.input_sexps, but returns a reversed list of S-expressions, which is slightly more efficient.
Loading of (converted) S-expressions
val load_sexp : ?strict:bool -> ?buf:bytes -> string -> t
load_sexp ?strict ?buf file
reads one S-expression fromfile
using bufferbuf
for storing intermediate data. Faster than the scan-functions.- raises Parse_error
if the S-expression is unparseable.
- raises Failure
if parsing reached the end of file before one S-expression could be read.
- raises Failure
if
strict
is true and there is more than one S-expression in the file.
- parameter strict
default =
true
val load_sexps : ?buf:bytes -> string -> t list
load_sexps ?buf file
reads a list of whitespace separated S-expressions fromfile
using bufferbuf
for storing intermediate data. Faster than the scan-functions.- raises Parse_error
if there is unparseable data in the file.
- raises Failure
if parsing reached the end of file before the last S-expression could be fully read.
val load_rev_sexps : ?buf:bytes -> string -> t list
load_rev_sexps ?buf file
same asSexp
.load_sexps, but returns a reversed list of S-expressions, which is slightly more efficient.
val load_sexp_conv : ?strict:bool -> ?buf:bytes -> string -> (t -> 'a) -> 'a Annotated.conv
load_sexp_conv ?strict ?buf file f
likeSexp
.load_sexp, but performs a conversion on the fly usingf
. Performance is equivalent to executingSexp
.load_sexp and performing conversion when there are no errors. In contrast to the plain S-expression loader, this function not only performs the conversion, it will give exact error ranges for conversion errors.- raises Parse_error
if there is unparseable data in the file.
- raises Failure
if parsing reached the end of file before the last S-expression could be fully read.
val load_sexp_conv_exn : ?strict:bool -> ?buf:bytes -> string -> (t -> 'a) -> 'a
load_sexp_conv_exn ?strict ?buf file f
likeload_sexp_conv
, but returns the converted value or raisesOf_sexp_error
with exact location information in the case of a conversion error.
val load_sexps_conv : ?buf:bytes -> string -> (t -> 'a) -> 'a Annotated.conv list
load_sexps_conv ?buf file f
likeSexp
.load_sexps, but performs a conversion on the fly usingf
. Performance is equivalent to executingSexp
.load_sexps and performing conversion when there are no errors. In contrast to the plain S-expression loader, this function not only performs the conversion, it will give exact error ranges for conversion errors.- raises Parse_error
if there is unparseable data in the file.
- raises Failure
if parsing reached the end of file before the last S-expression could be fully read.
val load_sexps_conv_exn : ?buf:bytes -> string -> (t -> 'a) -> 'a list
load_sexps_conv_exn ?buf file f
likeload_sexps_conv
, but returns the converted value or raisesOf_sexp_error
with exact location information in the case of a conversion error.
Output of S-expressions to I/O-channels
val output_hum : Stdlib.out_channel -> t -> unit
output_hum oc sexp
outputs S-expressionsexp
to output channeloc
in human readable form.
val output_hum_indent : int -> Stdlib.out_channel -> t -> unit
output_hum_indent indent oc sexp
outputs S-expressionsexp
to output channeloc
in human readable form using indentation levelindent
.
val output_mach : Stdlib.out_channel -> t -> unit
output_mach oc sexp
outputs S-expressionsexp
to output channeloc
in machine readable (i.e. most compact) form.
val output : Stdlib.out_channel -> t -> unit
output oc sexp
same asoutput_mach
.
Output of S-expressions to file
val save_hum : ?perm:int -> string -> t -> unit
save_hum ?perm file sexp
outputs S-expressionsexp
tofile
in human readable form.- parameter perm
default = umask
val save_mach : ?perm:int -> string -> t -> unit
save_mach ?perm file sexp
outputs S-expressionsexp
tofile
in machine readable (i.e. most compact) form.- parameter perm
default = umask
val save_sexps_hum : ?perm:int -> string -> t list -> unit
save_sexps_hum ?perm file sexps
outputs S-expression listsexps
tofile
in human readable form, each sexp being followed by a newline.- parameter perm
default = umask
val save_sexps_mach : ?perm:int -> string -> t list -> unit
save_sexps_mach ?perm file sexps
outputs S-expression listsexps
tofile
in machine readable form, each sexp being followed by a newline.- parameter perm
default = umask
val save_sexps : ?perm:int -> string -> t list -> unit
save_sexps ?perm file sexp
same assave_sexps_mach
.
Output of S-expressions to formatters
val pp_hum : Stdlib.Format.formatter -> t -> unit
pp_hum ppf sexp
outputs S-expressionsexp
to formatterppf
in human readable form.
val pp_hum_indent : int -> Stdlib.Format.formatter -> t -> unit
pp_hum_indent n ppf sexp
outputs S-expressionsexp
to formatterppf
in human readable form and indentation leveln
.
val pp_mach : Stdlib.Format.formatter -> t -> unit
pp_mach ppf sexp
outputs S-expressionsexp
to formatterppf
in machine readable (i.e. most compact) form.
val pp : Stdlib.Format.formatter -> t -> unit
pp ppf sexp
same aspp_mach
.
String and bigstring conversions
module Of_string_conv_exn : sig ... end
Module encapsulating the exception raised by string converters when type conversions fail.
val of_string : string -> t
of_string str
converts stringstr
to an S-expression. NOTE: trailing whitespace is considered an error, which may be overly strict for some applications. Either strip the string of trailing whitespace first, or, even cheaper, useparse
instead.
val of_string_conv : string -> (t -> 'a) -> 'a Annotated.conv
of_string_conv str conv
likeof_string
, but performs type conversion withconv
.- returns
conversion result.
val of_string_conv_exn : string -> (t -> 'a) -> 'a
of_string_conv_exn str conv
likeof_string_conv
, but raisesOf_string_conv_exn.E
if type conversion fails.- returns
converted value.
val of_bigstring_conv : bigstring -> (t -> 'a) -> 'a Annotated.conv
of_bigstring_conv bstr conv
likeof_bigstring
, but performs type conversion withconv
.- returns
conversion result.
val of_bigstring_conv_exn : bigstring -> (t -> 'a) -> 'a
of_bigstring_conv_exn bstr conv
likeof_bigstring_conv
, but raisesOf_string_conv_exn.E
if type conversion fails.- returns
converted value.
val to_string_hum : ?indent:int -> t -> string
to_string_hum ?indent sexp
converts S-expressionsexp
to a string in human readable form with indentation levelindent
.- parameter indent
default =
!default_indent
val to_string_mach : t -> string
to_string_mach sexp
converts S-expressionsexp
to a string in machine readable (i.e. most compact) form.
val to_string : t -> string
to_string sexp
same asto_string_mach
.
Buffer conversions
val to_buffer_hum : buf:Stdlib.Buffer.t -> ?indent:int -> t -> unit
to_buffer_hum ~buf ?indent sexp
outputs the S-expressionsexp
converted to a string in human readable form to bufferbuf
.- parameter indent
default =
!default_indent
val to_buffer_mach : buf:Stdlib.Buffer.t -> t -> unit
to_buffer_mach ~buf sexp
outputs the S-expressionsexp
converted to a string in machine readable (i.e. most compact) form to bufferbuf
.
val to_buffer : buf:Stdlib.Buffer.t -> t -> unit
to_buffer ~buf sexp
same asto_buffer_mach
.
val to_buffer_gen : buf:'buffer -> add_char:('buffer -> char -> unit) -> add_string:('buffer -> string -> unit) -> t -> unit
to_buffer_gen ~buf ~add_char ~add_string sexp
outputs the S-expressionsexp
converted to a string to bufferbuf
using the output functionsadd_char
andadd_string
.
Utilities for automated type conversions
val unit : t
unit
the unit-value as expressed by an S-expression.
val is_unit : t -> bool
val sexp_of_t : t -> t
sexp_of_t sexp
maps S-expressions which are part of a type with automated S-expression conversion to themselves.
val t_of_sexp : t -> t
t_of_sexp sexp
maps S-expressions which are part of a type with automated S-expression conversion to themselves.
val t_sexp_grammar : Sexplib0.Private.Raw_grammar.t
Utilities for conversion error handling
type found
=[
|
`Found
|
`Pos of int * found
]
Type of successful search results.
`Found
means that an S-expression was found at the immediate position, and`Pos (pos, found)
indicates that it was found at positionpos
within a structure (= S-expression list) wherefound
describes recursively where it was found in that structure.
type search_result
=[
|
`Not_found
|
found
]
Type of search results.
`Not_found
means that an S-expression was not found within another S-expression.
val search_physical : t -> contained:t -> search_result
search_physical sexp ~contained
- returns
the search result indicating whether, and if, where the S-expression
contained
was found within S-expressionsexp
.
val subst_found : t -> subst:t -> found -> t
subst_found sexp ~subst found
- returns
the S-expression that results from substituting
subst
within S-expressionsexp
at the location described byfound
.
module With_layout : sig ... end
S-expressions annotated with relative source positions and comments