Hello, @d-plaindoux and @pytre and I are very happy to present Preface, a project that has occupied part of our free time for almost 2 years. We received a lot of help from various people (as mentioned in the CREDITS page), including some present on this forum (@gasche, @octachron and @snowleopard)
Preface is an opinionated library designed to facilitate the handling of recurring functional programming idioms in OCaml. Many of the design decisions were made in an attempt to calibrate, as best as possible, to the OCaml language. Trying to get the most out of the module language. The name “preface” is a nod to “Prelude” .
When learning functional programming, one is often confronted with constructs derived (or not) from category theory. Languages such as Haskell offer very complete libraries to use them, and thus, facilitate their learning. In OCaml, it often happens that these abstractions are buried in the heart of certain libraries/projects (Lwt, Cmdliner, Bonsai, Dune etc.). This is why one of the objectives of Preface is to propose tools for concretising these abstractions, at least as a pedagogical tool.
Since OCaml allows for efficient imperative programming, Preface is probably not really useful for building software. However, we (the maintainers) think that Preface can be useful for a few things:
- technical experimentation with abstractions (especially those from the Haskell world) that allow programming in a fun style.
- As an educational tool. Many teaching aids generally only offer the minimal interfaces to these abstractions. Preface tries to be as complete as possible.
- It was a lot of fun to make. The last point is obviously the lightest but building Preface was really fun! So even if some people won’t see the point… we had fun making it!
Let’s imagine this scenario! Oh, there’s this article that seems to describe quite precisely how to solve
this complex problem, elegantly, using this
collection of abstractions. After reading, the article is clear and I know how to use this
collection of abstractions in practice. I would like to test it. Not having enough RAM to install Cabal, I decided to do it in OCaml. But as one abstraction leads to another, I am obliged to build an armada of things and I abandon my experimentation.
So now, rather than doing it, locally, for the understanding of an article, I add it in Preface.
The README is quite expansive on motivations and some design choices, but we have tried to add some concrete guides:
- Understanding the module breakdown of Preface
- Effect handling using Freer
- Error handling with Result/Validation and a Free Applicative
And in addition here is a project, by a friend of ours, that uses Preface, to build static blog generators (very original isn’t it :P), the code is highly documented and can be an entry point into how to use it: Github repository of the project, which is called Wordpress
Preface does not offer much that is new, but we have tried to make it user-friendly and to document as much as possible the code and design choices. It’s a lot of fun to build… and it will probably be just as much fun to maintain.
We are extremely open to contributions and feedback.
And my last words will be a warm thank you to the OCaml ecosystem that has facilitated so much of our development: Testing with Alcotest and QCheck is a pleasure. Dune is a fast and pleasant build system. ODoc has allowed us to have more control over the generation of documentation, especially with the
@inline comment (on includes) which allows signatures from different modules to be merged. And MDX which I did not know at all and which is used extensively for guides.
I hope you can find interest in this project! Good luck with the rest of the containment (for those concerned).