C++ API Reference

This section provides the API documentation for the C++ components of the xeus-ocaml kernel.

The documentation is automatically generated from the source code comments in the /include and /src directories using Doxygen and Breathe.

namespace xeus_ocaml

The main namespace for the xeus-ocaml kernel.

Functions

nl::json handle_completion_request(const std::string &code, int cursor_pos)

Handles a code completion request from the Jupyter frontend.

This function orchestrates the process of getting completion suggestions from the Merlin backend via the ocaml_engine and formatting the response into a valid Jupyter complete_reply message.

Parameters:

  • code – The entire code content of the cell.

  • cursor_pos – The position of the cursor within the code.

Returns:

A JSON object representing the complete_reply message, containing the list of matches and cursor positions.

nl::json handle_inspection_request(const std::string &code, int cursor_pos, int detail_level)

Handles a code inspection request from the Jupyter frontend.

This function queries the Merlin backend for both the type signature and the documentation of the identifier under the cursor. It then formats this information into a rich inspect_reply message containing both plain text and Markdown representations.

Parameters:

  • code – The entire code content of the cell.

  • cursor_pos – The position of the cursor within the code.

  • detail_level – The level of detail requested by the frontend (currently unused).

Returns:

A JSON object representing the inspect_reply message.

static std::string map_ocaml_kind_to_icon(const nl::json &kind_json)

Maps OCaml entity kinds from Merlin to Jupyter’s completion item types.

This enhances the user experience in frontends that support rich completion suggestions by displaying appropriate icons for functions, modules, etc.

Parameters:

kind_json – The JSON string representing the entity kind from Merlin’s response.

Returns:

A string representing the corresponding Jupyter completion item type (e.g., “function”, “module”). Defaults to “text” for unknown kinds.

static std::string parse_merlin_docstring(std::string doc)

Parses and reformats a raw Merlin docstring for Markdown display.

This helper function performs several transformations:

  • Converts Merlin’s bold syntax {!...} to Markdown code blocks `...`.

  • Unwraps indented paragraphs by replacing newlines followed by spaces with a single space.

  • Creates proper Markdown paragraph breaks by replacing single newlines with double newlines.

Parameters:

doc – The raw docstring received from the Merlin backend.

Returns:

A cleaned and formatted string suitable for Markdown rendering.

void global_setup_callback(const std::string &result_str)

Global C-style callback for the asynchronous OCaml setup (Phase 1).

This function is invoked by the OCaml backend when the initial setup, including fetching standard library files, is complete. It then triggers the C++-side setup (Phase 2), such as mounting the virtual filesystem.

Parameters:

result_str – A JSON string from the OCaml backend indicating the result of the setup operation.

void global_eval_callback(int request_id, const std::string &result_str)

Global C-style callback for asynchronous OCaml code execution.

This function is invoked by the OCaml backend when an Eval action completes. It acts as the bridge to pass the execution result back to the correct interpreter instance.

Parameters:

  • request_id – The unique ID of the original execution request, used to route the result to the correct pending callback.

  • result_str – A JSON string from the OCaml backend containing the execution outputs or an error message.

EMSCRIPTEN_BINDINGS(xocaml_kernel_callbacks)

Emscripten bindings to export global callbacks to JavaScript.

This block makes the C++ global_setup_callback and global_eval_callback functions callable from the JavaScript environment, allowing the OCaml backend to trigger them.

class interpreter : public xeus::xinterpreter
#include <xinterpreter.hpp>

The main xeus interpreter for the OCaml kernel.

This class is responsible for handling Jupyter protocol messages, managing the execution lifecycle, and coordinating with the underlying OCaml engine. It delegates specific tasks like code completion and inspection to dedicated modules.

Public Functions

void handle_eval_callback(int request_id, const std::string &result_str)

Public callback handler for asynchronous execution results from JavaScript.

This method is invoked by the global C-style callback function when a response from an asynchronous ‘Eval’ action is received from the OCaml/JS backend.

Parameters:

  • request_id – The unique ID of the original execution request.

  • result_str – The JSON string result from the JavaScript backend.

void handle_setup_callback(const std::string &result_str)

Public callback handler for the initial setup result.

This method is invoked when Phase 1 of the OCaml setup completes. It checks for success and then triggers Phase 2 via the ocaml_engine.

namespace ocaml_engine

Functions

nl::json call_merlin_sync(const nl::json &request)

Synchronously executes a Merlin command and returns the result.

This function is intended for quick, non-blocking operations like code completion or type inspection. It directly calls the processMerlinAction function exported by the OCaml/JS module.

Parameters:

request – A JSON object representing the Merlin action and its payload, conforming to the protocol defined in protocol.ml.

Returns:

A JSON object containing the response from the Merlin backend. In case of an error, it returns a JSON object with a “class” of “error”.

void call_toplevel_async(const nl::json &request, emscripten::val callback)

Asynchronously executes a Toplevel command.

This function is used for potentially long-running operations like code execution (Eval) or environment setup (Setup). It calls the processToplevelAction function exported by the OCaml/JS module and passes a C++ callback function that will be invoked upon completion.

Parameters:

  • request – A JSON object representing the Toplevel action and its payload.

  • callback – An Emscripten value (emscripten::val) representing the JavaScript-bound callback function to be executed with the result.

void mount_fs()

Calls the OCaml function to mount the Emscripten FS device.