This chapter describes the toplevel system for Objective Caml, that permits interactive use of the Objective Caml system through a read-eval-print loop. In this mode, the system repeatedly reads Caml phrases from the input, then typechecks, compile and evaluate them, then prints the inferred type and result value, if any. The system prints a # (sharp) prompt before reading each phrase.
Input to the toplevel can span several lines. It is terminated by ;; (a double-semicolon). The toplevel input consists in one or several toplevel phrases, with the following syntax:
toplevel-input: {toplevel-phrase};;
toplevel-phrase: definition | expr |#
ident directive-argument definition:let
[rec
] let-binding {and
let-binding} |external
value-name:
typexpr=
external-declaration | type-definition | exception-definition |module
module-name [:
module-type]=
module-expr |module
type
modtype-name=
module-type |open
module-path directive-argument: nothing | string-literal | integer-literal | value-path
A phrase can consist of a definition, similar to those found in
implementations of compilation units or in struct
...end
module expressions. The definition can bind value names, type names,
an exception, a module name, or a module type name. The toplevel
system performs the bindings, then prints the types and values (if
any) for the names thus defined.
A phrase may also consist in a open directive (see section 5.12), or a value expression (section 5.8). Expressions are simply evaluated, without performing any bindings, and the value of the expression is printed.
Finally, a phrase can also consist in a toplevel directive, starting with # (the sharp sign). These directives control the behavior of the toplevel; they are listed below in section 8.2.
The toplevel system does not perform line editing, but it can easily be used in conjunction with an external line editor such as fep; just run fep -emacs ocaml or fep -vi ocaml. Another option is to use ocaml under Gnu Emacs, which gives the full editing power of Emacs (see the subdirectory emacs of the Objective Caml distribution).
At any point, the parsing, compilation or evaluation of the current phrase can be interrupted by pressing ctrl-C (or, more precisely, by sending the intr signal to the ocaml process). The toplevel then immediately returns to the # prompt.
The ``Terminal'' windows is split in two panes. Phrases are entered and edited in the bottom pane. The top pane displays a copy of the input phrases as they are processed by the Caml Light toplevel, interspersed with the toplevel responses. The ``Return'' key sends the contents of the bottom pane to the Caml Light toplevel. The ``Enter'' key inserts a newline without sending the contents of the Input window. (This can be configured with the ``Preferences'' menu item.)
The contents of the input window can be edited at all times, with the standard Windows interface. An history of previously entered phrases is maintained and displayed in a separate window.
To quit the Camlwin application, either select ``Quit'' from the ``File'' menu, or use the quit function described below.
At any point, the parsing, compilation or evaluation of the current phrase can be interrupted by selecting the ``Interrupt Caml Light'' menu item. This goes back to the # prompt.
The following command-line options are recognized by the ocaml command.
Directories can also be added to the search path once the toplevel is running with the #directory directive (section 8.2).
The following environment variables are also consulted:
The following directives control the toplevel behavior, load files in memory, and trace program execution.
Toplevel phrases can refer to identifiers defined in compilation units with the same mechanisms as for separately compiled units: either by using qualified names (modulename.localname), or by using the open construct and unqualified names (see section 5.4).
However, before referencing another compilation unit, an implementation of that unit must be present in memory. At start-up, the toplevel system contains implementations for all the modules in the the standard library. Implementations for user modules can be entered with the #load directive described above. Referencing a unit for which no implementation has been provided results in the error ``Reference to undefined global `...'''.
Note that entering open mod merely accesses the compiled interface (.cmi file) for mod, but does not load the implementation of mod, and does not cause any error if no implementation of mod has been loaded. The error ``reference to undefined global mod'' will occur only when executing a value or module definition that refers to mod.
This section describes and explains the most frequently encountered error messages.
If filename has the format mod.cmi, this means you have referenced the compilation unit mod, but its compiled interface could not be found. Fix: compile mod.mli or mod.ml first, to create the compiled interface mod.cmi.
If filename has the format mod.cmo, this means you are trying to load with #load a bytecode object file that does not exist yet. Fix: compile mod.ml first.
If your program spans several directories, this error can also appear because you haven't specified the directories to look into. Fix: use the #directory directive to add the correct directories to the search path.
The ocamlmktop command builds Objective Caml toplevels that contain user code preloaded at start-up.
The ocamlmktop command takes as argument a set of .cmo and .cma files, and links them with the object files that implement the Objective Caml toplevel. The typical use is:
ocamlmktop -o mytoplevel foo.cmo bar.cmo gee.cmoThis creates the bytecode file mytoplevel, containing the Objective Caml toplevel system, plus the code from the three .cmo files. This toplevel is directly executable and is started by:
./mytoplevelThis enters a regular toplevel loop, except that the code from foo.cmo, bar.cmo and gee.cmo is already loaded in memory, just as if you had typed:
#load "foo.cmo";; #load "bar.cmo";; #load "gee.cmo";;on entrance to the toplevel. The modules Foo, Bar and Gee are not opened, though; you still have to do
open Foo;;yourself, if this is what you wish.
The following command-line options are recognized by ocamlmktop.