Lua API: modules

This page lists every function of the Lua modules that a script of Tilde can call, with its arguments and what it returns.

The modules are globals: a script calls log.info(...) without a require. Load the scripts and see their errors with:

tcli scripts

How to write a script is on Scripts. The events are on Lua API: events.

`log`

Writes to the log of Tilde. The message is a Serilog template whose properties the extra arguments fill: log.info("new mail in {Folder}", e.folder).

Function	Returns	Meaning
`log.debug(message, ...)`	nothing	Logs at Debug.
`log.info(message, ...)`	nothing	Logs at Information.
`log.warning(message, ...)`	nothing	Logs at Warning.
`log.error(message, ...)`	nothing	Logs at Error.

The constants log.LEVEL_DEBUG, log.LEVEL_INFO, log.LEVEL_WARNING and log.LEVEL_ERROR hold the numbers of the Serilog levels.

`events`

Function	Returns	Meaning
`events.on(name, fn)`	nothing	Runs `fn(e)` every time the event `name` happens; `e` is a table of the fields of the event. An unknown name is an error.

`commands`

Function	Returns	Meaning
`commands.add(name, fn, description)`	nothing	Adds a command. `fn` gets a table of the words typed after the name; a string it returns is the message of the command. `description` is optional.
`commands.remove(name)`	nothing	Removes a command that the scripts added. An unknown name is ignored.
`commands.list()`	table of names	Every command, native and script, in the order they were added.
`commands.run(name, ...)`	`{ ok, message }`	Runs a command with the words given. `ok` is true when it ran; `message` is what it returned or why it failed.

A name has 1 to 64 characters: lowercase letters, digits, _, - and ., starting with a letter, with no empty part between dots (test.show). A script command cannot replace a native one. The names that start with keys.fn. are kept for the functions bound to keys.

`keys`

Function	Returns	Meaning
`keys.bind(context, lhs, rhs, description)`	nothing	Binds the key or sequence `lhs` in a context. `rhs` is the name of a command, or a function called with a table of the words (a count typed before the key is the first word). `description` is optional. The same key again in the same context replaces the binding.
`keys.unbind(context, lhs)`	nothing	Removes the binding of `lhs` from that context only. A key that is not bound is ignored.

The contexts and the commands of tt are on tt commands and contexts. The notation is on Change a key.

`jobs`

Function	Returns	Meaning
`jobs.enqueue(fn)`	nothing	Runs `fn` once, in the background, as soon as a worker is free.
`jobs.every(name, minutes, fn)`	nothing	Runs `fn` every `minutes` minutes under a unique name. The first run is one interval from now; `minutes` is more than zero.
`jobs.remove(name)`	nothing	Stops the recurring job `name`. An unknown name is ignored.
`jobs.list()`	table of jobs	The active jobs, each a table with `name`, `kind`, `state`, `interval_minutes`, `last_error` and `progress`.

Two Lua jobs never run at the same time. A reload of the scripts removes the recurring jobs and cancels the queued ones that have not started.

`timers`

Function	Returns	Meaning
`timers.after(seconds, fn)`	id	Runs `fn` once after `seconds`.
`timers.every(seconds, fn)`	id	Runs `fn` every `seconds`, the first time after one interval. A tick that finds the previous run still going is skipped.
`timers.cancel(id)`	boolean	Cancels a timer, also a run that waits to start. False when there is no such timer, it has run already, or it is not one of the scripts.

A reload of the scripts cancels every timer.

`bar`

Function	Returns	Meaning
`bar.top(fn)`	nothing	Sets the function of the top bar; `nil` removes it. `fn(ctx)` returns `{ left, right, bg }`.
`bar.bottom(fn)`	nothing	Sets the function of the status line, in the same way.
`bar.interval(seconds)`	nothing	Builds the bars again every `seconds`, from 1 to 86400; `nil` stops it.
`bar.hints(keys, style)`	list of items	Turns `ctx.keys` into items, one group for each hint.

A reload of the scripts forgets the functions and the interval. See Bars, What a bar returns and The bar context.

`sys`

Function	Returns	Meaning
`sys.date(format)`	string	The local time as text. The format is a .NET one of 1 to 64 characters, such as `"HH:mm:ss"`.
`sys.memory()`	string	The memory Tilde uses, in the unit that fits, such as `241.3 MB`.

`rules`

Added by the rules plugin. See Mail rules and Chat rules.

Function	Returns	Meaning
`rules.mail(name, conditions, actions)`	nothing	Defines a rule for new mail. The same name replaces the rule and keeps its place. A rule that is not valid is an error.
`rules.chat(name, conditions, actions)`	nothing	Defines a rule for new chat messages. A mail rule with the same name is an error.
`rules.off(name)`	boolean	Removes a rule; false for an unknown name.
`rules.list()`	`{ mail = {...}, chat = {...} }`	The names of the rules of each kind, in the order they were defined.
`rules.run(account, folder, options)`	`{ examined, items }`	Applies the mail rules to the newest messages of a folder. `options`: `dry_run`, `limit` (50) and `rule` (the only rule to apply).

Rule	Conditions (all must hold)	Actions
mail	`from`, `to`, `subject` (text or list: the field contains one, any case), `header` (header name to text, list or `true`), `account`, `folder` (without it only `INBOX`)	`mark_read`, `flag` (booleans), `move` (a folder, made when missing), `stop`, `run` (a function)
chat	`from`, `channel`, `account`, `text` (text or list), `direct`, `mention` (booleans)	`mark_read`, `stop`, `run` (a function)

Each item of rules.run has id, subject, rules and steps; a step has step (mark_read, flag, create_folder, move or run), status (done, planned, skipped or failed), detail and error. A run step is always skipped there.

What a script does not have

There is no io, os or debug; dofile, loadfile, rawset, package.path and coroutine.create are gone; print writes to the log; require reads only the scripts folder. See The sandbox.