From a9c1cf9dda7238f197cdf61f95624b7b9a304061 Mon Sep 17 00:00:00 2001
From: TopchetoEU <36534413+TopchetoEU@users.noreply.github.com>
Date: Thu, 6 Feb 2025 02:58:20 +0200
Subject: [PATCH] add readme

---
 .gitignore |  2 ++
 README.md  | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 61 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index fb52eeb..efa3226 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,5 @@
 !/mod/
 !/.gitignore
 !/Makefile
+!/README.md
+!/License
diff --git a/README.md b/README.md
index b199f29..85579fe 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,60 @@
-# tal
+# TAL - TopchetoEU's Atrocious Lua
 
-TopchetoEU's Atrocious Lua
\ No newline at end of file
+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).