$ show ocaml-ppx/ppxlib
ppxlib is the standard library for writing PPX rewriters in OCaml—compile-time preprocessors that transform the OCaml abstract syntax tree (AST). It provides a unified framework for defining extension points (`[%...]`), deriving generators (`[@@deriving ...]`), context‑free rewrite rules, and global transformations. The library abstracts over multiple OCaml compiler versions (4.08 through 5.06) via its own frozen AST definitions and bidirectional migration modules, insulating PPX authors from version-specific parsetree changes. The core architecture consists of a driver that orchestrates transformation phases (lint, preprocess, instrument, context‑free, global, last instrument) and can be compiled into standalone executables or used as a Dune build plugin. The codebase is actively maintained with extensive documentation, benchmark infrastructure (including a vendored ppx_sexp_conv for comparison), and a comprehensive test suite covering error embedding, code path tracking, and AST round‑tripping. Despite the complexity of cross‑version AST support, the internal APIs are cleanly separated into reusable components such as typed attribute handlers, composable deriving arguments, and a GADT‑based DSL for context‑free rules.
The LLM identified 4 files worth highlighting for reuse:
Provides a typed, hygienic API for declaring and manipulating attributes on AST nodes. Uses a GADT-based context system (`Context.t`) to statically enforce which attribute classes are valid on which AST constructors, and supports scoped reservation of namespaces to prevent false positives. The `check_unused` mechanism tracks attribute consumption across traversals. This module is self-contained and could be extracted to any OCaml metaprogramming project needing safe attribute handling.
Implements a type‑safe DSL for context‑free AST rewrite rules. The `Rule` type uses existential wrapping over a GADT field to encode different rule kinds (extension, special function, constant, attribute replacement, etc.) while ensuring that each rule’s payload matches the expected AST node type. The `map_nodes` function applies these rules in a single top‑down pass. This pattern enables extensible, composable, and declarative rewriting without exposing traversal logic—ideal for any OCaml AST‑manipulation library.
Offers a combinator library for destructing (matching) AST nodes in a type‑safe way. Primitives like `__` (match‑any) and combinators like `drop`, `map`, `alt`, and `single_expr_payload` allow concise and expressive pattern matching over the OCaml parsetree. This module is a core utility for PPX authors and demonstrates a non‑trivial embedding of pattern matching logic into OCaml values that could be reused in any project needing typed structural matching over recursive data types.
Contains the `Non_intersecting_ranges` type—a data structure for maintaining a set of non‑overlapping integer ranges with operations `insert`, `union`, and `covered_by`. It is used to enforce the invariant that generated AST nodes have proper location nesting and do not overlap. The implementation is compact and efficient, and it solves a general problem (tracking disjoint intervals) that recurs in many code generation and static analysis contexts. The `enforce_invariants` class demonstrates a custom traversal that injects this invariant check into the standard `Ast_traverse` fold.