= S-Expressions parser and generator library in C++ (SEXP in C++)
image:https://github.com/rnpgp/sexp/workflows/build-and-test/badge.svg["Build status Ubuntu/macOS/Windows", link="https://github.com/rnpgp/sexp/actions?workflow=build-and-test"] image:https://github.com/rnpgp/sexp/workflows/build-and-test-rh/badge.svg["Build status CentOS/Fedora", link="https://github.com/rnpgp/sexp/actions?workflow=build-and-test-rh"] image:https://github.com/rnpgp/sexp/workflows/build-and-test-deb/badge.svg["Build status Debian", link="https://github.com/rnpgp/sexp/actions?workflow=build-and-test-deb"] image:https://github.com/rnpgp/sexp/workflows/build-and-test-msys/badge.svg["Build status MSys", link="https://github.com/rnpgp/sexp/actions?workflow=build-and-test-msys"]
image:https://codecov.io/gh/rnpgp/sexpp/branch/main/graph/badge.svg["Code coverage", link="https://codecov.io/gh/rnpgp/sexpp"] image:https://github.com/rnpgp/sexpp/workflows/CodeQL/badge.svg["CodeQL analysis", link="https://github.com/rnpgp/sexpp/actions?workflow=CodeQL"] image:https://scan.coverity.com/projects/28717/badge.svg["Coverity Scan Build Status", link="https://scan.coverity.com/projects/rnpgp-sexpp"]
== Purpose
This is a C++ library for working with S-Expressions.
This implementation is derived from the reference SEXP C library developed by Prof. Ronald Rivest and Prof. Butler Lampson of MIT LCS (now CSAIL).
This library differs from the original C implementation in the following ways:
The original C library was available at (but no longer accessible):
== Background
S-Expressions are a data structure for representing complex data as a variation on https://en.wikipedia.org/wiki/Lisp_(programming_language)[LISP] S-Expressions.
S-Expressions were originally adopted for use in http://theory.lcs.mit.edu/~cis/sdsi.html[SDSI] and http://world.std.com/~cme/html/spki.html[SPKI].
SDSI has been developed by Prof. https://people.csail.mit.edu/rivest/index.html[Ronald L. Rivest] and Prof. Butler Lampson of http://www.lcs.mit.edu/[MIT's Laboratory for Computer Science], members of http://theory.lcs.mit.edu/~cis[LCS's Cryptography and Information Security] research group.
NOTE: SDSI research has been supported by DARPA contract DABT63-96-C-0018, "Security for Distributed Computer Systems".
NOTE: SPKI has been developed by http://www.clark.net/pub/cme/home.html[Carl Ellison] and others in the IETF SPKI working group.
== S-Expressions specification
NOTE: The "SEXP 1.0 guide" used to be at https://people.csail.mit.edu/rivest/Sexp.txt.
== Code
The library is a deep rework to C++ of the original https://people.csail.mit.edu/rivest/sexp.html[SEXP library] that maintains full support of original specification.
While most applications will not need anything but the simple canonical and transport formats; however, the code here is considerably more complex because it also supports the advanced format, both for input and for output.
== Building and installation
== CMake script options
BUILD_SHARED_LIBS:BOOL::
(default: OFF)
build shared library
WITH_SEXP_TESTS:BOOL::
(default: ON)
build tests
DOWNLOAD_GTEST::
(default: ON)
if tests are built, automatically download googletest from GitHub;
when set to OFF, the googletest binary package needs to be available for SEXP
tests.
WITH_SEXP_CLI:BOOL::
(default: ON) build the sexp command-line utility
WITH_SANITIZERS:BOOL::
(default: OFF)
build with address and other sanitizers (requires clang compiler)
== SEXPP command-line utility
The sexpp command-line utility is reference parser and generator of
S-Expressions. It can read, parse and print out SEXP in all defined formats.
=== Switches
.sexpp switches
[options="header"]
|===
| Switch | Description | Default
3+| Input
| -i <filename> | input file name | read input from console (stdin)
| -p | prompt input if reading from console | disabled
| -s | treat input as a single SEXP string | disabled, input is treated as an S-Expression
3+| Output
| -o <filename> | output file name: | write output to console (stdout)
| -a | generate advanced transport format | enabled if no format is specified
| -b | generate base-64 transport format | disabled
| -c | generate canonical format | disabled
| -l | suppress linefeeds after output | disabled
| -w <width> | set output line width (0 implies no constraint)| 75
3+| Miscellaneous
| -x | execute repeatedly until EOF | process single S-Expression then exit
| -h | print help message and exit |
|===
Running without switches implies: -p -a -b -c -x.
=== Usage examples
Prompt for S-Expressions input from console, parse and output it to
certificate.dat in base64 transport format.
$ sexpp -o certificate.dat -p -b
Input: (aa bb (cc dd))
Writing base64 (of canonical) output to 'certificate.dat'
Parse all S-Expressions from certificate.dat, output them to console in
advanced transport format with no prompts:
$ sexpp -i certificate.dat -x
(2:aa2:bb(2:cc2:dd))
Parse S-Expressions from certificate.dat, output it to console in canonical,
base64 and advanced format with prompts and no width limitation:
$ sexpp -i certificate.dat -a -b -c -p -w 0
Reading input from certificate.dat
Canonical output: (2:aa2:bb(2:cc2:dd)) Base64 (of canonical) output: {KDI6YWEyOmJiKDI6Y2MyOmRkKSk=} Advanced transport output: (aa bb (cc dd))
Repeatedly prompt for S-Expressions input from console, parse and output it console in advanced, base64 and canonical formats:
or just
$ sexpp
Input: (abc def (ghi jkl))
Canonical output: (3:abc3:def(3:ghi3:jkl)) Base64 (of canonical) output: {KDM6YWJjMzpkZWYoMzpnaGkzOmprbCkp} Advanced transport output: (abc def (ghi jkl))
Input: ^C
== License
Copyright Ribose.
The code is made available as open-source software under the MIT License.