Is there a ppxlib template repository somewhere? Should there be?

[Gopiandcode]

@pitag

Were you referring to the PPX’s dune file?

The dune file configuration for ppxs is actually pretty straighforward - I just need to add an extra option to my stanzas and then I’m writing ppxs - this works really well.

@pitag

Or were you referring to getting your head around and manipulating the AST? Or to making sure that your PPX is trustable and doesn’t tinker with the rest of the program (keywords error handling and hygiene).

Manipulating syntax does require a little concentration to make sure you’re doing the right thing, but that’s more intrinsic to the domain of metaprogramming. My main pain points with ppxlib relate more to the bureaucracy.

@pitag

Or to registering the PPX (so e.g. in the case of a deriver calling Deriving.Generator.V2.make_noarg and then Deriving.add)?

Yes, this is exactly the problem - I’m not sure if this is a very constructive critisism, but in my experience, I’ve found that the API for ppxlib isn’t very “discoverable”:

• one way this occurs is in the arcane sequence of incantations required to setup a ppx (some sequence of rules, rewrites, etc.)[1]
• another way this arises is in the large number of modules possible to be opened at any time - it’s easy to fall into a rabbit hole of exploring the APIs modules that are completely irrelevant to most cases of writing a ppx.

For the second case, I understand that these modules are really necessary for supporting all the usecases of ppx, but sometimes as a beginner, I don’t want to have to see all of them.

I think one thing that might help is defining a module that re-exports a subset of the core modules of ppxlib that a beginner should use, and then tell beginners to primarily only use modules exported in this simplified module. (i.e only use modules under Ppxlib.Beginner.*). This would work hand in hand with merlin and make it much easier to discover the api, as autocompleting Ppxlib.Beginner.* would quickly give me a list of modules that I should be using).

@pitag

@panglesd has recently done and is currently doing an amazing job at improving the ppxlib documentation on different levels! For example, see the manual @sabine has linked to above. I recommend having a look at it, it’s really good work (and he’s even still improving things and making them more complete)!

The improvements to the ppxlib documentation are much appreciated! The documentation is so much easier to understand now since when I first looked at it a few years back. Major kudos to the people who have worked on it!

[1] As a side note - one thing that I consistently leaves me scratching my head, even though I’ve found the answer myself several times before, is the ~name parameter - when setting up a ppx, there are several points at which you need to supply a name. Some of these parameters are actually relevant to the usage of the ppx (such as defining the [%<name ...] forms that will run the ppx), but some others are just for debugging. Every time I write a ppx, I spend a bit of time trying to recall which ones are which.