Camlet: Plug-ins

To get started writing a plug-in, see the quick start guide for Python or Rust.

For a full reference of all commands, see command reference.

Plug-ins implement new functionality for camlet. Each plug-in is a directory located in camlet’s plug-in directory (~/.config/camlet/plugins by default). Each plug-in directory contains:

A file called about.txt
An executable file called run or run.<something>. This will be run by camlet (as a child process) whenever the plug-in is enabled. camlet sends commands to the plug-in while it is running and waits for its responses.

Also camlet generates the following files, and puts them in your plug-in’s directory:

A file called settings.txt to store the plug-in’s settings. You shouldn’t try to read or change that file yourself, since the format may change from version to version.
camlet_disabled, if the user requests the plug-in to be disabled.
In the future, potentially other files/directories starting with camlet. So, don’t create any such files yourself since they may conflict. It’s okay to have a file starting with camlet in a subdirectory though.

Technical details

You can safely ignore this section if you’re just using a camlet plug-in library.

camlet starts plug-in processes with file descriptor 3 connected to a socket which can be used for communication.

At any time, camlet can send a “command” to a plug-in. Each command has the format

<name>
<argument1_name>:
><argument1_value_line1>
><argument1_value_line2>
><etc.>
<argument2_name>:
><argument2_value_line1>
><argument2_value_line2>
<etc.>

(The last argument is followed by an extra newline to indicate that the arguments are over.)

This means that the argument argument1_name is given the value "<argument1_value_line1>\n<argument1_value_line2>\n...\n<argument1_value_lineN>".

camlet sends out commands to every plug-in for which the command is applicable simultaneously, then, if the <name> doesn’t start with an underscore, it waits for a response from each plug-in, which must be of the form:

ack <name>
<response_argument1_name>:
><response_argument1_value_line1>
><response_argument1_value_line2>
><etc.>
<response_argument2_name>:
><response_argument2_value_line1>
><response_argument2_value_line2>
<etc.>

(The last argument is followed by an extra newline to indicate that the arguments are over.)

Note that you should not send responses for any commands starting with _.

All response arguments are always optional, except for the ok/error response to the init command. Plug-ins must respond to all commands, even ones they don’t recognize so that camlet isn’t waiting around forever for a response that isn’t coming. In the future, more commands may be added without a major version change. You should respond to an unrecognized command with an empty response.