The toplevel system (csltop)

This chapter describes the toplevel system for Caml Special Light, that permits interactive use of the Caml Special Light 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.

A toplevel phrase can span several lines. It is terminated by ;; (a double-semicolon). The syntax of toplevel phrases is as follows:

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 ), or a value expression (section ). 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 .

The toplevel system is started by the command csltop. Phrases are read on standard input, results are printed on standard output, errors on standard error. End-of-file on standard input terminates csltop (see also the #quit directive in section ).

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 csltop or fep -vi csltop. Another option is to use csltop under Gnu Emacs, which gives the full editing power of Emacs (see the camlmode package distributed with Caml Light 0.7).

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 csltop process). The toplevel then immediately returns to the # prompt.

Options

The following command-line options are recognized by the csltop command.

-I directory
Add the given directory to the list of directories searched for source and compiled files. By default, the current directory is searched first, then the standard library directory. Directories added with -I are searched after the current directory, in the order in which they were given on the command line, but before the standard library directory.

Directories can also be added to the search path once the toplevel is running with the #directory directive (section ).

-unsafe
See the corresponding option for cslc, chapter . Turn bound checking off on array and string accesses (the v.(i) and s.[i] constructs). Programs compiled with -unsafe are therefore slightly faster, but unsafe: anything can happen if the program accesses an array or string outside of its bounds.

The following environment variables are also consulted:

LC_CTYPE
If set to iso_8859_1, accented characters (from the ISO Latin-1 character set) in string and character literals are printed as is; otherwise, they are printed as decimal escape sequences (\ddd).

TERM
When printing error messages, the toplevel system attempts to underline visually the location of the error. It consults the TERM variable to determines the type of output terminal and look up its capabilities in the terminal database.

Toplevel directives

The following directives control the toplevel behavior, load files in memory, and trace program execution.

#quit;;
Exit the toplevel loop and terminate the csltop command.

#directory "dir-name";;
Add the given directory to the list of directories searched for source and compiled files.

#cd "dir-name";;
Change the current working directory.

#load "file-name";;
Load in memory a bytecode object file (.cmo file) produced by the batch compiler cslc.

#use "file-name";;
Read, compile and execute source phrases from the given file. This is textual inclusion: phrases are processed just as if they were typed on standard input. The reading of the file stops at the first error encountered.

#install_printer printer-name;;
This directive registers the function named printer-name (a value path) as a printer for objects whose types match the argument type of the function. That is, the toplevel loop will call printer-name when it has such an object to print. The printing function printer-name must use the Format library module to produce its output, otherwise its output will not be correctly located in the values printed by the toplevel loop.

#remove_printer printer-name;;
Remove the named function from the table of toplevel printers.

#trace function-name;;
After executing this directive, all calls to the function named function-name will be ``traced''. That is, the argument and the result are displayed for each call, as well as the exceptions escaping out of the function, raised either by the function itself or by another function it calls. If the function is curried, each argument is printed as it is passed to the function.

#untrace function-name;;
Stop tracing the given function.

#untrace_all;;
Stop tracing all functions traced so far.

#print_depth n;;
Limit the printing of values to a maximal depth of n. The parts of values whose depth exceeds n are printed as ... (ellipsis).

#print_length n;;
Limit the number of value nodes printed to at most n. Remaining parts of values are printed as ... (ellipsis).

The toplevel and the module system

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 ).

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.

Common errors

This section describes and explains the most frequently encountered error messages.

Cannot find file filename
The named file could not be found in the current directory, nor in the directories of the search path.

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.

This expression has type t1, but is used with type t2
See section .

Reference to undefined global mod
You have neglected to load in memory an implementation for a module with #load. See section above.

Building custom toplevel systems: cslmktop

The cslmktop command builds Caml Special Light toplevels that contain user code preloaded at start-up.

The cslmktop command takes as argument a set of .cmo and .cma files, and links them with the object files that implement the Caml Special Light toplevel. The typical use is: 

        cslmktop -o mytoplevel foo.cmo bar.cmo gee.cmo
This creates the bytecode file mytoplevel, containing the Caml Special Light toplevel system, plus the code from the three .cmo files. This toplevel is directly executable and is started by: 
        ./mytoplevel
This 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.

Options

The following command-line options are recognized by cslmktop.

-cclib libname
Pass the -llibname option to the C linker when linking in ``custom runtime'' mode. See the corresponding option for cslc, in chapter .

-ccopt option
Pass the given option to the C compiler and linker, when linking in ``custom runtime'' mode. See the corresponding option for cslc, in chapter .

-custom
Link in ``custom runtime'' mode. See the corresponding option for cslc, in chapter .

-I directory
Add the given directory to the list of directories searched for compiled object code files (.cmo and .cma).

-o exec-file
Specify the name of the toplevel file produced by the linker. The default is a.out.