Module Sexplib.SexpSource

Sexp: Module for handling S-expressions (I/O, etc.)

include Sexp_intf.S
Sourcetype t = Type.t =
  1. | Atom of string
  2. | List of t list

Type of S-expressions

Type of bigstrings

Sourceval compare : t -> t -> int
Sourceval equal : t -> t -> bool
Defaults
Sourceval default_indent : int ref

default_indent reference to default indentation level for human-readable conversions. Initialisation value: 2.

S-expression size
Sourceval size : t -> int * int

size sexp

  • returns

    (n_atoms, n_chars), where n_atoms is the number of atoms in S-expression sexp, and n_chars is the number of characters in the atoms of the S-expression.

Scan functions
Sourceval scan_sexp : ?buf:Buffer.t -> Lexing.lexbuf -> t

scan_sexp ?buf lexbuf scans an S-expression from lex buffer lexbuf using the optional string buffer buf for storing intermediate strings.

Sourceval scan_sexps : ?buf:Buffer.t -> Lexing.lexbuf -> t list

scan_sexps ?buf lexbuf reads a list of S-expressions from lex buffer lexbuf using the optional string buffer buf for storing intermediate strings.

Sourceval scan_rev_sexps : ?buf:Buffer.t -> Lexing.lexbuf -> t list

scan_rev_sexps ?buf lexbuf same as scan_sexps, but returns the reversed list and is slightly more efficient.

Sourceval scan_sexp_opt : ?buf:Buffer.t -> Lexing.lexbuf -> t option

scan_sexp_opt ?buf lexbuf is equivalent to scan_sexp ?buf lexbuf except that it returns None when the eof is reached.

Sourceval scan_iter_sexps : ?buf:Buffer.t -> f:(t -> unit) -> Lexing.lexbuf -> unit

scan_iter_sexps ?buf ~f lexbuf iterates over all S-expressions scanned from lex buffer lexbuf using function f, and the optional string buffer buf for storing intermediate strings.

Sourceval scan_fold_sexps : ?buf:Buffer.t -> f:('a -> t -> 'a) -> init:'a -> Lexing.lexbuf -> 'a

scan_fold_sexps ?buf ~f ~init lexbuf folds over all S-expressions scanned from lex buffer lexbuf using function f, initial state init, and the optional string buffer buf for storing intermediate strings.

Sourceval scan_sexps_conv : ?buf:Buffer.t -> f:(t -> 'a) -> Lexing.lexbuf -> 'a list

scan_sexps_conv ?buf ~f lexbuf maps all S-expressions scanned from lex buffer lexbuf to some list using function f, and the optional string buffer buf for storing intermediate strings.

Type and exception definitions for (partial) parsing
Sourcemodule Parse_pos : sig ... end
Sourcemodule Cont_state : sig ... end
Sourcetype ('a, 't) parse_result = ('a, 't) Pre_sexp.parse_result =
  1. | Done of 't * Parse_pos.t
    (*

    Done (t, parse_pos) finished parsing an S-expression. Current parse position is parse_pos.

    *)
  2. | 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 call parse_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 raise Failure otherwise!

    *)

Type of result from calling Sexp.parse.

Sourceand ('a, 't) parse_fun = pos:int -> len:int -> 'a -> ('a, 't) parse_result

Type of parsing functions with given offsets and lengths.

Sourcemodule Annotated : sig ... end

Module for parsing S-expressions annotated with location information

Sourcetype 't parse_state = private 't Pre_sexp.parse_state = {
  1. parse_pos : Parse_pos.t;
    (*

    Current parse position

    *)
}

Type of state maintained during parsing

Sourcetype parse_error = Pre_sexp.parse_error = {
  1. err_msg : string;
    (*

    Reason why parsing failed

    *)
  2. parse_state : [ `Sexp of t list list parse_state | `Annot of Annotated.stack parse_state ];
    (*

    State of parser

    *)
}

Type of parse errors

Sourceexception Parse_error of parse_error

Exception raised during partial parsing

Unannotated (partial) parsing
Sourceval 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 buffer str starting out with position information provided in parse_pos and reading at most len 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 parsing str at position parse_pos.buf_pos. Each subsequent parse_fun from a Cont uses the buf and pos that is supplied to it. The final parse_fun that returns Done mutates the buf_pos in the originally supplied parse_pos, and then returns it.

  • parameter parse_pos

    default = Parse_pos.create ()

  • parameter len

    default = String.length str - parse_pos.Parse_pos.buf_pos

Sourceval parse_bigstring : ?parse_pos:Parse_pos.t -> ?len:int -> bigstring -> (bigstring, t) parse_result

parse_bigstring ?parse_pos ?len str same as parse, but operates on bigstrings.

Sourceval input_sexp : ?parse_pos:Parse_pos.t -> in_channel -> t

input_sexp ?parse_pos ic parses an S-expression from input channel ic using initial position information in parse_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.

  • parameter parse_pos

    default = Parse_pos.create ()

Sourceval input_sexps : ?parse_pos:Parse_pos.t -> ?buf:bytes -> in_channel -> t list

input_sexps ?parse_pos ?buf ic parses S-expressions from input channel ic until EOF is reached. Faster than the scan-functions.

  • parameter parse_pos

    default = Parse_pos.create ()

Sourceval input_rev_sexps : ?parse_pos:Parse_pos.t -> ?buf:bytes -> in_channel -> t list

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

Loading of (converted) S-expressions
Sourceval load_sexp : ?strict:bool -> ?buf:bytes -> string -> t

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

  • 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

Sourceval load_sexps : ?buf:bytes -> string -> t list

load_sexps ?buf file reads a list of S-expressions from file using buffer buf 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.

Sourceval load_rev_sexps : ?buf:bytes -> string -> t list

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

Sourceval load_sexp_conv : ?strict:bool -> ?buf:bytes -> string -> (t -> 'a) -> 'a Annotated.conv

load_sexp_conv ?strict ?buf file f like Sexp.load_sexp, but performs a conversion on the fly using f. Performance is equivalent to executing Sexp.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.

Sourceval load_sexp_conv_exn : ?strict:bool -> ?buf:bytes -> string -> (t -> 'a) -> 'a

load_sexp_conv_exn ?strict ?buf file f like load_sexp_conv, but returns the converted value or raises Of_sexp_error with exact location information in the case of a conversion error.

Sourceval load_sexps_conv : ?buf:bytes -> string -> (t -> 'a) -> 'a Annotated.conv list

load_sexps_conv ?buf file f like Sexp.load_sexps, but performs a conversion on the fly using f. Performance is equivalent to executing Sexp.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.

Sourceval load_sexps_conv_exn : ?buf:bytes -> string -> (t -> 'a) -> 'a list

load_sexps_conv_exn ?buf file f like load_sexps_conv, but returns the converted value or raises Of_sexp_error with exact location information in the case of a conversion error.

Output of S-expressions to I/O-channels

NOTE: for performance reasons these output functions may need to allocate large strings to write out huge S-expressions. This may cause problems on 32-bit platforms. If you think that you may need to write huge S-expressions on such platforms, you might want to use the pretty-printers that write to formatters instead (see further below).

Sourceval output_hum : out_channel -> t -> unit

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

Sourceval output_hum_indent : int -> out_channel -> t -> unit

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

Sourceval output_mach : out_channel -> t -> unit

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

Sourceval output : out_channel -> t -> unit

output oc sexp same as output_mach.

Output of S-expressions to file

All save-functions write to a temporary file before moving it into place to avoid intermittent garbling of existing files, which may cause problems for other processes that try to read.

Sourceval save_hum : ?perm:int -> string -> t -> unit

save_hum ?perm file sexp outputs S-expression sexp to file in human readable form.

  • parameter perm

    default = umask

Sourceval save_mach : ?perm:int -> string -> t -> unit

save_mach ?perm file sexp outputs S-expression sexp to file in machine readable (i.e. most compact) form.

  • parameter perm

    default = umask

Sourceval save : ?perm:int -> string -> t -> unit

save ?perm file sexp same as save_mach.

Sourceval save_sexps_hum : ?perm:int -> string -> t list -> unit

save_sexps_hum ?perm file sexps outputs S-expression list sexps to file in human readable form, each sexp being followed by a newline.

  • parameter perm

    default = umask

Sourceval save_sexps_mach : ?perm:int -> string -> t list -> unit

save_sexps_mach ?perm file sexps outputs S-expression list sexps to file in machine readable form, each sexp being followed by a newline.

  • parameter perm

    default = umask

Sourceval save_sexps : ?perm:int -> string -> t list -> unit

save_sexps ?perm file sexp same as save_sexps_mach.

Output of S-expressions to formatters
Sourceval pp_hum : Format.formatter -> t -> unit

pp_hum ppf sexp outputs S-expression sexp to formatter ppf in human readable form.

Sourceval pp_hum_indent : int -> Format.formatter -> t -> unit

pp_hum_indent n ppf sexp outputs S-expression sexp to formatter ppf in human readable form and indentation level n.

Sourceval pp_mach : Format.formatter -> t -> unit

pp_mach ppf sexp outputs S-expression sexp to formatter ppf in machine readable (i.e. most compact) form.

Sourceval pp : Format.formatter -> t -> unit

pp ppf sexp same as pp_mach.

String and bigstring conversions
Sourcemodule Of_string_conv_exn : sig ... end

Module encapsulating the exception raised by string converters when type conversions fail.

Sourceval of_string : string -> t

of_string str parses a string str as an S-expression.

Sourceval of_string_many : string -> t list

of_string_many parses a string containing zero or more S-expressions.

Unlike many other functions in this module, on parse failure it raises Parsexp.Parse_error rather than a native Sexplib.Sexp.Parse_error.

Sourceval of_string_conv : string -> (t -> 'a) -> 'a Annotated.conv

of_string_conv str conv like of_string, but performs type conversion with conv.

  • returns

    conversion result.

Sourceval of_string_many_conv_exn : string -> (t -> 'a) -> 'a list

of_string_many_conv_exn str conv like of_string_many, but performs type conversion with conv. Raises if type conversion fails.

Unlike many other functions in this module, on parse failure it raises Parsexp.Parse_error rather than a native Sexplib.Sexp.Parse_error.

It still raises Sexplib.Sexp.Of_string_conv_exn on sexp conversion errors.

  • returns

    conversion result.

Sourceval of_string_conv_exn : string -> (t -> 'a) -> 'a

of_string_conv_exn str conv like of_string_conv, but raises Of_string_conv_exn.E if type conversion fails.

  • returns

    converted value.

Sourceval of_bigstring : bigstring -> t

of_bigstring bstr same as of_string, but operates on bigstrings.

Sourceval of_bigstring_conv : bigstring -> (t -> 'a) -> 'a Annotated.conv

of_bigstring_conv bstr conv like of_bigstring, but performs type conversion with conv.

  • returns

    conversion result.

Sourceval of_bigstring_conv_exn : bigstring -> (t -> 'a) -> 'a

of_bigstring_conv_exn bstr conv like of_bigstring_conv, but raises Of_string_conv_exn.E if type conversion fails.

  • returns

    converted value.

Sourceval 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.

  • parameter indent

    default = !default_indent

Sourceval to_string_mach : t -> string

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

Sourceval to_string : t -> string

to_string sexp same as to_string_mach.

Buffer conversions
Sourceval to_buffer_hum : buf:Buffer.t -> ?indent:int -> t -> unit

to_buffer_hum ~buf ?indent sexp outputs the S-expression sexp converted to a string in human readable form to buffer buf.

  • parameter indent

    default = !default_indent

Sourceval to_buffer_mach : buf:Buffer.t -> t -> unit

to_buffer_mach ~buf sexp outputs the S-expression sexp converted to a string in machine readable (i.e. most compact) form to buffer buf.

Sourceval to_buffer : buf:Buffer.t -> t -> unit

to_buffer ~buf sexp same as to_buffer_mach.

Sourceval 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-expression sexp converted to a string to buffer buf using the output functions add_char and add_string.

Utilities for automated type conversions
Sourceval unit : t

unit the unit-value as expressed by an S-expression.

Sourceval is_unit : t -> bool
Sourceval 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.

Sourceval 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.

Sourceval t_sexp_grammar : t Sexplib0.Sexp_grammar.t
Utilities for conversion error handling
Sourcetype found = [
  1. | `Found
  2. | `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 position pos within a structure (= S-expression list) where found describes recursively where it was found in that structure.

Sourcetype search_result = [
  1. | `Not_found
  2. | found
]

Type of search results. `Not_found means that an S-expression was not found within another S-expression.

Sourceval 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-expression sexp.

Sourceval subst_found : t -> subst:t -> found -> t

subst_found sexp ~subst found

  • returns

    the S-expression that results from substituting subst within S-expression sexp at the location described by found.

Sourcemodule With_layout : sig ... end

S-expressions annotated with relative source positions and comments