15 poked

The poke application is a REPL (Read-Evaluate-Print-Loop) and therefore the user interacts with it by providing Poke statements or expressions (or dot-commands) in the standard input, and then the program prints the response to the commands in the standard output, or standard error. This is good for human users, but not that convenient for other programs that may wish to communicate with a poke incremental compiler.

poked is a different sort of application that accepts Poke code (and more) over Unix sockets and provides responses over the same socket. This is very convenient for programs to interact with the poke incremental compiler. The client programs that interact with poked are called pokelets.

This form of interaction is particularly userful to write user interfaces to GNU poke, in the form of several pokelets. Examples of such interfaces are Emacs interface to poke and pacme.

poked is basically a message broker that provides (for now) 120 input channels and 120 output channels. The first 60 channels are reserved for the poked developers in order to provide standard channels whose meaning is fixed and the same for any pokelet. The rest of the channels can be freely dedicated for any purpose by anybode else.

The combination of channel number and channel direction creates the client’s role. For now, it’s a single byte. The most significant bit determines whether it’s an input or output channel. Or in poke syntax:

var PDAP_DIRECTION_IN  = 0 as uint<1>,
    PDAP_DIRECTION_OUT = 1 as uint<1>;

type PDAP_Role = struct uint<8>
  {
    uint<1> direction;
    uint<7> channel : 0 < channel && channel <= 120;
  };

Pokelets are expected to write their role over the socket when they’re connected to the poked.

poked, on start up, will create a Unix socket and prints current options to the stdout. Options are a pair of space-separated key/values, each on one line. Options will end with an empty line. An example of poked output:

socket_path /tmp/poked.ipc
pdap_version 0

Currently, only first two input channels are active. Input channel number 1 is for code input which means anything sent to this channel will be compiled and executed using pk_compile_buffer function of libpoke; and input channel number 2 is for command input which will compile and execute the input message using pk_compile_statement function.

For output channels:

Channel 1

Terminal output.

Channel 2

View (vu) output.

Channel 3

Poke Virtual Machine (PVM) disassembly output.

Channel 4

Treevu (tree view) output (not supported yet).

Channel 5

Auto-completion output.

Channel 6

CPU disassembly output.

The format of each message written to output channels are documented in pdap.pk pickle.

The following functions are available for pokelets:

poked_pdap_version

Version of current PDAP (PokeD Application Protocol).

poked_libpoke_version

Version of libpoke.

poked_restart

Restart the Poke environment of poked.

poked_exit

Exit the poked.

poked_chan_send

Signature: (uint<7> chan, byte[] data) void. Send data to the specified output channel.

The following variable is also available for pokelets to use:

poked_after_cmd_hook

An array of callbacks to be run after executing the command (received from input channel 2). Callback signature: ()void.