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

In progress. Browse a directory of articles like [Kragen Sitaker's dercuano](https://gitlab.com/kragen/dercuano).

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
  * ...

My tentative goal is to be able to post comments on articles, send updates
around using git, and browse comments from all commenters in line with
articles. It's unclear whether it will be economical to support editing
articles. My priority is a commenting experience rather than a CMS for the
author(s) of articles.

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.

Status: you can read articles. There's a 'comment' button, but it doesn't do
anything yet.

![demo](assets/20221228-luaML-driver.gif)

_The name_: 'pothi' is [Sanskrit for 'book'](https://en.wiktionary.org/wiki/%E0%A4%AA%E0%A5%8B%E0%A4%A5%E0%A5%80),
often [a loose-bound collection of palm leaf manuscripts](https://en.wikipedia.org/wiki/Palm-leaf_manuscript).

driver.love is a fork of [lines.love](http://akkartik.name/lines.html), an
editor for plain text where you can also seamlessly insert line drawings.

pothi.love is a ["freewheeling" app](https://git.sr.ht/~akkartik/driver.love)
that you can read and modify the source code for as it runs.

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

Run this app from the terminal, [passing its directory to LÖVE](https://love2d.org/wiki/Getting_Started#Running_Games).
pothi.love will print the path where it expects to find articles. Quit, create
a folder called `data/` under this path, put text files there. Restart.

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.

For example, I created the `data/` dir using these commands on my machine:

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.

  ```
  cd ~/.local/share/love/pothi
  git clone http://canonical.org/~kragen/sw/pavnotes2.git data
  ```

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

And now I can see the files when I restart:

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

  ```
  love ~/pothi
  ```

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.

The app will open to a directory view by default (though there's no scrolling
or filtering yet, sorry..). Click on any filename to read it.

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

To modify it live without restarting the app each time, download [the driver

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.

While reading a single file:

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+o` to switch to a different file
* `ctrl+f` to search for strings

* `ctrl+right`/`ctrl+left` to jump to the next/previous word, respectively

When no definition has focus:
* arrow keys pan the surface

* mouse drag and arrow keys pan the surface

* 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](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.

* Both freewheeling apps and the driver for them currently benefit from being
  launched in terminal windows rather than by being clicked on in a desktop
  OS. See [the driver app](https://git.sr.ht/~akkartik/driver.love/src/branch/main/README.md)
  for details.

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:

Its immediate upstream is [text.love](https://git.sr.ht/~akkartik/text.love),
a version without support for line drawings. Updates to it can be downloaded
from the following mirrors:

* https://git.sr.ht/~akkartik/driver.love
* https://codeberg.org/akkartik/driver.love

* https://git.sr.ht/~akkartik/pothi.love