UTOP(1)

NAME
utop - Universal toplevel for OCaml

SYNOPSIS
utop [ options ] [ object-files ] [ script-file ]

DESCRIPTION

utop is an enhanced toplevel for OCaml with many features, including context sensitive completion.

When you start utop what you see is the prompt followed by a bar containing words. This is the completion bar: it contains the possible completion and is updated as you type. The highlighted word in the completion bar is the selected word. You can navigate using the keys M-Left and M-Right and select one completion using M-down. Here M represents the meta key, which is Alt on most systems. You can configure these bindings in the file ~/.config/lambda-term-inputrc - see lambda-term-inputrc(5) for details.

utop supports completion on:

        * directives and directive arguments
        * identifiers
        * record fields
        * variants
        * function labels
        * object methods

Colors are by default configured for terminals with dark colors, such as white on black, so the prompt may look too bright on light-colored terminals. You can change that by setting the color profile of utop. To do that, type:

        UTop.set_profile UTop.Light;;

You can then add this line to your ~/.config/utop/init.ml file.

To turn off utop's advanced prompt features, add the following to init.ml to turn off respectively (a) colors and the upper information line, and (b) the lower boxed list of possible completions:

        #utop_prompt_dummy;;
        UTop.set_show_box false

You can enable basic syntax highlighting in utop by writing a ~/.utoprc file. See utoprc(5) for that.

Vi edit mode is enabled by the command

        #edit_mode_vi

It currently supports three vi modes: normal, insert, visual mode, and you can get/set content with vim-like registers.

utop.el is a package that provides utop integration with Emacs. The package allows you to run utop inside Emacs and to evaluate code in it straight from your source buffers (with the help of utop-minor-mode). The recommended way to install utop.el is via Emacs's built-in package manager package.el. More detailed installation and configuration instructions may be found on the project's code repository at https://github.com/ocaml-community/utop.

You can start utop inside Emacs with M-x utop.

The default install also has a minor mode with the following key bindings:

        C-c C-s Start a utop buffer (utop)
        C-x C-e Evaluate the current phrase (utop-eval-phrase)
        C-x C-r Evaluate the selected region (utop-eval-region)
        C-c C-b Evaluate the current buffer (utop-eval-buffer)
        C-c C-k Kill a running utop process (top-kill)
        C-c C-z Switch to utop process (utop-switch-to-repl)

then you can run utop by pressing M-x and typing "utop". utop supports completion in Emacs mode. Just press Tab to complete a word. You can also integrate it with the tuareg, caml or typerex mode. For that add the following lines to your ~/.emacs file:

        (autoload 'utop-minor-mode "utop" "Minor mode for utop" t)
        (add-hook 'tuareg-mode-hook 'utop-minor-mode)

OPTIONS
See utop --help for the full list of available options. There is considerable overlap with options available for ocaml(1).

A commonly used option is -require package to load package into the execution environment. It is equivalent to using #require from inside utop(1).

-absname
    Show absolute filenames in error message.

-I dir
    Add dir to the list of include directories.

-init file
    Load file instead of the default init file.

-labels
    Use commuting label mode.

-no-app-funct
    Deactivate applicative functors.

-noassert
    Do not compile assertion checks.

-nolabels
    Ignore non-optional labels in types.

-nostdlib
    Do not add the default directory to the list of include directories.

-ppx command
    Pipe abstract syntax trees through the preprocessor command.

-principal
    Check principality of type inference.

-safe-string
    Make strings immutable.

-short-paths
    Shorten paths in types (the default).

-no-short-paths
    Do not shorten paths in types.

-rectypes
    Allow arbitrary recursive types.

-stdin
    Read script from standard input.

-strict-sequence
    Left-hand part of a sequence must have type unit.

-unsafe
    Do not compile bounds checking on array and string access.

-version
    Print version and exit.

-vnum
    Print version number and exit.

-w list
    Enable or disable warnings according to list.

-warn-error list
    Enable or disable error status for warnings according to list. See option -w for the syntax of list. Default setting is -a+31.

-warn-help
    Show description of warning numbers.

-emacs
    Run in emacs mode.

-hide-reserved
    Hide identifiers starting with a '_' (the default).

-show-reserved
    Show identifiers starting with a '_'.

-no-implicit-bindings
    Don't add implicit bindings for expressions (the default).

-implicit-bindings
    Add implicit bindings: expr;; -> let _0 = expr;;

-no-autoload
    Disable autoloading of files in $OCAML_TOPLEVEL_PATH/autoload.

-require package
    Load this package.

-dparsetree
    Dump OCaml AST after rewriting.

-dsource
    Dump OCaml source after rewriting.

-help
    Display this list of options.

--help
    Display this list of options.

FILES
~/.config/utop/init.ml
    The initialization file of the toplevel.
~/.ocamlinit
    The alternative initialization file of the toplevel.
~/.utoprc
    The configuration file for utop. See utoprc(5).
~/.config/lambda-term-inputrc
    The file containing key bindings. See lambda-term-inputrc(5).

AUTHOR
Jérémie Dimino <jeremie@dimino.org>

SEE ALSO
utoprc(5), lambda-term-inputrc(5), ocaml(1).