jon.recoil.org
this repo has no description
1(** Backend abstraction for x-ocaml.
2
3 This module provides a unified client type that can use either the built-in
4 x-ocaml worker or js_top_worker as the backend.
5
6 Usage:
7 {[
8 (* Select backend from attribute *)
9 let worker = Backend.make ~backend:"jtw" worker_url in
10
11 (* Use unified API *)
12 Backend.on_message worker (fun msg -> ...);
13 Backend.eval ~id:1 ~line_number:1 worker "let x = 1";
14 ]} *)
15
16(** The backend module signature *)
17module type S = sig
18 type t
19
20 (** Create a new backend client.
21 @param extra_load Optional URL to load before the worker
22 @param url URL to the worker script *)
23 val make : ?extra_load:string -> string -> t
24
25 (** Set the response handler. Called for each response from the worker. *)
26 val on_message : t -> (X_protocol.response -> unit) -> unit
27
28 (** Send a raw protocol message to the worker.
29 Note: Some backends may not support all message types (e.g., Merlin). *)
30 val post : t -> X_protocol.request -> unit
31
32 (** Evaluate OCaml code.
33 @param id Cell identifier
34 @param line_number Starting line number
35 @param t The client
36 @param code OCaml code to evaluate *)
37 val eval : id:int -> line_number:int -> t -> string -> unit
38
39 (** Format OCaml code using ocamlformat.
40 @param id Cell identifier
41 @param t The client
42 @param code OCaml code to format *)
43 val fmt : id:int -> t -> string -> unit
44
45 (** Terminate the worker and create a fresh one. *)
46 val reset : t -> unit
47
48 (** Whether this backend supports Merlin integration *)
49 val has_merlin : bool
50end
51
52(** {1 Unified Client Type} *)
53
54(** Unified client type that can hold any backend *)
55type t
56
57(** Check if the backend supports Merlin integration *)
58val has_merlin : t -> bool
59
60(** Create a client with the built-in x-ocaml worker backend *)
61val make_builtin : ?extra_load:string -> string -> t
62
63(** Create a client with the js_top_worker backend.
64 @param findlib_requires Packages to load during worker init
65 @param findlib_index URL to findlib_index.json *)
66val make_jtw : ?findlib_requires:string list -> ?findlib_index:string -> string -> t
67
68(** Create a client with the specified backend.
69 @param backend Backend name: "builtin", "x-ocaml", "jtw", or "js_top_worker"
70 @param extra_load Optional URL to load before the worker (builtin only)
71 @param findlib_requires Packages to load during worker init (jtw only)
72 @param findlib_index URL to findlib_index.json (jtw only)
73 @param url URL to the worker script *)
74val make : backend:string -> ?extra_load:string -> ?findlib_requires:string list -> ?findlib_index:string -> string -> t
75
76(** Set the response handler *)
77val on_message : t -> (X_protocol.response -> unit) -> unit
78
79(** Send a raw protocol message (no-op for jtw backend) *)
80val post : t -> X_protocol.request -> unit
81
82(** Evaluate OCaml code *)
83val eval : id:int -> line_number:int -> t -> string -> unit
84
85(** Format OCaml code *)
86val fmt : id:int -> t -> string -> unit
87
88(** Terminate the current worker and create a fresh one.
89 After reset, the backend must be re-initialised (Setup, Format_config, etc.)
90 and all cells should be considered invalidated. *)
91val reset : t -> unit
92
93(** {1 Module-based Interface} *)
94
95(** Built-in x-ocaml worker backend module *)
96module Builtin_mod : S
97
98(** js_top_worker backend module *)
99module Jtw_mod : S
100
101(** Select backend module by name.
102 @param name "builtin" or "jtw"
103 @return The backend module *)
104val select : string -> (module S)