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 (once per each cron.after)

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

cron.update(5) -- nothing (total time: 5)
cron.update(4) -- nothing (total time: 9)
cron.update(12) -- prints 'Hello' twice (total time is now 21)

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.

Examples using tags:

-- 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').every(2, showMenu)

-- after also has a tagged version:
cron.tagged('menu').after(10, doSomething)

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

-- cron.update updates all the time entries, no matter how they are tagged:
cron.update(2) -- updates everything

-- the tagged version of cron.cancel does not take params:
cron.tagged('main-menu').cancel() -- cancels any entry tagged 'main-menu'

-- A very nice thing: You are not restrited to using strings for tags. Any Lua
-- object (including tables) can be used. This way, you can link time entries
-- to specific instances.

local player = ... -- some table representing the player

cron.tagged(player, 'movement').after(10, startBoredAnimation)
...
cron.tagged(player).cancel() -- cancel all time entries tagged with the player
cron.tagged(player, 'movement') -- cancell the player entries related with movement only

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/*