Up  Next

Module UTop

module UTop: sig .. end
UTop configuration.
val version : string
Version of utop.
val count : int React.signal
The number of commands already executed.
val keywords : Set.Make(String).t Pervasives.ref
The set of OCaml keywords.
val add_keyword : string -> unit
Add a new OCaml keyword.
val require : string list -> unit
Load all the given findlib packages
type ui =
| Console
| Emacs (*
The user interface in use.
*) 
val get_ui : unit -> ui
Returns the user interface in use.
val 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.

val get_hide_reserved : unit -> bool
Returns the value of UTop.hide_reserved.
val set_hide_reserved : bool -> unit
Modifies UTop.hide_reserved.
val topfind_verbose : bool React.signal
If false (the default) messages from findlib are hidden. This is only effective with findlib >= 1.4.
val get_topfind_verbose : unit -> bool
Returns the value of UTop.topfind_verbose.
val set_topfind_verbose : bool -> unit
Modifies UTop.topfind_verbose.
val topfind_log : string list React.signal
List of messages logged by findlib since the beginning of the session. This requires findlib >= 1.4.
val show_box : bool React.signal
If true (the default) the completion bar is displayed.
val get_show_box : unit -> bool
Returns the value of UTop.show_box.
val set_show_box : bool -> unit
Modifies UTop.show_box.
val 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 (max 80 size.cols)
      

type syntax =
| Normal (*
No camlp4.
*)
| Camlp4o (*
Camlp4, original syntax.
*)
| Camlp4r (*
Camlp4, revised syntax.
*)
Syntax.
val syntax : syntax React.signal
The syntax in use. If it is Camlp4o or Camlp4r quotations are recognized. It is modified when you type #camlp4o or #camlp4r. At the beginning it is Normal.
val get_syntax : unit -> syntax
Returns the current value of UTop.syntax.
val set_syntax : syntax -> unit
Changes the syntax used in utop. If the syntax is the same as the current one, it does nothing. Otherwise it loads camlp4 and setup several configuration variables.

Notes:


val phrase_terminator : string React.signal
The phrase terminator. It is ";;" by default and ";" when you use revised syntax.
val get_phrase_terminator : unit -> string
Returns the value of UTop.phrase_terminator.
val set_phrase_terminator : string -> unit
Modifies UTop.phrase_terminator.
val 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")
      

val get_auto_run_lwt : unit -> bool
Returns the value of UTop.auto_run_lwt.
val set_auto_run_lwt : bool -> unit
Modifies UTop.auto_run_lwt.
val 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))
      

val get_auto_run_async : unit -> bool
Returns the value of UTop.auto_run_async.
val set_auto_run_async : bool -> unit
Modifies UTop.auto_run_async.
val 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 ~/.ocamlinit: 

       #require "lambda-term";;
       LTerm_read_line.bind
         [ { control = false; meta = false; shift = false; code = Enter } ]
         [ UTop.end_and_accept_current_phrase ]
     

val external_editor : string React.signal
External editor command. None for default.
val set_external_editor : string -> unit
val get_external_editor : unit -> string

History

val 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 ~/.ocamlinit file: 

        #require "lambda-term";;
        LTerm_history.set_max_entries UTop.history 1000;;
      

val history_file_name : string option Pervasives.ref
Name of the history file. If None, no history will be loaded or saved.
val history_file_max_size : int option Pervasives.ref
Maximum size of the history file. If None (the default) the maximum size of history will be used.
val history_file_max_entries : int option Pervasives.ref
Maximum entries to store in the history file. If None (the default) the maximum number of entries if history will be used.

Console specific configuration

type profile =
| Dark
| Light (*
Profile for colors.
*) 
val profile : profile React.signal
The color profile. It defaults to Dark. This is used by the default prompt to choose colors.
val set_profile : profile -> unit
Sets the color profile.
val size : LTerm_geom.size React.signal
The current size of the terminal. This is used only in the console UI.
val key_sequence : LTerm_key.t list React.signal
The current key sequence entered by the user. This is used only in the console UI.
val time : float Pervasives.ref
The time of the beginning of the current command.
val prompt : LTerm_text.t React.signal Pervasives.ref
The prompt.

Hooks

val new_command_hooks : (unit -> unit) Lwt_sequence.t
Functions called before each new command.
val at_new_command : (unit -> unit) -> unit
at_new_command f adds f to the hooks executed before each new commands.

Parsing

type location = int * int
Type of a string-location. It is composed of a start and stop offsets (in bytes).
type 'a result =
| Value of 'a (*
The function succeeded and returned this value.
*)
| 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.
exception Need_more
Exception raised by a parser when it need more data.
val parse_use_file : (string -> bool -> Parsetree.toplevel_phrase list result) Pervasives.ref
val parse_use_file_default : string -> bool -> Parsetree.toplevel_phrase list result
The default parser for toplevel regions. It uses the standard ocaml parser.
val parse_toplevel_phrase : (string -> bool -> Parsetree.toplevel_phrase result) Pervasives.ref
parse_toplevel_phrase is the function used to parse a phrase typed in the toplevel.

Its arguments are:

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 UTop.Need_more must be thrown.

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

val parse_toplevel_phrase_default : string -> bool -> Parsetree.toplevel_phrase result
The default parser for toplevel phrases. It uses the standard ocaml parser.
val parse_default : (Lexing.lexbuf -> 'a) -> string -> bool -> 'a result
The default parser. It uses the standard ocaml parser.
val input_name : string
The name you must use in location to let ocaml know that it is from the toplevel.
val lexbuf_of_string : bool Pervasives.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

val get_message : (Format.formatter -> 'a -> unit) -> 'a -> string
get_message printer x applies printer on x and returns everything it prints as a string.
val get_ocaml_error_message : exn -> location * string
get_ocaml_error_message exn returns the location and error message for the exception exn which must be an exception from the compiler.
val check_phrase : Parsetree.toplevel_phrase -> (location list * string) 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.

val 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.
val discard_formatters : Format.formatter list -> (unit -> 'a) -> 'a
discard_formatters pps f executes f, dropping everything it prints on pps.
val split_words : string -> string list

compiler-libs reexports

val load_path : string list Pervasives.ref
load_path is an alias of Config.load_path, normally hidden in toplevel. It contains the list of directories added by findlib-required packages and #directory directives.