NOTE: timers use NSTimer internally, which will be paused when computers sleep. Especially, repeating timers won't be triggered at the specificed time when there are sleeps in between. The workaround is to prevent system from sleeping, configured in Energy Saver in System Preferences.
microsecs - A number containing a time in microseconds to block for
Use of this function is strongly discouraged, as it blocks all main-thread execution in Hammerspoon. This means no hotkeys or events will be processed in that time, no GUI updates will happen, and no Lua will execute. This is only provided as a last resort, or for extremely short sleeps. For all other purposes, you really should be splitting up your code into multiple functions and calling hs.timer.doAfter()
Creates and starts a timer which will perform fn at the given (local) time and then (optionally) repeat it every interval.
time - number of seconds after (local) midnight, or a string in the format "HH:MM" (24-hour local time), indicating the desired trigger time
repeatInterval - (optional) number of seconds between triggers, or a string in the format "DDd", "DDdHHh", "HHhMMm", "HHh" or "MMm" indicating days, hours and/or minutes between triggers; if omitted or 0 the timer will trigger only once
fn - a function to call every time the timer triggers
continueOnError - an optional boolean flag, defaulting to false, which indicates that the timer should not be automatically stopped if the callback function results in an error.
a timer object
The timer can trigger up to 1 second early or late
The first trigger will be set to the earliest occurrence given the repeatInterval; if that's omitted, and time is earlier than the current time, the timer will trigger the next day. If the repeated interval results in exactly 24 hours you can schedule regular jobs that will run at the expected time independently of when Hammerspoon was restarted/reloaded. E.g.:
If it's 19:00, hs.timer.doAt("20:00",somefn) will set the timer 1 hour from now
If it's 21:00, hs.timer.doAt("20:00",somefn) will set the timer 23 hours from now
If it's 21:00, hs.timer.doAt("20:00","6h",somefn) will set the timer 5 hours from now (at 02:00)
To run a job every hour on the hour from 8:00 to 20:00: for h=8,20 do hs.timer.doAt(h..":00","1d",runJob) end
Creates a new hs.timer object for repeating interval callbacks
interval - A number of seconds between firings of the timer
fn - A function to call every time the timer fires
continueOnError - An optional boolean, true if the timer should continue to be triggered after the callback function has produced an error, false if the timer should stop being triggered after the callback function has produced an error. Defaults to false.
An hs.timer object
The returned object does not start its timer until its :start() method is called
If interval is 0, the timer will not repeat (because if it did, it would be repeating as fast as your machine can manage, which seems generally unwise)
For non-zero intervals, the lowest acceptable value for the interval is 0.00001s. Values >0 and <0.00001 will be coerced to 0.00001
Creates and starts a timer which will perform actionFn when predicateFn returns false. The timer is automatically stopped when actionFn is called.
predicateFn - a function which determines when actionFn should be called. This function takes no arguments, but should return false when it is time to call actionFn.
actionFn - a function which performs the desired action. This function may take a single argument, the timer itself.
checkInterval - an optional parameter indicating how often to repeat the predicateFn check. Defaults to 1 second.
a timer object
The timer is stopped before actionFn is called, but the timer is passed as an argument to actionFn so that the actionFn may restart the timer to be called again the next time predicateFn returns false.
See also hs.timer.waitUntil, which is essentially the opposite of this function
Returns the number of seconds until the timer will next trigger
A number containing the number of seconds until the next firing
The return value may be a negative integer in two circumstances:
Hammerspoon's runloop is backlogged and is catching up on missed timer triggers
The timer object is not currently running. In this case, the return value of this method is the number of seconds since the last firing (you can check if the timer is running or not, with hs.timer:running()