Lesson 4: Listen for IRC events

Goal: answer !ping in a channel.

--! name: Ping
--! description: Replies pong to !ping
--! api: 1
--! permissions: send
swizzin.on("message", function(e)
    if e.text == "!ping" then
        swizzin.send(e.target, "pong")
    end
end)

What it does

swizzin.on(event, fn, opts?) calls fn with an event table for each event of that kind. Useful fields: e.nick (who), e.target (channel), e.text, e.network_name, e.time (milliseconds). Other events include join, part, quit, nick, kick, topic, mode, connect, disconnect and reconnecting: see IRC events.

Expected result

When someone types !ping in a channel you are in, the script replies pong on the same network.

Good to know

By default a script does not receive your own events, so it cannot answer itself in a loop. Pass {own = true} only if you need that.
Lines replayed by a bouncer are skipped unless you pass {playback = true}.
Event text is untrusted: it comes from other people.

Common mistakes

Assuming e.target is always a channel: for a private message it is the other nickname, and private is a separate event.
Slow handlers: a callback has 250 ms, and events past the queue of 256 are dropped.

Troubleshooting

Nothing happens: the script is off, lacks the send approval, or you are not in the channel.
An unknown event name raises an error listing the valid names.