\" utop.1
\" ------
\" Copyright : (c) 2011, Jeremie Dimino <jeremie@dimino.org>
\" Licence   : BSD3
\"
\" This file is a part of utop.

.TH UTOP 1 "August 2011"

.SH NAME
utop \- Universal toplevel for OCaml

.SH SYNOPSIS
.B utop
[
.I options
]
[
.I object-files
]
[
.I script-file
]

.SH DESCRIPTION

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

When you start
.B 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 Alt+Left and Alt+Right
and you can complete using the currently selected word by pressing
Alt+Tab (you can configure these bindings in the file
.I ~/.config/lambda-term-inputrc
, see
.BR 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 looks too bright on light colors
terminals. You can change that by setting the color profile of
utop. For that type:

        UTop.set_profile UTop.Light;;

You can then add this line to your
.I ~/.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
.I ~/.utoprc
file. See
.BR utoprc (5)
for that.

Finally utop can run in emacs. For that you have to add the following line to your
.I ~/.emacs
file:

        (autoload 'utop "utop" "Toplevel for OCaml" t)

then you can run utop by pressing M-x and typing "utop". utop support
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
.I ~/.emacs
file:

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

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

A commonly used option is
\fB-require\fI package\fR
to load \fIpackage\fR into the execution environment. It is equivalent
to using \fb#require\fR from inside
.BR utop (1).

.PP
.TP
.BI -absname
Show absolute filenames in error message.
.TP
.BI -I " dir"
Add \fIdir\fR to the list of include directories.
.TP
.BI -init " file"
Load \fIfile\fR instead of default init file.
.TP
.BI -labels
Use commuting label mode.
.TP
.BI -no-app-funct
Deactivate applicative functors.
.TP
.BI -noassert
Do not compile assertion checks.
.TP
.BI -nolabels
Ignore non-optional labels in types.
.TP
.BI -nostdlib
Do not add default directory to the list of include directories.
.TP
.BI -ppx " command"
Pipe abstract syntax trees through preprocessor \fIcommand\fR.
.TP
.BI -principal
Check principality of type inference.
.TP
.BI -safe-string
Make strings immutable.
.TP
.BI -short-paths
Shorten paths in types (the default).
.TP
.BI -no-short-paths
Do not shorten paths in types.
.TP
.BI -rectypes
Allow arbitrary recursive types.
.TP
.BI -stdin
Read script from standard input.
.TP
.BI -strict-sequence
Left-hand part of a sequence must have type unit.
.TP
.BI -unsafe
Do not compile bounds checking on array and string access.
.TP
.BI -version
Print version and exit.
.TP
.BI -vnum
Print version number and exit.
.TP
.BI -w " list"
Enable or disable warnings according to \fIlist\fR.
.TP
.BI -warn-error " list"
Enable or disable error status for warnings according to \fIlist\fR.
See option \fB-w\fR for the syntax of \fIlist\fR.
Default setting is \fB-a+31\fR.
.TP
.BI -warn-help
Show description of warning numbers.
.TP
.BI -emacs
Run in emacs mode.
.TP
.BI -hide-reserved
Hide identifiers starting with a '_' (the default).
.TP
.BI -show-reserved
Show identifiers starting with a '_'.
.TP
.BI -no-implicit-bindings
Don't add implicit bindings for expressions (the default).
.TP
.BI -implicit-bindings
Add implicit bindings: \fIexpr\fR;; -> let _0 = \fIexpr\fR;;
.TP
.BI -no-autoload
Disable autoloading of files in 
.I $OCAML_TOPLEVEL_PATH/autoload.
.TP
.BI -require " package"
Load this package.
.TP
.BI -dparsetree
Dump OCaml AST after rewriting.
.TP
.BI -dsource
Dump OCaml source after rewriting.
.TP
.BI -help
Display this list of options.
.TP
.BI --help
Display this list of options.

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

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

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