teal-cli: an unofficial command line interface to the Teal compiler

Teal is a typed dialect of Lua, get it here

Why use this over the official one?

This is an experimental attempt to make the interface a little more friendly looking (internally and externally)
Having the compiler separate from the cli means that it can be written in Teal itself a little more easily
Extensibility and some more conveniece features
Complies to freedesktop standards (the global config file goes to $XDG_CONFIG_HOME/teal)

Why NOT use this over the official one?

Consider literally everything about this unstable until I make a release for luarocks
- this won't be for a while
This is extremely catered towards my needs in particular
Features could be introduced in one commit, then removed two commits later for refactoring

Extensibility

You can add your own commands to the cli by putting a .lua file that returns a specially formatted module (Docs coming eventually™) in $XDG_CONFIG_HOME/teal/commands. Additionally, some useful modules are exposed through the tlcli namespace. In particular tlcli.fs, tlcli.util, and tlcli.loader will probably be the most useful externally.

Dependencies

Teal itself (along with its dependencies)
ltreesitter (for quickly parsing internal dependencies)

Installation

Luarocks

luarocks install --dev teal-cli

Manual

(make sure you have the dependencies)

clone this repo
navigate to the root directory and run tl build to compile (and run busted if you'd like to run the test suite)
add the build directory to your lua path, or copy it somewhere in your lua path
add the bin directory of this repo to your path, or copy the executable somewhere in your path
To see if it works, try running tlc build in the repo, it should build the project into a tmp dir it creates

Usage

tlc <command>

Current Commands

Currently the same as upstream tl.

build: Build a project according to a tlcconfig.lua file at the root of the project.
check: Type check one or more Teal scripts.
gen: Compile one or more Teal scripts (without type checking).
run: Run a Teal script.

Config format

This is subject to change quite a bit because I am fickle ¯\_(ツ)_/¯

Each command is allowed to expose one function to the config file. This function shares a name with the command. All built in commands follow vaguely the same signature of function(string): (function({string:any}) | function({string}))

This type signature is illustrated more clearly by an example

build "options" {
   source_dir = "src",
   build_dir = "build",
}

build "flags" {
   "keep_going"
}

In short, the function signature takes advantage of Lua's syntactic sugar to make a nicer looking config file (at least imo).

Config Options

Coming Eventually™

Features

This is intended to be a build system first and foremost. So most features are within the build command itself

build
- can be run from anywhere within your project, not just the root
- only compiles when sources have changed, similar to Make and other build tools
- your source directory doesn't have to be the same name as your module to compile, if you provide a table of the type
```
record ModuleInfo
   source: string
   name: string
end
```
to project "module", Teal will know how to search for your internal modules for example: if our project was laid out as such
```
src/
   | thing.tl
   | stuff.tl
```
and thing.tl had a require("this_module.stuff"), normal type checking wouldn't work, since by default, module searching can not be modified in such a way to accomodate this and Teal wouldn't find this_module, but if we specify in tlcconfig.lua:
```
project "module" {
   source = "src",
   name = "this_module",
}
build "options" {
   source_dir = "src",
   build_dir = "build",
}
```
then it builds fine and is properly type checked. (Internally this is currently done with a tiny but non-harmful hack that can hopefully be implemented in upstream Teal)
Colored output/fun ANSI stuffs
A pretty okay api, with filesystem utilities
A (subjectively) better config format
listing dependencies in your tlcconfig.lua will add the appropriate paths to find type definitions, provided you have the teal-types repo installed in $XDG_CONFIG_HOME/teal, so instead of the current include_dir solution:

return {
   include_dir = {
      my_types_dir .. "/argparse",
      my_types_dir .. "/luafilesystem",
   }
}

you can do the following:

project "deps" {
   "argparse",
   "luafilesystem",
}

the eventual plan for this is to be able to autogenerate a rockspec file as well for luarocks dependencies

Planned Features

Integration with C tools, or at the very least, be able to specify C source and a C compiler when building
Have a config option to point to the teal-types install location rather than force it to be in $XDG_CONFIG_HOME/teal
an install command and/or integration with luarocks' install command
better luarocks integration such as auto-generating rockspecs that install .tl files in the correct place
and more, but these become easier to implement the more mature tl itself becomes as a language.

API documentation