Teal support on Alfons!

[daelvn]

In this post I'm just talking about the Teal support, for the complete usage, it's a good idea to read the full docs.

Inspired by the Teal CLI discussion, I decided to add Teal support to one of my projects, Alfons, a task runner for Lua, MoonScript and now Teal. I'll briefly describe what the project does and then move on to explain how it supports Teal.

As the README describes, Alfons is inspired by the "worst use cases of Make". The hole this tries to fill is running scripts, really. Instead of having a Makefile to do things like compiling, cleaning your compiled files, fetching dependencies, uploading rockspecs... you just use Alfons. You use a Taskfile (or Alfonsfile) to describe Tasks, which you can use in combination with several provided functions. You can install it via LuaRocks (rock alfons).

The first way in which Teal is supported is that you can now define your taskfiles in Teal. You make an Alfons.tl file in your current directory, and running alfons will detect it automatically. Since this is a showcase of the Teal support, and not of the whole project, I will show the second way in which Alfons supports Teal: through an utility plugin. It's shipped by default on 4.4.1 (latest), and all you have to do is create an always task, and load the plugin there.

global function always()
  load "teal"
end

And you're good to go! Now, if you want to declare dependencies and install them, it simply one more line:

global function always()
  load "teal"
  store.dependencies = {"your", "deps", "here"}
end

Now you can run alfons install from the command line and it will install dependencies! If you want to do the same thing from the Taskfile, simply call tasks.install(). (Note: You probably should be using luarocks make --pin --only-deps for this)

But there's more. The task build is an alias to the shell command tl build, for convenience. It can also download type definitions from teal-types. You can do this in several ways:

Individually, from the command line: alfons typings -m <module>
Individually, from the Taskfile task: tasks.typings{ module = "module" }
In bulk, using the Taskfile task: tasks.typings{ modules = {"moda", "modb"} }
In bulk, automatically, using store:

global function always()
  store.typings = {"moda", "modb"}
  store.teal_auto = true
  load "teal"
end

And last but not least, it supports Hooks. You can define tasks with specific names such as teal_postbuild to run scripts after tl build was run:

global function always()
  load "teal"
end

global function teal_postbuild()
  prints "This will run after the build completes!"
end

However, there are some shortcomings:

• Since there is no official, updated LuaRocks API, it has to resort to running shell commands to install dependencies. This will pose a real challenge in the future unless something changes on the LuaRocks side.
• Some useful commands, like watch or lazy builds haven't been implemented yet. However, you can make them yourself with the watch and build functions that Alfons provides.
• Downloading type definitions depends on two other rocks. There isn't much I can do about this.

Here are the docs for the Teal plugin. Thanks for reading!

[lenscas]

it can run teal scripts, both during setup, when you start to build and afterwards? Now all it need is a way to enforce a consistent naming scheme (assuming it doesn't already have that) and then it can be bundled with the proposed CLI and ideally get driven by it :)

One thing that I would like if is teal_postbuild gets the path to the output folder passed. Just makes transforming the generated lua files rely a bit less on magic strings :) However, I guess that that would break the api with the other languages used?

[daelvn]

it can run teal scripts, both during setup, when you start to build and afterwards?

You can write the main Taskfile in teal, and "plugins" (loaded with load) use require internally, so that's up to how require handles it. You are still able to define whatever you want in the main Taskfile, though.

Now all it need is a way to enforce a consistent naming scheme (assuming it doesn't already have that)

There is currently no way of enforcing a consistent naming scheme, no, but at the same time, there is not much you can do about it: all tasks are loaded from the Taskfile and there are no default tasks pre-loaded. However, when you load a plugin, certain tasks get loaded, like with the Teal plugin. They can be overriden, but you generally shouldn't (because it's not a really good practice). The solution I would see here is simply to standardize the Teal plugin, which comes with its own tasks, which presumably won't be overwritten.

One thing that I would like if is teal_postbuild gets the path to the output folder passed. Just makes transforming the generated lua files rely a bit less on magic strings :) However, I guess that that would break the api with the other languages used?

This plugin doesn't actually get the build.tl nor the tlconfig.lua file, it just runs tl build on os.execute (because trying to reimpement tl build in Alfons would be way overkill). It also is because Alfons really just limits itself to do what it should: which is run things. If you wanted to do this though, you could always do require "tlconfig" to get the config table, and use your output folder from there. Alternatively (and this will be the option I will probably be using), you can replicate part of the tlconfig.lua functionality manually:

global function always()
  load "teal"
end

global function compile()
  build(wildcard("**.tl"), function(file:string)
    local code: number = select(3, sh "tl check " .. file)
    if code == 0 then sh string.format("tl gen -o %s.lua %s", basename(file), file) end
  end)
end

It is still very primitive as you can see, because the Teal module does not have a very good build API.

Disclaimer: I usually write my Taskfiles in MoonScript