From 8d73a96993aca6decc024641313ea240c27e4eed Mon Sep 17 00:00:00 2001 From: Zoffix Znet Date: Fri, 29 Jul 2016 11:39:53 -0400 Subject: Add events reference --- docs/02-event-reference.md | 246 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 241 insertions(+), 5 deletions(-) diff --git a/docs/02-event-reference.md b/docs/02-event-reference.md index b1ec2ba..6233b24 100644 --- a/docs/02-event-reference.md +++ b/docs/02-event-reference.md @@ -49,8 +49,12 @@ irc-addressed ▶ irc-to-me ▶ irc-notice-channel ▶ irc-notice irc-mode-channel ▶ irc-mode ▶ irc-all irc-mode-me ▶ irc-mode ▶ irc-all - irc-connected ▶ irc-numeric ▶ irc-XXX ▶ irc-all - irc-numeric ▶ irc-XXX ▶ irc-all + irc-connected ▶ irc-XXX ▶ irc-numeric ▶ irc-all + irc-XXX ▶ irc-numeric ▶ irc-all + irc-join ▶ irc-all + irc-part ▶ irc-all + irc-quit ▶ irc-all + irc-unknown ▶ irc-all irc-started ``` @@ -72,11 +76,11 @@ the plugins ### `irc-addressed` ``` -irc-addressed ▶ irc-to-me ▶ irc-privmsg-channel ▶ irc-privmsg ▶ irc-all -irc-addressed ▶ irc-to-me ▶ irc-notice-channel ▶ irc-notice ▶ irc-all +irc-addressed ▶ irc-to-me ▶ irc-privmsg-channel ▶ irc-privmsg ▶ irc-all +irc-addressed ▶ irc-to-me ▶ irc-notice-channel ▶ irc-notice ▶ irc-all ``` -This event chain is triggered when the client is addressed in channel either +This event chain is triggered when the client is addressed in a channel either via a `PRIVMSG` or `NOTICE` IRC message. 'Addressed' means the message line starts with the current nickname of the client, followed by single whitespace character, `;`, or `,` characters, followed by any number of whitespace; or in regex terms, matches `/^ $nick <[,:\s]> \s* /`. This prefix portion will be @@ -87,6 +91,44 @@ Possible message objects received by event handler: * `IRC::Client::Message::Privmsg::Channel` * `IRC::Client::Message::Notice::Channel` +### `irc-all` + +``` +irc-all +``` + +Triggered on all events, except for the special `irc-started` event. + +Possible message objects received by event handler: +* `IRC::Client::Message::Notice::Channel` +* `IRC::Client::Message::Notice::Me` + +### `irc-connected` + +``` +irc-connected ▶ irc-001 ▶ irc-numeric ▶ irc-all +``` + +Triggered on `001` numeric IRC command that indicates we successfully +connected to the IRC server and obtained a nickname. *Note:* it's not +guaranteed that we already joined all the channels when this event is triggered; +in fact, it's more likely that we haven't yet. *Also note:* that in long +running programs this event will be triggered more than once, because the +client automatically reconnects when connection drops, so the event will +be triggered on each reconnect. See also `irc-started` + +Receives `IRC::Client::Message::Numeric` message object. + +### `irc-join` + +``` +irc-join ▶ irc-all +``` + +Triggered when someone joins a channel we are in. *Note:* typically the +server will generate this event when *we* join a channel too. +Receives `IRC::Client::Message::Join` message object. + ### `irc-mentioned` ``` @@ -94,9 +136,203 @@ irc-mentioned ▶ irc-privmsg-channel ▶ irc-privmsg ▶ irc-all irc-mentioned ▶ irc-notice-channel ▶ irc-notice ▶ irc-all ``` +This event chain is triggered when the client is mentioned in a channel either +via a `PRIVMSG` or `NOTICE` IRC message. Being mentioned means the message +contains our nick delimited by word boundaries on both sides; or in regex +terms, matches `/ << $nick >> /`. + +Possible message objects received by event handler: +* `IRC::Client::Message::Privmsg::Channel` +* `IRC::Client::Message::Notice::Channel` + +### `irc-mode` + +``` +irc-mode ▶ irc-all +``` + +Triggered when `MODE` commands are performed on the client or on the channel +we are in. + +Possible message objects received by event handler: +* `IRC::Client::Message::Mode::Channel` +* `IRC::Client::Message::Mode::Me` + +### `irc-mode-channel` + +``` +irc-mode-channel ▶ irc-mode ▶ irc-all +``` + +Triggered when `MODE` commands are performed on a channel the client is in +Receives `IRC::Client::Message::Mode::Channel` message object. + +### `irc-mode-me` + +``` +irc-mode-me ▶ irc-mode ▶ irc-all +``` + +Triggered when `MODE` commands are performed on the client. +Receives `IRC::Client::Message::Mode::Me` message object. + +### `irc-notice` + +``` +irc-notice ▶ irc-all +``` + +Triggered on `NOTICE` messages sent to a channel the client is in or to +the client directly. + +Possible message objects received by event handler: +* `IRC::Client::Message::Notice::Channel` +* `IRC::Client::Message::Notice::Me` + +### `irc-notice-channel` + +``` +irc-notice-channel ▶ irc-notice ▶ irc-all +``` + +Triggered on `NOTICE` messages sent to a channel the client is in. +Receives `IRC::Client::Message::Notice::Channel` message object. + +### `irc-notice-me` + +``` +irc-notice-me ▶ irc-notice ▶ irc-all +``` + +Triggered on `NOTICE` messages sent directly to the client. +Receives `IRC::Client::Message::Notice::Me` message object. + +### `irc-numeric` + +``` +irc-numeric ▶ irc-XXX ▶ irc-all +``` + +Triggered on numeric IRC commands. +Receives `IRC::Client::Message::Numeric` message object. + +### `irc-part` + +``` +irc-part ▶ irc-all +``` + +Triggered when someone parts (leaves without quitting IRC entirely) a channel +we are in. Receives `IRC::Client::Message::Part` message object. + +### `irc-privmsg` + +``` +irc-privmsg ▶ irc-all +``` + +Triggered on `PRIVMSG` messages sent to a channel the client is in or to +the client directly. + +Possible message objects received by event handler: +* `IRC::Client::Message::Privmsg::Channel` +* `IRC::Client::Message::Privmsg::Me` + +### `irc-privmsg-channel` + +``` +irc-privmsg-channel ▶ irc-privmsg ▶ irc-all +``` + +Triggered on `PRIVMSG` messages sent to a channel the client is in. +Receives `IRC::Client::Message::Privmsg::Channel` message object. + + +### `irc-privmsg-me` + +``` +irc-privmsg-me ▶ irc-privmsg ▶ irc-all +``` + +Triggered on `PRIVMSG` messages sent directly to the client. +Receives `IRC::Client::Message::Privmsg::Me` message object. + +### `irc-quit` + +``` +irc-quit ▶ irc-all +``` + +Triggered when someone in a channel we are in quits IRC. +Receives `IRC::Client::Message::Quit` message object. + +### `irc-started` + +``` +irc-started +``` + +The event is different from all others (see end of `Event Map` section). It's +triggered just once per call of `.run` method on `IRC::Client` object, +regardless of how many times the client reconnects, and it's +called on all of the plugins, regardless of the return value of the +event handler. + +Does not receive any arguments. + +### `irc-to-me` + +``` +irc-addressed ▶ irc-to-me ▶ irc-privmsg-channel ▶ irc-privmsg ▶ irc-all + irc-to-me ▶ irc-privmsg-me ▶ irc-privmsg ▶ irc-all + +irc-addressed ▶ irc-to-me ▶ irc-notice-channel ▶ irc-notice ▶ irc-all + irc-to-me ▶ irc-notice-me ▶ irc-notice ▶ irc-all +``` + +This event chain is triggered when the client is addressed in a channel via +a `PRIVMSG` or `NOTICE` IRC message or receives a private or notice +message directly. In cases where the trigger happened due to being addressed +in channel, the prefix used for addressing (nick + `,` or `.` + whitespace) +will be stripped from the message. + Possible message objects received by event handler: * `IRC::Client::Message::Privmsg::Channel` +* `IRC::Client::Message::Privmsg::Me` * `IRC::Client::Message::Notice::Channel` +* `IRC::Client::Message::Notice::Me` + +*Note irrelevant to common users:* to avoid spurious triggers during +IRC server connection negotiation, this event does *not* fire until the server +deems the client connected; that is, sends the IRC `001` command. + +### `irc-unknown` + +``` +irc-unknown ▶ irc-all +``` + +Triggered when an unknown event is generated. You're not supposed to receive +any of these and receiving one likely indicates a problem with `IRC::Client`. +Please report this [on the Issue +tracker](https://github.com/zoffixznet/perl6-IRC-Client/issues/new), +indicating what server generated such a message and include your code too, +if possible. + +Receives `IRC::Client::Message::Unknown` message object. + +### `irc-XXX` + +**Note:*** `XXX` stands for a three-digit numeric code of the command that +triggered the event, for example `irc-001`. See `irc-numeric` for event trigger +that responds to all numerics. + +``` +irc-XXX ▶ irc-numeric ▶ irc-all +``` + +Triggered on numeric IRC commands. +Receives `IRC::Client::Message::Numeric` message object. ## Up Next -- cgit v1.1