package sexplib

  1. Overview
  2. Docs
Library for serializing OCaml values to and from S-expressions

Install

Dune Dependency

github.com Readme Changelog MIT License Edit opam file Versions (54)

Authors

  1. J
    Jane Street Group, LLC

Maintainers

  1. J
    Jane Street developers

Sources

sexplib-v0.14.0.tar.gz
sha256=a2d2c5fdab67b37f06a5ae190de18ba4488d02894f09fd866d4e66e60cb3348b
md5=6e230eae22face46cb8645e53e351067

Description

Part of Jane Street's Core library The Core suite of libraries is an industrial strength alternative to OCaml's standard library that was developed by Jane Street, the largest industrial user of OCaml.

Published: 31 May 2020

README

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:

#+begin_src ocaml
type sexp = Atom of string | List of sexp list
#+end_src

** Usage example

In this example we build an s-expression that corresponds to =(This
(is an) (s expression))=, serialize that into a string, and then parse
the string back into an s-expression.

#+begin_src ocaml
open Sexplib

let () =
  (* Build an Sexp from: (This (is an) (s expression)) *)
  let exp1 = Sexp.(List [
    Atom "This";
    List [Atom "is"; Atom "an"];
    List [Atom "s"; Atom "expression"]
  ]) in
  (* Serialize an Sexp object into a string *)
  print_endline (Sexp.to_string exp1);
  (* Parse a string and produce a Sexp object  *)
  let exp2 = Sexp.of_string "(This (is an) (s expression))" in
  (* Ensure we parsed what we expected. *)
  assert (Sexp.compare exp1 exp2 = 0)
#+end_src


** About

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 [[https://github.com/janestreet/ppx_sexp_conv][=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 [[http://caml.inria.fr/pub/docs/manual-ocaml/][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

#+begin_src scheme
  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" |# |#
    )
  )
#+end_src

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

Dependencies (5)

  1. num
  2. dune >= "2.0.0"
  3. sexplib0 >= "v0.14" & < "v0.15"
  4. parsexp >= "v0.14" & < "v0.15"
  5. ocaml >= "4.04.2"

Dev Dependencies

None

  1. amf < "0.1.2"
  2. arakoon = "1.9.0"
  3. async-zmq >= "0.3.0"
  4. async_core < "108.00.02"
  5. awa < "0.2.0"
  6. biocaml >= "0.11.0"
  7. bistro >= "0.2.0" & < "0.4.0" | >= "0.6.0"
  8. bookaml >= "3.1"
  9. caldav
  10. cconv-ppx
  11. charrua
  12. charrua-core >= "0.3"
  13. charrua-server
  14. cohttp >= "0.20.0" & < "1.2.0"
  15. cohttp-lwt = "1.1.1"
  16. cohttp-mirage < "2.0.0"
  17. conduit >= "0.12.0" & != "3.0.0" & < "7.0.0"
  18. conduit-async >= "1.2.0" & != "3.0.0" & < "7.0.0"
  19. conduit-lwt >= "1.3.0" & != "3.0.0" & < "7.0.0"
  20. conduit-mirage != "3.0.0" & < "7.0.0"
  21. conformist >= "0.2.1"
  22. coq-lsp >= "0.2.0+8.17" & < "0.2.0+8.19"
  23. coq-serapi < "8.7.2+0.4.13" | >= "8.9.0+0.6.0"
  24. core >= "v0.14.0" & < "v0.15.0"
  25. core_kernel >= "v0.14.0" & < "v0.15.0"
  26. cppffigen
  27. cstruct >= "1.8.0" & != "3.6.0" & < "4.0.0"
  28. cstruct-sexp
  29. csvfields = "v0.14.0"
  30. current_web >= "0.4"
  31. datakit-server >= "0.10.0" & < "0.11.0"
  32. datakit-server-9p
  33. decoders-sexplib
  34. diet < "0.4"
  35. dns-forward
  36. dockerfile >= "1.3.0"
  37. dockerfile-cmd >= "8.1.0"
  38. dockerfile-opam = "4.0.0" | >= "7.1.0"
  39. dune-compiledb
  40. dune-deps
  41. dune-expand
  42. earlybird >= "1.0.1"
  43. ego
  44. erlang
  45. ezjsonm >= "0.4.0" & < "1.2.0"
  46. ezjsonm-lwt
  47. frenetic >= "5.0.0"
  48. git < "1.1.0"
  49. git-http >= "1.11.4" & < "2.1.0"
  50. graphql < "0.4.0"
  51. graphql_parser < "0.9.0"
  52. guile
  53. hack_parallel
  54. ipaddr >= "2.8.0" & < "3.0.0"
  55. irmin-unix >= "3.0.0" & < "3.2.0"
  56. jekyll-format >= "0.3.0"
  57. ketrew = "3.0.0"
  58. lazy-trie >= "1.2.0"
  59. lua_parser
  60. mecab
  61. message-switch >= "1.4.0"
  62. mirage-conduit = "1.3.0" | >= "3.1.0"
  63. mirage-crypto-pk < "0.10.4"
  64. mirage-http >= "2.5.0" & < "2.5.3"
  65. mirage-net-macosx
  66. mirage-net-xen >= "1.6.0" & < "1.7.1"
  67. mirage-tc >= "0.2.0" & < "0.3.0"
  68. msgpck < "1.1"
  69. nbd >= "2.1.0" & < "2.1.3" | >= "3.0.0"
  70. netchannel
  71. nocrypto >= "0.5.4-1"
  72. not-ocamlfind < "0.07.02"
  73. obuilder
  74. obuilder-spec
  75. ocaml-basics
  76. ocaml-indent
  77. ocaml-topexpect >= "0.3"
  78. ocaml_plugin = "v0.14.0"
  79. odep
  80. odoc >= "1.4.0" & < "2.0.0"
  81. opam-dune-lint
  82. opass >= "1.0.6"
  83. open_packaging
  84. opine
  85. opium >= "0.14.0" & < "0.16.0"
  86. opium_kernel
  87. otr >= "0.3.1" & < "0.3.6"
  88. pa_ppx = "0.03" | >= "0.10"
  89. pgocaml >= "4.2"
  90. pgocaml_ppx >= "4.2" & < "4.3.0"
  91. planck >= "2.2.0"
  92. ppx_cstruct >= "4.0.0"
  93. ppx_log < "v0.15.0"
  94. ppx_meta_conv = "2.0.2" | = "2.5.0"
  95. ppx_protocol_conv >= "5.1.2"
  96. ppx_protocol_conv_json >= "3.1.0" & != "4.0.0"
  97. ppx_protocol_conv_jsonm != "4.0.0"
  98. ppx_protocol_conv_msgpack >= "3.1.0" & != "4.0.0"
  99. ppx_protocol_conv_xml_light >= "3.1.0" & != "4.0.0"
  100. ppx_protocol_conv_xmlm
  101. ppx_protocol_conv_yaml >= "3.1.0" & != "4.0.0"
  102. protocol-9p >= "0.6.0"
  103. protocol-9p-unix != "2.0.0"
  104. pyre-ast
  105. qcow
  106. qcow-format >= "0.3"
  107. qcow-tool
  108. rpc_parallel = "v0.14.0"
  109. sentry >= "v0.11.0"
  110. sexp = "v0.14.0"
  111. sexp_macro = "v0.14.0"
  112. sexp_pretty = "v0.14.0"
  113. shared-block-ring >= "2.3.0"
  114. sihl < "0.2.0" | >= "0.3.0~rc2"
  115. sihl-core
  116. spin
  117. ssh-agent < "0.4.0"
  118. sslconf
  119. syguslib-utils
  120. timedesc = "0.8.0"
  121. timedesc-sexp
  122. timmy
  123. tls >= "0.7.1" & < "0.17.0"
  124. tlstunnel >= "0.1.2"
  125. torch < "v0.16.0"
  126. um-abt >= "0.1.7"
  127. uri >= "1.9.2" & < "2.0.0"
  128. vchan >= "2.1.0" & < "6.0.2"
  129. vchan-unix < "6.0.2"
  130. vchan-xen < "6.0.2"
  131. vmnet >= "1.1.0"
  132. vscoq-language-server
  133. wamp = "1.0"
  134. websocket-lwt-unix >= "2.17"
  135. x509 >= "0.5.1" & < "0.7.0"
  136. xapi-backtrace < "0.7"
  137. yaml >= "0.2.0" & < "3.0.0"
  138. yaml-sexp
  139. yices2_bindings
  140. zanuda

Conflicts

None

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct