Oil's Headless Mode: For Alternative UIs

A GUI or TUI process can start Oil like this:

osh --headless

and send messages to it over a Unix domain socket. In this mode, the language and shell state are decoupled from the user interface.

This is a unique feature that other shells don't have!

Note: This doc is in progress. Join the #shell-gui channel on Zulip for current information.

Table of Contents
The General Idea
How to Write a Client for a Headless Shell
Implement the FANOS Protocol
Send Commands and File Descriptors to the "Server"
Query Shell State and Render it in the UI
Example Code
Related Links

The General Idea

The UI process should handle these things:

The shell process handles these things:

How to Write a Client for a Headless Shell

Implement the FANOS Protocol

FANOS stands for File descriptors and Netstrings Over Sockets. It's a control protocol that already has 2 implementations, which are very small:

Send Commands and File Descriptors to the "Server"

List of commands:

TODO: More commands.

Query Shell State and Render it in the UI

You may want to use commands like these to draw the UI:

You can redirect them to a pipe, rather than displaying them in the terminal.

Remember that a fundamental difference between a REPL and a GUI is that a GUI shows state explicitly. This is a good thing and you should take advantage of it!

Example Code

See client/headless_demo.py. This is pure Python code that's divorced from the rest of Oil.

Related Links

Feel free to edit these pages:


Generated on Wed May 3 15:38:09 EDT 2023