ocaml-trace/ppxlib/quick_intro.html

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>quick_intro (ppxlib.quick_intro)</title><meta charset="utf-8"/><link rel="stylesheet" href="../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="../index.html">Index</a> &#x00BB; <a href="index.html">ppxlib</a> &#x00BB; quick_intro</nav><header class="odoc-preamble"><p> <div style="display: flex; justify-content:space-between"><div> </div><div><a href="driver.html" title="driver">The Driver &gt;</a> </div></div></p><h1 id="introduction"><a href="#introduction" class="anchor"></a>Introduction</h1><p>This guide is intended at authors or future authors of PPX rewriters. If you don't know what a PPX is, or if you are looking for a guide intended at PPX users, read the <a href="https://ocaml.org/docs/metaprogramming">OCaml official guide on meta-programming</a> first, although the beginning of this guide may be of interest to everyone.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#preprocessing-in-ocaml">Preprocessing in OCaml</a></li><li><a href="#ppxlib"><code>ppxlib</code></a></li><li><a href="#this-guide">This Guide</a></li><li><a href="#ppxs-and-ppxlib-history">PPXs and <code>ppxlib</code> History</a></li></ul></nav></div><div class="odoc-content"><h2 id="preprocessing-in-ocaml"><a href="#preprocessing-in-ocaml" class="anchor"></a>Preprocessing in OCaml</h2><p>OCaml doesn't have a macro system, that is, there is no official part of the OCaml language that will be executed at compile time in order to generate or alter the source code. However, OCaml does have an official part of its syntax dedicated to this: <a href="https://ocaml.org/manual/extensionnodes.html">extension nodes</a> and <a href="https://ocaml.org/manual/attributes.html">attributes</a>; both of them introduced in OCaml 4.02. The preprocessing itself, though, is left to external programs, written by the community and specialised for their own tasks. However, without a unification framework, the following issues arise:</p><ul><li>Ambiguity when using several preprocessors due to lacking clear composition semantics</li><li>Duplication of code and efforts on the different preprocessors</li><li>Performance loss with many phases (parsing, pretty-printing, etc.) being executed multiple times</li><li>Lack of cross-compiler compatibility</li><li>Incompatibility among the different preprocessor rather than one homogeneous preprocessor ecosystem</li></ul><h2 id="ppxlib"><a href="#ppxlib" class="anchor"></a><code>ppxlib</code></h2><p>The goal of <code>ppxlib</code> is to solve these problems, by providing a unifying framework for writing preprocessors. It sits in between the OCaml compiler and toolchain, and the PPX authors provide an API for them. One could sum up the <code>ppxlib</code> features as:</p><ul><li>It deals with all boilerplate, such as parsing the input, outputting the rewritten output, generating an executable, etc.</li><li>It generates a single executable for multiple transformations and defines clear composition semantics for local transformations</li><li>It integrates well with Dune and Merlin</li><li>It provides a more stable API than the compiler for manipulating the AST</li><li>A single PPX codebase usually works on several OCaml versions of the AST</li><li>It defines restricted rewriters whose semantic ensure better confidence for the user and better compositional semantics</li><li>It provides many helpers to pattern-match and generate AST nodes, as well as traverse the AST.</li></ul><h2 id="this-guide"><a href="#this-guide" class="anchor"></a>This Guide</h2><p>This guide is separated into several parts.</p><p>First, we focus on the <a href="driver.html" title="driver">driver</a> that performs the AST transformations: how it is generated, executed, and more importantly, what it does exactly, from migrating the AST to the different rewriting phases it goes through.</p><p>After that, we explain <a href="writing-ppxs.html" title="writing-ppxs">the different kinds</a> of transformations that <code>ppxlib</code> supports, and how to register them to the driver. This section only describes the transformations and their properties, not how to actually manipulate the AST.</p><p>The part where we discuss how to manipulate the AST is split in three pages: <a href="generating-code.html" title="generating-code">generating AST nodes</a> to generate OCaml code, <a href="matching-code.html" title="matching-code">destructing AST nodes</a> to extract information and act differently depending on what is extracted, and <a href="ast-traversal.html" title="ast-traversal">traversing the AST</a> to use <code>fold</code>, <code>iter</code>, and <code>map</code> on the AST. This code-manipulation part explains using the modules <a href="Ppxlib/Ast_builder/index.html" title="Ppxlib.Ast_builder"><code>Ast_builder</code></a>, <a href="Ppxlib/Ast_pattern/index.html" title="Ppxlib.Ast_pattern"><code>Ast_pattern</code></a>, and the <code>ppxlib</code>'s PPX <a href="Ppxlib_metaquot/index.html" title="Ppxlib_metaquot"><code>Metaquot</code></a>.</p><p>We finally discuss several <a href="good-practices.html" title="good-practices">good practices</a>, such as how to properly report errors, how to test your PPX, or how to migrate from other PPX libraries, such as <code>OMP</code> and <code>ppx_deriving</code>.</p><p>We end by including some <a href="examples.html" title="examples">examples</a>, which you can also find in the <code>examples</code> <a href="https://github.com/ocaml-ppx/ppxlib/tree/main/examples">folder</a> of <code>ppxlib</code>'s repository.</p><h2 id="ppxs-and-ppxlib-history"><a href="#ppxs-and-ppxlib-history" class="anchor"></a>PPXs and <code>ppxlib</code> History</h2><p>The preprocessing history of OCaml started long before <code>ppxlib</code>. However, this section is not yet written. You can find more information in these resources: <a href="https://lists.ocaml.org/pipermail/wg-camlp4/2013-January/000000.html">1</a> <a href="https://caml.inria.fr/pub/docs/manual-camlp4/manual002.html">2</a> <a href="https://camlp5.github.io/">3</a> <a href="https://discuss.ocaml.org/t/an-update-on-the-state-of-the-ppx-ecosystem-and-ppxlib-s-transition/8200">5</a>. You can also contribute to the <code>ppxlib</code> documentation by opening a pull request in the <a href="https://github.com/ocaml-ppx/ppxlib/">repository</a>.</p><p> <div style="display: flex; justify-content:space-between"><div> </div><div><a href="driver.html" title="driver">The Driver &gt;</a> </div></div></p></div></body></html>
		`<!DOCTYPE html>`
		<html xmlns="http://www.w3.org/1999/xhtml"><head><title>quick_intro (ppxlib.quick_intro)</title><meta charset="utf-8"/><link rel="stylesheet" href="../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="../index.html">Index</a> » <a href="index.html">ppxlib</a> » quick_intro</nav><header class="odoc-preamble"><p> <div style="display: flex; justify-content:space-between"><div> </div><div><a href="driver.html" title="driver">The Driver ></a> </div></div></p><h1 id="introduction"><a href="#introduction" class="anchor"></a>Introduction</h1><p>This guide is intended at authors or future authors of PPX rewriters. If you don't know what a PPX is, or if you are looking for a guide intended at PPX users, read the <a href="https://ocaml.org/docs/metaprogramming">OCaml official guide on meta-programming</a> first, although the beginning of this guide may be of interest to everyone.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#preprocessing-in-ocaml">Preprocessing in OCaml</a></li><li><a href="#ppxlib"><code>ppxlib</code></a></li><li><a href="#this-guide">This Guide</a></li><li><a href="#ppxs-and-ppxlib-history">PPXs and <code>ppxlib</code> History</a></li></ul></nav></div><div class="odoc-content"><h2 id="preprocessing-in-ocaml"><a href="#preprocessing-in-ocaml" class="anchor"></a>Preprocessing in OCaml</h2><p>OCaml doesn't have a macro system, that is, there is no official part of the OCaml language that will be executed at compile time in order to generate or alter the source code. However, OCaml does have an official part of its syntax dedicated to this: <a href="https://ocaml.org/manual/extensionnodes.html">extension nodes</a> and <a href="https://ocaml.org/manual/attributes.html">attributes</a>; both of them introduced in OCaml 4.02. The preprocessing itself, though, is left to external programs, written by the community and specialised for their own tasks. However, without a unification framework, the following issues arise:</p><ul><li>Ambiguity when using several preprocessors due to lacking clear composition semantics</li><li>Duplication of code and efforts on the different preprocessors</li><li>Performance loss with many phases (parsing, pretty-printing, etc.) being executed multiple times</li><li>Lack of cross-compiler compatibility</li><li>Incompatibility among the different preprocessor rather than one homogeneous preprocessor ecosystem</li></ul><h2 id="ppxlib"><a href="#ppxlib" class="anchor"></a><code>ppxlib</code></h2><p>The goal of <code>ppxlib</code> is to solve these problems, by providing a unifying framework for writing preprocessors. It sits in between the OCaml compiler and toolchain, and the PPX authors provide an API for them. One could sum up the <code>ppxlib</code> features as:</p><ul><li>It deals with all boilerplate, such as parsing the input, outputting the rewritten output, generating an executable, etc.</li><li>It generates a single executable for multiple transformations and defines clear composition semantics for local transformations</li><li>It integrates well with Dune and Merlin</li><li>It provides a more stable API than the compiler for manipulating the AST</li><li>A single PPX codebase usually works on several OCaml versions of the AST</li><li>It defines restricted rewriters whose semantic ensure better confidence for the user and better compositional semantics</li><li>It provides many helpers to pattern-match and generate AST nodes, as well as traverse the AST.</li></ul><h2 id="this-guide"><a href="#this-guide" class="anchor"></a>This Guide</h2><p>This guide is separated into several parts.</p><p>First, we focus on the <a href="driver.html" title="driver">driver</a> that performs the AST transformations: how it is generated, executed, and more importantly, what it does exactly, from migrating the AST to the different rewriting phases it goes through.</p><p>After that, we explain <a href="writing-ppxs.html" title="writing-ppxs">the different kinds</a> of transformations that <code>ppxlib</code> supports, and how to register them to the driver. This section only describes the transformations and their properties, not how to actually manipulate the AST.</p><p>The part where we discuss how to manipulate the AST is split in three pages: <a href="generating-code.html" title="generating-code">generating AST nodes</a> to generate OCaml code, <a href="matching-code.html" title="matching-code">destructing AST nodes</a> to extract information and act differently depending on what is extracted, and <a href="ast-traversal.html" title="ast-traversal">traversing the AST</a> to use <code>fold</code>, <code>iter</code>, and <code>map</code> on the AST. This code-manipulation part explains using the modules <a href="Ppxlib/Ast_builder/index.html" title="Ppxlib.Ast_builder"><code>Ast_builder</code></a>, <a href="Ppxlib/Ast_pattern/index.html" title="Ppxlib.Ast_pattern"><code>Ast_pattern</code></a>, and the <code>ppxlib</code>'s PPX <a href="Ppxlib_metaquot/index.html" title="Ppxlib_metaquot"><code>Metaquot</code></a>.</p><p>We finally discuss several <a href="good-practices.html" title="good-practices">good practices</a>, such as how to properly report errors, how to test your PPX, or how to migrate from other PPX libraries, such as <code>OMP</code> and <code>ppx_deriving</code>.</p><p>We end by including some <a href="examples.html" title="examples">examples</a>, which you can also find in the <code>examples</code> <a href="https://github.com/ocaml-ppx/ppxlib/tree/main/examples">folder</a> of <code>ppxlib</code>'s repository.</p><h2 id="ppxs-and-ppxlib-history"><a href="#ppxs-and-ppxlib-history" class="anchor"></a>PPXs and <code>ppxlib</code> History</h2><p>The preprocessing history of OCaml started long before <code>ppxlib</code>. However, this section is not yet written. You can find more information in these resources: <a href="https://lists.ocaml.org/pipermail/wg-camlp4/2013-January/000000.html">1</a> <a href="https://caml.inria.fr/pub/docs/manual-camlp4/manual002.html">2</a> <a href="https://camlp5.github.io/">3</a> <a href="https://discuss.ocaml.org/t/an-update-on-the-state-of-the-ppx-ecosystem-and-ppxlib-s-transition/8200">5</a>. You can also contribute to the <code>ppxlib</code> documentation by opening a pull request in the <a href="https://github.com/ocaml-ppx/ppxlib/">repository</a>.</p><p> <div style="display: flex; justify-content:space-between"><div> </div><div><a href="driver.html" title="driver">The Driver ></a> </div></div></p></div></body></html>