What is the OCaml toplevel?

Many OCaml guides and tutorials refer to the OCaml toplevel, but what exactly is this thing? In short, the toplevel is OCaml’s Read-Eval-Print-Loop (repl) allowing interative use of the OCaml system. You can consider the toplevel an alternative to compiling OCaml into an executable. In this mode, the OCaml system is configured to repeatedly read phrases from input, typecheck, compile, and evaluate them, then print the inferred type and result value.

Any input into the toplevel can span several lines and we terminate toplevel statements with a double-semicolon (;;).

Starting the toplevel

If you have an OCaml system installed you can start a toplevel environment by typing ocaml at a command prompt. You can check that it is working by doing some basic math. The toplevel system prints a # prompt before reading your input.

1
2
3
$ ocaml
# 3 + 4;;
- : int = 7

Starting utop

utop provides an improved interactive to the OCaml toplevel. It supports command history, macro expansion, module completion, and other additions that make OCaml programming easier. After installing UTop you can start it with the utop command to start the interactive environment. When you start typing a command from the utop prompt, you will see automatic completions being presented. Press tab at any time to select a completion.

Using the toplevel

When you start a new toplevel session, no code is loaded — you begin with a complete blank slate which isn’t very interesting. Where this becomes useful is testing code you’ve written and exploring code written by others. To load an OCaml module installed through opam in the toplevel, use the open command:

1
# open Base;;

By opening Base, we make the definitions it contains available without having to reference Base explicitly. You can do the same for any modules you’ve written in two different ways. First, you can use the #use command to directly include the file into the toplevel. For example, if I have the file hello_ocaml.ml that simply encodes a message:

1
2
16:38 $ cat hello_ocaml.ml
let message = "Hello OCaml!"

I can directly include that in the toplevel with #use. The message variable declared in the file becomes available to the toplevel.

1
2
3
4
5
utop # #use "hello_ocaml.ml";;
val message : string = "Hello OCaml!"
-( 16:36:37 )-< command 7 >-----------------------------{ counter: 0 }-
utop # message;;
- : string = "Hello OCaml!"

To include the file as a module, rather than directly, use the #mod_use command. In this case, the message variable is available to us prefixed by the module name we loaded (which is the file name with a uppercase first letter).

1
2
3
4
5
utop # #mod_use "hello_ocaml.ml";;
module Hello_ocaml : sig val message : string end
-( 16:47:26 )-< command 1 >-----------------------------{ counter: 0 }-
utop # Hello_ocaml.message;;
- : string = "Hello OCaml!"

Lastly, you can compile your file into bytecode, and load the associated bytecode into the toplevel through the #load command.

1
2
3
4
5
6
7
$ ocamlc -c hello_ocaml.ml  # compiles hello_ocaml.ml into hello_caml.cmo
$ utop  # start utop
-( 16:50:10 )-< command 0 >-----------------------------{ counter: 0 }-
utop # #load "hello_ocaml.cmo";;
-( 16:50:11 )-< command 1 >-----------------------------{ counter: 0 }-
utop # Hello_ocaml.message;;
- : string = "Hello OCaml!"

This should get you started using the Ocaml toplevel to interact with your code.

See also

comments powered by Disqus