IsabelleClientMini (isabelle_elixir v0.1.0)
View SourceMinimalistic stateless Elixir client for the Isabelle Server
This module wraps the Isabelle Server command‑line tools (isabelle server
,
isabelle client
) and its TCP protocol (see Isabelle System Manual,
Chapter 4 under https://isabelle.in.tum.de/doc/system.pdf) in a set of
synchronous helper functions that remain completely stateless. You can use
these to spin up a resident server, connect to it, fire high‑level
commands (session_start
, use_theories
, …) and consume the streamed
results without having to parse the Isabelle wire protocol yourself.
Typical lifecycle
- (optionally) Start a resident server with
new_server/2
(or reuse an existing one found vialist_servers/0
). Both commands require a local Isabelle installation whosebin/
directory is on thePATH
. - Connect using the password/token reported by the server (
connect/3
). The corresponding Isabelle server only needs to be accessible via TCP. - Launch a session once per logic image (
start_session/2
). - Edit/compile theories with
use_theories/2
, polling forFINISHED | FAILED | NOTE
messages viapoll_status/2
. - Extract results or artefacts with helpers such as
extract_results/1
. - Stop the session (
stop_session/2
). - (optionally) Shutdown the server (
shutdown_server/1
). If running Isabelle locally you can alternatively usekill_server/1
.
Caveats
- The client is intentionally stateless — it does not keep supervision trees, reconnect, or monitor server liveness for you. Compose it inside your own supervision strategy if you need robustness.
- Network I/O is done via
:gen_tcp
in passive mode; all helpers block the calling process. For high‑latency sessions consider running them inside a dedicated Task or GenServer.
Summary
Functions
Build session images (wrapper around session_build
).
Cancel a running asynchronous task (identified by its UUID).
Close a previously opened TCP connection.
Open a TCP connection to an Isabelle server and perform the initial password handshake.
Round‑trip test helper that sends echo <json>
and returns the decoded value.
Useful for verifying the connection.
Extract the plain‑text messages from a :finished
status keyword list.
Grab the session_id
UUID from a :finished
status keyword list.
Return the list of command names supported by the server (help
).
Force‑terminate a named Isabelle server process via the CLI
(isabelle server -n <name> -x
). In case you really want to kill the Isabelle server,
you can use this as a last resort if a clean shutdown
over the TCP protocol is impossible.
List all locally running Isabelle servers. Under the hood this simply invokes
isabelle server -l
and parses its stdout. Same caveat apply as with new_server/2
.
Spawn a resident Isabelle Server in the background.
Recursively poll the socket until the server finishes an async task.
Purge theories from heap to reclaim memory (purge_theories
).
Send a shutdown
command over the given socket, causing the server
process itself to exit (all connected sessions will be dropped).
Start an Isabelle PIDE session, implicitly building images if needed.
Gracefully stop a running session (session_stop
).
Load / re‑load theories into the session (use_theories
).
Functions
Build session images (wrapper around session_build
).
Cancel a running asynchronous task (identified by its UUID).
Close a previously opened TCP connection.
Open a TCP connection to an Isabelle server and perform the initial password handshake.
Parameters
password
– token obtained from the server descriptor (returned bynew_server/2
orlist_servers/0
if running locally).host
– IPv4 address as string (default127.0.0.1
).port
– TCP port (default9999
).
Return value
socket
– a live socket ready for further commands.
{:error, reason}
on connection failures.
Round‑trip test helper that sends echo <json>
and returns the decoded value.
Useful for verifying the connection.
Extract the plain‑text messages from a :finished
status keyword list.
Grab the session_id
UUID from a :finished
status keyword list.
Return the list of command names supported by the server (help
).
Force‑terminate a named Isabelle server process via the CLI
(isabelle server -n <name> -x
). In case you really want to kill the Isabelle server,
you can use this as a last resort if a clean shutdown
over the TCP protocol is impossible.
List all locally running Isabelle servers. Under the hood this simply invokes
isabelle server -l
and parses its stdout. Same caveat apply as with new_server/2
.
Spawn a resident Isabelle Server in the background.
The function runs isabelle server -n <name> -p <port>
via an Erlang port,
waits for its first line of output, parses the server descriptor and then
closes the port (leaving the JVM process running detached).
Note that if you want to start (and list) Isabelle servers programmatically
(via the functions: new_server and list_servers) you have to make sure
that the "bin" directory in your Isabelle installation is in the PATH.
Parameters
name
– arbitrary label used to identify the server inlist_servers/0
. Defaults to"elixir"
.port
– TCP port on which the server accepts connections. Defaults to9999
.
Return value
[%{"name" => name, "host" => host, "port" => port, "password" => pw}]
on
success, or {:error, reason}
on failure / timeout.
Recursively poll the socket until the server finishes an async task.
The function returns immediately when it encounters one of the following conditions in the buffered stream:
{:finished, ...}
– successful result (seeextract_results/1
).{:failed, ...}
– task failed.{:error, reason}
– protocol mismatch / time‑out / empty buffer.
Internally it keeps a growing accumulator so you don't lose any partial chunks.
Purge theories from heap to reclaim memory (purge_theories
).
Send a shutdown
command over the given socket, causing the server
process itself to exit (all connected sessions will be dropped).
Start an Isabelle PIDE session, implicitly building images if needed.
Gracefully stop a running session (session_stop
).
Load / re‑load theories into the session (use_theories
).