Chapter 14 The browser/editor (ocamlbrowser)
This chapter describes OCamlBrowser, a source and compiled interface
browser, written using LablTk. This is a useful companion to the
programmer.
Its functions are:
-
navigation through OCaml’s modules (using compiled interfaces).
- source editing, type-checking, and browsing.
- integrated OCaml shell, running as a subprocess.
14.1 Invocation
The browser is started by the command ocamlbrowser, as follows:
ocamlbrowser options
The following command-line options are recognized by ocamlbrowser.
- -I directory
-
Add the given directory to the list of directories searched for
source and compiled files. By default, only the standard library
directory is searched. The standard library can also be changed by
setting the OCAMLLIB environment variable.
- -nolabels
-
Ignore non-optional labels in types. Labels cannot be used in
applications, and parameter order becomes strict.
- -oldui
-
Old multi-window interface. The default is now more like Smalltalk’s
class browser.
- -rectypes
-
Allow arbitrary recursive types during type-checking. By default,
only recursive types where the recursion goes through an object type
are supported.
- -version
-
Print version string and exit.
- -vnum
-
Print short version number and exit.
- -w warning-list
-
Enable or disable warnings according to the argument warning-list.
Most options can also be modified inside the application by the Modules - Path editor and Compiler - Preferences commands.
They are inherited when you start a toplevel shell.
14.2 Viewer
This is the first window you get when you start OCamlBrowser.
It displays a search window, and the list of modules in the load path.
At the top a row of menus.
-
File - Open and File - Editor give access to the
editor.
- File - Shell creates an OCaml subprocess in a shell.
- View - Show all defs displays the signature of the currently
selected module.
- View - Search entry shows/hides the search entry just
below the menu bar.
- Modules - Path editor changes the load path. Modules
- Reset cache rescans the load path and resets the module cache.
Do it if you recompile some interface, or get confused about what is
in the cache.
- Modules - Search symbol allows searching a symbol either
by its name, like the bottom line of the viewer, or more
interestingly, by its type. Exact type searches for a type
with exactly the same information as the pattern (variables match
only variables). Included type allows giving only partial
information: the actual type may take more arguments and return more
results, and variables in the pattern match anything. In both cases,
argument and tuple order is irrelevant1,
and unlabeled arguments in the pattern match any label.
- The Search entry just below the menu bar allows one to
search for an identifier in all modules (wildcards “?” and “*”
allowed). If you choose the type option, the search is done by type
inclusion (cf. Search Symbol - Included type).
- The Close all button is there to dismiss the windows
created by the Detach button.
By double-clicking on it you will quit the browser.
14.3 Module browsing
You select a module in the leftmost box by either cliking on it or
pressing return when it is selected. Fast access is available in all
boxes pressing the first few letter of the desired name.
Double-clicking / double-return displays the whole signature for the
module.
Defined identifiers inside the module are displayed in a box to the
right of the previous one. If you click on one, this will either
display its contents in another box (if this is a sub-module) or
display the signature for this identifier below.
Signatures are clickable. Double clicking with the left mouse
button on an identifier in a signature brings you to its signature.
A single click on the right button pops up a menu displaying the
type declaration for the selected identifier. Its title, when
selectable, also brings you to its signature.
At the bottom, a series of buttons, depending on the context.
-
Detach copies the currently displayed signature in a new window,
to keep it.
- Impl and Intf bring you to the implementation or
interface of the currently displayed signature, if it is available.
Control-S lets you search a string in the signature.
14.4 File editor
You can edit files with it, if you’re not yet used to emacs. Otherwise
you can use it as a browser, making occasional corrections.
The Edit menu contains commands for jump (C-g), search (C-s),
and sending the current phrase (or selection if some text is selected)
to a sub-shell (M-x). For this last option, you may choose the shell
via a dialog.
Essential functions are in the Compiler menu.
-
Preferences opens a dialog to set internals of the editor
and type-checker.
- Lex adds colors according to lexical categories.
- Typecheck verifies typing, and memorizes to let one see an
expression’s type by double-clicking on it. This is also valid for
interfaces. If an error occurs, the part of the interface preceding
the error is computed.
After typechecking, pressing the right button pops up a menu that gives
the type of the pointed expression and, where applicable, provides
some links that can be followed.
- Clear errors dismisses type-checker error messages and warnings.
- Signature shows the signature of the current file
(after type checking).
14.5 Shell
When you create a shell, a dialog is presented to you, letting you
choose which command you want to run, and the title of the shell (to
choose it in the Editor).
The executed subshell is given the current load path.
-
File use a source file or load a bytecode file. You may
also import the browser’s path into the subprocess.
- History M-p and M-n browse up and down.
- Signal C-c interrupts, and you can also kill the subprocess.