[ANN] Preface (initial release)

Ecosystem
1

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ā€ .

About the project, and motivation

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.

Is Preface useful

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.

Additional links

The README is quite expansive on motivations and some design choices, but we have tried to add some concrete guides:

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

Conclusion

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).

Regards.

Xavier.

28 Likes
2

Very nice! Iā€™ll be interested to see how this develops.

1 Like
3

Hello, I stumbled upon your project by accident (spamming Google then getting back to some open tabs weeks later :upside_down_face:)

Iā€™m puzzled but your comment regarding the usefulness of the library, what do you mean exactly here?

I read your error handling guide here: https://github.com/xvw/preface/blob/master/guides/error_handling.md

And, to me, some of these abstractions look desirable and very useful.

2 Likes
4

First of all, thank you for your interest and your feedback.
Indeed, the words in the preamble are a little harsh. I think we chose them because, unlike Haskell, the OCaml community generally uses a fairly small set of abstractions (with a few exceptions).

After several years, even though the main contributors to Preface (including myself) use it on (somewhat marginal) projects, there is only one really ambitious project using it: YOCaml (whose use is documented in this blog article). But the very reason for its existence was to improve the ergonomics of Preface (by using it in a real project).

Weā€™re currently working on other projects, but our medium-term goal is to provide an alternative to the standard library (yet another one!) using the abstractions proposed by Preface and really separating the library for ā€˜building abstractionsā€™ (specs + make) and the implementation of these abstractions (We have already started to integrate indexed abstractions into this PR).

We hope to publish the new version here soon, with a small standard library that is more usable than the current one. Thanks again for your interest, and donā€™t hesitate to point out anything I can clarify.

2 Likes
5

Great, Iā€™ll be on the look out then :slight_smile:

I havenā€™t dug into the alternative standard libraries yet, sounds appealing though!

Iā€™m quite interested in learning more functional idioms so itā€™d be great if I could explore those within the bounds of OCaml.

Haskell does interest me too, but I think OCaml hits a sweet spot for me.

1 Like