cron.lua/README.md

cron.lua

cron.lua are a set of functions for executing actions at a certain time interval.

API

• cron.after(time, callback) will execute callback after the given amount of time units. Returns an identifier (id)
• cron.every(time, callback) will repeat the same action periodically. Returns an identifier (id)
• cron.cancel(id) will stop a timed action from happening, and will interrupt the periodical execution of a periodic action.
• cron.reset() removes all timed and periodic actions, and resets the time passed back to 0.
• cron.update(dt) is needed to be executed on the main program loop. dt is the amount of time that has passed since the last iteration. When cron.update is executed, cron will check the list of pending actions and execute them if needed.
• cron.tagged(tag1, tag2, tag3 ...) filters other cron methods (cron.after, cron.every, cron.update & cron.cancel but not cron.reset) so that they create clocks with specific tags/ act on clocks with specific tags.

Examples

local cron = require 'cron'

local function printMessage()
  print('Hello')
end

-- the following calls are equivalent:
cron.after(5, printMessage)
cron.after(5, print, 'Hello')

cron.update(5) -- will print 'Hello' twice

-- this will print the message periodically:
local id = cron.every(10, printMessage)

cron.update(5) -- nothing
cron.update(4) -- nothing
cron.update(12) -- prints 'Hello' twice

cron.cancel(id) -- stops the execution the element defined by id. Works with periodical or one-time actions.

cron.reset() -- stops all the current actions, both timed ones and periodical ones.

Some tag examples:

-- This has the same effect of cron.after(2, showMenu), except that the
-- time entry is tagged with the tags 'main-menu' and 'menu'
cron.tagged('main-menu', 'menu').after(2, showMenu)

-- This updates the time entries tagged with the tag 'menu', but not the rest
cron.tagged('menu').update(2)

-- cron.cancel does not admit filtering via tags, but it admits tags as params
-- the previous call is equivalent to this one:
cron.tagged('main-menu').cancel()

Gotchas / Warnings

• cron.lua does not implement any hardware or software clock; you will have to provide it with the access to the hardware timers, in the form of periodic calls to cron.update
• cron does not have any defined time units (seconds, milliseconds, etc). You define the units it uses by passing it a dt on cron.update. If dt is in seconds, then cron will work in seconds. If dt is in milliseconds, then cron will work in milliseconds.

Installation

Just copy the cron.lua file somewhere in your projects (maybe inside a /lib/ folder) and require it accordingly.

Remember to store the value returned by require somewhere! (I suggest a local variable named cron)

local cron = require 'cron'

Also, make sure to read the license file; the text of that license file must appear somewhere in your projects' files.

Specs

This project uses "telescope":https://github.com/norman/telescope for its specs. If you want to run the specs, you will have to install telescope first. Then run:

tsc spec/*