Module Protocol

Communication Protocol

Defines the core data structures used for communication between the C++/JavaScript frontend and the OCaml backend of the kernel.

These types are automatically serialized to and from JSON using `ppx_deriving_yojson`, forming a strict contract between the two parts of the application. This module is the single source of truth for the API.

module Location = Ocaml_parsing.Location
type source = string

Represents a block of OCaml source code to be processed.

val source_to_yojson : source -> Yojson.Safe.t
val source_of_yojson : Yojson.Safe.t -> source Ppx_deriving_yojson_runtime.error_or
type position = [
  1. | `Offset of int
]

Represents a cursor position within a source code buffer.

  • `Offset i indicates the position is at the i-th byte from the start.
val position_to_yojson : position -> Yojson.Safe.t
val position_of_yojson : Yojson.Safe.t -> position Ppx_deriving_yojson_runtime.error_or
val to_msource_position : position -> Merlin_kernel.Msource.position

Converts a position from this protocol into Merlin's internal Msource.position type, which is required for all Merlin queries.

type dynamic_setup_config = {
  1. dsc_url : string;
    (*

    The base URL from which to fetch dynamic standard library files and other assets.

    *)
}

Configuration data required for the initial kernel setup.

val dynamic_setup_config_to_yojson : dynamic_setup_config -> Yojson.Safe.t
val dynamic_setup_config_of_yojson : Yojson.Safe.t -> dynamic_setup_config Ppx_deriving_yojson_runtime.error_or
type action =
  1. | Complete_prefix of {
    1. source : source;
    2. position : position;
    }
    (*

    A request for code completion at a given position.

    *)
  2. | Type_enclosing of {
    1. source : source;
    2. position : position;
    }
    (*

    A request for the type of the expression enclosing a given position.

    *)
  3. | Document of {
    1. source : source;
    2. position : position;
    }
    (*

    A request for the documentation (docstring) of the identifier at a given position.

    *)
  4. | Eval of {
    1. source : source;
    }
    (*

    A request to evaluate a block of source code.

    *)
  5. | All_errors of {
    1. source : source;
    }
    (*

    A request to get all syntax and type errors in a source buffer.

    *)
  6. | Setup of dynamic_setup_config
    (*

    The initial command to set up the kernel environment.

    *)
  7. | List_files of {
    1. path : string;
    }
    (*

    A utility command to list files in the virtual filesystem (for debugging).

    *)

The main variant type that represents all possible commands the frontend can send to the OCaml backend.

val action_to_yojson : action -> Yojson.Safe.t
val action_of_yojson : Yojson.Safe.t -> action Ppx_deriving_yojson_runtime.error_or
type error = {
  1. kind : Location.report_kind;
    (*

    The category of the report (e.g., error, warning).

    *)
  2. loc : Location.t;
    (*

    The source code location of the error.

    *)
  3. main : string;
    (*

    The primary error message.

    *)
  4. sub : string list;
    (*

    A list of secondary or supplementary messages.

    *)
  5. source : Location.error_source;
    (*

    The stage of the toolchain that produced the error (lexer, parser, typer).

    *)
}

Represents a single structured error or warning from the OCaml toolchain.

type output =
  1. | Stdout of string
    (*

    Content captured from the standard output channel.

    *)
  2. | Stderr of string
    (*

    Content captured from the standard error channel.

    *)
  3. | Value of string
    (*

    The formatted string representation of a toplevel expression's result (e.g., `- : int = 2`).

    *)
  4. | DisplayData of Yojson.Safe.t
    (*

    A rich output represented as a JSON MIME bundle, for rendering HTML, images, etc.

    *)

Represents all possible kinds of output that can result from a code evaluation. These are collected and sent back to the frontend for rendering.

val output_to_yojson : output -> Yojson.Safe.t
val output_of_yojson : Yojson.Safe.t -> output Ppx_deriving_yojson_runtime.error_or
val _ : Yojson.Safe.t -> output Ppx_deriving_yojson_runtime.error_or
type completions = {
  1. from : int;
    (*

    The starting position (byte offset) of the text to be replaced.

    *)
  2. to_ : int;
    (*

    The ending position (byte offset) of the text to be replaced.

    *)
  3. entries : Query_protocol.Compl.entry list;
    (*

    The list of completion entries provided by Merlin.

    *)
}

A record representing a list of completion candidates from Merlin.

type is_tail_position = [
  1. | `No
  2. | `Tail_position
  3. | `Tail_call
]

A type used by Merlin to indicate if a position is in a tail-call context.

val report_source_to_string : Location.error_source -> string

Converts a Merlin Location.error_source variant to a human-readable string.