diff options
author | Zoffix Znet <cpan@zoffix.com> | 2016-07-29 11:39:53 -0400 |
---|---|---|
committer | Zoffix Znet <cpan@zoffix.com> | 2016-07-29 11:39:53 -0400 |
commit | 8d73a96993aca6decc024641313ea240c27e4eed (patch) | |
tree | 5b10030f12b94eb8e4459688164c2b4f080a9174 /docs/02-event-reference.md | |
parent | fba0bb9ed6774b666fa4002fa4a052ae3964bb8e (diff) |
Add events reference
Diffstat (limited to 'docs/02-event-reference.md')
-rw-r--r-- | docs/02-event-reference.md | 246 |
1 files 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 |