bot.alarm
Exports functions for setting and modifying alarms, which can trigger messages at specified times or intervals.
In addition to the exported functions, this module maintains a collection of persistent AnyEvent timer objects which are used to fire the alarm messages asynchronously from any regular message processing.
set-alarm
Description
Creates a new alarm in the current channel. The only required parameters are an alarm name and its first occurrence. An optional message may be included, which will be echoed whenever the alarm fires. Its length and formatting are limited only by the features of the network on which the alarm was set (e.g. IRC will generally be a couple hundred characters or less of plain text, whereas Slack would allow several KB of text with formatting).
Alternately, the message may be given as a quoted expression, which will be stored and evaluated anew with each occurrence of the alarm. These expressions will not receive any arguments, but they may interact with global variables defined within the same network on which the alarm is created. Because the alarms trigger in an anonymous context (i.e. they are not responses to an individual user's message), functions which assume a user will either fail or behave oddly.
Unquoted expressions will be evaluated once at the time of alarm creation, and that result will simply be echoed each time the alarm triggers. You must quote the expression if you wish it to be evaluated on each alarm occurrence.
The initial date and time of the alarm, specified with ``:first`` must be a valid ISO8601 formatted timestamp. The timezone is optional and will default to that of the server on which the bot is running if omitted. It must also be a date and time in the future.
Alarms may be set to recur by specifying an interval with ``:recurring``. The format of the interval (shockingly!) matches that of the interval type in PostgreSQL. Before the alarm is created, a test is performed to ensure that the alarm will not fire too often, as a small measure to prevent abuse. The alarm creation will be rejected if it will emit messages more than a few times an hour.
An exclusion pattern may also be specified with ``:exclude``. Any timestamps from the recurrence interval that match the exclusion patterns will be skipped. The format of the is a comma-separated list of ``<field>=<regular expression>`` and may use any of the PostgreSQL ``to_char(...)`` formatting fields.
Usage
<alarm name> :first <ISO8601> [:recurring <interval>] [:exclude <pattern>] [<message or quoted expression>]
Examples
(set-alarm daily-standup
:first "2016-04-25 10:00:00 US/Eastern"
:recurring "1 day"
:exclude "Day=(Saturday|Sunday)"
"Daily Standup time! Meet in the large conference room.")
(set-alarm open-tickets
:first "2016-10-01 10:00:00 US/Eastern"
:recurring "1 day"
'(join "\n"
(jq "$.[*].ticket-summary"
(http-get (str "https://example.com/api/tickets?"
(query-string { :status "open" :format "json" }))))))delete-alarm
Description
Permanently removes the named alarm from the current channel. The alarm must be recreated from scratch if you wish to use it again.
Usage
<alarm name>
Examples
(delete-alarm daily-standup)show-alarm
Description
Displays the named alarm and its current settings.
Usage
<alarm name>
Examples
(show-alarm daily-standup)list-alarms
Description
Displays all of the alarms for the current channel, as well as their current state (active or suspended) and their next triggering time. If the alarms are recurring that is noted with the recurrence interval.
suspend-alarm
Description
Temporarily suspends the named alarm.
Usage
<alarm name>
Examples
(suspend-alarm daily-standup)resume-alarm
Description
Resumes a suspended alarm. Does nothing to alarms which are not currently suspended. A non-recurring alarm which had been suspended during the time at which it should have triggered is effectively deleted by resuming it. Recurring alarms will simply skip past any triggering intervals which passed during their suspension.
Usage
<alarm name>
Examples
(resume-alarm daily-standup)