TAL - TopchetoEU's Atrocious Lua

I am very sorry for the hastily written README, I will refactor it.

BIG NOTE NUMERO NIL: This is a project I use for myself. If you decide (for some ungodly reason) to use this project, you use it at your own sanity's risk BIG NOTE NUMERO UNO: As the name suggest, I STRONGLY suggest that you DO NOT use this in production. BIG NOTE NUMERO DOS: The project supports ONLY Linux (and probably Mac, IDK tho). I plan to support Windows, but it's not a priority for me

This is a pseudo-runtime for lua, written in lua. Most importantly, it includes the following shinies:

The event loop (as it stands it's pretty useless, because there aren't any async functions)
Pseudo-arrays (objects with a special prototypes with some nice-to-have functions)
Symmetric coroutines by default, via a modified version of "coro" (avoids some painful problems with asymmetric coroutines)
A nicer REPL with better values display (via the "pprint" function, aka pretty-print)
A better module system (C modules not yet supported), that provides relative imports and global scope isolation
Some utility modules, like "json", "path" for path manipulation and "args" for CLI args reading

Installing

The included Makefile can be used to copy the necessary files where they need to be - on linux machines, it should be enough to run make install. This command will copy tal into ~/.local/bin and will copy the stdlibs into ~/.local/lib/.tal_mod. Feel free to do that manually

Usage

The runtime is used through the CLI tal command. It works pretty much like the lua command, for more details, read the --help output.

One major difference is that the executed file will be imported as a module, and it is expected that it either:

Exports the main function
Exports a field main that is a function or
Defines a main global that is a function

You can still write scripts that don't exports a main function, but they won't be able to accept CLI arguments.

Module system

The module system is inspired both by CommonJS and Lua's module system. I believe that I have achieved a pretty nice balance between both.

You have two ways of importing modules - with import and with require. Using import requires you specify the real "path" to the module, aka "./my/precious/module.lua". On the other hand, require supports the lua-styled syntax - ".my.precious.module". Note that to use relative imports you need to prefix the module ID with at least one dot. Every additional prefix dot equates to one ../ prepended to the id. Example: .a.b.c -> ./a/b/c.lua, ..a.b -> ../a/b.lua, ...a.b -> ../../a/b.

If the imported ID doesn't start with ./, ../ or /, it will be searched for in the module.path array. If it isn't found there, an error will occur. On the other hand, if the ID has one of these prefixes, it won't be searched in the module.path folders. This ensures that you know exactly which module you are importing.

Exporting can happen in several ways:

Just returning - this works exactly how lua's module system would - it will override the default exports object with the return value. Note that if you return zero values, no overriding will occur. This has the best IDE support
Assigning to the exports global - like NodeJS's module system, exports is a reference to the default module.exports object. This has no IDE support
Assigning to the module.exports field - will work like CommonJS
Assigning to module.returns - this will expect the return of box, aka a tuple with an integer n field. In this way, you can specify what values will be returned by an eventual import of the module. This is how the values, return-ed by the module are stored
By using the export function - this function accepts one object and will assign all of its fields to module.exports. This has no IDE support, and frankly, IDK if it's possible.

Existing code support

none. don't even try.

LuaLS support

I've written some ad-hoc meta modules, but 1. the type definitions are shitty and 2. I never managed to get the LuaLS addon working at all :/

Documentation

Currently, documentation is virtually inexistent. Use --help where applicable, otherwise, go spelunking trough the code (I'm sorry, but read big note numero nil).

4.3 KiB Raw Blame History