README.adoc

S-Expressions parser and generator library in C++ (SEXP in C++)

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:

• It aims to be reusable in C++ implementations and is importable via CMake.

• It includes a test suite for correctness testing and tests against malformed S-Expressions.

• It supports, and is tested against, all major platforms, including:

  • Ubuntu, Debian, Fedora, CentOS, NixOS

  • macOS

  • Windows

  • msys

• It implements additional interface to work with S-Expressions wrapped by GnuPG 2.3+ extended format (specification).

The original C library was available at (but no longer accessible):

• http://people.csail.mit.edu/rivest/sexp.html

Background

S-Expressions are a data structure for representing complex data as a variation on LISP S-Expressions.

S-Expressions were originally adopted for use in SDSI and SPKI.

SDSI has been developed by Prof. Ronald L. Rivest and Prof. Butler Lampson of MIT’s Laboratory for Computer Science, members of 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 Carl Ellison and others in the IETF SPKI working group.

S-Expressions specification

• https://datatracker.ietf.org/doc/draft-rivest-sexp/

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

$ mkdir build
$ cd build
$ cmake ..
$ cmake --build .
$ ctest
$ cmake --install .

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

Table 1. sexpp switches

Switch	Description	Default
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
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
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:

$ sexpp -p -a -b -c -x

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.