Automated S-expression conversion
OCaml Vim script Makefile
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
num/lib v0.11.117.00+101 Mar 29, 2018
src v0.11.117.19+55 Aug 10, 2018
test v0.11.117.19+55 Aug 10, 2018
top 108.09.00 Jan 30, 2013
unix/lib v0.11.117.00+101 Mar 29, 2018
vim/syntax 108.00.02 Jan 28, 2013
.gitignore 114.35+03 Mar 7, 2017
CHANGES.md v0.11.116.17+187 Mar 16, 2018
CHANGES.txt 113.24.00 Jan 12, 2016
CONTRIBUTING.md v0.11.117.08+54 May 23, 2018
COPYRIGHT.txt 113.24.00 Jan 12, 2016
LICENSE-Tywith.txt 108.00.02 Jan 28, 2013
LICENSE.md v0.11.117.08+54 May 23, 2018
Makefile v0.11.117.08+54 May 23, 2018
README.org v0.10.116.11+46 Jan 31, 2018
THIRD-PARTY.txt 114.06+90 Aug 19, 2016
sexplib.opam v0.11.117.08+54 May 23, 2018

README.org

Sexplib - S-Expressions for OCaml

sexplib contains functionality for parsing and pretty-printing s-expressions. S-expressions are defined by the following type:

type sexp = Atom of string | List of sexp list

and are rendered as parenthesized lists of strings, e.g., (This (is an) (s expression)).

This library is often used in conjunction with ppx_sexp_conv, a syntax extension which generates code from type definitions for efficiently converting OCaml-values to s-expressions and vice versa.

Together, these two libraries make it easy to convert your OCaml values to and from a human-readable serializable form, without the tedium of having to write your own converters.

The library also offers functionality for extracting and replacing sub-expressions in s-expressions. Here, we’ll only document sexplib proper. If you want to know more about the way in which OCaml types are mapped on to s-expressions, you should look at the documentation for =ppx_sexp_conv=.

Lexical conventions of s-expression

Whitespace, which consists of the space, newline, horizontal tab, and form feed characters, is ignored unless within an OCaml-string, where it is treated according to OCaml-conventions. The left parenthesis opens a new list, the right one closes it again. Lists can be empty.

The double quote denotes the beginning and end of a string following the lexical conventions of OCaml (see the OCaml-manual for details). All characters other than double quotes, left and right parentheses, whitespace, carriage return, and comment-introducing characters or sequences (see next paragraph) are considered part of a contiguous string.

Comments

There are three kinds of comments:

  • line comments are introduced with ;, and end at the newline.
  • sexp comments are introduced with #;, and end at the end of the following s-expression.
  • block comments are introduced with #| and end with |#. These can be nested, and double-quotes within them must be balanced and be lexically correct OCaml strings.

Grammar of s-expressions

S-expressions are either strings (= atoms) or lists. The lists can recursively contain further s-expressions or be empty, and must be balanced, i.e., parentheses must match.

Examples

this_is_an_atom_123'&^%!  ; this is a comment
"another atom in an OCaml-string \"string in a string\" \123"

; empty list follows below
()

; a more complex example
(
  (
    list in a list  ; comment within a list
    (list in a list in a list)
    42 is the answer to all questions
    #; (this S-expression
         (has been commented out)
       )
    #| Block comments #| can be "nested" |# |#
  )
)

I/O and Type Conversions

There are multiple ways to perform I/O with s-expressions. If exact error locations are required when type conversions fail, s-expressions need to be parsed with location annotations. The associated parser is slower, however, and needs more memory.

In most cases users may therefore want to use functions like load_sexp_conv or load_sexp_conv_exn, which load s-expressions from files and convert them. They initially read the file without location annotations for performance reasons. Only if conversions fail will the file be reparsed with location annotations. Type errors can then be reported accurately with file name, line number, column, and file position.

Custom converters

In addition to the converters provided automatically by ppx_sexp_conv, it’s possible to write one’s own sexp-converter. For such converters to be available by other automatically generated converters, it should follow the convention of being defined in the same scope as the type, and should be named sexp_of_[type] and [type]_of_sexp.

You must report failures by raising the Of_sexp_error-exception so that then sexplib’s tools for pinpointing the location of type errors within an s-expression file will work properly.