# Thin programming environment for making edits to live, "freewheeling" LÖVE apps
[](https://0dependencies.dev)
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.
This repo is an example of a [Freewheeling App](http://akkartik.name/freewheeling),
designed above all to be easy to run, easy to modify and easy to share.
## Getting started
Install [LÖVE](https://love2d.org). It's just a 5MB download, open-source and
extremely well-behaved.
[Run the app using LÖVE.](https://love2d.org/wiki/Getting_Started#Running_Games)
You must have a ["freewheeling"](http://akkartik.name/post/roundup22) 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](https://git.sr.ht/~akkartik/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:
[Some reference documentation on how to create your own apps.](reference.md)
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](https://love2d.org/wiki/love.filesystem.getSaveDirectory).
## 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](http://akkartik.name/lines.html), an
editor for plain text where you can also seamlessly insert line drawings.
Its immediate upstream is [luaML.love](https://git.sr.ht/~akkartik/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.](http://akkartik.name/contact) Messages, PRs, patches,
forks, it's all good.