Adding upstream version 0.8.7.upstream/0.8.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.