Automated S-expression conversion
OCaml Vim script Makefile
Latest commit 4556057 Feb 21, 2017 @trefis trefis 114.33+05
Permalink
Failed to load latest commit information.
num/lib 114.20+69 Dec 15, 2016
src 114.20+69 Dec 23, 2016
test 114.28+32 Jan 19, 2017
top 108.09.00 Jan 30, 2013
unix/lib 114.29+68 Jan 26, 2017
vim/syntax 108.00.02 Jan 28, 2013
.gitignore 114.20+69 Dec 15, 2016
CHANGES.md 113.43+70 May 20, 2016
CHANGES.txt 113.24.00 Jan 12, 2016
COPYRIGHT.txt 113.24.00 Jan 12, 2016
LICENSE-Tywith.txt 108.00.02 Jan 28, 2013
LICENSE.txt 108.00.01 Jan 28, 2013
Makefile 114.20+69 Dec 15, 2016
README.org 113.33.00 Mar 9, 2016
THIRD-PARTY.txt 114.06+90 Aug 19, 2016
sexplib.opam 114.33+05 Feb 21, 2017

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 and convenient 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 space, newline, horizontal tab, and form feed, 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 of performing 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, the file will 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.