Fork of Lua 5.1 to encourage end-user programming
Go to file
Kartik K. Agaram 294c135d3f elaborate a little more on install instructions
Thanks to Mariano Guerra for the Nix command, and to Konrad Hinsen for
the Guix command.
2021-12-03 20:55:32 -08:00
doc tour: add some images 2021-11-27 12:18:23 -08:00
src support the comment/uncomment hotkey on Macs 2021-12-03 20:19:32 -08:00
.gitattributes . 2021-11-11 08:56:45 -08:00
.gitignore . 2021-11-23 23:07:34 -08:00
COPYRIGHT.md new fork of Lua 5.1 2021-10-22 19:24:44 -07:00
Makefile drop an obsolete build target 2021-11-10 08:35:08 -08:00
README.md elaborate a little more on install instructions 2021-12-03 20:55:32 -08:00
advent.tlv more speculatively efficient advent.tlv 2021-12-02 20:40:51 -08:00
chesstv.tlv . 2021-11-26 21:56:22 -08:00
counter.tlv . 2021-11-26 21:56:22 -08:00
hanoi.lua learning about Lua's debug infrastructure 2021-11-11 22:05:15 -08:00
hanoi.tlv . 2021-11-26 21:56:22 -08:00
life.tlv . 2021-11-26 21:56:22 -08:00
manual_tests why not keep manual tests in the repo? 2021-11-29 08:18:28 -08:00
shell.nix elaborate a little more on install instructions 2021-12-03 20:55:32 -08:00
template.tlv a starting point for new apps 2021-11-27 21:08:05 -08:00
tour.md tour: add some images 2021-11-27 12:18:23 -08:00

README.md

Teliva - an environment for end-user programming

“Enable all people to modify the software they use in the course of using it.” — https://futureofcoding.org/episodes/033.html

“What if we, and all computer users, could reach in and modify our favorite apps?” — https://www.inkandswitch.com/end-user-programming

“Software must be as easy to change as it is to use.” — https://malleable.systems

What's this, then?

An extremely naïve, brutalist environment for little text-mode Lua apps that are easy to modify.

Here's how you run one of the example apps (the Tower of Hanoi):

git clone https://github.com/akkartik/teliva
cd teliva
make linux  # replace with 'macosx' or 'bsd' depending on your OS
src/teliva hanoi.tlv
screenshot of Teliva running the Towers of Hanoi

No matter what app you run, you are always guaranteed access to a single obvious, consistent way (currently the hotkey ctrl-e) to edit its sources. Make a change, hit ctrl-e again, and the app will run with your updates. (video)

You will need some Unix-like platform with a C compiler and the ncurses and openssl libraries. Some possible commands to install them, depending on your OS and package manager of choice:

  • guix shell -D lua openssl -- make linux
  • nix-shell --pure (from a directory containing shell.nix in this repo)
  • sudo apt install libncursesw6-dev openssl
  • brew install ncurses openssl

So far I've tested Teliva on Linux, Mac OS X and OpenBSD; it should also work on other flavors of BSD, WSL on Windows, etc. with only minor modifications.

Isn't this just an IDE?

There's one big difference: these apps are not intended to be runnable outside of the Teliva environment. Editing the sources will always be a core feature that's front and center in the UI.

A second, more subtle difference: it's primarily an environment for running apps, and only secondarily for editing them. Starting up the environment puts you in a running app by default. Creating an app from a clean slate is a low-priority use case, as is lots of specialized support for developing complex apps. The sweet spot for Teliva is simple apps that people will want to edit after using for a while.

Why Lua?

It's reputedly the fastest interpreted language per line of implementation code.

Will it run any Lua program?

Not quite. My priority is providing a good experience for newcomers to comprehend and modify the programs they use. If it's not clear how to provide that experience for some kinds of Lua programs, I'd rather disable support for them in Teliva and let people use regular Lua. Or other platforms!

  • This approach doesn't make sense for batch programs, I think. I also don't yet have a good story for building server programs in this way.

  • I don't know how to obtain a simple, shallow graphics stack, so there's no support for graphics at the moment.

  • Teliva initializes the ncurses library by default, so apps should assume they have access to a (color, UTF-8) text-mode window for printing text to, and a keyboard for reading unbuffered keystrokes from.

  • Teliva doesn't use files for source code, so the require keyword no longer makes sense. You get some libraries preloaded (see below). Beyond those, apps should include all Lua code they want to use.

  • I want to provide sandboxed access to system resources (file system, network, etc.) which will likely create incompatibilities with the standard library. I'm disinclined to try to improve on Lua syntax, however. It's not my favorite, but it's good enough.

  • To create a well-behaved sandbox, Teliva doesn't support adding libraries with C bindings beyond the few it starts up with.

Teliva is not tested much at all yet. This is my first time programming either in Lua or within Lua. So bug reports are most appreciated if Lua programs behave unexpectedly under Teliva.

What's included?

  • Lua 5.1
  • The ncurses library for building text-mode user interfaces. (Alternative documentation)
  • The Kilo text editor, modified to use ncurses. (Read more about it in this fantastic walk-through.)
  • The lcurses binding for ncurses (as module curses).
  • The luasocket library of networking primitives (modules socket, http, url, headers, mime, ltn12).
  • The luasec library for HTTPS support (modules https and ssl).
  • The json.lua library for serializing/deserializing to JSON (module json).

The modules mentioned above are always available, just like standard Lua 5.1 libraries. They're available in their entirety with one exception:

While most things in these modules are currently available, I expect to delete capabilities throughout this stack as I discover features that don't fit well with the Teliva experience. If you find Teliva of use, please introduce yourself to me so that I am aware of your use cases. Anybody who is interested can gain a say in its future direction.

Known issues

  • Colors are currently hardcoded. To obtain say a dark background, modify the call to assume_default_colors() in function main() at the bottom of src/lua.c. If you do this, you'll likely also need to tweak other colors for legibility. Look for calls to FG(), BG() and COLOR_PAIR().

  • Backspace is known to not work in some configurations. As a workaround, typing ctrl-h tends to work in those situations.

  • Keys outside the main keyboard area are mostly not supported. This includes the delete key when it's set away from the main keyboard area. (Macs call the backspace key “delete”; it should behave like backspace. As a consequence the menu sometimes mentions keys that don't work, just to encourage people to try options.)

What's with the name?

Teliva is the Tamil root for clear. Very much aspirational.

Other apps to try out

  • Conway's Game of Life, as an example of an animated local app.

    src/teliva life.tlv
    

    video

  • A viewer for LiChess TV, as an example of animation and accessing a remote API over a network.

    src/teliva chesstv.tlv
    

    video

Feedback

Most appreciated.