metaquot

OCaml syntax extension for quoting code
README

metaquot is a PPX rewriter that provides several extensions for
quoting OCaml code in expressions, à la ppxtools.ppx_metaquot
and ppxlib.metaquot. In comparison to these libraries, metaquot
is built by meta-programmation over the Parsetree module (thanks
to metapp) and is meant to be trivial to update for future
versions of OCaml (on the other hand, metaquot only builds AST for
the current version of OCaml: you may use helpers provided by
Ast_helper or Metapp to manipulate the AST in a
version-independent manner).

metaquot can be used with dune by using the preprocess field.

(executable
  ...
  (preprocess (pps metaquot.ppx))
  ...)

The following extensions are provided.

|Quotation |Type |
|--------------|--------------------------|
|[%expr ...] |Parsetree.expression |
|[%pat? ...] |Parsetree.pattern |
|[%type: ...]|Parsetree.core_type |
|[%sig: ...] |Parsetree.signature |
|[%sigi: ...]|Parsetree.signature_item|
|[%str ...] |Parsetree.structure |
|[%stri ...] |Parsetree.structure_item|
|[%lid ...] |Parsetree.longident |

The produced AST uses !Ast_helper.default_loc as location: you may
change the location with Ast_helper.with_default_loc.

Moreover, in quoted code, the following extensions allow to evaluate
and insert expressions or patterns (anti-quotations).

|Anti-quotation|Type |
|--------------|--------------------------------------------------------|
|[%e ...] |Parsetree.expression |
|[%p ...] |Parsetree.pattern |
|[%t ...] |Parsetree.core_type |
|[%m ...] |Parsetree.module_type or Parsetree.module_expr |
|[%i ...] |Parsetree.signature_item or Parsetree.structure_item|

To insert expressions or patterns to syntactic places where
anti-quotations are not supported, substitutions can be specified in attributes.
For instance:

  • [%str module M = struct ... end][@subst let M : string = s]
    defines a module, the name of which is given by an expression s of
    type string

  • [%str match x with c -> .][@subst let c : list = cases] constructs
    a pattern matching, the cases of which is given by an expression
    cases of type case list (note that the substitution is specified by
    giving only the type name list).

More generally, substitutions are given using let-binding syntax,
specifying the name of the substituted identifier, the name of the
type of the AST node to be replaced, and the expression or the pattern
to use for the substitution: when the identifier appears, the closest
parent AST node of the given type name is replaced by the given
expression or pattern. Currently, only binding variable names are
supported for patterns.
The [@subst] attribute can be carried either by the quotation extension
itself or by any subelement.

Inside quoted expressions, the [@for] attribute can be used to
repeat an element in an AST node of type _ list. For instance,
[%str type t1 and t2 and t3] can
be written
[%str type t [@@subst let t : string = name][@@for name := ["t1"; "t2"; "t3"]]].
The element is repeated in the closest parent AST node of type _ list.

In addition to the syntax extension, the metaquot package provides
the Metaquot module, which contains lifters: the Metaquot.Exp
module lifts to expressions and Metaquot.Pat lifts to patterns. For
instance, Metaquot.Exp.pattern : Parsetree.pattern -> Parsetree.expression is a function that returns an OCaml expression
that builds the AST corresponding to the given pattern.

Install
Published
21 Mar 2022
Sources
metaquot.0.5.1.tar.gz
sha512=96c864805f6d1a562780ea23b46eb8b886b9aba2214948824b7051c3e4058bf8170a5bca43c9c1b35c4b29bb347ccb2858c3ffe665e880ad276f6d0ec1bb2990
Dependencies
odoc
with-doc & >= "1.5.1"
metapp
>= "0.4.3" & < "0.4.4"
dune
>= "1.11.0"
ocamlfind
>= "1.8.1"
ppxlib
>= "0.22.0"
stdcompat
>= "12"
ocaml
>= "4.08.0"
Reverse Dependencies
clangml
>= "4.3.0"
override
>= "0.4.0"
pattern
>= "0.3.0"
ppx_pbt
< "0.2.1"
refl
>= "0.4.0"
traverse
>= "0.3.0"