IsabelleClientMini (isabelle_elixir v0.1.0)

View Source

Minimalistic 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

  1. (optionally) Start a resident server with new_server/2 (or reuse an existing one found via list_servers/0). Both commands require a local Isabelle installation whose bin/ directory is on the PATH.
  2. Connect using the password/token reported by the server (connect/3). The corresponding Isabelle server only needs to be accessible via TCP.
  3. Launch a session once per logic image (start_session/2).
  4. Edit/compile theories with use_theories/2, polling for FINISHED | FAILED | NOTE messages via poll_status/2.
  5. Extract results or artefacts with helpers such as extract_results/1.
  6. Stop the session (stop_session/2).
  7. (optionally) Shutdown the server (shutdown_server/1). If running Isabelle locally you can alternatively use kill_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(socket, session_args)

Build session images (wrapper around session_build).

cancel_task(socket, task_id)

Cancel a running asynchronous task (identified by its UUID).

close(socket)

Close a previously opened TCP connection.

connect(password, host_str \\ "127.0.0.1", port \\ 9999)

Open a TCP connection to an Isabelle server and perform the initial password handshake.

Parameters

  • password – token obtained from the server descriptor (returned by new_server/2 or list_servers/0 if running locally).
  • host – IPv4 address as string (default 127.0.0.1).
  • port – TCP port (default 9999).

Return value

 socket – a live socket ready for further commands.  {:error, reason} on connection failures.

echo(socket, value)

Round‑trip test helper that sends echo <json> and returns the decoded value. Useful for verifying the connection.

extract_results(status)

Extract the plain‑text messages from a :finished status keyword list.

extract_session(status)

Grab the session_id UUID from a :finished status keyword list.

help(socket)

Return the list of command names supported by the server (help).

kill_server(name)

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_servers()

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.

new_server(name \\ "elixir", port \\ 9999)

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 in list_servers/0. Defaults to "elixir".
  • port – TCP port on which the server accepts connections. Defaults to 9999.

Return value

[%{"name" => name, "host" => host, "port" => port, "password" => pw}] on success, or {:error, reason} on failure / timeout.

poll_status(socket, acc \\ <<>>)

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 (see extract_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(socket, purge_theories_args)

Purge theories from heap to reclaim memory (purge_theories).

shutdown_server(socket)

Send a shutdown command over the given socket, causing the server process itself to exit (all connected sessions will be dropped).

start_session(socket, session_args)

Start an Isabelle PIDE session, implicitly building images if needed.

stop_session(socket, session_id)

Gracefully stop a running session (session_stop).

use_theories(socket, use_theories_args)

Load / re‑load theories into the session (use_theories).