mirror of
https://github.com/kikito/cron.lua.git
synced 2024-12-19 18:34:20 +00:00
README
This commit is contained in:
kikito
parent
610dfaaacc
commit
deb91cf5fe
81
README.md
Normal file
81
README.md
Normal file
@ -0,0 +1,81 @@
|
||||
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/*
|
||||
|
||||
|
||||
@ -1,80 +0,0 @@
|
||||
h1. cron.lua
|
||||
|
||||
@cron.lua@ are a set of functions for executing actions at a certain time interval.
|
||||
|
||||
h1. Examples of use
|
||||
|
||||
* @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.
|
||||
|
||||
<pre>
|
||||
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.
|
||||
</pre>
|
||||
|
||||
Some tag examples:
|
||||
|
||||
<pre>
|
||||
-- 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()
|
||||
</pre>
|
||||
|
||||
|
||||
h1. 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.
|
||||
|
||||
h1. 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@)
|
||||
|
||||
<pre>
|
||||
local cron = require 'cron'
|
||||
</pre>
|
||||
|
||||
Also, make sure to read the license file; the text of that license file must appear somewhere in your projects' files.
|
||||
|
||||
h1. 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:
|
||||
|
||||
<pre>
|
||||
tsc spec/*
|
||||
</pre>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user