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.

driver.love is a fork of lines.love, an editor for plain text where you can also seamlessly insert line drawings. Designed above all to be easy to modify and give you early warning if your modifications break something.

Getting started

Install LÖVE. It's just a 5MB download, open-source and extremely well-behaved. I'll assume below that you can invoke it using the love command, but that might vary depending on your OS.

Run this app from the terminal, passing its directory to 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

To edit formatting you'll need to modify the code for the app. To do this live without restarting the app each time, download the driver app. Here's an example session using a fork of this repo:

Some reference documentation on how to create your own apps.

To publish your changes:

• delete all files with a numeric prefix from the repo, and then
• move all files with a numeric prefix from the save directory to the repo.

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.

• Don't give up your other tools just yet. It's easy to make a mistake that the app doesn't recover from when you fix it. Try restarting the app, and if it still doesn't work, perhaps you need to fix the initial load. This isn't yet a tool you can keep open for months on end. (And I'm ambivalent about making it such a tool since your programs might stop working for others.)

• I still see driver and the app being driven occasionally crash. When I do I try to make things more robust. If you do you'll quite possibly crash again if you try to restart. In such a situation you'll have to bump down to editing the underlying version files by other means. See representation.md for details of the underlying representation on disk.

• Given the above issues, both this driver and its client freewheeling app benefit from being launched in terminal windows rather than by being clicked on in a desktop OS.

• No support yet for Unicode graphemes spanning multiple codepoints.

• No support yet for right-to-left languages.

• Undo/redo may be sluggish in editor windows containing large files. Large files may grow sluggish in other ways.

• If you kill the process, say by force-quitting because things things get sluggish, you can lose data.

• 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://codeberg.org/akkartik/driver.love

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

Feedback

Most appreciated.