diff options
Diffstat (limited to 'README.adoc')
| -rw-r--r-- | README.adoc | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..765685c --- /dev/null +++ b/README.adoc @@ -0,0 +1,230 @@ += 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: + +* 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 + (https://github.com/gpg/gnupg/blob/master/agent/keyformat.txt[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 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 + +* 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 +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 + +[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. |