cron.lua/README.md

cron.lua
========

[![Build Status](https://travis-ci.org/kikito/cron.lua.png?branch=master)](https://travis-ci.org/kikito/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.doFor(time, callback)` will execute a callback every time `cron.update` is called until the timer expires. 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/*