calculon/README.md

# Calculon

A basic math library to package Teal project with LuaRocks.

Calculon is a simple library written with the Teal language that is packaged with LuaRocks.

The `consumer-project` is another LuaRocks project using Teal that tries to use the Calculon library.

![Calculon](doc/Calculon.webp "Calculon")

# TODO

* ~~The consumer works only because the generated file can find the module thanks to `./lua` that includes paths to locally installed packages~~ → is it really an issue?
* ~~Distribute teal files in the rock~~ → I think the rock should be Lua only (+ types definition for teal optionally)
* To not commit generated Lua files, the calculon module can have a `generate-rock` script that build and package the module (Can be done from a CI/CD like GitHub Actions 💡)
* The type definition trick works by abusing Luarocks specs, this needs to me standardized

# Logbook

## e18f54c977 init

Initialize a teal project with `cyan init`, then write the `calculon.tl` Lua.

Note : I also added `.gitignore` and `.gitkeep` files to not commit generated
files from `cyan build`.

## d24e69a41e add(consumer) init

Add a Lua consumer script to try the calculon lib. It can be run with:

```sh
lua consumer.lua
```

Notes : 

* We need to first build the lib with `cyan build`
* The consumer needs to require calculon from the build directory

## a433eb2fe4 add(luarocks) init

Initialize a Luarocks module in the current directory.

I need to add the module `calculon = "build/calculon/init.lua"` to make the
rock not empty.

## b4d00c05ae add(build) force commit lua

Because the rock needs the generated Lua, I have force commit it 😭

## acb833e8e1 add(consumer) load calculon as module

Now that the calculon lib ships the Lua files, the consumer can  load it as a normal module!

## 5eb06ccafb chore(consumer) move it to a project

Move the consumer to its own project with Luarocks.

Notes : Calculon is not uploaded to Luarocks repositories. We need to install calculon manually from the rockspec file with: `./luarocks install ../calculon-0.1-1.rockspec`

## dac8260ea9 add(consumer) teal

Move the consumer to teal!

It can be built with `tl build`. Then run with `./lua build/consumer.lua`.

Note :

* To prevent the missing types definition error, I need to use the trick from tabular module
* We can't run the teal file directly `tl run src/consumer.tl` 😭

# 72c84c39e6 add(d.tl) calculon type definition

Add type definition to the calculon module and package.

Note : We force the type definition to be part of the module by abusing the `build.install.lua` table.

# 3baa006cb0 add(consumer) use type definitions

The consumer module doesn't need any trick thanks to the type definition file being part of the rock!

Note : We need to include the `lua_modules/share/lua/5.4` path to the tlconfig for this to work

# References

* https://github.com/teal-language/tl/blob/master/docs/tutorial.md
* https://github.com/teal-language/cyan
* https://github.com/teal-language/teal-types
* https://github.com/hishamhm/tabular

Image from https://futurama.fandom.com/wiki/Calculon