jon.recoil.org
this repo has no description
Phase 3: Add documentation structure to impl.ml
Organize impl.ml with odoc-style section comments to improve navigation
and understanding. The module is now divided into clear sections:
- {1 OCaml Toplevel Implementation} - Module overview
- {2 Cell Dependency System} - Cell ID → module wrapping
- {2 PPX Preprocessing} - JsooTopPpx module
- {2 Backend Signature} - Module type S
- {2 Main Functor} - Make(S) containing:
- {3 State} - Mutable refs
- {3 Lexer Helpers} - refill_lexbuf
- {3 Setup and Initialization} - exec', setup
- {3 Output Helpers} - buffer utilities
- {3 Phrase Execution} - execute, typecheck
- {3 Dynamic CMI Loading} - add_dynamic_cmis
- {3 RPC Handlers} - init, setup, exec, etc.
- {3 Merlin Integration} - completion, errors, type_enclosing
This makes the ~900 line file more navigable without changing functionality.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+55
-6
lib/impl.ml
+55
-6
lib/impl.ml
···
1
-
(* Implementation *)
1
+
(** {1 OCaml Toplevel Implementation}
2
+
3
+
This module provides the core toplevel functionality for js_top_worker.
4
+
It implements phrase execution, type checking, and Merlin integration
5
+
(completion, errors, type info).
6
+
7
+
The module is parameterized by a backend signature [S] which provides
8
+
platform-specific operations for different environments (WebWorker,
9
+
Node.js, Unix). *)
10
+
2
11
open Js_top_worker_rpc
3
12
module M = Rpc_lwt.ErrM (* Server is not synchronous *)
4
13
module IdlM = Rpc_lwt
5
14
6
15
let ( let* ) = Lwt.bind
7
16
17
+
(** {2 Cell Dependency System}
18
+
19
+
Cells are identified by string IDs and can depend on previous cells.
20
+
Each cell is wrapped in a module [Cell__<id>] so that later cells can
21
+
access earlier bindings via [open Cell__<id>]. *)
22
+
8
23
type captured = { stdout : string; stderr : string }
9
24
10
25
let modname_of_id id = "Cell__" ^ id
···
70
85
Printf.printf "src length: %d\n%!" (String.length src));
71
86
(line1, src)
72
87
88
+
(** {2 PPX Preprocessing}
89
+
90
+
Handles PPX rewriter registration and application. The [Ppx_js.mapper]
91
+
is registered by default to support js_of_ocaml syntax extensions. *)
92
+
73
93
module JsooTopPpx = struct
74
94
open Js_of_ocaml_compiler.Stdlib
75
95
···
98
118
| Ptop_dir _ as x -> x
99
119
end
100
120
121
+
(** {2 Backend Signature}
122
+
123
+
Platform-specific operations that must be provided by each backend
124
+
(WebWorker, Node.js, Unix). *)
125
+
101
126
module type S = sig
102
127
type findlib_t
103
128
···
114
139
val require :
115
140
bool -> findlib_t -> string list -> Toplevel_api_gen.dynamic_cmis list
116
141
end
142
+
143
+
(** {2 Main Functor}
144
+
145
+
The toplevel implementation, parameterized by backend operations. *)
117
146
118
147
module Make (S : S) = struct
148
+
(** {3 State} *)
149
+
119
150
let functions : (unit -> unit) list option ref = ref None
120
151
let requires : string list ref = ref []
121
152
let path : string option ref = ref None
122
153
let findlib_v : S.findlib_t Lwt.t option ref = ref None
123
154
let execution_allowed = ref true
155
+
156
+
(** {3 Lexer Helpers} *)
124
157
125
158
let refill_lexbuf s p ppf buffer len =
126
159
if !p = String.length s then 0
···
140
173
p := !p + len'';
141
174
len''
142
175
143
-
(* RPC function implementations *)
144
-
145
-
(* These are all required to return the appropriate value for the API within the
146
-
[IdlM.T] monad. The simplest way to do this is to use [IdlM.ErrM.return] for
147
-
the success case and [IdlM.ErrM.return_err] for the failure case *)
176
+
(** {3 Setup and Initialization} *)
148
177
149
178
let exec' s =
150
179
S.capture
···
189
218
stdout = Buffer.contents stdout_buff;
190
219
stderr = Buffer.contents stderr_buff;
191
220
}
221
+
222
+
(** {3 Output Helpers} *)
192
223
193
224
let stdout_buff = Buffer.create 100
194
225
let stderr_buff = Buffer.create 100
···
212
243
Some loc
213
244
| _ -> None
214
245
246
+
(** {3 Phrase Execution} *)
247
+
215
248
let execute printval ?pp_code ?highlight_location pp_answer s =
216
249
let s =
217
250
let l = String.length s in
···
269
302
mime_vals;
270
303
}
271
304
305
+
(** {3 Dynamic CMI Loading}
306
+
307
+
Handles loading .cmi files on demand for packages that weren't
308
+
compiled into the worker. *)
309
+
272
310
let filename_of_module unit_name =
273
311
Printf.sprintf "%s.cmi" (String.uncapitalize_ascii unit_name)
274
312
···
367
405
load := new_load ~s:"merl" ~old_loader
368
406
in
369
407
Lwt.return ()
408
+
409
+
(** {3 RPC Handlers}
410
+
411
+
Functions that implement the toplevel RPC API. Each function returns
412
+
results in the [IdlM.ErrM] monad. *)
370
413
371
414
let init (init_libs : Toplevel_api_gen.init_config) =
372
415
Lwt.catch
···
555
598
let result = execute phrase in
556
599
IdlM.ErrM.return result
557
600
601
+
(** {3 Merlin Integration}
602
+
603
+
Code intelligence features powered by Merlin: completion, type info,
604
+
error diagnostics. *)
605
+
558
606
let config () =
559
607
let path =
560
608
match !path with Some p -> p | None -> failwith "Path not set"
···
569
617
Merlin_kernel.Mpipeline.with_pipeline pipeline @@ fun () ->
570
618
Query_commands.dispatch pipeline query
571
619
620
+
(** Completion prefix extraction, adapted from ocaml-lsp-server. *)
572
621
module Completion = struct
573
622
open Merlin_utils
574
623
open Std