comm-central/third_party/rnp/src/libsexpp/README.adoc

Revision control

Copy as Markdown

Other Tools

= 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 reuseable 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
** macOS
** Windows
** msys
* It implements additional interface to work with S-Expressions wrapped by GnuPG
2.3+ extended format
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
S-Expressions were originally adopted for use in
SDSI has been developed by Prof.
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
== Code
The library is a deep rework to C++ of the original
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
[source,sh]
----
$ 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
.`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.
[source]
----
$ 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:
[source,sh]
----
$ 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:
[source,sh]
----
$ 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:
[source,sh]
----
$ sexpp -p -a -b -c -x
----
or just
[source,sh]
----
$ 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.