mirror of
https://github.com/kikito/cron.lua.git
synced 2024-12-19 18:34:20 +00:00
Time-related functions for Lua, inspired in javascript's setTimeout and setInterval
spec | ||
.travis.yml | ||
cron.lua | ||
MIT-LICENSE.txt | ||
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. Whencron.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 notcron.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 tocron.update
cron
does not have any defined time units (seconds, milliseconds, etc). You define the units it uses by passing it adt
oncron.update
. Ifdt
is in seconds, thencron
will work in seconds. Ifdt
is in milliseconds, thencron
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 busted for its specs. If you want to run the specs, you will have to install it first. Then run:
cd path/where/the/spec/folder/is
busted