document the freewheeling protocol

[?]

May 1, 2023, 7:07 AM

GX6ZCSI76XEPPYNRTZA2JSOG2BCJGXFN7CO5C5BB7D7QZGMLL7XQC

Dependencies

[2] HXH4AIF2 primitives for writing tests
[*] N2NUGNN4 include a brief reference enabling many useful apps

Change contents

edit in reference.md at line 358

[2.1123]

### The freewheeling protocol with the driver

Freewheeling apps currently respond to the following commands from the driver:
* `QUIT` -- tells the current app to quit
* `RESTART` -- tells the current app to reinitialize after saving any settings
* `MANIFEST` -- requests a list of definitions the app knows about. The
app returns only definitions that were created using the freewheeling
framework and so can be modified and errors recovered from.
* `DEFAULT_MAP` -- requests a default map of the code. Everyone is free to
create their own "memory palace", but this is usually a good default to
start with.
* `GET <name>` -- requests the source code for definition `<name>`.
* `GET* <name> ...` -- requests source code for multiple definitions.
* `DELETE <name>` -- requests deletion of the definition `<name>`. Only
permitted for definitions created using the freewheeling framework, not
lower-level definitions.
* anything else -- is considered a new definition to be loaded into the
app.

Commands may cause an error response, which is sent back to the driver.

In addition, any _run-time_ errors caused as the app executes are also sent
back to the driver. These don't need an explicit command from the driver.

Some primitives available for complying with the protocol:

* `live.receive_from_driver()` -- looks for a message from the driver, and
returns nil if there's nothing.

* `live.send_to_driver(msg)` -- sends a message to the driver.

* `live.send_run_time_error_to_driver(msg)` -- sends an error to the driver.
Automatically invoked by the LÖVE error handler, so you shouldn't need to
call this.

* `live.get_cmd_from_buffer(buf)` -- helper to extract the first word from a
command.

* `live.get_binding(name)` -- look up the repo for the source code for a
`name`.