2022-12-24 16:53:49 +00:00
|
|
|
# LuaML: An experimental markup language and 'browser' for it
|
2022-08-14 17:17:53 +01:00
|
|
|
|
2022-12-24 16:53:49 +00:00
|
|
|
Demo of a simple structured editor for formatted text atop an infinite 2D
|
|
|
|
surface that can be panned and zoomed.
|
2022-05-30 01:03:01 +01:00
|
|
|
|
2022-12-24 16:53:49 +00:00
|
|
|
For ease of implementation, LuaML documents are always legal Lua objects
|
|
|
|
rather than a first-class language like HTML. A simple example:
|
|
|
|
|
|
|
|
```
|
|
|
|
{ type='text', data={'hello, world!',} }
|
|
|
|
```
|
|
|
|
|
|
|
|
Text object data consists of an array of strings, one for each line. No
|
|
|
|
newlines at the moment. (Everything is subject to change.)
|
|
|
|
|
|
|
|
You can draw various shapes on the surface:
|
|
|
|
```
|
|
|
|
{type='line', data={0,0, 0,600}},
|
|
|
|
{type='line', data={0,0, 800,0}},
|
|
|
|
{type='text', data={'0'}, x=-20,y=-20},
|
|
|
|
{type='rectangle', x=50,y=50, w=20,h=80, r=1,g=0,b=0},
|
|
|
|
{type='text', data={'abc', 'def'}, x=150, y=50, w=50,h=50, fg={r=0,g=0.4, b=0.9}},
|
|
|
|
{type='circle', x=300,y=200, radius=40, r=1,g=0,b=1},
|
|
|
|
{type='arc', x=0,y=0, radius=50, angle1=0, angle2=math.pi*2/3},
|
|
|
|
{type='ellipse', x=100,y=100, radiusx=10, radiusy=50},
|
|
|
|
{type='bezier', data={25,25, 25,125, 75,25, 125,25}},
|
|
|
|
```
|
|
|
|
|
|
|
|
But most of the design effort so far has focused on the 3 text types:
|
|
|
|
* `text` for runs of text to be line-wrapped over the given `width`.
|
|
|
|
* `rows` and `cols`, the only hierarchical types, ways to compose `text` nodes
|
|
|
|
into various grid layouts.
|
|
|
|
|
|
|
|
Some more examples.
|
|
|
|
|
|
|
|
Adjust foreground/background color (akin to a `div` with inline `style`):
|
|
|
|
```
|
|
|
|
{ type='text', fg={r=1,g=0,b=0}, bg={r=1,g=1,b=0},
|
|
|
|
data={'hello, world!'}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
Two-column text:
|
|
|
|
```
|
|
|
|
{ type='cols', data={
|
|
|
|
{type='text', data={'first column'}},
|
|
|
|
{type='text', data={'second column'}},
|
|
|
|
}}
|
|
|
|
```
|
|
|
|
|
|
|
|
A table with two rows and two columns:
|
|
|
|
```
|
|
|
|
{ type='cols', data={
|
|
|
|
{ type='rows', data={
|
2022-12-25 05:24:46 +00:00
|
|
|
{type='text', data={'abc'}},
|
|
|
|
{type='text', data={'def'}},
|
2022-12-24 16:53:49 +00:00
|
|
|
}},
|
|
|
|
{ type='rows', data={
|
2022-12-25 05:24:46 +00:00
|
|
|
{type='text', data={'ghi'}},
|
|
|
|
{type='text', data={'jkl'}},
|
2022-12-24 16:53:49 +00:00
|
|
|
}},
|
|
|
|
}}
|
|
|
|
```
|
|
|
|
|
|
|
|
(With the current design, cols of rows seem strictly superior to rows of cols.
|
|
|
|
Column boundaries line up consistently across rows.)
|
|
|
|
|
|
|
|
This is still quite incomplete. Come help figure out its future. Currently
|
|
|
|
supported "attributes":
|
|
|
|
* `fg`, `bg` for color (no `blink` tag yet)
|
|
|
|
* `margin` (used as `margin-left` or `margin-top` depending on whether the
|
|
|
|
parent node has `cols` or `rows` respectively)
|
|
|
|
* `width` in pixels (I'd like to add '%' units here.)
|
|
|
|
|
|
|
|
Since this is all Lua, unrecognized attributes are silently ignored. In the
|
|
|
|
app itself you'll see attributes like `name` and `doc`. (This is a nightmare
|
|
|
|
if you imagine this turning into some sort of long-lived standard with
|
|
|
|
versions and compatibility guarantees. I don't. I just want an app-internal
|
|
|
|
format for creating UIs with very little code.)
|
|
|
|
|
|
|
|
LuaML.love is a fork of [lines.love](http://akkartik.name/lines.html), an
|
2022-12-01 03:45:17 +00:00
|
|
|
editor for plain text where you can also seamlessly insert line drawings.
|
2022-06-07 02:33:44 +01:00
|
|
|
Designed above all to be easy to modify and give you early warning if your
|
|
|
|
modifications break something.
|
|
|
|
|
2023-01-25 02:46:40 +00:00
|
|
|
## Getting started
|
|
|
|
|
|
|
|
Install [LÖVE](https://love2d.org). 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.
|
2022-06-07 21:58:38 +01:00
|
|
|
|
2023-01-08 16:11:15 +00:00
|
|
|
Run this app from the terminal, [passing its directory to LÖVE](https://love2d.org/wiki/Getting_Started#Running_Games)
|
2022-08-14 16:52:58 +01:00
|
|
|
|
2022-12-24 16:53:49 +00:00
|
|
|
You'll see a page that's currently hard-coded in the app.
|
|
|
|
|
|
|
|
![initial view](assets/1.png)
|
|
|
|
|
|
|
|
All text is currently editable. There's a table on the right that will grow
|
|
|
|
and shrink as you add and delete text.
|
|
|
|
|
|
|
|
Changes you make are currently not saved. This is just a demo.
|
|
|
|
|
|
|
|
To pan, drag the surface around. To increase/decrease zoom, press `ctrl+=`,
|
|
|
|
`ctrl+-` respectively. To reset zoom press `ctrl+0`.
|
2022-06-07 02:33:44 +01:00
|
|
|
|
new file-system format for freewheeling apps
1. No more version history, now we have just the contents of the current
version.
2. Editing a definition no longer changes the order in which definitions
load.
This should make repos easier to browse, and more amenable to modify.
You don't need driver.love anymore. And a stable order eliminates some
gotchas. For example:
using driver.love, define `Foo = 3` in a definition
define `Bar = Foo + 1`
edit and redefine `Foo = 4`
Before this commit, you'd get an error when you restart the app.
Definitions used to be loaded in version order, and editing a definition
would move it to the end of the load order, potentially after
definitions using it. I mostly avoided this by keeping top-level
definitions independent. It's fine to refer to any definition inside a
function body, we only need to be careful with initializers for global
variables which run immediately while loading.
After this commit you can still end up in a weird state if you modify a
definition that other later definitions use. In the above example, you
will now see Foo = 4 and Bar = 4. But when you restart, Foo = 4 and Bar
= 5. But that's no more confusing than Emacs's C-x C-e. It's still
a good idea to keep top-level definitions order-independent. It's just
confusing in a similar way to existing tools if you fail to do so. And
your tools won't tend to break as badly.
Why did I ever do my weird version history thing? I think it's my deep
aversion to risking losing any data entered. (Even though the app
currently will seem to lose data in those situations. You'd need to
leave your tools to find the data.) Now I rely on driver.love's undo to
avoid data loss, but once you shut it down you're stuck with what you
have on disk. Or in git.
I also wasn't aware for a long time of any primitives for deleting
files. This might have colored my choices a lot.
2023-04-16 19:15:03 +01:00
|
|
|
## Hacking
|
|
|
|
|
2022-12-24 16:53:49 +00:00
|
|
|
To edit formatting you'll need to modify the code for the app. To do
|
2023-01-25 02:39:00 +00:00
|
|
|
this live without restarting the app each time, download [the driver
|
2023-01-23 08:49:48 +00:00
|
|
|
app](https://git.sr.ht/~akkartik/driver.love). Here's an example session
|
2023-01-08 16:11:15 +00:00
|
|
|
using a fork of this repo:
|
2022-06-07 02:33:44 +01:00
|
|
|
|
2022-12-24 16:53:49 +00:00
|
|
|
![making changes without restarting the app](assets/2.gif)
|
2022-06-07 02:33:44 +01:00
|
|
|
|
new file-system format for freewheeling apps
1. No more version history, now we have just the contents of the current
version.
2. Editing a definition no longer changes the order in which definitions
load.
This should make repos easier to browse, and more amenable to modify.
You don't need driver.love anymore. And a stable order eliminates some
gotchas. For example:
using driver.love, define `Foo = 3` in a definition
define `Bar = Foo + 1`
edit and redefine `Foo = 4`
Before this commit, you'd get an error when you restart the app.
Definitions used to be loaded in version order, and editing a definition
would move it to the end of the load order, potentially after
definitions using it. I mostly avoided this by keeping top-level
definitions independent. It's fine to refer to any definition inside a
function body, we only need to be careful with initializers for global
variables which run immediately while loading.
After this commit you can still end up in a weird state if you modify a
definition that other later definitions use. In the above example, you
will now see Foo = 4 and Bar = 4. But when you restart, Foo = 4 and Bar
= 5. But that's no more confusing than Emacs's C-x C-e. It's still
a good idea to keep top-level definitions order-independent. It's just
confusing in a similar way to existing tools if you fail to do so. And
your tools won't tend to break as badly.
Why did I ever do my weird version history thing? I think it's my deep
aversion to risking losing any data entered. (Even though the app
currently will seem to lose data in those situations. You'd need to
leave your tools to find the data.) Now I rely on driver.love's undo to
avoid data loss, but once you shut it down you're stuck with what you
have on disk. Or in git.
I also wasn't aware for a long time of any primitives for deleting
files. This might have colored my choices a lot.
2023-04-16 19:15:03 +01:00
|
|
|
To publish your changes:
|
|
|
|
* delete all files with a numeric prefix from the repo, and then
|
2023-04-21 19:43:14 +01:00
|
|
|
* move all files with a numeric prefix from the [save directory](https://love2d.org/wiki/love.filesystem.getSaveDirectory)
|
|
|
|
to the repo.
|
2022-06-07 02:33:44 +01:00
|
|
|
|
|
|
|
## Keyboard shortcuts
|
|
|
|
|
|
|
|
While editing text:
|
|
|
|
* `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
|
2022-06-17 18:28:25 +01:00
|
|
|
* `alt+right`/`alt+left` to jump to the next/previous word, respectively
|
2022-11-19 08:11:39 +00:00
|
|
|
* mouse drag or `shift` + movement to select text, `ctrl+a` to select all
|
2022-06-07 02:33:44 +01:00
|
|
|
|
2022-12-24 17:09:15 +00:00
|
|
|
When cursor is not in an editor:
|
|
|
|
* arrow keys pan the surface
|
|
|
|
* `shift`+arrow keys pan faster
|
|
|
|
- `pagedown` and `pageup` are aliases for `shift+down` and `shift+up` respectively
|
|
|
|
|
2023-04-21 19:55:34 +01:00
|
|
|
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
|
|
|
|
|
2022-05-30 01:03:01 +01:00
|
|
|
## Known issues
|
2022-05-21 18:36:27 +01:00
|
|
|
|
2023-01-08 16:11:15 +00:00
|
|
|
* 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
|
2023-01-23 08:49:48 +00:00
|
|
|
OS. See [the driver app](https://git.sr.ht/~akkartik/driver.love/src/branch/main/README.md)
|
2023-01-08 16:11:15 +00:00
|
|
|
for details.
|
|
|
|
|
2022-05-18 06:05:00 +01:00
|
|
|
* No support yet for Unicode graphemes spanning multiple codepoints.
|
2022-05-21 18:36:27 +01:00
|
|
|
|
2022-07-08 22:16:48 +01:00
|
|
|
* No support yet for right-to-left languages.
|
|
|
|
|
2023-04-22 07:16:51 +01:00
|
|
|
* Undo/redo may be sluggish in editor windows containing large files. Large
|
|
|
|
files may grow sluggish in other ways.
|
2022-06-05 18:26:35 +01:00
|
|
|
|
2022-06-10 22:19:27 +01:00
|
|
|
* If you kill the process, say by force-quitting because things things get
|
|
|
|
sluggish, you can lose data.
|
|
|
|
|
2022-06-03 21:32:42 +01:00
|
|
|
* Can't scroll while selecting text with mouse.
|
|
|
|
|
|
|
|
* No scrollbars yet. That stuff is hard.
|
2022-06-07 02:33:44 +01:00
|
|
|
|
|
|
|
## Mirrors and Forks
|
|
|
|
|
2023-01-19 04:30:37 +00:00
|
|
|
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.
|
2023-01-23 08:57:13 +00:00
|
|
|
Its immediate upstream is [the template repo for freewheeling apps](https://git.sr.ht/~akkartik/template-live-editor).
|
2023-01-09 05:55:50 +00:00
|
|
|
Updates to it can be downloaded from the following mirrors:
|
2022-06-15 21:35:55 +01:00
|
|
|
|
2023-01-09 05:55:50 +00:00
|
|
|
* https://git.sr.ht/~akkartik/luaML.love
|
2023-01-23 08:57:13 +00:00
|
|
|
* https://codeberg.org/akkartik/luaML.love
|
2022-07-02 23:23:44 +01:00
|
|
|
|
2022-08-14 17:17:53 +01:00
|
|
|
Further forks are encouraged. If you show me your fork, I'll link to it here.
|
2022-07-02 23:23:44 +01:00
|
|
|
|
2023-01-23 08:57:13 +00:00
|
|
|
* https://git.sr.ht/~akkartik/driver.love - the driver app for modifying
|
2023-01-08 17:05:31 +00:00
|
|
|
freewheeling apps without restarting them.
|
2023-04-22 02:43:58 +01:00
|
|
|
* https://git.sr.ht/~akkartik/snap.love - a graph drawing tool.
|
2023-01-08 16:11:15 +00:00
|
|
|
|
2022-06-07 02:33:44 +01:00
|
|
|
## Feedback
|
|
|
|
|
|
|
|
[Most appreciated.](http://akkartik.name/contact)
|