A much nicer REPL experience

The biggest chunk of work went into the REPL (toplevel) integration. I’m well aware that the OCaml toplevel isn’t terribly popular with seasoned OCaml developers — most of them reach for a proper build and a debugger instead. But I think newcomers get a lot of mileage out of a REPL, and (no surprise to anyone who’s followed my work) I’m a Lisper at heart with a real soft spot for interactive development. Clojure and Emacs Lisp spoiled me, and I want OCaml beginners to taste a bit of that too.

So, what’s new:

• A dedicated REPL per project. The REPL buffer is now named after its project (e.g. *OCaml: myproject*), and the send commands route to the current buffer’s project REPL. You can have several projects running side by side without them stepping on each other.

• Choose your toplevel. The new neocaml-repl-flavor lets you pick between ocaml, utop, and dune-utop. Set it globally, or per project via .dir-locals.el:

  1
  ((neocaml-mode . ((neocaml-repl-flavor . dune-utop))))
  

  The active flavor shows up in the REPL’s mode line, so you always know what you’re talking to.

• Send a phrase and step. C-c C-n (neocaml-repl-send-phrase-and-step) sends the phrase at point to the REPL and moves on to the next one — perfect for walking through a file top to bottom while you experiment.
• #require from Emacs. neocaml-repl-require loads a findlib package into the running toplevel without you having to type the directive by hand.
• Restart on demand. neocaml-repl-restart kills and restarts the toplevel when things get into a weird state.

Completion for Opam and Dune, no LSP required

This one I’m particularly happy with. .ml/.mli files have ocaml-lsp-server to lean on for completion, but the auxiliary file formats have no language server at all. That’s exactly the kind of gap neocaml is meant to fill, so both neocaml-dune-mode and neocaml-opam-mode now ship a completion-at-point backend.

In a dune file you get completion for stanza names, the field names valid for the enclosing stanza, and library names inside libraries/pps fields:

(library
 (name my_lib)
 (libraries str re|))   ; <- completes both your own libraries and installed findlib ones

The library candidates combine your project’s own libraries with whatever’s installed in the active Opam switch. And it’s switch-aware — if there’s a project-local switch (an _opam/ directory), neocaml detects it and queries it via opam exec --, without any configuration on your part. The results are cached per project, so it stays snappy.

In opam files you get completion for field and section names, and package names inside depends/depopts/conflicts (sourced from opam list):

depends: [
  "dune" {>= "3.0"}
  "cmd|"   ; <- completes to cmdliner and friends
]

Both backends can be toggled off via neocaml-dune-complete-libraries and neocaml-opam-complete-packages if you’d rather not have them.

Robustness improvements

A good chunk of this release is the unglamorous but important work of making things just behave correctly:

• Character literals and quoted strings at the syntactic layer. Tree-sitter fontifies '"', '(', and {|raw "strings"|} correctly, but the syntax table underneath was getting confused — which broke forward-sexp, delete-pair, and electric-pair-mode around those constructs. The fix was a good old syntax-propertize-function. I wrote up the whole story over on Emacs Redux in Tree-sitter Modes Still Need a Syntax Table, if you’re into mode-writing internals.
• project.el integration. A directory with a dune-project file is now recognized as a project root (even without version control), _build/ and _opam/ are ignored, and compile-command defaults to dune build in dune projects.

There’s more in there too — ocamlformat integration (C-c C-f), clickable URLs and bug references in comments, a font-lock level selector, and richer menus across the modes.

OCaml 5.5 support, and the ABI 14 balancing act

OCaml 5.5 was released on June 19th, so this felt like a good moment to ship 5.5 support in neocaml. The ocaml and ocaml-interface grammars now track tree-sitter-ocaml v0.25.0, which brings the 5.5 grammar along with it.

There’s a wrinkle here that’s worth explaining, because it’s shaped the last few releases. A tree-sitter grammar gets compiled into a parser that speaks a particular ABI version, and Emacs can only load parsers up to the latest ABI supported by the libtree-sitter it was built against — it’s not the Emacs version itself that sets the ceiling. In practice a lot of Emacs 30 builds out there (notably Homebrew’s on macOS) are linked against tree-sitter 0.24, which tops out at ABI 14; you need an Emacs built against tree-sitter 0.25+ to load ABI 15 grammars. The trouble is that the tree-sitter 0.25 CLI now generates ABI 15 parsers by default, so any grammar regenerated with current tooling produces something those builds simply can’t load — you install it and it just errors out. Emacs 31 will ship with newer tree-sitter and make ABI 15 the common case, but it’s not out yet. (This isn’t a neocaml problem as such; it’s been biting tree-sitter modes across the ecosystem.)

After a few users ran into exactly this, I’ve made a deliberate decision: stick to ABI 14 grammars until Emacs 31 is widely available. That effort started a couple of releases back — in 0.8.1 I lowered the ABI requirement from 15 to 14 across the opam, dune, and ocamllex modes, switched the menhir recipe to tmcgilchrist/tree-sitter-menhir, and pinned ocamllex back to v0.24.0, all of which target ABI 14 (#42). 0.9 extends that policy to the core OCaml grammars.

The catch with v0.25.0 is precisely that it generates an ABI 15 parser. Happily, the 5.5 grammar didn’t actually need any ABI 15 features — the bump rode along with the CLI upgrade — so an ABI 14 regeneration of the very same grammar is a drop-in. Big thanks to 314eter, the tree-sitter-ocaml maintainer, for cutting a v0.25.0-abi14 tag for exactly this purpose (#141). The one snag was that tagging normally triggers releases to NPM, crates.io, and PyPI, so I sent a small PR to skip publishing for ABI-suffixed tags (#142), and the tag followed. neocaml now pins both grammars to it.

Roadmap and docs

If you’re curious where neocaml is headed, I’ve started keeping a ROADMAP.md with ideas and guiding principles (short version: tree-sitter first, lean on the LSP stack for .ml/.mli, and own the auxiliary modes that have no language server). The project also has a proper documentation site now at neocaml.org, so there’s a real home for the details beyond the README.

Give it a Try

As always — update from MELPA, play with it, and let me know how it goes. The full list of changes is in the 0.9.0 release notes. Bug reports, feature requests, and pull requests are all welcome on GitHub.

That’s all from me, folks! Keep hacking!

Versions 0.2-0.5 brought polish and bug fixes, but fundamentally the feature set stayed the same. I was even more convinced a grand 1.0 release was just around the corner.

I was wrong.

Of course, OCaml files don’t exist in isolation. They live alongside Opam files that describe packages and Dune files that configure builds. And as I was poking around the Tree-sitter ecosystem, I discovered that there were already grammars for both Opam and Dune files. Given how simple both formats are (Opam is mostly key-value pairs, Dune is s-expressions), adding support for them turned out to be fairly straightforward.

So here we are with neocaml 0.6, which is quite a bit bigger than I expected originally.

Note: One thing worth mentioning — all the new modes are completely isolated from the core OCaml modes. They’re separate files with no hard dependency on neocaml-mode, loaded only when you open the relevant file types. I didn’t want to force them upon anyone — for me it’s convenient to get Opam and Dune support out-of-the-box (given how ubiquitous they are in the OCaml ecosystem), but I totally get it if someone doesn’t care about this.

Let me walk you through what’s new.

neocaml-opam-mode

The new neocaml-opam-mode activates automatically for .opam and opam files. It provides:

• Tree-sitter-based font-lock (field names, strings, operators, version constraints, filter expressions, etc.)
• Indentation (lists, sections, option braces)
• Imenu for navigating variables and sections
• A flymake backend that runs opam lint on the current buffer, giving you inline diagnostics for missing fields, deprecated constructs, and syntax errors

The flymake backend registers automatically when opam is found in your PATH, but you need to enable flymake-mode yourself:

1
(add-hook 'neocaml-opam-mode-hook #'flymake-mode)

Flycheck users get opam lint support out of the box via Flycheck’s built-in opam checker — no extra configuration needed.

This bridges some of the gap with Tuareg, which also bundles an Opam major mode (tuareg-opam-mode). The Tree-sitter-based approach gives us more accurate highlighting, and the flymake integration is a nice bonus on top.

neocaml-dune-mode

neocaml-dune-mode handles dune, dune-project, and dune-workspace files — all three use the same s-expression syntax and share a single Tree-sitter grammar. You get:

• Font-lock for stanza names, field names, action keywords, strings, module names, library names, operators, and brackets
• Indentation with 1-space offset
• Imenu for stanza navigation
• Defun navigation and which-func support

This removes the need to install the separate dune package (the standalone dune-mode maintained by the Dune developers) from MELPA. If you prefer to keep using it, that’s fine too — neocaml’s README has instructions for overriding the auto-mode-alist entries.

neocaml-dune-interaction-mode

Beyond editing Dune files, I wanted a simple way to run Dune commands from any neocaml buffer. neocaml-dune-interaction-mode is a minor mode that provides keybindings (under C-c C-d) and a “Dune” menu for common operations:

All commands run via Emacs’s compile, so you get error navigation, clickable source locations, and the full compilation-mode interface for free. With a prefix argument (C-u), build, test, and fmt run in watch mode (--watch), automatically rebuilding when files change.

The utop command is special — it launches through neocaml-repl, so you get the full REPL integration (send region, send definition, etc.) with your project’s libraries preloaded.

This mode is completely independent from neocaml-dune-mode — it doesn’t care which major mode you’re using. You can enable it in OCaml buffers like this:

1
(add-hook 'neocaml-base-mode-hook #'neocaml-dune-interaction-mode)

Rough Edges

Both the Opam and Dune Tree-sitter grammars are relatively young and will need some more work for optimal results. I’ve been filing issues and contributing patches upstream to improve them — for instance, the Dune grammar currently flattens field-value pairs in a way that makes indentation less precise than it could be, and neither grammar supports variable interpolation (%{...}) yet. These are very solvable problems and I expect the grammars to improve over time.

What’s Next?

At this point I think I’m (finally!) out of ideas for new functionality. This time I mean it! Neocaml now covers pretty much everything I ever wanted, especially when paired with the awesome ocaml-eglot.

Down the road there might be support for OCamllex (.mll) or Menhir (.mly) files, but only if adding them doesn’t bring significant complexity — both are mixed languages with embedded OCaml code, which makes them fundamentally harder to support well than the simple Opam and Dune formats.

I hope OCaml programmers will find the new functionality useful. If you’re using neocaml, I’d love to hear how it’s working for you — bug reports, feature requests, and general feedback are all welcome on GitHub. You can find the full list of changes in the changelog.

As usual — update from MELPA, kick the tires, and let me know what you think.

That’s all I have for you today! Keep hacking!

OCaml doesn’t have built-in string interpolation. And here’s the funny thing – I didn’t even notice when I was first learning the language. Looking back at my first impressions article, I complained about the comment syntax, the semicolons in lists, the lack of list comprehensions, and a dozen other things – but never once about string interpolation. I was happily concatenating strings with ^ and using Printf.sprintf without giving it a second thought.

I only started thinking about this while working on my PPX article and going through the catalog of popular PPX libraries. That’s when I stumbled upon ppx_string and thought “wait, why doesn’t OCaml have interpolation?”

Why OCaml Doesn’t Have String Interpolation

The short answer: OCaml has no way to generically convert a value to a string. There’s no universal to_string method, no Show typeclass, no runtime reflection that would let the language figure out how to stringify an arbitrary expression inside a string literal.

In Ruby, every object responds to .to_s. In Python, everything has __str__. These languages can interpolate anything because there’s always a fallback conversion available at runtime. OCaml’s type information is erased at compile time, so the compiler would need to know at compile time which conversion function to call for each interpolated expression – and the language has no mechanism for that.¹

OCaml does have Printf.sprintf, which is actually quite nice and type-safe:

1
2
let greeting name age =
  Printf.sprintf "Hello, %s! You are %d years old." name age

The format string "%s ... %d" is statically checked by the compiler – if you pass an int where %s expects a string, you get a compile-time error, not a runtime crash. That’s genuinely better than what most dynamically typed languages offer. But it’s not interpolation – the values aren’t inline in the string, and for complex expressions it gets unwieldy fast.

There’s also plain string concatenation with ^:

1
2
let greeting name age =
  "Hello, " ^ name ^ "! You are " ^ string_of_int age ^ " years old."

This works, but it’s ugly and error-prone for anything beyond trivial cases.

ppx_string to the Rescue

ppx_string is a Jane Street PPX that adds string interpolation to OCaml at compile time. The basic usage is straightforward:

1
2
let greeting name =
  [%string "Hello, %{name}!"]

For non-string types, you specify the module whose to_string function should be used:

1
2
let status name age score =
  [%string "Player %{name}, age %{age#Int}, score %{score#Float}"]

The #Int suffix tells the PPX to call Int.to_string on age, and #Float calls Float.to_string on score. Note that Int.to_string, Float.to_string, etc. are conventions from Jane Street’s Base/Core libraries – OCaml’s Stdlib uses string_of_int, string_of_float and so on, which won’t work with the #Module syntax. This is another reason ppx_string really only makes sense within the Jane Street ecosystem.

Any module that exposes a to_string function works here – including your own:

1
2
3
4
5
6
7
module Player = struct
  type t = { name : string; score : int }
  let to_string p = Printf.sprintf "%s (%d)" p.name p.score
end

let announce player =
  [%string "Next up: %{player#Player}"]

You can also use arbitrary expressions inside the interpolation braces:

1
2
let summary items =
  [%string "Found %{List.length items |> Int.to_string} items"]

Though at that point you might be better off with a let binding or sprintf for readability.

Tips and Limitations

A few practical things worth knowing:

• You need the pps stanza in your dune file:

  (library
   (name mylib)
   (preprocess (pps ppx_string)))
  

• String values interpolate directly, everything else needs a conversion suffix. Unlike Ruby where .to_s is called implicitly, ppx_string requires you to be explicit about non-string types. This is annoying at first, but it’s consistent with OCaml’s philosophy of being explicit about types.
• It’s a Jane Street library. If you’re already in the Jane Street ecosystem (Core, Base, etc.), adding ppx_string is trivial. If you’re not, pulling in a Jane Street dependency just for string interpolation might feel heavy. In that case, Printf.sprintf is honestly fine.
• It doesn’t work with the Format module. If you’re building strings for pretty-printing, you’ll still want Format.fprintf or Format.asprintf. ppx_string is for building plain strings, not format strings.
• Nested interpolation doesn’t work – you can’t nest %{...} inside another %{...}. Keep it simple.

Do You Actually Need String Interpolation?

Honestly? Probably not as much as you think. I’ve been writing OCaml for a while now without it, and it rarely bothers me. Here’s why:

• Printf.sprintf is good. It’s type-safe, it’s concise enough for most cases, and it’s available everywhere without extra dependencies.
• Most string building in OCaml happens through Format. If you’re writing pretty-printers (which you will be, thanks to [@@deriving show]), you’re using Format.fprintf, not string concatenation or interpolation.
• OCaml code tends to be more compute-heavy than string-heavy. Compared to, say, a Rails app or a shell script, the typical OCaml program just doesn’t build that many ad-hoc strings.

That said, when you do need to build a lot of human-readable strings – error messages, log output, CLI formatting – interpolation is genuinely nicer than sprintf. If you’re in the Jane Street ecosystem, there’s no reason not to use ppx_string.

Closing Thoughts

The lack of string interpolation in OCaml is one of those things that sounds worse than it actually is. In practice, Printf.sprintf and Format cover the vast majority of use cases, and the code you write with them is arguably clearer about types than magical interpolation would be.

It’s also a nice example of OCaml’s general philosophy: keep the language core small, provide solid primitives (Printf, Format), and let the PPX ecosystem fill in the syntactic sugar for those who want it. The same pattern plays out with [@@deriving show] for printing, ppx_let for monadic syntax, and many other conveniences.

Will OCaml ever get built-in string interpolation? Maybe. There have been discussions on the forums over the years, and the language did absorb binding operators (let*, let+) from the PPX world. But I wouldn’t hold my breath – and honestly, I’m not sure I’d even notice if it landed.

That’s all I have for you today. Keep hacking!

1
2
3
4
type person = {
  name : string;
  age  : int;
} [@@deriving show, eq]

My first reaction was “what the hell is [@@deriving show, eq]?” Coming from languages like Ruby and Clojure, where metaprogramming is either built into the runtime (reflection) or baked into the language itself (macros), OCaml’s approach felt alien. There’s no runtime reflection, no macro system in the Lisp sense – just this mysterious @@ syntax that somehow generates code at compile time.

That mystery is PPX (PreProcessor eXtensions), and once you understand it, a huge chunk of the OCaml ecosystem suddenly makes a lot more sense. This article is my attempt to demystify PPX for people like me – developers who want to use PPX effectively without necessarily becoming PPX authors themselves.

What Is PPX and Why Should You Care?

OCaml is a statically typed language with no runtime reflection. That means you can’t do things like “iterate over all fields of a record at runtime” or “automatically serialize any type to JSON.” The type information simply isn’t available at runtime – it’s erased during compilation. One of my biggest frustrations as a newcomer was not being able to just print arbitrary data for debugging – there’s no generic print or inspect that works on any type. That frustration was probably my first real interaction with PPX.

PPX solves this by generating code at compile time. When the OCaml compiler parses your source code, it builds an Abstract Syntax Tree (AST) – a tree data structure that represents the syntactic structure of your program. PPX rewriters are programs that receive this AST, transform it, and return a modified AST back to the compiler. The compiler then continues as if you had written the generated code by hand.

In practical terms, this means that when you write:

1
2
type color = Red | Green | Blue
[@@deriving show]

The PPX rewriter generates something like this behind the scenes:

1
2
3
4
5
6
7
8
type color = Red | Green | Blue

let pp_color fmt = function    (* uses OCaml's Format module for pretty-printing *)
  | Red -> Format.fprintf fmt "Red"
  | Green -> Format.fprintf fmt "Green"
  | Blue -> Format.fprintf fmt "Blue"

let show_color x = Format.asprintf "%a" pp_color x  (* returns the formatted string *)

You get a pretty-printer for free, derived from the type definition. No boilerplate, no manual work, and it stays in sync with your type automatically.

If you’ve used Rust’s #[derive(Debug, PartialEq)] or Haskell’s deriving (Show, Eq), the idea is very similar. The syntax is different, but the motivation is identical – generating repetitive code from type definitions.

Why Isn’t This Built into the Language?

If you’re coming from Rust, you might wonder why OCaml doesn’t just have a built-in macro system like proc_macro. It’s a fair question, and the answer says a lot about OCaml’s design philosophy.

OCaml has always favored a small, stable language core. The compiler is famously lean and fast, and the language team is conservative about adding complexity to the specification. A full macro system baked into the compiler would be a significant undertaking – it would need to be designed, specified, maintained, and kept compatible across versions, forever.

Instead, OCaml took a more minimal approach: the compiler provides just two things – extension points and attributes – as syntactic hooks in the AST. Everything else lives in the ecosystem. The actual PPX rewriters are ordinary OCaml programs that happen to transform ASTs. The ppxlib framework that ties it all together is a regular library, not part of the compiler.

This has some real advantages:

• The ecosystem can evolve independently. ppxlib can ship new features, fix bugs, and improve APIs without waiting for a compiler release. Compare this to Rust, where changes to the proc macro system require the full RFC process and a compiler update.
• Tooling stays simple. Because [@@deriving show] and [%blob "file"] are valid OCaml syntax, every tool – editors, formatters, documentation generators – can parse PPX-annotated code without knowing anything about the specific PPX. The code is always syntactically valid OCaml, even before preprocessing.
• The compiler stays lean. No macro expander, no hygiene system, no special compilation phases – just a hook that says “here, transform this AST before I type-check it.”

The trade-offs are real, though. Rust’s proc macros are more tightly integrated – you get better error messages pointing at macro-generated code, better IDE support for macro expansions, and the macro system is a documented, stable part of the language. With PPX, you’re sometimes left staring at cryptic type errors in generated code and reaching for dune describe pp to figure out what went wrong.

That said, OCaml’s approach feels very OCaml – pragmatic, minimal, and trusting the ecosystem to build what’s needed on top of a simple foundation. And in practice, it works remarkably well.

A Bit of History

PPX wasn’t OCaml’s first metaprogramming system. Before PPX, there was Camlp4 (and its fork Camlp5) – a powerful but complex preprocessor that maintained its own parser, separate from the compiler’s parser. Camlp4 could extend OCaml’s syntax in arbitrary ways, which sounds great in theory but was a maintenance nightmare in practice. Every OCaml release risked breaking Camlp4, and code using Camlp4 extensions often couldn’t be processed by standard tools like editors and documentation generators.

OCaml 4.02 (2014) introduced extension points and attributes directly into the language grammar – syntactic hooks specifically designed for preprocessor extensions. This was a much simpler and more maintainable approach: PPX rewriters use the compiler’s own AST, the syntax is valid OCaml (so tools can still parse your code), and the whole thing is conceptually just “AST in, AST out.”

Camlp4 was officially retired in 2019. Today, the PPX ecosystem is built on ppxlib, a unified framework that provides a stable API across OCaml versions and handles all the plumbing for PPX authors.

Understanding the Syntax

Before diving into specific libraries, let’s decode the bracket soup. PPX uses two syntactic mechanisms built into OCaml:

Extension Nodes

Extension nodes are placeholders that a PPX rewriter must replace with generated code (compilation fails if no PPX handles them):

1
2
3
4
5
6
7
(* Expression-level extension *)
let pos = [%here]            (* replaced with current source position *)
let data = [%blob "icon.png"] (* replaced with file contents as a string *)

(* The "let%" infix syntax is sugar for expression extensions *)
let%bind x = fetch () in     (* equivalent to [%bind let x = fetch () in ...] *)
process x

Attributes

Attributes attach metadata to existing code. Unlike extension nodes, the compiler silently ignores attributes that no PPX handles:

1
2
3
4
5
6
7
8
9
(* [@attr] -- attaches to the nearest expression/pattern/type *)
x + y [@warning "-8"]

(* [@@attr] -- attaches to the enclosing declaration *)
type t = { name : string; age : int }
[@@deriving show]

(* [@@@attr] -- floating attribute at module level *)
[@@@warning "-32"]

The one you’ll see most often is [@@deriving ...] on type declarations. The distinction between @, @@, and @@@ is about scope – one @ for the innermost node, two for the enclosing declaration, three for the whole module-level.

Tip: Don’t worry about memorizing all of this upfront. In practice, you’ll mostly use [@@deriving ...] and occasionally [%extension ...] or let%... – and the specific PPX library’s documentation will tell you exactly which syntax to use.

Using PPX with Dune

To use a PPX library in your project, you add it to the preprocess stanza in your dune file:

(library
 (name mylib)
 (libraries yojson)
 (preprocess (pps ppx_deriving.show ppx_deriving.eq ppx_deriving_yojson)))

That’s it. List all the PPX rewriters you need after pps, and Dune takes care of the rest (it even combines them into a single binary for performance). For ppx_deriving plugins specifically, you use dotted names like ppx_deriving.show.

The PPX Libraries You’ll Actually Use

Let’s look at the PPX libraries that cover probably 90% of real-world use cases.

ppx_deriving – The Swiss Army Knife

ppx_deriving is the community’s general-purpose deriving framework. It comes with several built-in plugins:

1
2
3
4
5
6
7
8
type point = { x : float; y : float }
[@@deriving show, eq, ord]

(* Generates:
   val pp_point : Format.formatter -> point -> unit
   val show_point : point -> string
   val equal_point : point -> point -> bool
   val compare_point : point -> point -> int *)

show is the one you’ll reach for first – it’s essentially the answer to “how do I just print this thing?” that every OCaml newcomer asks sooner or later. The most commonly used plugins:

A neat convention: if your type is named t (as is idiomatic in OCaml), the generated functions drop the type name suffix – you get pp, show, equal, compare instead of pp_t, show_t, etc.

You can also customize behavior per field with attributes:

1
2
3
4
5
type file = {
  name : string [@equal fun a b ->
    String.lowercase_ascii a = String.lowercase_ascii b];
  perm : int    [@compare fun a b -> compare b a]  (* reverse order *)
} [@@deriving eq, ord]

And you can derive for anonymous types inline:

1
2
3
4
5
(* Sort a list of pairs by their second element *)
let sorted = List.sort [%derive.ord: int * int] pairs

(* Print a list of pairs *)
let () = print_endline ([%derive.show: (string * int) list] data)

ppx_deriving_yojson – JSON Serialization

ppx_deriving_yojson generates JSON serialization and deserialization functions using the Yojson library:

1
2
3
4
5
6
7
8
9
type person = {
  name : string;
  age  : int;
  email : string option;
} [@@deriving yojson]

(* Generates:
   val person_to_yojson : person -> Yojson.Safe.t
   val person_of_yojson : Yojson.Safe.t -> (person, string) result *)

1
2
3
4
let alice = { name = "Alice"; age = 30; email = Some "alice@example.com" }

let json = person_to_yojson alice |> Yojson.Safe.to_string
(* {"name":"Alice","age":30,"email":"alice@example.com"} *)

You can use [@@deriving to_yojson] or [@@deriving of_yojson] if you only need one direction.

This is incredibly useful in practice – writing JSON serializers by hand for complex types is tedious and error-prone.

ppx_sexp_conv – S-expression Serialization

If you’re using Jane Street’s Core library, you’ll encounter S-expression serialization everywhere. (Tip: Jane Street bundles most of their PPXs into a single ppx_jane package, so you can add just ppx_jane to your pps instead of listing each one individually.) ppx_sexp_conv generates converters between OCaml types and S-expressions:

1
2
3
4
5
6
7
8
9
type config = {
  host : string;
  port : int    [@default 8080];
  debug : bool  [@sexp.bool];
} [@@deriving sexp]

(* Generates:
   val sexp_of_config : config -> Sexp.t
   val config_of_sexp : Sexp.t -> config *)

The attributes here are quite handy – [@default 8080] provides a default value during deserialization, and [@sexp.bool] means the field is represented as a present/absent atom rather than (debug true).

ppx_fields_conv and ppx_variants_conv – Accessor Generation

Two more Jane Street PPXs that you’ll see a lot in Core-based codebases. ppx_fields_conv generates first-class accessors and iterators for record fields:

1
2
3
4
5
6
7
8
9
type person = {
  name : string;
  age  : int;
} [@@deriving fields]

(* Generates field accessors, a fold over all fields, iter, map, etc. *)
let () = Fields.iter
  ~name:(fun name -> Printf.printf "name: %s\n" name)
  ~age:(fun age -> Printf.printf "age: %d\n" age)

ppx_variants_conv does something similar for variant types – generating constructors as functions, fold/iter over all variants, and more.

ppx_inline_test and ppx_expect – Testing

These Jane Street PPXs let you write tests directly in your source files:

1
2
3
4
5
6
7
8
(* Simple boolean test *)
let%test "addition works" = 1 + 1 = 2

(* Test with side effects *)
let%test_unit "list operations" =
  let l = [1; 2; 3] in
  assert (List.length l = 3);
  assert (List.hd l = 1)

ppx_expect is particularly nice – it captures printed output and compares it against expected output:

1
2
3
let%expect_test "printing" =
  List.iter (fun x -> Printf.printf "%d " x) [1; 2; 3];
  [%expect {| 1 2 3 |}]

If the output doesn’t match, the test fails and you can run dune promote to automatically update the expected output in your source file. It’s a very productive workflow for testing functions that produce output.

ppx_let – Monadic Syntax

ppx_let provides syntactic sugar for working with monads and other “container” types:

1
2
3
4
5
6
7
8
9
10
11
(* Without ppx_let -- callback nesting hell *)
let result =
  bind (fetch_user id) (fun user ->
    bind (fetch_posts user) (fun posts ->
      return (user, posts)))

(* With ppx_let -- reads like sequential code *)
let result =
  let%bind user = fetch_user id in
  let%bind posts = fetch_posts user in
  return (user, posts)

How does ppx_let know which bind to call? It looks for a Let_syntax module in scope that provides the underlying bind and map functions. In practice, you’ll typically open a module that defines Let_syntax before using let%bind:

1
open Lwt.Syntax  (* or Deferred.Let_syntax, etc. *)

Note: Since OCaml 4.08, the language has built-in binding operators (let*, and*, let+, and+) that cover the basic use cases of ppx_let without needing a preprocessor. If you’re not using Jane Street’s ecosystem, binding operators are probably the simpler choice. ppx_let still offers extra features like match%bind, if%bind, and optimized let%mapn though.

ppx_blob – Embedding Files

ppx_blob is beautifully simple – it embeds a file’s contents as a string at compile time:

1
2
3
let icon_data = [%blob "assets/icon.png"]
let shader_source = [%blob "shaders/vertex.glsl"]
let default_config = [%blob "config/defaults.json"]

No more worrying about file paths at runtime or packaging data files with your binary. The file contents become part of your compiled program.

ppx_string – String Interpolation

One thing that’s always bugged me about OCaml is the lack of string interpolation. ppx_string fills that gap:

1
2
let greeting name age =
  [%string "Hello, %{name}! You are %{age#Int} years old."]

The #Int suffix tells the PPX to convert the value using Int.to_string. You can use any module that provides a to_string function.

Writing Your Own PPX (A Gentle Introduction)

Most OCaml developers will never need to write a PPX, but understanding the basics helps demystify the whole system. Let’s build a very simple one.

Say we want an extension [%upcase ...] that converts a string literal to uppercase at compile time. Here’s the complete implementation using ppxlib:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
(* ppx_upcase.ml *)
open Ppxlib

let extension =
  Extension.V3.declare
    "upcase"
    Extension.Context.expression
    Ast_pattern.(single_expr_payload (estring __))
    (fun ~ctxt expr ->
      let loc = Expansion_context.Extension.extension_point_loc ctxt in
      let uppercased = String.uppercase_ascii expr in
      Ast_builder.Default.estring ~loc uppercased)

let rule = Context_free.Rule.extension extension
let () = Driver.register_transformation ~rules:[rule] "ppx_upcase"

The dune file:

(library
 (name ppx_upcase)
 (kind ppx_rewriter)
 (libraries ppxlib))

And usage:

1
2
let greeting = [%upcase "hello world"]
(* After preprocessing: let greeting = "HELLO WORLD" *)

The key pieces are:

1. Extension.V3.declare – registers an extension with a name, the context where it can appear (expressions, patterns, types, etc.), the expected payload pattern, and an expansion function.
2. Ast_pattern – a pattern-matching DSL for destructuring AST nodes. Here estring __ matches a string literal and captures its value.
3. Ast_builder.Default – helpers for constructing AST nodes. estring builds a string literal expression.
4. Driver.register_transformation – registers the rule with ppxlib’s driver.

For more complex PPXs (especially derivers), you’ll also want to use Metaquot (ppxlib.metaquot), which lets you write AST-constructing code using actual OCaml syntax instead of manual AST builder calls:

1
2
3
4
5
6
7
(* Without metaquot -- verbose *)
Ast_builder.Default.pexp_apply ~loc
  (Ast_builder.Default.evar ~loc "string_of_int")
  [(Nolabel, expr)]

(* With metaquot -- just write OCaml *)
[%expr string_of_int [%e expr]]

The ppxlib documentation has excellent tutorials if you want to go deeper.

Debugging PPX-generated Code

One practical tip: when something goes wrong with PPX-generated code and you’re staring at a confusing type error, you can inspect what the PPX actually generated:

1
2
3
4
5
6
7
8
9
# Show the preprocessed output for a file (dune 3.x+)
dune describe pp src/myfile.ml

# Alternatively, build the .pp.ml target and inspect it directly
dune build src/.mylib.pp/myfile.pp.ml
cat _build/default/src/.mylib.pp/myfile.pp.ml

# Or use ocaml-print-intf to see the generated interface
dune exec -- ocaml-print-intf src/myfile.ml

Seeing the expanded code often makes the error immediately obvious.

The PPX Ecosystem Today

Most of the introductory PPX content out there was written around 2018-2019, so it’s worth noting how things have evolved since then.

The big story has been ppxlib’s consolidation of the ecosystem. Back in 2019, some PPX rewriters still used the older ocaml-migrate-parsetree (OMP) library, creating fragmentation. By 2021, nearly all PPXs had migrated to ppxlib, effectively ending the split. Today ppxlib is the way to write PPX rewriters – there’s no real alternative to consider.

The transition hasn’t always been smooth, though. In 2025, ppxlib 0.36.0 bumped its internal AST to match OCaml 5.2, which changed how functions are represented in the parse tree. This broke many downstream PPXs and temporarily split the opam universe between packages that worked with the new version and those that didn’t. The community worked through it with proactive patching, but it highlighted an ongoing tension in the PPX world: ppxlib shields you from most compiler changes, but major AST overhauls still ripple through the ecosystem.

On the API side, ppxlib is gradually deprecating its copy of Ast_helper in favor of Ast_builder, with plans to remove Ast_helper entirely in a future 1.0.0 release. If you’re writing a new PPX today, use Ast_builder exclusively.

Meanwhile, OCaml 4.08’s built-in binding operators (let*, let+, etc.) have reduced the need for ppx_let in projects that don’t use Jane Street’s ecosystem. It’s a nice example of the language absorbing a pattern that PPX pioneered. Perhaps one day we’ll see more of this (e.g. native string interpolation).

Further Reading

This article covers a lot of ground, but the PPX topic is pretty deep and complex, so depending on how far you want to go you might want to read more on it. Here are some of the best resources I’ve found on PPX:

• Preprocessors and PPXs – the official OCaml documentation on metaprogramming. A solid reference, though it assumes some comfort with the compiler internals.
• An Introduction to OCaml PPX Ecosystem – Nathan Rebours’ 2019 deep dive for Tarides. This is the most thorough tutorial on writing PPX rewriters I’ve seen. Some API details have changed since 2019 (notably the Ast_helper → Ast_builder shift), but the concepts and approach are still excellent.
• ppxlib Quick Introduction – ppxlib’s own getting-started guide. The best place to begin if you want to write your own PPX.
• A Guide to PreProcessor eXtensions – OCamlverse’s reference page with a comprehensive list of available PPX libraries.
• A Guide to Extension Points in OCaml – Whitequark’s original 2014 guide that introduced many developers to PPX. Historically interesting as a snapshot of the early PPX days.

I was amused to see whitequark’s name pop up while I was doing research for this article – we collaborated quite a bit back in the day on her Ruby parser project, which was instrumental to RuboCop. Seems you can find (former) Rubyists in pretty much every language community.

Epilogue

This article turned out to be a beast! I’ve wanted to write something on the subject for quite a while now, but I’ve kept postponing it because I was too lazy to do all the necessary research. I’ll feel quite relieved to put it behind me!

PPX might look intimidating at first – all those brackets and @ symbols can feel like line noise. But the core idea is simple: PPX generates boilerplate code from your type definitions at compile time. You annotate your types with what you want (show, eq, yojson, sexp, etc.), and the PPX rewriter produces the code you’d otherwise have to write by hand.

For day-to-day OCaml programming, you really only need to know:

1. [@@deriving ...] on type declarations to generate useful functions
2. How to add PPX libraries to your dune file with (pps ...)
3. Which PPX libraries exist for common tasks (serialization, testing, pretty-printing)

The “writing your own PPX” part is there for when you need it, but honestly most OCaml developers get by just fine using the existing ecosystem.

That’s all I have for you today. Keep hacking!

This means you need to be explicit about how to print every type you define. That sounds tedious (and it can be), but the community has developed tools that make it mostly painless. Let me walk you through the common approaches.

Printing Built-in Types

For basic types, OCaml provides dedicated print functions in Stdlib:

1
2
3
4
5
6
print_int 42;;
print_float 3.14;;
print_string "hello";;
print_endline "hello with newline";;
print_char 'x';;
print_newline ();;

There are also simple conversion functions like string_of_int and string_of_float when you just need a string:

1
2
let s = "Age: " ^ string_of_int 42;;
(* "Age: 42" *)

And of course there’s Printf.printf for formatted output:

1
Printf.printf "Name: %s, Age: %d, Score: %.2f\n" "Alice" 30 95.5;;

A quick cheat sheet for the format specifiers you’ll use most often: %s for strings, %d for ints, %f for floats (%.2f for 2 decimal places), %b for bools, and %S for strings with quotes around them (handy for debugging). You can use Printf.sprintf instead of printf to get a string back rather than printing to stdout.

This is all straightforward. The trouble starts when you want to print your own types.

The Running Example

Let’s use something more fun than the usual person record. We’ll model superheroes:

1
2
3
4
5
6
7
8
9
10
11
type power = Flight | SuperStrength | Telepathy | Speed | Gadgets

type strength = Human | Enhanced | Superhuman | Cosmic

type superhero = {
  name : string;
  alias : string;
  powers : power list;
  strength : strength;
  first_appearance : int;  (* year *)
}

And a few heroes to work with:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
let batman = {
  name = "Bruce Wayne";
  alias = "Batman";
  powers = [Gadgets];
  strength = Human;
  first_appearance = 1939;
}

let superman = {
  name = "Clark Kent";
  alias = "Superman";
  powers = [Flight; SuperStrength];
  strength = Cosmic;
  first_appearance = 1938;
}

let wonder_woman = {
  name = "Diana Prince";
  alias = "Wonder Woman";
  powers = [Flight; SuperStrength; Telepathy];
  strength = Superhuman;
  first_appearance = 1941;
}

Now try print_endline batman and… you get a type error. OCaml has no idea how to turn a superhero into a string. Let’s fix that.

Writing Manual Printers

The most basic approach is to write dedicated print functions. For our superhero types, we’d need to handle each layer:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
let string_of_power = function
  | Flight -> "Flight"
  | SuperStrength -> "Super Strength"
  | Telepathy -> "Telepathy"
  | Speed -> "Speed"
  | Gadgets -> "Gadgets"

let string_of_strength = function
  | Human -> "Human"
  | Enhanced -> "Enhanced"
  | Superhuman -> "Superhuman"
  | Cosmic -> "Cosmic"

let show_superhero h =
  Printf.sprintf "%s (%s) - %s, first appeared in %d, powers: %s"
    h.alias h.name
    (string_of_strength h.strength)
    h.first_appearance
    (h.powers |> List.map string_of_power |> String.concat ", ")

1
2
3
4
5
print_endline (show_superhero batman);;
(* Batman (Bruce Wayne) - Human, first appeared in 1939, powers: Gadgets *)

print_endline (show_superhero wonder_woman);;
(* Wonder Woman (Diana Prince) - Superhuman, first appeared in 1941, powers: Flight, Super Strength, Telepathy *)

This works, but it’s tedious. We had to write a conversion function for every variant type and compose them manually. Every time you add a new power or a new field to the record, you have to remember to update all the printers. And for nested types the boilerplate multiplies fast. Coming from languages where printing just works out of the box, this feels like a lot of ceremony for something that should be trivial.

That said, manual printers give you full control over formatting, which is exactly what you want for user-facing output (error messages, CLI output, log lines).

Automatic Printing with ppx_deriving

This is where ppx_deriving saves the day. Its show plugin generates printer functions automatically from your type definitions. Just add [@@deriving show]:

1
2
3
4
5
6
7
8
9
10
11
12
13
type power = Flight | SuperStrength | Telepathy | Speed | Gadgets
[@@deriving show]

type strength = Human | Enhanced | Superhuman | Cosmic
[@@deriving show]

type superhero = {
  name : string;
  alias : string;
  powers : power list;
  strength : strength;
  first_appearance : int;
} [@@deriving show]

That annotation generates two functions per type:

• pp_superhero : Format.formatter -> superhero -> unit – a pretty-printer for use with OCaml’s Format module
• show_superhero : superhero -> string – returns the string representation directly

Now printing is trivial:

1
2
3
4
print_endline (show_superhero batman);;
(* { name = "Bruce Wayne"; alias = "Batman";
     powers = [Gadgets]; strength = Human;
     first_appearance = 1939 } *)

The generated printers are compositional – they know how to handle lists, options, and other standard types automatically, as long as the element type also derives show. So printing a list of heroes just works:

1
2
3
let justice_league = [batman; superman; wonder_woman]

let () = print_endline ([%show: superhero list] justice_league)

The [%show: superhero list] syntax is really handy – it lets you derive a printer for any type expression inline, without needing a separate type declaration.

To use ppx_deriving in your project, add it to your dune file:

(library
 (name mylib)
 (preprocess (pps ppx_deriving.show)))

I slap [@@deriving show] on pretty much every type I define these days. The small compile-time cost is well worth the debugging convenience. If you want to learn more about PPX in general, I wrote a longer article about it.

Debugging Tips

A few practical things I’ve picked up:

Debug Printing Mid-pipeline

You can sneak a print into a |> chain without breaking the flow:

1
2
3
4
5
6
7
8
9
let debug label x =
  Printf.printf "[DEBUG] %s: %s\n" label (show_superhero x);
  x

let result =
  batman
  |> debug "before upgrade"
  |> upgrade_powers
  |> debug "after upgrade"

Inline [%show: ...] for Complex Types

When you need to print something and don’t want to define a type just for it:

1
2
3
Printf.printf "Heroes and powers: %s\n"
  ([%show: (string * power list) list]
    (List.map (fun h -> (h.alias, h.powers)) justice_league))

Watch Out for Missing show on Nested Types

If your record contains a type that doesn’t derive show, you’ll get a compile error about a missing pp_ function. The error message can be cryptic – just look for the type that’s missing the derivation and add [@@deriving show] to it.

{ with_path = false } for Cleaner Output

By default, derived printers qualify variant constructors with their module path (e.g. Superhero.Flight). If you find this noisy:

1
2
3
4
type power = Flight | SuperStrength | Telepathy | Speed | Gadgets
[@@deriving show { with_path = false }]

(* Now prints "Flight" instead of "Superhero.Flight" *)

Printing in the Toplevel

If you’re exploring code in utop (or the plain ocaml toplevel), you’ll notice that it already displays values of built-in types:

1
2
3
4
5
6
# 42;;
- : int = 42
# [1; 2; 3];;
- : int list = [1; 2; 3]
# "hello";;
- : string = "hello"

But for your own types, you just see the structure without much help:

1
2
# batman;;
- : superhero = {name = "Bruce Wayne"; alias = "Batman"; ...}

Actually, the toplevel does a decent job with simple records and variants – it knows the structure from the type definition. Where it falls short is with abstract types or types from external modules where the representation is hidden.

If you’ve derived show for your types, you can register the generated pretty-printer with the toplevel using #install_printer:

1
2
3
# #install_printer pp_superhero;;
# batman;;
- : superhero = { name = "Bruce Wayne"; alias = "Batman"; ... }

This tells the toplevel to use your pp_superhero function whenever it needs to display a superhero value. This is especially useful for abstract types or when you want a custom representation. The function you install must have the signature Format.formatter -> 'a -> unit – which is exactly what [@@deriving show] generates as pp_*.

When to Use What

For debugging and development, [@@deriving show] is the obvious winner. It’s become such a standard part of my OCaml workflow that I barely think about it anymore.

For user-facing output (error messages, CLI formatting, log lines), you’ll still want manual formatting with Printf.sprintf or Format.asprintf. The derived printers produce a generic representation that’s great for debugging but not something you’d want to show end users.

And in the toplevel, make friends with #install_printer – it makes interactive exploration much more pleasant.

That’s all I have for you today. Keep hacking!

Let’s explore records using a fun data model – superheroes:

1
2
3
4
5
6
7
8
9
10
11
type power = Flight | SuperStrength | Telepathy | Speed | Gadgets

type strength = Human | Enhanced | Superhuman | Cosmic

type superhero = {
  name : string;
  alias : string;
  powers : power list;
  strength : strength;
  first_appearance : int;
}

Creating Records

Creating a record is straightforward – list all fields with their values:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
let batman = {
  name = "Bruce Wayne";
  alias = "Batman";
  powers = [Gadgets];
  strength = Human;
  first_appearance = 1939;
}

let superman = {
  name = "Clark Kent";
  alias = "Superman";
  powers = [Flight; SuperStrength];
  strength = Cosmic;
  first_appearance = 1938;
}

Note that you don’t specify the type anywhere – the compiler infers it from the field names. This works great when field names are unique, but can cause trouble when two record types in scope share a field name:

1
2
3
4
5
6
type hero = { name : string; power : string }
type villain = { name : string; evil_plan : string }

(* Which type is this? The compiler picks the most recently defined one -- villain *)
let mystery = { name = "Enigma"; power = "puzzles" }
(* Error: Unbound record field power *)

You can disambiguate by annotating the type:

1
let h : hero = { name = "Enigma"; power = "puzzles" }

Or by prefixing a field name with the module:

1
let h = { Hero.name = "Enigma"; power = "puzzles" }

In practice, this ambiguity rarely bites you because OCaml’s module system naturally separates types into different scopes. The idiomatic approach is to define one main record type per module (named t by convention), which avoids collisions entirely.

Accessing Fields

Field access uses the usual dot notation:

1
2
let name = batman.name               (* "Bruce Wayne" *)
let year = batman.first_appearance   (* 1939 *)

You can use fields directly in expressions:

1
2
3
4
let is_golden_age hero = hero.first_appearance < 1956
let () = Printf.printf "%s: golden age = %b\n"
  batman.alias (is_golden_age batman)
(* Batman: golden age = true *)

Functional Updates

Records are immutable by default in OCaml. You can’t modify a field in place – instead, you create a new record with some fields changed using the with keyword:

1
2
3
4
let upgraded_batman = { batman with
  powers = [Gadgets; SuperStrength];
  strength = Enhanced;
}

This creates a new superhero record that’s a copy of batman with only the specified fields changed. The original is untouched. If you’ve used Haskell’s record update syntax or Erlang’s map update syntax, this will feel familiar.

Functional updates are especially handy when your records have many fields and you only want to change one or two:

1
2
3
4
5
let justice_league = [batman; superman]

(* Promote everyone to Cosmic strength *)
let cosmic_league =
  List.map (fun h -> { h with strength = Cosmic }) justice_league

Mutable Fields

While records are immutable by default, OCaml lets you mark individual fields as mutable:

1
2
3
4
5
6
7
8
type battle_stats = {
  hero : string;
  mutable wins : int;
  mutable losses : int;
}

let stats = { hero = "Batman"; wins = 0; losses = 0 }
let () = stats.wins <- stats.wins + 1   (* wins is now 1 *)

The <- operator mutates the field in place. Note that only fields explicitly marked mutable can be changed this way – trying to mutate an immutable field is a compile error.

I’d use mutable fields sparingly – they’re there when you need them for performance-critical code, but immutable records with functional updates are generally the idiomatic approach in OCaml.

Pattern Matching on Records

Like everything in OCaml, records work with pattern matching. You can destructure them directly in function arguments:

1
2
3
4
5
6
7
8
9
let describe { alias; strength; first_appearance; _ } =
  let strength_str = match strength with
    | Human -> "human-level"
    | Enhanced -> "enhanced"
    | Superhuman -> "superhuman"
    | Cosmic -> "cosmic"
  in
  Printf.printf "%s (%d) - %s strength\n"
    alias first_appearance strength_str

The _ in the pattern tells the compiler you’re intentionally ignoring the other fields. Without it, you’d get a warning about inexhaustive field patterns.

You can also pattern match in let bindings:

1
2
let { alias; powers; _ } = batman in
Printf.printf "%s has %d powers\n" alias (List.length powers)

And in match expressions for more complex logic:

1
2
3
4
5
6
let classify = function
  | { strength = Cosmic; _ } -> "overpowered"
  | { strength = Human; powers; _ } when List.length powers > 0 ->
    "resourceful"
  | { strength = Human; _ } -> "ordinary"
  | _ -> "super"

Field Punning

You might have noticed the shorthand in the examples above – { alias; strength; _ } instead of { alias = alias; strength = strength; _ }. This is called “field punning” and it works both in patterns and when constructing records:

1
2
3
4
5
6
7
8
9
10
let alias = "Flash"
let name = "Barry Allen"
let powers = [Speed]
let strength = Superhuman
let first_appearance = 1956

(* these are equivalent *)
let flash_v1 = { name = name; alias = alias; powers = powers;
                 strength = strength; first_appearance = first_appearance }
let flash_v2 = { name; alias; powers; strength; first_appearance }

If you’re coming from JavaScript, this is the same idea as ES6’s shorthand property names in object literals. It’s particularly nice when you’re constructing a record from variables that already have the right names.

Records and Modules

The idiomatic OCaml pattern is to define one main type per module, named t:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
(* superhero.ml *)
type power = Flight | SuperStrength | Telepathy | Speed | Gadgets
type strength = Human | Enhanced | Superhuman | Cosmic

type t = {
  name : string;
  alias : string;
  powers : power list;
  strength : strength;
  first_appearance : int;
}

let create ~name ~alias ~powers ~strength ~first_appearance =
  { name; alias; powers; strength; first_appearance }

let is_golden_age t = t.first_appearance < 1956

This convention means you refer to the type as Superhero.t from outside the module, and field access reads naturally as hero.Superhero.alias (or just hero.alias if you’ve opened the module). It also avoids the field name collision problem entirely, since each module has its own namespace.

Printing Records

You can’t just print a record in OCaml – there’s no generic print that works on any type. The easiest solution is [@@deriving show] from ppx_deriving:

1
2
3
4
5
6
7
type superhero = {
  name : string;
  alias : string;
  powers : power list;
} [@@deriving show]

let () = print_endline (show_superhero batman)

I wrote a dedicated article on printing data structures if you want the full story.

Records vs Tuples

One question that comes up for beginners: when should you use a record instead of a tuple?

Tuples are great for quick, throwaway groupings – returning two values from a function, for example. But once you have more than two or three fields, or when the meaning of each position isn’t obvious, records are almost always better:

1
2
3
4
5
(* Tuple -- what does each position mean? *)
let hero = ("Bruce Wayne", "Batman", 1939)

(* Record -- self-documenting *)
let hero = { name = "Bruce Wayne"; alias = "Batman"; first_appearance = 1939 }

Records also give you pattern matching with named fields, functional updates with with, and better error messages from the compiler. If you find yourself reaching for a tuple with more than 2-3 elements, it’s probably time for a record.

Further Reading

• Records – the Real World OCaml chapter on records. Goes deeper into functional updates, first-class fields (via ppx_fields_conv), and the interaction between records and modules.
• Basic Data Types and Pattern Matching – the official ocaml.org guide covering records alongside other core data types.

That’s all I have for you today. Keep hacking!

Why Tree-sitter?

Before Tree-sitter, Emacs font-locking was done with regular expressions and indentation was handled by ad-hoc engines (SMIE, custom indent functions, or pure regex heuristics). This works, but it has well-known problems:

• Regex-based font-locking is fragile. Regexes can’t parse nested structures, so they either under-match (missing valid code) or over-match (highlighting inside strings and comments). Every edge case is another regex, and the patterns become increasingly unreadable over time.

• Indentation engines are complex. SMIE (the generic indentation engine for non-Tree-sitter modes) requires defining operator precedence grammars for the language, which is hard to get right. Custom indentation functions tend to grow into large, brittle state machines. Tuareg’s indentation code, for example, is thousands of lines long.

Tree-sitter changes the game because you get a full, incremental, error-tolerant syntax tree for free. Font-locking becomes “match this AST pattern, apply this face”:

1
2
3
;; Highlight let-bound functions: match a let_binding with parameters
(let_binding pattern: (value_name) @font-lock-function-name-face
             (parameter)+)

And indentation becomes “if the parent node is X, indent by Y”:

1
2
;; Children of a let_binding are indented by neocaml-indent-offset
((parent-is "let_binding") parent-bol neocaml-indent-offset)

The rules are declarative, composable, and much easier to reason about than regex chains.

In practice, neocaml’s entire font-lock and indentation logic fits in about 350 lines of Elisp. The equivalent in tuareg is spread across thousands of lines. That’s the real selling point: simpler, more maintainable code that handles more edge cases correctly.

Challenges

That said, Tree-sitter in Emacs is not a silver bullet. Here’s what I ran into.

Every grammar is different

Tree-sitter grammars are written by different authors with different philosophies. The tree-sitter-ocaml grammar provides a rich, detailed AST with named fields. The tree-sitter-clojure grammar, by contrast, deliberately keeps things minimal – it only models syntax, not semantics, because Clojure’s macro system makes static semantic analysis unreliable.¹ This means font-locking def forms in Clojure requires predicate matching on symbol text, while in OCaml you can directly match let_binding nodes with named fields.

To illustrate: here’s how you’d fontify a function definition in OCaml, where the grammar gives you rich named fields:

1
2
3
;; OCaml: grammar provides named fields -- direct structural match
(let_binding pattern: (value_name) @font-lock-function-name-face
             (parameter)+)

And here’s the equivalent in Clojure, where the grammar only gives you lists of symbols and you need predicate matching:

1
2
3
4
;; Clojure: grammar is syntax-only -- match by symbol text
((list_lit :anchor (sym_lit !namespace
                            name: (sym_name) @font-lock-keyword-face))
 (:match ,clojure-ts--definition-keyword-regexp @font-lock-keyword-face))

You can’t learn “how to write Tree-sitter queries” generically – you need to learn each grammar individually. The best tool for this is treesit-explore-mode (to visualize the full parse tree) and treesit-inspect-mode (to see the node at point). Use them constantly.

Grammar quality varies wildly

You’re dependent on someone else providing the grammar, and quality is all over the map. The OCaml grammar is mature and well-maintained – it’s hosted under the official tree-sitter GitHub org. The Clojure grammar is small and stable by design. But not every language is so lucky.

asciidoc-mode uses a third-party AsciiDoc grammar that employs a dual-parser architecture – one parser for block-level structure (headings, lists, code blocks) and another for inline formatting (bold, italic, links). This is the same approach used by Emacs’s built-in markdown-ts-mode, and it makes sense for markup languages where block and inline syntax are largely independent.

The problem is that the two parsers run independently on the same text, and they can disagree. The inline parser misinterprets * and ** list markers as emphasis delimiters, creating spurious bold spans that swallow subsequent inline content. The workaround is to use :override t on all block-level font-lock rules so they win over the incorrect inline faces:

1
2
3
4
5
6
7
8
;; Block-level rules use :override t so block-level faces win over
;; spurious inline emphasis nodes (the inline parser misreads `*'
;; list markers as emphasis delimiters).
:language 'asciidoc
:override t
:feature 'list
'((ordered_list_marker) @font-lock-constant-face
  (unordered_list_marker) @font-lock-constant-face)

This doesn’t fix inline elements consumed by the spurious emphasis – that requires an upstream grammar fix. When you hit grammar-level issues like this, you either fix them yourself (which means diving into the grammar’s JavaScript source and C toolchain) or you live with workarounds. Either way, it’s a reminder that your mode is only as good as the grammar underneath it.

Getting the font-locking right in asciidoc-mode was probably the most challenging part of all three projects, precisely because of these grammar quirks. I also ran into a subtle treesit behavior: the default font-lock mode (:override nil) skips an entire captured range if any position within it already has a face. So if you capture a parent node like (inline_macro) and a child was already fontified, the whole thing gets skipped silently. The fix is to capture specific child nodes instead:

1
2
3
4
5
6
;; BAD: entire node gets skipped if any child is already fontified
;; (inline_macro) @font-lock-function-call-face

;; GOOD: capture specific children
(inline_macro (macro_name) @font-lock-function-call-face)
(inline_macro (target) @font-lock-string-face)

These issues took a lot of trial and error to diagnose. The lesson: budget extra time for font-locking when working with less mature grammars.

Grammar versions and breaking changes

Grammars evolve, and breaking changes happen. clojure-ts-mode switched from the stable grammar to the experimental branch because the stable version had metadata nodes as children of other nodes, which caused forward-sexp and kill-sexp to behave incorrectly. The experimental grammar makes metadata standalone nodes, fixing the navigation issues but requiring all queries to be updated.

neocaml pins to v0.24.0 of the OCaml grammar. If you don’t pin versions, a grammar update can silently break your font-locking or indentation.

The takeaway: always pin your grammar version, and include a mechanism to detect outdated grammars. clojure-ts-mode tests a query that changed between versions to detect incompatible grammars at startup.

Grammar delivery

Users shouldn’t have to manually clone repos and compile C code to use your mode. Both neocaml and clojure-ts-mode include grammar recipes:

1
2
3
4
5
6
7
(defconst neocaml-grammar-recipes
  '((ocaml "https://github.com/tree-sitter/tree-sitter-ocaml"
           "v0.24.0"
           "grammars/ocaml/src")
    (ocaml-interface "https://github.com/tree-sitter/tree-sitter-ocaml"
                     "v0.24.0"
                     "grammars/interface/src")))

On first use, the mode checks treesit-language-available-p and offers to install missing grammars via treesit-install-language-grammar. This works, but requires a C compiler and Git on the user’s machine, which is not ideal.²

The Emacs Tree-sitter APIs are a moving target

The Tree-sitter support in Emacs has been improving steadily, but each version has its quirks:

Emacs 29 introduced Tree-sitter support but lacked several APIs. For instance, treesit-thing-settings (used for structured navigation) doesn’t exist – you need a fallback:

1
2
3
;; Fallback for Emacs 29 (no treesit-thing-settings)
(unless (boundp 'treesit-thing-settings)
  (setq-local forward-sexp-function #'neocaml-forward-sexp))

Emacs 30 added treesit-thing-settings, sentence navigation, and better indentation support. But it also had a bug in treesit-range-settings offsets (#77848) that broke embedded parsers, and another in treesit-transpose-sexps that required clojure-ts-mode to disable its Tree-sitter-aware version.

Emacs 31 has a bug in treesit-forward-comment where an off-by-one error causes uncomment-region to leave *) behind on multi-line OCaml comments. I had to skip the affected test with a version check:

1
2
3
(when (>= emacs-major-version 31)
  (signal 'buttercup-pending
          "Emacs 31 treesit-forward-comment bug (off-by-one)"))

The lesson: test your mode against multiple Emacs versions, and be prepared to write version-specific workarounds. CI that runs against Emacs 29, 30, and snapshot is essential.

No .scm file support (yet)

Most Tree-sitter grammars ship with .scm query files for syntax highlighting (highlights.scm) and indentation (indents.scm). Editors like Neovim and Helix use these directly. Emacs doesn’t – you have to manually translate the .scm patterns into treesit-font-lock-rules and treesit-simple-indent-rules calls in Elisp.

This is tedious and error-prone. For example, here’s a rule from the OCaml grammar’s highlights.scm:

1
2
;; upstream .scm (used by Neovim, Helix, etc.)
(constructor_name) @type

And here’s the Elisp equivalent you’d write for Emacs:

1
2
3
4
;; Emacs equivalent -- wrapped in treesit-font-lock-rules
:language 'ocaml
:feature 'type
'((constructor_name) @font-lock-type-face)

The query syntax is nearly identical, but you have to wrap everything in treesit-font-lock-rules calls, map upstream capture names (@type) to Emacs face names (@font-lock-type-face), assign features, and manage :override behavior. You end up maintaining a parallel set of queries that can drift from upstream. Emacs 31 will introduce define-treesit-generic-mode which will make it possible to use .scm files for font-locking, which should help significantly. But for now, you’re hand-coding everything.

Tips and tricks

Debugging font-locking

When a face isn’t being applied where you expect:

1. Use treesit-inspect-mode to verify the node type at point matches your query.
2. Set treesit--font-lock-verbose to t to see which rules are firing.
3. Check the font-lock feature level – your rule might be in level 4 while the user has the default level 3. The features are assigned to levels via treesit-font-lock-feature-list.
4. Remember that rule order matters. Without :override, an earlier rule that already fontified a region will prevent later rules from applying. This can be intentional (e.g. builtin types at level 3 take precedence over generic types) or a source of bugs.

Use the font-lock levels wisely

Tree-sitter modes define four levels of font-locking via treesit-font-lock-feature-list, and the default level in Emacs is 3. It’s tempting to pile everything into levels 1–3 so users see maximum highlighting out of the box, but resist the urge. When every token on the screen has a different color, code starts looking like a Christmas tree and the important things – keywords, definitions, types – stop standing out.

Less is more here. Here’s how neocaml distributes features across levels:

1
2
3
4
5
(setq-local treesit-font-lock-feature-list
            '((comment definition)
              (keyword string number)
              (attribute builtin constant type)
              (operator bracket delimiter variable function)))

And clojure-ts-mode follows the same philosophy:

1
2
3
4
5
(setq-local treesit-font-lock-feature-list
            '((comment definition)
              (keyword string char symbol builtin type)
              (constant number quote metadata doc regex)
              (bracket deref function tagged-literals)))

The pattern is the same: essentials first, progressively more detail at higher levels. This way the default experience (level 3) is clean and readable, and users who want the full rainbow can bump treesit-font-lock-level to 4. Better yet, they can use treesit-font-lock-recompute-features to cherry-pick individual features regardless of level:

1
2
3
4
5
;; Enable 'function' (level 4) without enabling all of level 4
(treesit-font-lock-recompute-features '(function) nil)

;; Disable 'bracket' even if the user's level would include it
(treesit-font-lock-recompute-features nil '(bracket))

This gives users fine-grained control without requiring mode authors to anticipate every preference.

Debugging indentation

Indentation issues are harder to diagnose because they depend on tree structure, rule ordering, and anchor resolution:

1. Set treesit--indent-verbose to t – this logs which rule matched for each line, what anchor was computed, and the final column.
2. Use treesit-explore-mode to understand the parent chain. The key question is always: “what is the parent node, and which rule matches it?”

3. Remember that rule order matters for indentation too – the first matching rule wins. A typical set of rules reads top to bottom from most specific to most general:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   ;; Closing delimiters align with the opening construct
   ((node-is ")") parent-bol 0)
   ((node-is "end") parent-bol 0)
   
   ;; then/else clauses align with their enclosing if
   ((node-is "then_clause") parent-bol 0)
   ((node-is "else_clause") parent-bol 0)
   
   ;; Bodies inside then/else are indented
   ((parent-is "then_clause") parent-bol neocaml-indent-offset)
   ((parent-is "else_clause") parent-bol neocaml-indent-offset)
   

4. Watch out for the empty-line problem: when the cursor is on a blank line, Tree-sitter has no node at point. The indentation engine falls back to the root compilation_unit node as the parent, which typically matches the top-level rule and gives column 0. In neocaml I solved this with a no-node rule that looks at the previous line’s last token to decide indentation:

   1
   (no-node prev-line neocaml--empty-line-offset)
   

Build a comprehensive test suite

This is the single most important piece of advice. Font-lock and indentation are easy to break accidentally, and manual testing doesn’t scale. Both projects use Buttercup (a BDD testing framework for Emacs) with custom test macros.

Font-lock tests insert code into a buffer, run font-lock-ensure, and assert that specific character ranges have the expected face:

1
2
3
(when-fontifying-it "fontifies let-bound functions"
  ("let greet name = ..."
   (5 9 font-lock-function-name-face)))

Indentation tests insert code, run indent-region, and assert the result matches the expected indentation:

1
2
3
4
(when-indenting-it "indents a match expression"
  "match x with"
  "| 0 -> \"zero\""
  "| n -> string_of_int n")

Integration tests load real source files and verify that both font-locking and indentation survive indent-region on the full file. This catches interactions between rules that unit tests miss.

neocaml has 200+ automated tests and clojure-ts-mode has even more. Investing in test infrastructure early pays off enormously – I can refactor indentation rules with confidence because the suite catches regressions immediately.

A personal story on testing ROI

When I became the maintainer of clojure-mode many years ago, I really struggled with making changes. There were no font-lock or indentation tests, so every change was a leap of faith – you’d fix one thing and break three others without knowing until someone filed a bug report. I spent years working on a testing approach I was happy with, alongside many great contributors, and the return on investment was massive.

The same approach – almost the same test macros – carried over directly to clojure-ts-mode when we built the Tree-sitter version. And later I reused the pattern again in neocaml and asciidoc-mode. One investment in testing infrastructure, four projects benefiting from it.

I know that automated tests, for whatever reason, never gained much traction in the Emacs community. Many popular packages have no tests at all. I hope stories like this convince you that investing in tests is really important and pays off – not just for the project where you write them, but for every project you build after.

Pre-compile queries

This one is specific to clojure-ts-mode but applies broadly: compiling Tree-sitter queries at runtime is expensive. If you’re building queries dynamically (e.g. with treesit-font-lock-rules called at mode init time), consider pre-compiling them as defconst values. This made a noticeable difference in clojure-ts-mode’s startup time.

A note on naming

The Emacs community has settled on a -ts-mode suffix convention for Tree-sitter-based modes: python-ts-mode, c-ts-mode, ruby-ts-mode, and so on. This makes sense when both a legacy mode and a Tree-sitter mode coexist in Emacs core – users need to choose between them. But I think the convention is being applied too broadly, and I’m afraid the resulting name fragmentation will haunt the community for years.

For new packages that don’t have a legacy counterpart, the -ts-mode suffix is unnecessary. I named my packages neocaml (not ocaml-ts-mode) and asciidoc-mode (not adoc-ts-mode) because there was no prior neocaml-mode or asciidoc-mode to disambiguate from. The -ts- infix is an implementation detail that shouldn’t leak into the user-facing name. Will we rename everything again when Tree-sitter becomes the default and the non-TS variants are removed?

Be bolder with naming. If you’re building something new, give it a name that makes sense on its own merits, not one that encodes the parsing technology in the package name.

The road ahead

I think the full transition to Tree-sitter in the Emacs community will take 3–5 years, optimistically. There are hundreds of major modes out there, many maintained by a single person in their spare time. Converting a mode from regex to Tree-sitter isn’t just a mechanical translation – you need to understand the grammar, rewrite font-lock and indentation rules, handle version compatibility, and build a new test suite. That’s a lot of work.

Interestingly, this might be one area where agentic coding tools can genuinely help. The structure of Tree-sitter-based major modes is fairly uniform: grammar recipes, font-lock rules, indentation rules, navigation settings, imenu. If you give an AI agent a grammar and a reference to a high-quality mode like clojure-ts-mode, it could probably scaffold a reasonable new mode fairly quickly. The hard parts – debugging grammar quirks, handling edge cases, getting indentation just right – would still need human attention, but the boilerplate could be automated.

Still, knowing the Emacs community, I wouldn’t be surprised if a full migration never actually completes. Many old-school modes work perfectly fine, their maintainers have no interest in Tree-sitter, and “if it ain’t broke, don’t fix it” is a powerful force. And that’s okay – diversity of approaches is part of what makes Emacs Emacs.

Closing thoughts

Tree-sitter is genuinely great for building Emacs major modes. The code is simpler, the results are more accurate, and incremental parsing means everything stays fast even on large files. I wouldn’t go back to regex-based font-locking willingly.

But it’s not magical. Grammars are inconsistent across languages, the Emacs APIs are still maturing, you can’t reuse .scm files (yet), and you’ll hit version-specific bugs that require tedious workarounds. The testing story is better than with regex modes – tree structures are more predictable than regex matches – but you still need a solid test suite to avoid regressions.

If you’re thinking about writing a Tree-sitter-based major mode, do it. The ecosystem needs more of them, and the experience of working with syntax trees instead of regexes is genuinely enjoyable. Just go in with realistic expectations, pin your grammar versions, test against multiple Emacs releases, and build your test suite early.

Anyways, I wish there was an article like this one when I was starting out with clojure-ts-mode and neocaml, so there you have it. I hope that the lessons I’ve learned along the way will help build better modes with Tree-sitter down the road.

That’s all I have for you today. Keep hacking!

The New Stack

Here’s what I recommend today:

• neocaml instead of tuareg-mode
• ocaml-eglot instead of merlin-mode
• Eglot (built into Emacs 29+) as the LSP client

The key shift is from Merlin’s custom protocol to LSP. ocaml-lsp-server has matured significantly since my original article – it’s no longer a thin wrapper around Merlin. It now offers project-wide renaming, semantic highlighting, Dune RPC integration, and OCaml-specific extensions like pattern match generation and typed holes. ocaml-eglot is a lightweight Emacs package by Tarides that bridges Eglot with these OCaml-specific LSP extensions, giving you the full Merlin feature set through a standardized protocol.

And neocaml is my own Tree-sitter-powered OCaml major mode – modern, lean, and built for the LSP era. You can read more about it in the 0.1 release announcement.

The Essentials

First, install the server-side tools:

1
$ opam install ocaml-lsp-server

You no longer need to install merlin separately – ocaml-lsp-server vendors it internally.

Then set up Emacs:

1
2
3
4
5
6
7
8
9
10
11
12
;; Modern Tree-sitter-powered OCaml major mode
(use-package neocaml
  :ensure t)

;; Major mode for editing Dune project files
(use-package dune
  :ensure t)

;; OCaml-specific LSP extensions via Eglot
(use-package ocaml-eglot
  :ensure t
  :hook (neocaml-mode . ocaml-eglot-setup))

That’s it. Eglot ships with Emacs 29+, so there’s nothing extra to install for the LSP client itself. When you open an OCaml file, Eglot will automatically start ocaml-lsp-server and you’ll have completion, type information, code navigation, diagnostics, and all the other goodies you’d expect.

Compare this to the old setup – no more merlin-mode, merlin-eldoc, flycheck-ocaml, or manual Company configuration. LSP handles all of it through a single, uniform interface.

The Toplevel

neocaml includes built-in REPL integration via neocaml-repl-minor-mode. The basics work well:

• C-c C-z – start or switch to the OCaml toplevel
• C-c C-c – send the current definition
• C-c C-r – send the selected region
• C-c C-b – send the entire buffer

If you want utop specifically, you’re still better off using utop.el alongside neocaml. Its main advantage is that you get code completion inside the utop REPL within Emacs – something neocaml’s built-in REPL integration doesn’t provide:

1
2
3
(use-package utop
  :ensure t
  :hook (neocaml-mode . utop-minor-mode))

This will shadow neocaml’s REPL keybindings with utop’s, which is the intended behavior.

That said, as I’ve grown more comfortable with OCaml I find myself using the toplevel less and less. These days I rely more on a test-driven workflow – write a test, run it, iterate. In particular I’m partial to the workflow described in this OCaml Discuss thread – running dune runtest continuously and writing expect tests for quick feedback. It’s a more structured approach that scales better than REPL-driven development, especially as your projects grow.

Give neocaml a Try

If you’re an OCaml programmer using Emacs, I’d love for you to take neocaml for a spin. It’s available on MELPA, so getting started is just an M-x package-install away. The project is still young and I’m actively working on it – your feedback, bug reports, and pull requests are invaluable. Let me know what works, what doesn’t, and what you’d like to see next.

That’s all I have for you today. Keep hacking!

1
M-x package-install <RET> neocaml <RET>

That’s quite the journey from “a fun experimental project” to a proper Emacs package!

Why neocaml?

You might be wondering what’s wrong with the existing options. The short answer - nothing is wrong per se, but neocaml offers a different set of trade-offs:

• caml-mode is ancient and barely maintained. It lacks many features that modern Emacs users expect and it probably should have been deprecated a long time ago.
• tuareg-mode is very powerful, but also very complex. It carries a lot of legacy code and its regex-based font-locking and custom indentation engine show their age. It’s a beast - in both the good and the bad sense of the word.
• neocaml aims to be a modern, lean alternative that fully embraces Tree-sitter. The codebase is small, well-documented, and easy to hack on. If you’re running Emacs 29+ (and especially Emacs 30), Tree-sitter is the future and neocaml is built entirely around it.

Of course, neocaml is the youngest of the bunch and it doesn’t yet match Tuareg’s feature completeness. But for many OCaml workflows it’s already more than sufficient, especially when combined with LSP support.

I’ve started the project mostly because I thought that the existing Emacs tooling for OCaml was somewhat behind the times - e.g. both caml-mode and tuareg-mode have features that are no longer needed in the era of ocamllsp.

Let me now walk you through the highlights of version 0.1.

Features

The current feature-set is relatively modest, but all the essential functionality one would expect from an Emacs major mode is there.

Tree-sitter-powered Syntax Highlighting

neocaml leverages Tree-sitter for syntax highlighting, which is both more accurate and more performant than the traditional regex-based approaches used by caml-mode and tuareg-mode. The font-locking supports 4 customizable intensity levels (controlled via treesit-font-lock-level, default 3), so you can pick the amount of color that suits your taste.

Both .ml (source) and .mli (interface) files get their own major modes with dedicated highlighting rules.

Tree-sitter-powered Indentation

Indentation has always been tricky for OCaml modes, and I won’t pretend it’s perfect yet, but neocaml’s Tree-sitter-based indentation engine is already quite usable. It also supports cycle-indent functionality, so hitting TAB repeatedly will cycle through plausible indentation levels - a nice quality-of-life feature when the indentation rules can’t fully determine the “right” indent.

If you prefer, you can still delegate indentation to external tools like ocp-indent or even Tuareg’s indentation functions. Still, I think most people will be quite satisfied with the built-in indentation logic.

Code Navigation and Imenu

neocaml provides proper structural navigation commands (beginning-of-defun, end-of-defun, forward-sexp) powered by Tree-sitter, plus imenu integration – navigating definitions in a buffer has never been easier.

The older modes provide very similar functionality as well, of course, but the use of Tree-sitter in neocaml makes such commands more reliable and robust.

REPL Integration

No OCaml mode would be complete without REPL (toplevel) integration. neocaml-repl-minor-mode provides all the essentials:

• C-c C-z - Start or switch to the OCaml REPL
• C-c C-c - Send the current definition
• C-c C-r - Send the selected region
• C-c C-b - Send the entire buffer
• C-c C-p - Send a phrase (code until ;;)

The default REPL is ocaml, but you can easily switch to utop via neocaml-repl-program-name.

I’m still on the fence on whether I want to invest time into making the REPL-integration more powerful or keep it as simple as possible. Right now it’s definitely not a big priority for me, but I want to match what the other older OCaml modes offered in that regard.

LSP Support

neocaml works great with Eglot and ocamllsp, automatically setting the appropriate language IDs for both .ml and .mli files. Pair neocaml with ocaml-eglot and you get a pretty solid OCaml development experience.

The creation of LSP really simplified the lives of major mode authors like me, as now many of the features that were historically major mode specific are provided by LSP clients out-of-the-box.

That’s also another reason why you probably want a leaner major mode like neocaml-mode.

Other Goodies

But, wait, there’s more!

• C-c C-a to quickly switch between .ml and .mli files
• Prettify-symbols support for common OCaml operators
• Automatic installation of the required Tree-sitter grammars via M-x neocaml-install-grammars
• Compatibility with Merlin for those who prefer it over LSP

The Road Ahead

There’s still plenty of work to do:

• Support for additional OCaml file types (e.g. .mld)
• Improvements to structured navigation using newer Emacs Tree-sitter APIs
• Improvements to the test suite
• Addressing feedback from real-world OCaml users
• Actually writing some fun OCaml code with neocaml

If you’re following me, you probably know that I’m passionate about both Emacs and OCaml. I hope that neocaml will be my way to contribute to the awesome OCaml community.

I’m not sure how quickly things will move, but I’m committed to making neocaml the best OCaml editing experience on Emacs. Time will tell how far I’ll get!

Give it a Try

If you’re an OCaml programmer using Emacs, I’d love for you to take neocaml for a spin. Install it from MELPA, kick the tires, and let me know what you think. Bug reports, feature requests, and pull requests are all most welcome on GitHub!

That’s all from me, folks! Keep hacking!

The Fun module provides a few basic combinators for working with functions. Let’s go over them briefly:

• Fun.id

  1
  Fun.id : 'a -> 'a
  

  The identity function: returns its single argument unchanged.

• Fun.const

  1
  Fun.const : 'a -> 'b -> 'a
  

  Returns a function that always returns the first argument, ignoring its second argument.

• Fun.compose

  1
  Fun.compose : ('b -> 'c) -> ('a -> 'b) -> 'a -> 'c
  

  Composes two functions, applying the second function to the result of the first. Haskell and F# have special syntax for function composition, but that’s not the case in OCaml. (although you can easily map this to some operator if you wish to do so) Also, compose was introduced a bit later than the other functions in the module - namely in OCaml 5.2.

• Fun.flip

  1
  Fun.flip : ('a -> 'b -> 'c) -> 'b -> 'a -> 'c
  

  Reverses the order of arguments to a two-argument function.

• Fun.negate

  1
  Fun.negate : ('a -> bool) -> 'a -> bool
  

  Negates a boolean-returning function, returning the opposite boolean value. Useful when you want to provide a pair of inverse predicates (e.g. is_positive and is_negative)

I believe that those functions are pretty self-explanatory, but still below we’ll go over a few examples of using them:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
(* Fun.id *)
Fun.id 42
(* 42 *)

(* Fun.const *)
let always_hello = Fun.const "hello"
always_hello 12345
(* "hello" *)

(* Fun.flip *)
let subtract a b = a - b
let flipped_subtract = Fun.flip subtract
flipped_subtract 2 10
(* 8 *)

(* Fun.negate *)
let is_odd = negate is_even
is_odd 5
(* true *)

(* Fun.compose *)
let comp_f = Fun.compose (fun x -> x * x) (fun x -> x + 1)
comp_f 5
(* 36 *)

Admittedly the examples are not great, but I hope they managed to convey how to use the various combinators.

Those are definitely not the type of functions that you would use every day, but they can be useful in certain situations. Obviously I needed id at some point to discover the Fun module in the first place, and all of the functions there can be considered “classic” combinators in functional programming.

In practice most often I need id and negate, and infrequently comp and const. Right now I’m struggling to come up with good use-cases for flip, but I’m sure those exist. Perhaps you’ll share some examples in the comments?

How often do you use the various combinators? Which ones do you find most useful?

I find myself wondering if such fundamental functions shouldn’t have been part of Stdlib module directly, but overall I really like the modular standard library approach that OCaml’s team has been working towards in the past several years.² The important thing in the end of the day is to know that these functions exist and you can make use of them. Writing this short article will definitely help me to remember this.

That’s all I have for you today. Keep hacking!