# The on-disk representation of freewheeling apps
When you start up a freewheeling app, you'll see a directory printed out in
the parent terminal (always launch it from a terminal window):
```
new edits will go to /home/...
```
When editing such an app using the driver (see [README.md](README.md)), new
definitions will go into this directory. Let's call it `$SAVE_DIR` in the rest
of this doc.
It is always safe to move such definitions into this repo. (We'll call it `.`
in the rest of this doc.) You'll want to do this if you're sharing them with
others, and it's also helpful if the driver crashes on your app. Moving
definitions will never, ever change app behavior.
```sh
$ mv -i $SAVE_DIR/[0-9]* .  # should never clobber any existing files
$ mv $SAVE_DIR/head .  # expected to clobber the existing file
```
Try looking inside the `head` file with a text editor. It'll contain a number,
the current version of the _manifest_ for this app. For example:
```
478
```
This means the current state of the app is in a file called `0478-manifest`.
If you moved the files you should see such a file in `.`. If you open this
file, you'll see a JSON table from definition names to version ids. For
example:
```
{ "a": 273, "b": 478}
```
This means the current definition of `a` is in `0273-a` and of `b` in
`0478-b`.
Poking around these files gets repetitive, so there's a tool to streamline
things:
```
lua tools/stitch-live.lua 0478-manifest
```
`stitch-live.lua` takes a manifest file as its argument, and prints out all
the definitions that make up the app at that version.
To compare two versions of the app, use `stitch-live.lua` to copy the
definitions in each into a separate file, and use a file comparison tool (e.g.
`diff`) to compare the two files.

# Live apps that can have text editor widgets

# Example "freewheeling" app that can be modified without being restarted

A template repo for building live apps that juggle text editor widgets. The
editors support copy/paste, search, infinite undo, etc. You can't quite modify
editor functionality live (yet?).

Running this repo in isolation won't be very helpful. If you haven't yet,
first check out [the driver app](https://codeberg.org/akkartik/driver.love).
This repo is a template you can copy to create your own live apps that juggle
text editor widgets. The editors support copy/paste, search, infinite undo,
etc. You can't modify editor functionality live (yet?).
[More information about the on-disk representation of freewheeling apps.](representation.md)

To run from the terminal, [pass this directory to LÖVE](https://love2d.org/wiki/Getting_Started#Running_Games),
optionally with a file path to edit.
Alternatively, turn it into a .love file you can double-click on:
```
$ zip -r /tmp/text.love *.lua
```

Run this app from the terminal, [passing its directory to LÖVE](https://love2d.org/wiki/Getting_Started#Running_Games)

By default, it reads/writes the file `lines.txt` in your default
user/home directory (`https://love2d.org/wiki/love.filesystem.getUserDirectory`).

To modify it live without restarting the app each time, install [the driver
app](https://codeberg.org/akkartik/driver.love). Here's an example session
using a fork of this repo:

To open a different file, drop it on the app window.

![making changes without restarting the app](assets/2.gif)

While editing text:

Up to you! But within the included editor widget if you use it:

* 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://codeberg.org/akkartik/driver.love/src/branch/main/README.md)
  for details.

* https://codeberg.org/akkartik/luaML.love - a "browser" for a Lua-based
  markup language, loosely analogous to HTML except it's all Lua.