package ocamlgrep

Structural search of OCaml code

ocamlgrep is a command-line tool written at LexiFi to perform structural search of OCaml code.

The code is released as-is in case it is of interest to the community. The present code is extracted from a version used internally at LexiFi and we do not pretend that it is ready for public consumption, but we are making the code available to publicize the approach.

Compilation

dune build

The tool requires OCaml 5.2 (since it depends on compiler-libs, compilation aginst other versions of OCaml will require some adjustments).

This produces an executable _build/install/bin/ocamlgrep.exe which can be run from the command line.

Usage

ocamlgrep PATTERN

The tool assumes that it is executed within a Dune workspace, as it has a number of heuristics that will not work otherwise. The tool will search the files under the current directory subtree.

You will need to run dune build @check in your project to ensure all .cmt files are up-to-date before using ocamlgrep.

PATTERN: The pattern to search for. This should be a valid OCaml expression.

• The wildcard __ matches any expression or any record field.
• A numbered wildcard __1, __2, ... matches any expression or record field and enforce strict equality of all the matching occurrences for the same number.
• An identifier (value or class) is matched as a suffix of the fully qualified path in the typed expression.
• Labels and constructors identifiers are matched as a suffix of the identifier in the typed expression.

• For function applications, it is allowed to omit in the pattern any argument of the actual function call; special forms are recognized to enforce that a given optional argument present or missing:

    foo ?arg:PRESENT
  foo ?arg:MISSING

• Applications written with the operators |> and @@ of the standard library, or with explicit parentheses, are matched as plain applications: x |> f a, f a @@ x and (f a) x in the code are all matched as f a x. In the pattern, x |> f a and f a @@ x match either an application of an operator with the same name (which can be defined locally in the code) or f a x.
• Anonymous functions are matched one parameter at a time (labels included), so that fun p1 p2 -> e and fun p1 -> fun p2 -> e are equivalent, and an unlabeled parameter fun p -> e is equivalent to the single clause function p -> e (as for other function expressions, a single clause of the pattern can match several clauses of the code). For instance, fun __ -> __ matches fun x y -> e and function Some x -> e1 | None -> e2. An optional parameter without a default value in the pattern also matches one with a default value in the code.
• An expression (... : typexpr) matches any expression matching ... and whose type is equal to typexpr.
• For try..with/match..with/functions expressions, the order of clauses doesn't matter. A single clause of the searched expression can match several clauses of the code. Same set-semantics for record expressions.
• An expression e1.lid1 matches e2.lid2 <- e3 if e1 matches e2 and the label lid1 matches lid2.
• The expression __.id matches any pattern of the form {...; P.id; ...} for any prefix P. This rule was added so that grepping for __.foo will return every "get" and "set" of the record field foo, including reads in patterns.

Examples

ocamlgrep 'List.filter'
ocamlgrep '(__ (__ : floatarray): float array)'
ocamlgrep  'List.rev __ @ __'
ocamlgrep 'match __ with None -> __ | Some __1 -> Some __1'
ocamlgrep 'List.fold_left __ __ (List.map __ __)'
ocamlgrep 'Stdlib.max (__:float) __'