Initial commit.

1 files changed, 56 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..93f5a40
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# de Paul records
+
+Software freedom empowers sharing.  Let's dedicate our libre software projects
+to saints known for fostering sharing!
+
+This Guile records library is dedicated to St. Vincent de Paul, a french priest
+from 17th century who served the poor.  Being a great organizer, he managed to
+encourage even high-rank nobles to participate in charity work.  Apparently, he
+had more success than we have with encouraging state authorities to start caring
+about digital freedom…
+
+## Why another records API?
+
+GNU Guile implements SRFI-9 which already provides a records API.  Guile also
+includes a GNU extension in `(srfi srfi-9 gnu)` which provides an API for purely
+functional records.
+
+What these APIs lack is a nice syntax for record construction.  The constructor
+procedures they generate do — at the time of writing — only accept positional
+arguments which makes their use error-prone.  A solution would be to — for every
+record type defined — define one "null" record object and then construct
+subsequent records of this type by cloning and modifying that null record.
+
+This library builds upon @code{(srfi srfi-9 gnu)} to aid with this and also with
+other tasks.  Features include
+
+- automatic deriving of getter names from field names,
+- automatic generation of record constructor macros,
+- support for default field values,
+- support for programmer-supplied record finalizer procedures,
+- syntax for creation of a record object based on an existing one,
+- optional automatic export of generated getters and other variables,
+- and amended variants of `(ice-9 match)` forms with (unhygienic) record
+  matcher that allows fields to be matched **by name**.
+
+This library is inspired by the Guix records API but follows purely functional
+approach.
+
+## Use examples
+
+Please look into the test suite in `tests/guile/`.
+
+## Building & installation
+
+This software has a Guix package definition in Wojtek's [personal
+channel](https://git.koszko.org/guix/about).  That can serve you as a point of
+reference.
+
+## Copying
+
+The source code of this package is available under CC0 v1.0.  The repository is
+kept compliant with the [REUSE](https://reuse.software/) specification, version
+3.0.
+
+Note that the uderlying GNU Guile language is covered by the GNU GPL and hence
+any binary redistribution of *de Paul records* shall be covered by it as well.