package sexplib

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

Install

Dune Dependency

Authors

Maintainers

Sources

v0.9.2.tar.gz
md5=7d70f28d235a0ce28a57a5a2bf856326

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: 27 Jul 2017

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

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 [[http://www.ocaml.org/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 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.

Dependencies (3)

  1. num
  2. jbuilder >= "1.0+beta10"
  3. ocaml >= "4.03.0" & < "4.06.0"

Dev Dependencies

None

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

Conflicts (1)

  1. sexplib0