For context (skip to question if you like): I am learning ocaml and started reading the Real World Ocaml.
So far, really (really!) liking the language and the book.
One thing I'm starting to not like so much is this mysterious 'ppx' stuff that is starting to show up everywhere I look when I try to 'dig a little deeper'(typically this digging involves opening some source code of a dependency and then and stumbling onto some 'magic' things like [@@deriving sexp]).
From lots of googling / various scattered sources... this seems to be some kind of syntax extension mechanism based on AST transformations. It seems to be heavily used (at least in janestreet libs). Near I can tell this is an 'unofficial' or undocumented feature of Ocaml. For example, looking at the Ocaml manual I couldn't find any trace of it.
Now, the question. How official/supported is the ppx mechanism for extending ocaml with new syntax by means of AST transforms?
EDIT/note: It was pointed out in the answer by @octachron that there is in fact a 'trace' of the feature in the manual that I missed. The syntax for these [@@..] bits at least is documented in the manual / ocaml grammar.
But the answer i.m.o really should address two things: syntax and semantics.
- syntax is about "how do we write these magic new things".
- semantics is about how do we attach meaning to them.
A partial answer was already given by @octachron. It is clear now that the 'syntax' is official. But it is still a bit unclear to me how 'official' the support is for attaching semantics to these syntax extensions. So I am holding out for accepting an answer that is a bit more complete/explicit about semantics).
PS: Near as I can tell, there is nothing in the manual about this, and the Ocaml compiler ostensibly does nothing with the annotations at all (except, I suppose, parsing them). So unless I missed something else in the manual, then there isn't an 'official' mechanism in the language that lets you access the data in these annotations and do anything meaningful with them. Is that correct?
There are two parts to this question:
The first is syntax. That part was answered very well already by @octachron. The syntax for these
[@@..]bits are an official part of Ocaml syntax. They are described in the manual at https://ocaml.org/manual/attributes.html and https://ocaml.org/manual/extensionnodes.html.The second part is semantics. The answer here is more complex.
Note: Octachron already gave some answer here. However, the answer to me was a bit confusing. So I'll try and write an more detailed answer here myself that tries to address that confusion directly.
The tricky part (for me at least) to understand here was that, what you might call 'official support', depends a bit on your expectations, or point of view.
Looking at it from the point of view of the compiler and Ocaml as a programming language... The attributes and annotations have no meaning whatsoever. To the Ocaml compiler they are essentially treated much like comments. They are simply recognised by the parser and completely ignored.
So if the question is... "does the Ocaml language/compiler define an official way to attach semantics to extensionnodes and annotations?"; then the answer is "no". To the compiler... they simply have no semantics.
Any meaning comes from a 'ppx' pre-processor. A ppx pre-processor is a separate Ocaml program that reads in Ocaml source code and parses it into an AST, then transforms the AST. This process is totally separate from the Ocaml compiler and is a true pre-processor.
There is however an official/standard/recommended way that such pre-processors are created and used.
In a nutshell:
These things are explained in great detail in the 'official' ppxlib User manual.