ocaml-merlin#

Clean interface for OCaml Merlin operations.

Overview#

This library provides a backend-agnostic interface for querying Merlin, the OCaml editor service. It supports both process-based (subprocess) and library-based (merlin-lib) backends, allowing the same code to work in different deployment scenarios.

The primary use case is building tools that need structured access to OCaml source code -- linters, documentation generators, refactoring tools, and IDE integrations.

Installation#

opam install ocaml-merlin

Basic Usage#

Extracting File Outline#

open Ocaml_merlin

let () =
  let backend = Backend.subprocess () in
  match outline backend ~filename:"lib/main.ml" with
  | Ok items ->
      List.iter (fun item ->
        Fmt.pr "%s: %a@." item.name pp_symbol_kind item.kind
      ) items
  | Error e ->
      Fmt.epr "Error: %s@." e

Finding Occurrences#

let () =
  let backend = Backend.subprocess () in
  let pos = { line = 10; col = 5 } in
  match occurrences backend ~filename:"lib/main.ml" ~pos with
  | Ok locs ->
      List.iter (fun loc -> Fmt.pr "%a@." pp_location loc) locs
  | Error e ->
      Fmt.epr "Error: %s@." e

Outline Structure#

The outline represents the hierarchical structure of an OCaml file:

type outline_item = {
  name : string;
  kind : symbol_kind;
  type_sig : string option;
  deprecated : bool;
  location : location;
  children : outline_item list;
}

Symbol Kinds#

Outline Utilities#

(* Flatten nested outline to list *)
let all_items = flatten_outline outline

(* Filter by kind *)
let all_values = values outline
let all_types = types outline
let all_modules = modules outline

Limitations#

• The subprocess backend requires ocamlmerlin to be installed and in PATH
• AST dump parsing covers common cases but may not handle all Merlin output variants
• Performance depends on Merlin's response time, which varies with project size

Licence#

ISC