May 2018 DocJam: A Guide to PPX Extensions

Community
1

I’ve started writing a guide to the PPX ecosystem here:

It’s very, very rough and preliminary right now but I’d like to have it somewhat presentable by the end of the DocJam. Please feel free to suggest edits and additional text — you can even do a pull request or edit the document directly if you have commit rights to OCamlverse.

Note that I’m very weak in my understanding of PPXes, so actual text is preferred over suggested topics and the like — I’ll probably agree that the topic is good but not know what to say! If you suggest actual text, even if it is rough, I can always improve it.

2

Could you remove the suggestion to use {foo| ... |foo} syntax for extensions in the “Syntactic hooks for PPX extensions” section. Those are explicitly discouraged and people should use [%foo {| ... |}] instead.

3

I’m certain you know this, but the purpose of {foo|string|foo} is different than that, and it isn’t discouraged. It allows you to quote the sequence |} cleanly by picking a string foo that never appears before |} inside the string itself.

What is discouraged is using {foo|string|foo} instead of [%foo {|string|}], the foo should never be used to signal that a particular extension is supposed to be reading something, but it’s perfectly fine to use it to help with quoting!

Anyway, yes, it is my intention to add such language to the PPX guide, probably taken from the OCaml manual which already does a pretty good job of explaining this.

4

BTW, @lpw25, if you have substantive text to help me add to the document, especially for the section on writing extensions, that would be greatly appreciated!

5

Thanks for having started this guide, and sorry for chiming in so much time later! Before suggesting or submitting changes, I have questions and links to share.

Regarding the last section “Writing PPXs”, what about focusing on one particular stack, maybe with briefly mentioning others ? I think of Ppxlib with Dune. The following blog posts deal with writing PPXs:

Regarding the section “How PPXs are used”, I think about mentioning usage of several stacks like Ppx_deriving and Ppx_type_conv, and how to use them together in case it’s possible and needed.

6

I would love a Ppxlib tutorial. I just got finished making my very first ppx, and it was very hard for me due to the lack of docs.

7

Do you think you might be interested in helping to write some material to fill out the one I started? Given that you just wrote one much of what is needed is probably fresh in your mind.

8

I could put something together, but the issue is that I honestly can’t explain what I made that well. I’m missing a lot of foundational knowledge, and what I do know I scrounged from one blog post + reading .mli files. It’d kinda be like “you do this because…it works”, “I have no idea what %e means, but you need it”, etc.

9

Start with what you know even if it isn’t that good. That’s fine. We’ll add it to the existing document (you can do a pull request) and we’ll iteratively make it better. I have the same interest that you do, and the same dependence on cargo cult knowledge. Hopefully with a few iterations and a few of the more experienced OCamlers telling us we have it wrong, we may get to the point where it’s actually useful documentation. I may do a project purely to try to learn enough to help finish writing the document.