Thin programming environment for making edits to live, "freewheeling" LÖVE apps

Use this app to communicate over a back-channel with LÖVE apps that follow a certain protocol:

https://git.sr.ht/~akkartik/night.love -- sample app showing a slowly revolving night sky
https://git.sr.ht/~akkartik/template-live -- template for new apps
https://git.sr.ht/~akkartik/broadsheet.love -- multi-column text reader
https://git.sr.ht/~akkartik/mastodon-unfurl.love -- mastodon thread visualizer
https://git.sr.ht/~akkartik/spell-cards.love -- flash cards for drilling spelling
https://git.sr.ht/~akkartik/bf.love -- BF programming environment
https://git.sr.ht/~akkartik/luaML.love -- simple web-browser-like box model implementation
https://git.sr.ht/~akkartik/template-live-editor -- template for new apps that need editor widgets
...

Communication happens over temporary files in the file system that should live in an internal directory, but might end up in your home directory. Using these files, driver.love can make changes to these apps without needing to restart them.

demo

This repo is an example of a Freewheeling App, designed above all to be easy to run, easy to modify and easy to share.

Getting started

Install LÖVE. It's just a 5MB download, open-source and extremely well-behaved.

Run the app using LÖVE.

You must have a "freewheeling" client app running that can be communicated with and that you're trying to modify; otherwise driver.love will hang until it finds one, and might need to be force-quit. (Also, bad things will happen if you have more than a single client app running. Or if you close one app and open another without restarting the driver. Just always open the app and then the driver. If you close the app, close the driver.)

So download and run say broadsheet.love in a separate terminal.

Now try pressing ctrl+l in this driver app. Select on by some combination of typing letters and moving the arrow keys. It provides a useful orientation of available hooks when programming live, and also mentions an important gotcha.

Each definition lives in a blue box. You have to follow a specific Lua syntax where the name of the definition comes first: foo = function(...) ... end rather than function foo(...) ... end. The driver treats the first word in a definition is its name.

To pan, drag the surface around. To increase/decrease zoom, press ctrl+=, ctrl+- respectively. To reset zoom press ctrl+0.

To move a definition, drag the bar on the top-left.

Functions that start with test_ are tests, and run any time you hit f4. The driver will highlight them in green or red when they fail.

Hacking

While this app is used to help modify other apps, it is also itself a freewheeling app you can modify with another copy of itself with just a few changes. On a unix-like platform, run the following commands to turn this repo into a "meta-driver":

sed -i -e 's/app_driver/driver_driver2/g' -e 's/driver_app/driver2_driver/' driver.lua
sed -i -e 's/driver2_driver/driver3_driver2/g' -e 's/driver_driver2/driver2_driver3/' live.lua

Now you can modify the code for the driver without restarting it each time. Run some app, then run this driver, then run the meta-driver. Here's an example session:

making changes without restarting the app

Some reference documentation on how to create your own apps.

If you run off of this repo, changes to the driver will get saved right here. If you first create a .love file, your changes will go into the save directory.

Keyboard shortcuts

At any time:

f4 to send current buffer to the client app. (Run only one such "freewheeling" app at a time.)
ctrl+l to browse a list of definitions within the app that are available to edit. (Not everything will be.)
ctrl+d to delete a definition.
ctrl+g to zoom out to see everything, or zoom back in to where you were.

When some definition has focus (a cursor):

ctrl+f to find patterns within a file
ctrl+c to copy, ctrl+x to cut, ctrl+v to paste
ctrl+z to undo, ctrl+y to redo
ctrl+= to zoom in, ctrl+- to zoom out, ctrl+0 to reset zoom
ctrl+right/ctrl+left to jump to the next/previous word, respectively
mouse drag or shift + movement to select text, ctrl+a to select all

When no definition has focus:

arrow keys pan the surface
shift+arrow keys pan faster
- pagedown and pageup are aliases for shift+down and shift+up respectively

Exclusively tested so far with a US keyboard layout. If you use a different layout, please let me know if things worked, or if you found anything amiss: http://akkartik.name/contact

Known issues

Bad things will happen if you have more than a single client app running. Or if you close one app and open another without restarting the driver. Just always open the app and then the driver. If you close the app, close the driver.
You have to follow a specific Lua syntax where the name of the definition comes first: foo = function(...) ... end rather than function foo(...) ... end. The driver treats the first word in a definition is its name. For similar reasons, a definition can't start with a comment. Put comments within functions or after them.
No support yet for Unicode graphemes spanning multiple codepoints.
No support yet for right-to-left languages.
Can't scroll while selecting text with mouse.
No scrollbars yet. That stuff is hard.

Mirrors and Forks

This repo is a fork of lines.love, an editor for plain text where you can also seamlessly insert line drawings. Its immediate upstream is luaML.love, a box model for a Lua-based markup language that models an infinite pannable, zoomable 2D surface. Updates to it can be downloaded from the following mirrors:

https://git.sr.ht/~akkartik/driver.love
https://tildegit.org/akkartik/driver.love
https://git.merveilles.town/akkartik/driver.love
https://codeberg.org/akkartik/driver.love
https://nest.pijul.com/akkartik/driver.love (using the Pijul version control system)

Further forks are encouraged. If you show me your fork, I'll link to it here.

https://git.sr.ht/~akkartik/pothi.love - a browser for a directory of files

Feedback

Most appreciated. Messages, PRs, patches, forks, it's all good.