OCamlSpotter : OCaml source browsing
Camel spotter: Oh, it was extremely interesting, very, very -
quite... it was dull; dull, dull, dull, oh God it was dull.
Sitting in the Waterloo waiting room. ...
from You're No Fun Anymore,
Monty Python's Flying Circus
OCaml module language is powerful. So extremely powerful that you can
be lost yourself easily inside a huge OCaml project with tons of
modules and functors. Spotting the definition of a variable is
sometimes "extremely interesting". Let's see such an example:
let _ = f 1
Suppose you are not familiar with the function f and want to spot its
definition. Where to find it? Just from the code you are looking at,
it is not sure: if you are enough lucky it may be f in m.ml, n.ml or
o.ml in your current working directory. Otherwise, it may be O.f in
n.ml. Or probably N.O.f in m.ml. If you are unlucky and the project is
so sophisticated, there could be complex module operations in m.ml
(i.e includes, functor applications) and therefore the definition
might be found somewhere completely unexpected. Module packing, module
load paths and library installation without .ml files complicate the
situation even worse.
You first days after joining a large OCaml project should be this kind
of manual value definition spotting with find + grep commands. Yes,
actually it is very educational: you can learn a lot about the project
struggling in the source tree (only if your collegues have organized
things very well :-P), but it is still a dull job...
To say short, OCamlSpotter is a tool which does this dull job
automatically for you and permits your energy for something more
"interesting" like Yeti spotting:
- The -annot option of ocamlc and ocamlopt is extended and creates
<module>.spot files (<module>.spit for .mli), which record the
location information of the names defined and used in the module.
- A small application ocamlspot provides automatic where-about
spotting of the definition of the name you are interested in.
- ocamlspot.el provides interactive ocaml-spotting of definition
locations in emacs.
- Interfaces for other editors such as vi can be built easily, if you
want. I do not want.
Spotting / Definition analysis
search ::= [file] | [file]:[pos] | [file]:[kind]:[path]
pos ::= l[line]c[column_bytes] | b[bytes] | [bytes]
kind ::= v|t|e|m|mt|c|ct
Retrieve various annotation information from .spot or .spit files
of the source code position or identifier, specified by the
search spec. Information is prited to stdout. They are:
The definition position of the object which the search spec
points to, if available.
The type of the object which the search spec points to, if
available. In XType, paths are printed with position
informaiton: for example, "unit__6" instead of "unit".
Three kinds of searches are available: file-name-only,
by-position and by-path:
File-name-only search show the position independent information
of the module specified by [file].
$ ocamlspot -i ocamlspot.ml
Compile: ../ocamlc -nostdlib -I ../stdlib -annot -annot -w Ae -warn-error Ae -I ../parsing -I ../utils -I ../typing -I ../driver -I ../bytecomp -I ../tools -I ../toplevel/ -I ../otherlibs/unix -c ocamlspot.ml
By-position search has the form [file]:[pos]. [file] is the path
of the target ml/mli file and [pos] is the position in the
target file. [pos] has three formats: l[line]c[column_bytes] by the
line number and column bytes, b[bytes] (and [bytes] for backward
compatibility) by the bytes from the beginning of the source
$ ocamlspot ocamlspot.ml:l129c14
Tree: l129c8b4035:l129c28b4055 # pos of the inner most node
Use: Type, Path__360.t__G
XType: Path__360.t__G # type with ident id numbers
Spot: /..../ocaml/typing/path.ml:l15c5b875:l18c19b949 # the definition
Note that bytes are not chars in multi-byte-character
environment. OCaml is completely free from such mess and you
might need to count chars by yourself.
By-path search shows the definition spot of the given path
with ident id numbers. It will be useful with conjunction with
the path names obtained from XType: fields. No fancy elisp wrapper
is not available for it, though.
# checking a type named Path__360.t__G
$ ocamlspot ocamlspot.ml:t:Path__360.t__G
Skips the spotting, which may takes time. Useful if you are
interested in other things than the definition analysis,
i.e. types, paths, etc.
Bugs and future works
This software contain lots of bugs and todos.
Read LICENSE file in this directory.
Jun FURUSE (email@example.com). Bug reports and comments are
welcome. Patches are appreciated. Donating camel related gadgets is
the most wonderful. Complaints might be simply ignored.