package utop

  1. Overview
  2. Docs

Module UTopSource

UTop configuration.

Sourceval version : string

Version of utop.

Sourceval count : int React.signal

The number of commands already executed.

The set of OCaml keywords.

Sourceval add_keyword : string -> unit

Add a new OCaml keyword.

Sourceval require : string list -> unit

Load all the given findlib packages

Sourcetype ui =
  1. | Console
  2. | Emacs
    (*

    The user interface in use.

    *)
Sourceval get_ui : unit -> ui

Returns the user interface in use.

Sourceval hide_reserved : bool React.signal

If true (the default) identifiers starting with a '_' will be hidden from the output. i.e. the following phrase won't produces any output:

  let _x = 1

This is for hidding variables created by code generators for internal use. It can also be set/unset by the command line options -hide-reserved and -show-reserved.

Sourceval get_hide_reserved : unit -> bool

Returns the value of hide_reserved.

Sourceval set_hide_reserved : bool -> unit

Modifies hide_reserved.

Sourceval create_implicits : bool React.signal

If true (not the default) expressions entered in the toplevel are automatically bound, for example:

  # 3 + 4;;
  _0 : int = 7
  # _0 + 10;;
  _1 : int = 17
Sourceval get_create_implicits : unit -> bool

Returns the value of create_implicits.

Sourceval set_create_implicits : bool -> unit

Modifies create_implicits.

Sourceval topfind_verbose : bool React.signal

If false (the default) messages from findlib are hidden. This is only effective with findlib >= 1.4.

Sourceval get_topfind_verbose : unit -> bool

Returns the value of topfind_verbose.

Sourceval set_topfind_verbose : bool -> unit

Modifies topfind_verbose.

Sourceval topfind_log : string list React.signal

List of messages logged by findlib since the beginning of the session. This requires findlib >= 1.4.

Sourceval show_box : bool React.signal

If true (the default) the completion bar is displayed.

Sourceval get_show_box : unit -> bool

Returns the value of show_box.

Sourceval set_show_box : bool -> unit

Modifies show_box.

Sourceval set_margin_function : (LTerm_geom.size -> int option) -> unit

Margin of the standard and error formatters as a function of the screen size.

The default is:

  fun size -> Some (min 80 size.cols)
Sourceval phrase_terminator : string React.signal

The phrase terminator, ";;".

Sourceval get_phrase_terminator : unit -> string

Returns the value of phrase_terminator.

Sourceval set_phrase_terminator : string -> unit

Modifies phrase_terminator.

Sourceval auto_run_lwt : bool React.signal

If true (the default) toplevel lwt expressions are automatically run with Lwt_main.run. i.e. if you type:

  Lwt_io.printl "Hello, world"

this will be replaced by:

  Lwt_main.run (Lwt_io.printl "Hello, world")
Sourceval get_auto_run_lwt : unit -> bool

Returns the value of auto_run_lwt.

Sourceval set_auto_run_lwt : bool -> unit

Modifies auto_run_lwt.

Sourceval auto_run_async : bool React.signal

If true (the default) toplevel Async expressions are automatically run with in a separate thread with Thread_safe.block_on_async_exn. i.e. if you type:

  after (Time.Span.of_s 1.0)

this will be replaced by:

  Thread_safe.block_on_async_exn (fun () -> after (Time.Span.of_s 1.0))
Sourceval get_auto_run_async : unit -> bool

Returns the value of auto_run_async.

Sourceval set_auto_run_async : bool -> unit

Modifies auto_run_async.

Sourceval end_and_accept_current_phrase : LTerm_read_line.action

Action that add the phrase terminator at the end of the current phrase and accepts it. For instance to avoid typing ;;, add this to your ~/.config/utop/init.ml:

  #require "lambda-term";;
  LTerm_read_line.bind
    [ { control = false; meta = false; shift = false; code = Enter } ]
    [ UTop.end_and_accept_current_phrase ]
Sourceval external_editor : string React.signal

External editor command. None for default.

Sourceval set_external_editor : string -> unit
Sourceval get_external_editor : unit -> string
History
Sourceval history : LTerm_history.t

The history used by utop. You can configure limits using the LTerm_history module.

For example if you want to limit the history to 1000 line, add these lines to your ~/.config/utop/init.ml file:

  #require "lambda-term";;
  LTerm_history.set_max_entries UTop.history 1000;;
Sourceval history_file_name : string option ref

Name of the history file. If None, no history will be loaded or saved.

Sourceval history_file_max_size : int option ref

Maximum size of the history file. If None (the default) the maximum size of history will be used.

Sourceval history_file_max_entries : int option ref

Maximum entries to store in the history file. If None (the default) the maximum number of entries if history will be used.

Sourceval stashable_session_history : UTop_history.t

A history consisting of inputs and resulting values or errors of the current session. Because stashing is supposed to produce a valid OCaml file which will behave roughly the same as the console, it is best if this history never gets truncated. While this will certainly lead to a slight memory leaking problem, UTop sessions are rarely long enough to make it a serious issue.

Console specific configuration
Sourcetype profile =
  1. | Dark
  2. | Light
    (*

    Profile for colors.

    *)
Sourceval profile : profile React.signal

The color profile. It defaults to Dark. This is used by the default prompt to choose colors.

Sourceval set_profile : profile -> unit

Sets the color profile.

Sourceval size : LTerm_geom.size React.signal

The current size of the terminal. This is used only in the console UI.

Sourceval key_sequence : LTerm_key.t list React.signal

The current key sequence entered by the user. This is used only in the console UI.

Sourceval time : float ref

The time of the beginning of the current command.

Sourceval prompt : LTerm_text.t React.signal ref

The prompt.

Edit mode configuration

The edit mode.

Hooks
Sourceval new_command_hooks : (unit -> unit) LTerm_dlist.t

Functions called before each new command.

Sourceval at_new_command : (unit -> unit) -> unit

at_new_command f adds f to the hooks executed before each new commands.

Parsing
Sourcetype location = int * int

Type of a string-location. It is composed of a start and stop offsets (in bytes).

Sourcetype lines = {
  1. start : int;
  2. stop : int;
}

Type for a range of lines in a buffer from start to stop.

Sourcetype 'a result =
  1. | Value of 'a
    (*

    The function succeeded and returned this value.

    *)
  2. | Error of location list * string
    (*

    The function failed. Arguments are a list of locations to highlight in the source and an error message.

    *)

Result of a function processing a programx.

Sourceexception Need_more

Exception raised by a parser when it need more data.

Sourceval parse_use_file : (string -> bool -> Parsetree.toplevel_phrase list result) ref
Sourceval parse_use_file_default : string -> bool -> Parsetree.toplevel_phrase list result

The default parser for toplevel regions. It uses the standard ocaml parser.

Sourceval parse_toplevel_phrase : (string -> bool -> Parsetree.toplevel_phrase result) ref

parse_toplevel_phrase is the function used to parse a phrase typed in the toplevel.

Its arguments are:

  • input: the string to parse
  • eos_is_error

If eos_is_error is true and the parser reach the end of input, then Parse_failure should be returned.

If eos_is_error is false and the parser reach the end of input, the exception Need_more must be thrown.

Except for Need_more, the function must not raise any exception.

Sourceval parse_toplevel_phrase_default : string -> bool -> Parsetree.toplevel_phrase result

The default parser for toplevel phrases. It uses the standard ocaml parser.

Sourceval parse_default : (Lexing.lexbuf -> 'a) -> string -> bool -> 'a result

The default parser. It uses the standard ocaml parser.

Sourceval input_name : string

The name you must use in location to let ocaml know that it is from the toplevel.

Sourceval lexbuf_of_string : bool ref -> string -> Lexing.lexbuf

lexbuf_of_string eof str is the same as Lexing.from_string str except that if the lexer reach the end of str then eof is set to true.

Helpers
Sourceval get_message : (Format.formatter -> 'a -> unit) -> 'a -> string

get_message printer x applies printer on x and returns everything it prints as a string.

Sourceval get_ocaml_error_message : exn -> location * string * lines option

get_ocaml_error_message exn returns the location and error message for the exception exn which must be an exception from the compiler.

Sourceval check_phrase : Parsetree.toplevel_phrase -> (location list * string * lines option list) option

check_phrase phrase checks that phrase can be executed without typing or compilation errors. It returns None if phrase is OK and an error message otherwise.

If the result is None it is guaranteed that Toploop.execute_phrase won't raise any exception.

Sourceval collect_formatters : Buffer.t -> Format.formatter list -> (unit -> 'a) -> 'a

collect_formatters buf pps f executes f and redirect everything it prints on pps to buf.

Sourceval discard_formatters : Format.formatter list -> (unit -> 'a) -> 'a

discard_formatters pps f executes f, dropping everything it prints on pps.

Sourceval split_words : string -> string list
compiler-libs reexports
Sourceval get_load_path : unit -> string list
Sourceval set_load_path : string list -> unit

get_load_path and set_load_path manage the include directories.

The internal variable contains the list of directories added by findlib-required packages and #directory directives.